Rename Railway compose to template-base import artifact

Author: pRizz

README.md

@@ -84,6 +84,7 @@ Credentials: `docs/deploy/aws.md#retrieving-credentials`
 One-click deploy provisions a Railway service with automatic HTTPS.
 
 > **Important:** Attach a Railway Volume mounted to `/home/opencoder/.local/share/opencode` to prevent data loss across redeploys.
+> For manual template import, use `docker-compose.railway-template-base.yml` as a Railway importer compatibility base (not as the canonical runtime compose).
 
 Docs: `docs/deploy/railway.md`
 

docker-compose.railway.yml docker-compose.railway-template-base.ymldocker-compose.railway.yml renamed to docker-compose.railway-template-base.yml

@@ -1,8 +1,13 @@
-# opencode-cloud Railway Compose Template
+# opencode-cloud Railway template-base compose
 #
-# Use this file for Railway template import workflows.
-# The canonical docker-compose.yml remains local/quick-deploy focused and
-# includes six volumes that Railway template import does not support.
+# Import this file into Railway only as a base for template workflows.
+# The canonical runtime compose for local/quick-deploy remains
+# docker-compose.yml.
+#
+# Intentional Railway importer compatibility constraints:
+# - single persisted volume only
+# - fixed image string (no env interpolation in "image")
+# - import-focused subset of compose keys; runtime knobs kept where supported
 
 services:
   opencode:

docs/deploy/railway.md

@@ -21,23 +21,32 @@ Steps:
 > **Important:** After deploying, verify that a Railway Volume is attached.
 > Without a volume, all data is lost on every redeploy.
 
-## Template from Compose File (Manual Upload)
+## Template Base Compose for Railway Import (Manual Upload)
 
 If you are creating a Railway template by importing a Compose file, use
-`docker-compose.railway.yml` from this repository.
+`docker-compose.railway-template-base.yml` from this repository.
 
 Do **not** import the root `docker-compose.yml` for Railway templates. That
 file is local/quick-deploy oriented and declares six volumes.
 
 ```bash
-curl -O https://raw.githubusercontent.com/pRizz/opencode-cloud/main/docker-compose.railway.yml
+curl -O https://raw.githubusercontent.com/pRizz/opencode-cloud/main/docker-compose.railway-template-base.yml
 ```
 
-Railway template import supports one volume per service. The Railway-specific
-compose file keeps a single persisted mount at
-`/home/opencoder/.local/share/opencode` for compatibility.
-It keeps variable-driven runtime/logging knobs where Railway supports them and
-uses a fixed image reference to avoid Railway parser issues.
+This file is intentionally a **template-base import artifact**, not a full
+runtime compose parity file.
+
+Railway template import currently supports one volume per service and does not
+support all compose features uniformly. The template-base file intentionally
+keeps:
+- one persisted mount at `/home/opencoder/.local/share/opencode`
+- a fixed image reference (no env interpolation in `image`)
+- an import-focused subset of compose keys, with runtime knobs kept where
+  Railway supports them
+
+After import, apply any additional Railway-specific runtime configuration in
+Railway settings/template editor.
+
 ## Manual Deployment
 
 ### Prerequisites
@@ -223,6 +232,11 @@ To create or update the Railway one-click deploy template:
 7. **Create** and **Publish** the template
 8. Copy the template URL and update the deploy button in `README.md`
 
+Maintenance rule:
+- When image references or required Railway env keys change, update both
+  `docker-compose.yml` and `docker-compose.railway-template-base.yml` in the
+  same PR.
+
 The deploy button format:
 
 ```markdown