docs: demote VPN from on-ramp paths to a focused subsection

VPN pairing is irrelevant for adopters with public deploy hosts but
sat squarely on the path-of-least-resistance — Quick Start example,
secrets table, secrets list, plus four scattered mentions in
action.yml's marketplace description. Consolidate it into a single
"Private deploy hosts" subsection in getting-started, with short
pointers from README and examples for the audience that needs it.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jmschneider

README.md

@@ -73,13 +73,6 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      # Optional: open a VPN tunnel if your deploy host is private.
-      # The VPN action and kamal-previews are independent concerns —
-      # compose them as sibling steps. Drop this step if your host is
-      # public.
-      # - uses: <your-vpn-action>@v1
-      #   with: { ... }
-
       - uses: web-ascender/github-actions-kamal-previews@v1
         with:
           base-deploy-file:    config/deploy.staging.yml
@@ -103,7 +96,6 @@ The repo-level GitHub Actions secrets the workflow expects:
 | --- | --- |
 | `DEPLOY_SSH_KEY`     | Always — the deploy host SSH key. |
 | `DATABASE_ADMIN_URL` | Only if the URL exposed by your `base-secrets-file` doesn't have CREATEDB. Format: `postgres://admin:secret@host:5432/postgres?sslmode=verify-full`. |
-| VPN credentials (if any) | Only if pairing with a VPN step above. Names depend on the VPN action you choose. |
 
 Add them under Settings → Secrets and variables → Actions. The first PR
 you open after merging the workflow file will provision a preview
@@ -117,10 +109,13 @@ walkthrough including DNS, TLS, secrets, and host setup.
 Prefer the reusable workflow form
 (`uses: web-ascender/github-actions-kamal-previews/.github/workflows/preview.yml@v1`)
 when you want job-level features like matrix-fanned parallel orphan
-cleanup or GitHub's job-level concurrency UI. It does NOT support
-VPN pairing — workflows can't host sibling steps the way actions
-can — so private-host setups must use the composite action form above.
-See [`examples/README.md`](examples/README.md) for the comparison.
+cleanup or GitHub's job-level concurrency UI. See
+[`examples/README.md`](examples/README.md) for the comparison.
+
+> Private deploy host? Stick with the composite action form above and
+> add your VPN action as a sibling step — the reusable workflow form
+> can't host sibling steps. See
+> [getting-started](docs/getting-started.md#private-deploy-hosts).
 
 ## Architecture at a glance
 

action.yml

@@ -17,11 +17,6 @@ description: |
           steps:
             - uses: actions/checkout@v4
 
-            # Optional: open a VPN tunnel before this action runs,
-            # so SSH to a private deploy host works.
-            # - uses: <your-vpn-action>@v1
-            #   with: { ... }
-
             - uses: web-ascender/github-actions-kamal-previews@v1
               with:
                 base-deploy-file:    config/deploy.staging.yml
@@ -44,24 +39,18 @@ description: |
     - delete (branch)                            → teardown
     - anything else                              → skip (with notice)
 
-  VPN setup is intentionally NOT in this action — pair it with any VPN
-  action you already trust as a sibling step. Tunnels established in
-  earlier steps remain active for the subsequent `kamal-previews` step
-  in the same job.
-
   Two consumption forms; pick whichever fits:
 
   - **This composite action** — single-step, sibling-friendly. Use when
-    your job needs a sibling VPN tunnel, custom credential-fetch step,
-    or any other pre/post step around kamal-previews itself.
+    your job needs sibling steps around kamal-previews (e.g. opening a
+    VPN tunnel before SSH to a private deploy host, or a custom
+    credential-fetch step).
   - **Reusable workflow** at
     `web-ascender/github-actions-kamal-previews/.github/workflows/preview.yml@v1` —
     multi-job, with deploy and teardown as separate jobs. Use when you
     don't need sibling steps and want stricter concurrency control.
 
-  Both forms support `branch-pattern` and `max-active-previews`. Neither
-  ships with VPN inputs; add the VPN as a sibling step (composite) or a
-  pre-step in your wrapping workflow (reusable).
+  Both forms support `branch-pattern` and `max-active-previews`.
 
 inputs:
   base-deploy-file:           { required: true }

docs/getting-started.md

@@ -146,11 +146,6 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      # Optional: open a VPN tunnel before kamal-previews runs.
-      # Skip this step if your deploy host is publicly addressable.
-      # - uses: <your-vpn-action>@v1
-      #   with: { ... }
-
       - uses: web-ascender/github-actions-kamal-previews@v1
         with:
           base-deploy-file:    config/deploy.staging.yml
@@ -175,8 +170,6 @@ variables → Actions:
   out to `bin/rails credentials:fetch ...` for the URL
 - `DATABASE_ADMIN_URL` — only if your staging app role lacks `CREATEDB`
   privilege (then provide a separate admin URL with that privilege)
-- VPN credentials — only if you're using a VPN step (names depend
-  on the VPN action you choose)
 
 ## Step 6: Open a test PR
 
@@ -190,6 +183,28 @@ see:
 Open the URL in a browser — you should see your app, populated with the
 data from `myapp_staging` cloned moments ago.
 
+## Private deploy hosts
+
+If your deploy host isn't publicly reachable, open a VPN tunnel as a
+sibling step before the kamal-previews step. The two are independent
+concerns — pick whichever VPN action you already trust:
+
+```yaml
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: <your-vpn-action>@v1
+        with: { ... }
+
+      - uses: web-ascender/github-actions-kamal-previews@v1
+        with: { ... }
+```
+
+The tunnel established by the earlier step stays open for the rest of
+the job. Add whatever credential secrets the VPN action requires
+alongside `DEPLOY_SSH_KEY`. The reusable-workflow form doesn't support
+this pattern — for private hosts, stick with the composite action.
+
 ## Step 7 (recommended): Add the daily sweeper
 
 The deploy / teardown lifecycle is event-driven and very reliable, but

examples/README.md

@@ -7,16 +7,16 @@ adjust the `with:`, `env:`, and `secrets:` blocks for your environment.
 
 | File | Use when |
 | --- | --- |
-| [minimal/preview.yml](minimal/preview.yml)     | Public deploy host, single Postgres DB. The shortest config that works. |
-| [postgres/preview.yml](postgres/preview.yml)   | Your staging DB is PostgreSQL — full-featured (VPN pairing, multi-DB, caps). |
+| [minimal/preview.yml](minimal/preview.yml)     | Single Postgres DB, public deploy host. The shortest config that works. |
+| [postgres/preview.yml](postgres/preview.yml)   | Your staging DB is PostgreSQL — full-featured (multi-DB, resource caps, branch filters). |
 | [postgres/sweep.yml](postgres/sweep.yml)       | Optional daily orphan cleanup. |
 | [mysql/preview.yml](mysql/preview.yml)         | Your staging DB is MySQL. |
 | [sqlite/preview.yml](sqlite/preview.yml)       | Your staging DB is SQLite (file on the deploy host). |
 
 Every example uses the **composite action** form (`uses:
 web-ascender/github-actions-kamal-previews@v1`) — a single step inside a single job.
-This composes naturally with a sibling VPN step. See the
-[postgres example](postgres/preview.yml) for a worked VPN pairing.
+This composes naturally with sibling steps such as a VPN tunnel for
+private deploy hosts.
 
 ## Reusable-workflow form (advanced)
 
@@ -33,6 +33,7 @@ jobs:
     secrets: inherit
 ```
 
-The reusable workflow form does NOT support VPN pairing (workflows
-are jobs, not steps — there's no place to insert a sibling VPN step). If
-your deploy host is private, use the composite action form.
+The reusable workflow form is jobs-only — there's no place to insert
+sibling steps. If you need to pair kamal-previews with another step
+(e.g. a VPN tunnel for a private deploy host), use the composite
+action form.