docs: sync documentation with QuickStack changes (week of 2026-04-27)

content/docs/how-to/deployments/build-methods.mdx

@@ -0,0 +1,46 @@
+---
+sidebar_position: 3
+title: "Build Methods"
+description: "Choose between Railpack (zero-config, auto-detect) and Dockerfile build methods for Git-based apps in QuickStack."
+keywords: ["QuickStack build method", "Railpack", "Dockerfile", "buildpack", "auto-detect", "build configuration"]
+---
+
+When deploying an app from a Git repository, QuickStack supports two build methods:
+
+| Method | Requires Dockerfile | Best for |
+|--------|--------------------|-----------------------|
+| **Railpack** | No | Apps in supported languages where you want zero-config builds |
+| **Dockerfile** | Yes | Full control over the build; custom base images; unsupported stacks |
+
+## Railpack
+
+Railpack is an open-source build tool by [Railway](https://railway.app) that automatically detects your language and framework, then produces an optimised Docker image without any Dockerfile.
+Currently, Railpack supports 10+ languages and frameworks. For a full list, see the [Railpack documentation](https://railpack.com/).
+
+### When to use Railpack
+
+- You don't want to maintain a Dockerfile.
+- Your app uses a common language/framework that Railpack detects automatically.
+- You want fast zero-config onboarding.
+
+## Dockerfile
+
+The Dockerfile method uses [BuildKit](https://docs.docker.com/build/buildkit/) to build your image from a `Dockerfile` you provide in your repository.
+
+### When to use Dockerfile
+
+- Your stack is not supported by Railpack.
+- You need a custom base image or multi-stage build.
+- You require precise control over the build environment.
+- You are migrating an existing app that already has a Dockerfile.
+
+## Switching between methods
+
+You can switch build methods at any time by editing the app's General settings and redeploying. There is no data loss when switching — environment variables, volumes, and domains are unaffected.
+
+## Troubleshooting
+
+| Problem | Action |
+|---------|--------|
+| Railpack build fails with "unsupported" | Check whether your stack is listed at [docs.railpack.io](https://docs.railpack.io); switch to the Dockerfile method if not |
+| Dockerfile not found | Ensure the path is relative to repo root and the file exists on the configured branch |

content/docs/how-to/deployments/meta.json

@@ -1,6 +1,7 @@
 {
   "pages": [
     "redeploy-and-rollbacks",
+    "build-methods",
     "webhooks-auto-deploy"
   ]
 }

content/docs/how-to/deployments/redeploy-and-rollbacks.mdx

@@ -11,20 +11,20 @@ This is intentional: you can batch multiple config changes and apply them all at
 
 ## What "Deploy" does
 
-1. For Git-source apps: pulls the latest commit from the configured branch, builds a new Docker image via BuildKit, pushes it to the internal registry.
+1. For Git-source apps: pulls the latest commit from the configured branch, then builds a new Docker image using the configured [build method](/docs/how-to/deployments/build-methods) (Railpack or Dockerfile), and pushes it to the internal registry.
 2. For Docker image apps: pulls the specified image tag from the configured registry.
 3. Applies all staged config changes (env vars, volumes, ports, network policies, health checks, etc.).
 4. Performs a rolling update: new pods are started, old pods are terminated once the new ones are healthy.
 
+> **info No zero-downtime guarantee without health checks**
+> Without a configured [health check](/docs/how-to/observability/health-checks), Kubernetes marks pods ready as soon as they start, which may be before your app is actually serving requests. Configure a readiness probe for zero-downtime deploys.
+
 ## Deployment history
 
 The **Overview** tab shows a history of recent deployments. For Git-source apps, each entry displays the **git commit message** of the commit that triggered the build, making it easy to track which code change corresponds to each deployment.
 
 Kubernetes events (pod scheduling, image pull, container start/stop) are streamed directly into the deployment log, providing richer context when diagnosing a failed or slow deployment.
 
-> **info No zero-downtime guarantee without health checks**
-> Without a configured [health check](/docs/how-to/observability/health-checks), Kubernetes marks pods ready as soon as they start, which may be before your app is actually serving requests. Configure a readiness probe for zero-downtime deploys.
-
 > **info Running multiple builds**
 > If multiple builds are triggered at the same time, they will enter a **PENDING** state and execute in FIFO order as build slots become available. 
 

content/docs/tutorials/first-app-from-git.mdx

@@ -5,21 +5,16 @@ description: "Deploy an application directly from a Git repository using QuickSt
 keywords: ["QuickStack Git Deployment", "QuickStack Git Source", "QuickStack Git Deployment Guide"]
 ---
 
-QuickStack clones your repo, builds the Docker image from your Dockerfile, and runs it as a container. Every time you click **Deploy**, the current configuration is applied — changes to settings do not take effect automatically.
+QuickStack clones your repo, builds a Docker image, and runs it as a container. Every time you click **Deploy**, the current configuration is applied.
+
+QuickStack supports two [build methods](/docs/how-to/deployments/build-methods):
+- **Railpack** — auto-detects your language and framework; no Dockerfile needed.
+- **Dockerfile** — uses a `Dockerfile` you provide in your repository.
 
 ## Prerequisites
 
 - QuickStack installed ([installation guide](/docs/tutorials/installation))
-- A Git repository with a valid `Dockerfile`
-
-## Required inputs
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| Repo URL | Yes | **HTTPS** URL (e.g. `https://github.com/org/repo.git`) |
-| Branch | Yes | Branch to build from (e.g. `main`) |
-| Dockerfile path | Yes | Relative path from repo root (e.g. `./Dockerfile`) |
-| Git Username + Token | No | Required for private repositories |
+- A Git repository (with a `Dockerfile` if using the Dockerfile build method)
 
 ## Step 1: Create project and app
 
@@ -32,9 +27,12 @@ QuickStack clones your repo, builds the Docker image from your Dockerfile, and r
 
 1. Open the app and go to **App Settings** → **General** tab.
 2. Set **Source type** to **Git Repository**.
-3. Fill in: Repo URL, Branch, Dockerfile path.
-4. For private repos: add Git username and Personal Access Token.
-5. Click **Save**.
+3. Fill in: Repo URL and Branch.
+4. Choose a **Build Method**:
+   - **Railpack** — no Dockerfile needed. Railpack auto-detects your stack.
+   - **Dockerfile** — enter the path to your Dockerfile (e.g. `./Dockerfile`).
+5. For private repos: add Git username and Personal Access Token.
+6. Click **Save**.
 
 <img  src="/img/docs/managing-apps/creating-apps/enter-git-credentials.png" alt="QuickStack Git Credentials" />
 
@@ -58,7 +56,8 @@ Click the **Deploy** button at the top of the page. This triggers a fresh build
 
 | Symptom | Fix |
 |---------|-----|
-| Build fails | Check deployment logs for Dockerfile errors |
+| Build fails | Check deployment logs for build errors |
+| Railpack build fails | Verify your language/framework is [supported by Railpack](https://railpack.io); switch to the Dockerfile method if needed |
 | Dockerfile not found | Verify the path is relative to repo root (e.g. `./Dockerfile`) |
 | App not reachable after deploy | Add a domain in the **Domains** tab with the correct internal container port |