docs: add scope page and fix inaccurate deployment claims

Add docs/scope.md covering design boundaries, infrastructure constraints,
and when to use alternatives. Fix deployment.md: replace false
zero-downtime claim with honest deploy behavior, correct 3-environment
promotion to actual 2-environment model. Update cross-references in
tutorial.md, deploy-prompt.md, README.md, AGENTS.md, and mkdocs.yml.

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

Author: baijum

AGENTS.md

@@ -11,7 +11,7 @@ docs/                  # All documentation (Markdown)
   index.md             # Landing page
   architecture.md      # Platform design, tech stack, diagrams
   spec.md              # Application contract (ports, endpoints, env vars)
-  deployment.md        # CI/CD pipeline, zero-downtime deploys, migrations
+  deployment.md        # CI/CD pipeline, deploy behavior, migrations
   self-hosting.md      # Fork model, server requirements, bootstrap
   preview-environments.md  # PR previews, DNS, cleanup
   ecosystem.md         # Org structure, app template, multi-app hosting

README.md

@@ -10,7 +10,8 @@ Full documentation is available at **[towlion.github.io/platform](https://towlio
 
 - [Architecture](https://towlion.github.io/platform/architecture/) — platform design, tech stack, diagrams
 - [App Specification](https://towlion.github.io/platform/spec/) — application contract (ports, endpoints, env vars)
-- [Deployment](https://towlion.github.io/platform/deployment/) — CI/CD pipeline, zero-downtime deploys, migrations
+- [Scope](https://towlion.github.io/platform/scope/) — design boundaries and when to use something else
+- [Deployment](https://towlion.github.io/platform/deployment/) — CI/CD pipeline, deploy behavior, migrations
 - [Self-Hosting](https://towlion.github.io/platform/self-hosting/) — fork model, server requirements, bootstrap
 - [Preview Environments](https://towlion.github.io/platform/preview-environments/) — PR previews, DNS, cleanup
 - [Ecosystem](https://towlion.github.io/platform/ecosystem/) — org structure, app template, multi-app hosting

docs/deploy-prompt.md

@@ -58,5 +58,5 @@ Important notes:
 ## See also
 
 - [Tutorial](tutorial.md) — step-by-step walkthrough with detailed commands
-- [Deployment](deployment.md) — pipeline internals and zero-downtime strategy
+- [Deployment](deployment.md) — pipeline internals and deploy behavior
 - [Self-Hosting](self-hosting.md) — fork model and infrastructure overview

docs/deployment.md

@@ -39,26 +39,27 @@ Deployment command:
 docker compose up -d --build
 ```
 
-## Zero-Downtime Deployments
+## Deploy Behavior
 
-The platform uses rolling updates to keep applications available during deployments.
+The platform rebuilds and restarts containers on each deploy. There is a brief gap where the application is unavailable.
 
 ```
-Current version (v1) running
+Stop current container
         │
         ▼
-Start new container (v2)
+Rebuild image from source
         │
-Health check passes
+        ▼
+Start new container
         │
         ▼
-Switch traffic to v2
+Health check passes
         │
         ▼
-Stop v1
+Caddy routes traffic
 ```
 
-Docker Compose starts the new container before removing the old one. The reverse proxy (Caddy) only forwards traffic to healthy services.
+During the rebuild and restart, Caddy returns 502 for requests to the application. This gap is typically a few seconds. For the target use case — small apps with low traffic — this is acceptable. See [Scope and Design Boundaries](scope.md) for when to consider alternatives.
 
 ### Docker Health Check Configuration
 
@@ -74,7 +75,7 @@ services:
       retries: 5
 ```
 
-If the health check fails, traffic stays on the previous version.
+If the health check fails, Docker will restart the container according to the `restart: always` policy.
 
 ## Database Migrations
 
@@ -131,26 +132,26 @@ curl https://app.example.com/health
 
 ## Environment Promotion
 
-The platform supports promotion through environments:
+The platform has two environments:
 
 ```
 Pull Request → Preview environment
-Merge to develop → Staging deployment
 Merge to main → Production deployment
 ```
 
 | Branch | Environment |
 |---|---|
 | PR branch | Preview |
-| `develop` | Staging |
 | `main` | Production |
 
+Preview environments are created automatically for pull requests and cleaned up when the PR is closed. See [Preview Environments](preview-environments.md) for details.
+
 ## Platform Capabilities Summary
 
 | Feature | Implementation |
 |---|---|
 | CI/CD | GitHub Actions |
-| Zero-downtime deploys | Rolling container updates |
+| Deploy pipeline | Rebuild and restart on push to main |
 | Database migrations | Alembic |
 | Preview environments | PR deployments |
 | Object storage | MinIO |

docs/index.md

@@ -20,6 +20,8 @@ GitHub repository → GitHub Actions → SSH deploy → server runtime
 
 Each repository contains everything required to deploy itself. Push code, and your application is live.
 
+See [Scope and Design Boundaries](scope.md) for what the platform does and does not do.
+
 ## Key Features
 
 - **GitHub-native deployment** — no custom CLI or dashboard needed

docs/scope.md

@@ -0,0 +1,62 @@
+# Scope and Design Boundaries
+
+## What Towlion Is
+
+- A **single-server micro-PaaS** for deploying small web applications
+- **GitHub as the control plane** — no custom dashboard, CLI, or API
+- **Docker Compose** for container orchestration, **Caddy** for reverse proxy and automatic TLS
+- **Fork-to-deploy** model — fork a template repo, configure secrets, push to deploy
+- **Opinionated stack** — FastAPI, PostgreSQL, Redis, MinIO, Celery
+
+## Design Boundaries
+
+These are intentional constraints, not missing features. They keep the platform simple and predictable.
+
+### Infrastructure
+
+| Boundary | Detail |
+|---|---|
+| Single server only | No clustering, no multi-server, no load balancing. Your server is a single point of failure by design. |
+| Debian Linux only | The bootstrap script targets Debian 12. Other distributions are untested. |
+| No automated server provisioning | You create and manage your own server. The bootstrap script configures it, but you are responsible for procurement and access. |
+| Fixed resource limits | Static CPU and memory limits per container. No auto-scaling. |
+
+### Deployment
+
+| Boundary | Detail |
+|---|---|
+| Brief downtime during deploys | `docker compose up -d --build` rebuilds and restarts containers. Caddy returns 502 during the gap. This is typically a few seconds. |
+| No built-in test pipeline | The deploy workflow builds and deploys. It does not run your test suite — add that step yourself if needed. |
+| Push-to-main deploys | No staging environment, no approval gates, no canary or blue-green deploys. Merging to `main` deploys to production. |
+
+### Operations
+
+| Boundary | Detail |
+|---|---|
+| No high availability | Single PostgreSQL, Redis, and MinIO instances. No replication or automatic failover. |
+| 5-minute alert granularity | Health checks run via cron every 5 minutes. This is not real-time monitoring. |
+| 7-day backup retention | Daily `pg_dump` with 7-day retention. Recovery is manual. There is no disaster recovery plan beyond these backups. |
+| No multi-tenant management | Each fork is independent. There is no shared admin panel or centralized management across apps. |
+
+### Technology
+
+| Boundary | Detail |
+|---|---|
+| Not Kubernetes | Docker Compose only. If you need pods, services, ingress controllers, or declarative infrastructure, use Kubernetes. |
+| Opinionated stack | FastAPI + PostgreSQL + Redis + MinIO + Caddy. Other frameworks and databases are outside the supported path. |
+| No container registry | Images are built on the server from source code. There is no registry push/pull step. |
+
+## When to Use Something Else
+
+| If you need... | Consider instead |
+|---|---|
+| Multi-server / high availability | Kubernetes, Docker Swarm, Nomad |
+| Auto-scaling | AWS ECS, Cloud Run, Fly.io |
+| Managed databases | AWS RDS, DigitalOcean Managed DB |
+| Zero-downtime deploys | Kubernetes rolling updates, blue-green deploy tooling |
+| Large-scale traffic | Cloud-native platforms with load balancers |
+| Non-Python backends | Dokku, Coolify, CapRover |
+
+## Sweet Spot
+
+Towlion is built for indie developers, small SaaS products, personal tools, hobby projects, and AI-generated applications. If your app serves a handful of users, runs comfortably on a single server, and you want to own your infrastructure without managing Kubernetes, Towlion is a good fit.

docs/tutorial.md

@@ -236,7 +236,7 @@ git commit -m "feat: add new feature"
 git push origin main
 ```
 
-GitHub Actions runs the deployment pipeline automatically. The platform uses [rolling updates](deployment.md#zero-downtime-deployments) so your application stays available during deploys.
+GitHub Actions runs the deployment pipeline automatically. Your application will be briefly unavailable during the rebuild (typically a few seconds).
 
 To pull upstream changes from the original repository:
 

mkdocs.yml

@@ -31,6 +31,7 @@ extra_css:
 
 nav:
   - Home: index.md
+  - Scope: scope.md
   - Tutorial: tutorial.md
   - Architecture: architecture.md
   - App Specification: spec.md