diff --git a/docs/design/railway-preview-clone-spike/findings.md b/docs/design/railway-preview-clone-spike/findings.md
new file mode 100644
index 0000000000..3796370db1
--- /dev/null
+++ b/docs/design/railway-preview-clone-spike/findings.md
@@ -0,0 +1,336 @@
+# Findings: Railway clone-based preview spike (issue #5650)
+
+Status date: 2026-08-02. Schema facts below were verified against the real API
+via **unauthenticated introspection** (confirmed working: schema queries
+against `https://backboard.railway.com/graphql/v2` succeed with no
+`Authorization` header). Live-run rows are updated as phases execute.
+
+## Open questions from issue #5650
+
+| # | Question | Status | Answered by |
+|---|----------|--------|-------------|
+| Q1 | `environmentCreate` 504 behavior at 13-service scale: does the clone complete in the background, and does poll-by-name recover it reliably? | **answered live (2026-08-02): no 504 across 25+ clones** — every `environmentCreate` returned synchronously in 3-4s (`clone_s` column across both 10-cycle series). The poll-by-name fallback stays as unexercised insurance. | `results/cycle-log.csv`, both 10-cycle runs. |
+| Q2 | Clone fidelity: reference variables. Do `${{gateway.RAILWAY_PUBLIC_DOMAIN}}`, `${{Postgres.POSTGRES_PASSWORD}}` etc. stay references (re-resolving inside the clone) rather than freezing to template values? | **answered live (2026-08-02): yes, references re-resolve per clone.** Alembic connected to the CLONE's Postgres through `${{Postgres.*}}` references; the full smoke passed through the clone's own regenerated gateway domain. | Kept clone: migrations + 200 on all three smoke paths. |
+| Q3 | Clone fidelity: volumes (recreated empty and attached?) and service domains (expected NOT copied). | **answered live (2026-08-02): both better than expected.** Volumes: recreated empty and attached — clone Postgres booted on its own volume and alembic created all three databases from scratch. Domains: Railway REGENERATED a service domain for the gateway in the clone automatically (`gateway-<env-name>.up.railway.app`), so no `serviceDomainCreate` is needed (the script keeps it as a fallback). | Observed in the kept clone `pr-clone-c1-1785674907`. |
+| Q4 | Clone fidelity: private networking. Does `*.railway.internal` resolve per-environment inside the clone? | **answered live (2026-08-02): yes.** `/w`, `/api/health`, `/services/health` all returned 200 through the clone's gateway (nginx -> web/api/services over `*.railway.internal`), and api reached Postgres/redis/supertokens internally. | Kept clone smoke, 2026-08-02. |
+| Q5 | Can template services stay permanently undeployed while still cloning into deployable environments? | **answered live (2026-08-02): yes.** The 16:23+ cycles cloned from a template whose services showed `latestDeployment: NONE` (the earlier CLI-triggered deployments had been removed), and every clone deployed green. Template deployments are irrelevant to clones in both directions (stale ones don't leak, missing ones don't block). | Both 10-cycle series in `results/cycle-log.csv`. |
+| Q6 | CI auth: does the shared `secrets.RAILWAY_TOKEN` (account token) work from GitHub Actions for `me`, clone, delete — and what rate-limit tier do the headers report? | pending live run | Runbook phase 4: `spike/ci-auth-check.yml`. |
+| Q7 | Does `serviceInstanceUpdate` apply immediately, or does it only STAGE a change (staged-changes mutations exist in the schema: `environmentStageChanges`, `environmentPatchCommit*`, `environmentApplyChangeSet`) that a deploy would ignore? | **answered live (2026-08-02): applies immediately.** No `unmergedChangesCount` warning fired, and the clone deployment's `meta.serviceManifest` carried the patched `image`, the fixup `startCommand`, and the `ON_FAILURE`/10 restart policy verbatim. | Verified via `deployment(id).meta` of a clone deployment. |
+| Q8 | API calls per cycle: can a cycle fit in <=15 calls? | **answered live (2026-08-02): yes on mutations (8), 16 on total HTTP calls incl. polling.** The low-call mechanism is `environmentPatchCommit` (NOT `environmentTriggersDeploy`, which is per-service — see the deploy-mode section). Full verdict in the Results section. | Patch-mode rows in `results/cycle-log.csv`; Results section below. |
+| Q9 | Deployment status semantics for a one-shot service (alembic runs migrations and exits): does `latestDeployment.status` settle on `SUCCESS`, or `SLEEPING`/`REMOVED`? | **answered live (2026-08-02): stays `SUCCESS`.** With `restartPolicyType: ON_FAILURE` the exit-0 container is not restarted and the deployment keeps reporting SUCCESS. | Kept clone, alembic after migrations completed. |
+| Q10 | Is `startCommand` executed through a shell (needed for the alembic inline `psql` command)? | **answered live (2026-08-02): NO.** Railway tokenizes the string (quote-aware) and execs it argv-style. A bare `until ...` start command fails within seconds as FAILED with EMPTY build and deploy logs (the misleading signature that cost cycle 1). Wrapping in `sh -c '<script>'` works — the wrapped alembic ran all migrations to completion. Fixed in `build-template-env.sh`. | Kept clone: alembic FAILED bare, SUCCESS wrapped. |
+| Q11 | Do upload-built sources (`railway up`, used by the no-registry fallback for gateway/redis/seaweedfs) survive cloning — i.e. can a clone deploy them without a new upload? | **answered live (2026-08-02): NO, with a trap.** Gateway (pure upload source): `serviceInstanceDeployV2` in the clone fails with `"Deployment not found"` — the upload artifact is not part of the cloneable config. Redis/seaweedfs (created with `--image` then upped): the clone silently deploys the PLAIN base image (`redis:8`, `chrislusf/seaweedfs:4.37`) because `source.image` still points there — the wrapper entrypoints are LOST, resurfacing failure-history items 14 and 17. **Conclusion: the design requires real registry images for gateway/redis/seaweedfs (runbook phase 0.2). The `railway up` fallback only validates the rest of the flow.** A per-clone `railway up gateway` (+1 upload/cycle) is a workable interim. | Kept clone: gateway deployV2 error; redis/seaweedfs source.image inspection. |
+| Q12 | Deploy ordering: which services must wait for alembic? | **answered live (2026-08-02): supertokens.** Deployed alongside infra it exhausts its restarts and ends CRASHED because the `agenta_oss_supertokens` database does not exist until alembic runs. Order fixed in `preview-cycle.sh`: Postgres/redis/seaweedfs -> alembic -> supertokens + apps. A redeploy after alembic succeeds. | Kept clone: supertokens CRASHED pre-alembic, SUCCESS after. |
+
+## Statically verified vs assumed
+
+### Verified 2026-08-02 by unauthenticated introspection
+
+- Introspection itself requires no auth (claimed in
+  `research/railway-capabilities.md`; now confirmed empirically).
+- `environmentCreate(input: EnvironmentCreateInput!): Environment!`; input
+  fields exactly: `projectId!`, `name!`, `sourceEnvironmentId`,
+  `skipInitialDeploys`, `ephemeral`, `stageInitialChanges`,
+  `applyChangesInBackground`.
+- `environmentDelete(id: String!): Boolean!` (bare `id`, not an input object).
+- `serviceInstanceUpdate(serviceId: String!, environmentId: String, input:
+  ServiceInstanceUpdateInput!): Boolean!`; input includes `source`
+  (`ServiceSourceInput` = `{image, repo}`), `startCommand`, `healthcheckPath`,
+  `restartPolicyType`, `restartPolicyMaxRetries`, `preDeployCommand`,
+  `numReplicas`, `registryCredentials`, `sleepApplication`, `cronSchedule`.
+- `serviceInstanceDeployV2(environmentId: String!, serviceId: String!,
+  commitSha: String): String!` (returns a deployment id).
+- `serviceInstanceRedeploy(environmentId!, serviceId!)` exists (redeploys the
+  CURRENT deployment — not useful for first deploys of a skipped clone).
+- `environmentTriggersDeploy(input: {projectId, environmentId, serviceId})`
+  exists — candidate single-call deploy for a whole environment (semantics
+  unverified; `serviceId` presumably optional).
+- `environments(projectId: String!, first, isEphemeral, ...)` connection — the
+  poll-by-name path. `Environment` exposes `serviceInstances`,
+  `volumeInstances`, `sourceEnvironment`, `unmergedChangesCount`, `configEtag`.
+- `ServiceInstance` exposes `serviceId`, `serviceName`, `source {image repo}`,
+  `latestDeployment {status}`, `domains` (`AllDomains` = `{serviceDomains,
+  customDomains}`), `startCommand`, `healthcheckPath`.
+- `DeploymentStatus` enum: `BUILDING CRASHED DEPLOYING FAILED INITIALIZING
+  NEEDS_APPROVAL QUEUED REMOVED REMOVING SKIPPED SLEEPING SUCCESS WAITING`.
+- `variableCollectionUpsert(input: {projectId, environmentId, serviceId,
+  replace, skipDeploys, variables})` — matches configure.sh's production use.
+- `serviceDomainCreate(input: {environmentId, serviceId, targetPort}):
+  ServiceDomain` (`targetPort` optional; spike passes 8080, the gateway nginx
+  listen port).
+- `projectCreate(input: {name, defaultEnvironmentName, workspaceId, ...})`,
+  `projectDelete(id: String!)` (used for teardown).
+- Staged-changes mutations exist (basis for Q7).
+- Unauthenticated introspection responses carried NO `X-RateLimit-*` or
+  `Retry-After` headers; presumably only on authenticated calls (Q6 prints
+  them from CI).
+
+### Assumed (recorded, not invented silently)
+
+- ~~`startCommand` runs through a shell~~ — RESOLVED live: it does NOT (Q10).
+- ~~One-shot deployment status semantics~~ — RESOLVED live: stays SUCCESS (Q9).
+- ~~Environment duplication copies service config~~ — RESOLVED live: start
+  command, restart policy, image, variables (incl. references), volumes and
+  even the gateway service domain all carried over (Q2/Q3/Q7).
+- ~~`environmentTriggersDeploy` deploys every service when `serviceId` is
+  omitted (Q8's low-call path)~~ — DISPROVEN live (2026-08-02): introspection
+  shows `EnvironmentTriggersDeployInput.serviceId` is NON_NULL (the call is
+  per-service, tied to deploy triggers), and omitting it returns HTTP 400
+  "Problem processing request". There is NO single-call whole-environment
+  deploy. The real low-call path is `environmentPatchCommit` (see the live run
+  log): ONE mutation carries an `EnvironmentConfig` patch covering all 8 app
+  images AND deploys each service whose config actually changed.
+- `psql` remains available in the api image (verified today in
+  `api/oss/docker/Dockerfile.gh`: `postgresql-client-17`; re-check if that
+  Dockerfile changes).
+
+## Per-cycle API call ledger (static)
+
+Mutations, per-service deploy mode: 1 `environmentCreate` + 8
+`serviceInstanceUpdate` + 13 `serviceInstanceDeployV2` + <=1
+`serviceDomainCreate` + 1 `environmentDelete` = **24**. Plus reads: 1-2 id
+resolutions (amortized across cycles), 1 populate check, ~1 read per 15s of
+deploy wait. Realistic total: **~35-60/cycle**, dominated by status polling.
+
+Mutations, triggers mode: 1 create + 8 patches + 1 `environmentTriggersDeploy`
++ <=1 domain + 1 delete = **12**, meeting the <=15 criterion if polling reads
+are excluded (record both numbers in the spike report; reads and writes share
+the hourly budget).
+
+Further reduction candidates (not implemented):
+
+- If `source.image` accepts a reference variable (e.g.
+  `ghcr.io/agenta-ai/agenta-api:${{shared.IMAGE_TAG}}`), the 8 patch calls
+  collapse into one shared-variable upsert baked into the template. Worth one
+  manual dashboard experiment during phase 2.
+- `skipInitialDeploys: false` would drop the 13 deploy calls but deploys the
+  template's `:latest` images first, forcing 8 patch+redeploys anyway and
+  doubling build/start load — rejected.
+
+## How this addresses the failure history
+
+- Failures 1/2 (slow per-key variable writes): clones copy variables; zero
+  variable writes per PR.
+- Failures 5/6/7/8 (non-idempotent creates, read lag, list/link divergence):
+  the per-PR path creates exactly one resource (the environment) with a
+  name-poll reconcile; services/volumes/config come from the clone.
+- Failure 3 (rate limits): ~24 mutations vs ~58+ calls today, one project
+  instead of one per PR.
+- Failure 20 (wrapper drift): wrapper ENV/CMD now live once in the template
+  (build-template-env.sh fixups), not re-rendered per deploy. Residual risk:
+  the template itself drifts from compose — a template rebuild must become
+  part of changing the compose baseline if this design ships.
+
+## Live run log
+
+### 2026-08-02 — phase 1 (template build) — SUCCESS
+
+- Auth: account token verified through `lib-graphql.sh` (`me` query). Response
+  headers show the token is on the **Hobby tier: `x-ratelimit-limit: 1000`**
+  requests/hour (answers the header half of Q6 for local runs; CI still
+  pending).
+- **New live finding (fixed in the scripts): `projects` without arguments
+  returns an EMPTY list for account tokens.** Project lookup must be scoped
+  with `workspaceId`, iterating the workspaces from `me { workspaces { id } }`
+  (`rw_find_project_id` in `lib-graphql.sh`). The workspace also contains all
+  the per-PR preview projects, some with duplicate names — first match wins.
+- `bootstrap.sh` + `configure.sh` + GraphQL fixups all succeeded against the
+  throwaway project (fixups: 16 mutations + 3 resolution reads = 19 calls).
+- **Q5 amendment: a CLI-bootstrapped template does NOT stay undeployed.**
+  `railway add --service --image` triggers an initial deploy, so all 13
+  template services had deployments before the fixups ran. Consequences:
+  (a) the running template costs money continuously — if the design ships,
+  either stop/sleep the template services or accept the cost;
+  (b) the template's Postgres first deploy CRASHED because it started before
+  `configure.sh` set `POSTGRES_PASSWORD` (the official image refuses to boot
+  without it). Stale deployments do not affect clones — clones copy config,
+  not deployments — verified by the phase 2 cycle below.
+- The no-registry fallback (`railway up` one-time builds for
+  gateway/redis/seaweedfs) uploaded and built server-side. Observation for
+  Q11: while building, redis/seaweedfs still REPORT `source.image` as their
+  base image (`redis:8`, `chrislusf/seaweedfs:4.37`) and gateway reports a
+  null image (upload source) — what a clone inherits is answered in phase 2.
+
+### 2026-08-02 — phase 2 (preview cycles) — smoke GREEN after two fix rounds
+
+- Cycle 1 (scripted, auto-delete): clone 4s (no 504), 8 image patches applied
+  (verified in the clone deployment's `serviceManifest`), infra deployed, then
+  alembic FAILED in seconds with EMPTY build+deploy logs. Auto-delete
+  destroyed the evidence — diagnostics were added to the script
+  (`dump_failed_service_logs`) and later runs used `--keep`.
+- Cycle 2 (`--keep`): same failure, root causes found and fixed live:
+  1. Q10 — `startCommand` is execed, not shell-wrapped. Bare `until ...`
+     fails instantly, no logs. Fix: `sh -c '<script>'` (applied to the
+     template and to `build-template-env.sh`).
+  2. Q12 — supertokens deployed alongside infra CRASHED (its database only
+     exists after alembic). Fix: deploy order Postgres/redis/seaweedfs ->
+     alembic -> supertokens + apps (applied to `preview-cycle.sh`).
+  3. Q11 — gateway (upload source) cannot deploy in a clone
+     (`Deployment not found`); worked around with a per-clone
+     `railway up gateway`. redis/seaweedfs silently deployed their PLAIN base
+     images.
+- After the fixes, the kept clone reached ALL 13 services SUCCESS and the full
+  smoke passed: `/w`, `/api/health`, `/services/health` all 200 via the
+  clone's own regenerated gateway domain. The clone env was then deleted via
+  `environmentDelete` (clean).
+- Cost observation: the two scripted cycle attempts consumed 22-24 API calls
+  each up to the failure point; the whole live session (template build +
+  fixups + 2 cycles + debugging + manual completion) fit comfortably inside
+  the Hobby 1,000/hour budget.
+- Wall-time observation: clone + patch = ~7s; infra deploys reached SUCCESS in
+  well under a minute; the un-timed manual completion (supertokens + 8 app
+  deploys + gateway upload build) took a few minutes end to end. A clean
+  scripted cycle time comes from re-running phase 3 after the template gets
+  real wrapper images.
+
+### 2026-08-02 — wrapper images built; GHCR push BLOCKED on token scope
+
+- The three wrapper images now exist as real, self-contained build contexts in
+  `spike/images/{gateway,redis,seaweedfs}/` (byte-faithful to what
+  `deploy-from-images.sh` renders; provenance and the one deliberate
+  divergence — the redis base pin — documented at the top of each Dockerfile).
+  All three build clean for linux/amd64 and contain NO secrets (nginx.conf
+  routes internal hostnames only; both entrypoints read credentials from env at
+  runtime), so publishing them as public GHCR packages is safe once a push
+  succeeds.
+- **Push blocked at first: no `write:packages` credential existed.** The `gh`
+  OAuth token initially carried only read scopes; pushes to BOTH
+  `ghcr.io/agenta-ai/*` and the user namespace failed with
+  `denied: permission_denied: The token provided does not match expected scopes`.
+  **RESOLVED later the same day**: Mahmoud ran `gh auth refresh -s
+  write:packages` interactively, and all three images pushed to
+  `ghcr.io/agenta-ai/agenta-preview-{gateway,redis,seaweedfs}:spike`
+  (digests `sha256:62fc66b9…` gateway, `sha256:513f5420…` redis,
+  `sha256:bd1353af…` seaweedfs; image IDs match the locally audited builds).
+- **Visibility flip still pending — GitHub-UI-only.** New GHCR packages
+  default to PRIVATE and there is NO REST or GraphQL API to change package
+  visibility (`PATCH orgs/.../packages/...` returns 404; the docs describe
+  only the web UI "Danger Zone -> Change visibility" flow). Anonymous
+  manifest pulls return 401/403 while private, so Railway cannot pull them
+  yet. Once an org admin flips the three packages public,
+  `spike/switch-template-to-ghcr-images.sh` (pull-gated: it refuses to touch
+  the template while any package is private) switches the template to the
+  images and clears the startCommand overrides; run one patch-mode cycle to
+  certify the registry-backed path.
+- Consequence for the cycle tests: one interim cycle ran with
+  `preview-cycle.sh --gateway-up-interim` (uploads `spike/images/gateway` into
+  the clone via `railway up`; pass, 80s, "+cli-up" in the CSV) — and was then
+  SUPERSEDED the same day by the registry-free startCommand wrappers (next
+  section), which restore all three wrapper behaviors without any registry or
+  per-clone upload. ttl.sh was probed as an anonymous ephemeral registry and
+  ruled out: blob uploads stall from this network.
+
+### 2026-08-02 — registry-free wrappers via startCommand; templates fully image-backed
+
+With the GHCR push blocked and ttl.sh uploads stalling from this network
+(`POST /v2/.../blobs/uploads/` times out while `GET /v2/` returns 200), a
+third mechanism made the template registry-free: **Railway's start command
+"overrides the image's ENTRYPOINT in exec form"**
+(docs.railway.com/guides/start-command; consistent with Q10's exec-not-shell
+finding). `spike/apply-wrapper-startcommands.sh` therefore reshapes the three
+special services onto PUBLIC base images with the wrapper behavior in
+startCommand:
+
+- redis -> `redis:8` + `sh -c 'mkdir -p /data; chown -R redis:redis /data;
+  exec docker-entrypoint.sh redis-server'` (item 14 protection preserved).
+- seaweedfs -> `chrislusf/seaweedfs:4.37` + the EXACT wrapper entrypoint
+  (`spike/images/seaweedfs/entrypoint.sh`) shipped base64-inline and exec'd
+  (item 17 IAM protection preserved, byte-faithful).
+- gateway -> `nginx:1.27-alpine` + the EXACT `spike/images/gateway/nginx.conf`
+  shipped base64-inline + the wrapper's envsubst+nginx command; the wrapper
+  image's `ENV PORT=8080` became a gateway service variable.
+
+Railway accepted startCommands up to 3372 chars. All three deployed SUCCESS in
+the template in ~20s; deploy logs confirm real behavior (redis "Ready to
+accept connections"; seaweedfs runs `weed server` with filer+master, i.e. our
+entrypoint, not the base image's `mini` default). Every template service is
+now image-backed, so clones deploy with pure GraphQL — no per-clone
+`railway up`, no registry, no wrapper images required. Two caveats recorded:
+(a) if Railway ever switches startCommand to append-as-CMD semantics, the
+seaweedfs base entrypoint would break it (its default case is
+`exec /usr/bin/weed $@`, and it su-execs to the `seaweed` user first);
+(b) the wrapper images in `spike/images/` remain the intended production
+shape — the startCommand variant trades image immutability for registry
+independence, and the two must be kept in sync by rebuilding both from the
+same `hosting/railway/oss/` sources.
+
+### 2026-08-02 — deploy-mode findings: triggers disproven, patch mode wins
+
+- **Triggers mode is a dead end** (see the schema note above): the cycle run
+  recorded `fail` in 8s with HTTP 400. CSV row kept for honesty.
+- **`environmentPatchCommit` deploys exactly the services whose config
+  CHANGED.** First patch-mode run with `--image-tag latest` timed out: the
+  patch equaled the template config (template apps already point at
+  `:latest`), the commit was a silent no-op, and all 8 app services stayed
+  `latestDeployment: NONE`. With a real PR tag (`pr-5651-a46168f`, present for
+  all four app images) the same flow went green. Consequence for the design:
+  the template must pin app images to a tag a PR can never reuse (`:latest`
+  works only if PR tags are always `pr-<n>-<sha>`), and a `:latest` smoke test
+  of the cycle must use per-service mode.
+- Patch-mode per-cycle ledger (measured): 8 mutations (create + 3 infra
+  deploys + 1 patchCommit + supertokens + gateway + delete) and **16 TOTAL
+  API calls including polling**, at ~55s per cycle. The <=15-mutation
+  criterion is met with headroom; even total calls sit at the line.
+- The 7 non-alembic app services deploy in parallel with alembic after
+  Postgres is up and none of them terminally crashed while migrations ran
+  (10+ live cycles of evidence, all smoke-green).
+
+## Results: the 10-cycle runs vs the issue #5650 success criteria
+
+All rows in `spike/results/cycle-log.csv` (cycle numbers restart per script
+invocation — runs were chunked; `start_iso`/`env_name` order the sequence).
+Two full evidence series ran on 2026-08-02:
+
+- **Per-service mode, `--image-tag latest`: 10/10 consecutive green**
+  (16:26-16:37 UTC, strictly unbroken), 62-80s per cycle, 32-33 total API
+  calls per cycle (23 of them mutations).
+- **Patch mode, `--image-tag pr-5651-a46168f`: 10 consecutive green rows**
+  (16:53-17:23 UTC), 55-72s per cycle, 16 total API calls per cycle (8 of
+  them mutations). Honesty note: between the 8th and 9th green row one cycle
+  attempt was ABORTED mid-run (no CSV row): the hourly rate budget — spent by
+  the day's debugging, not by the cycles — ran out and the operator stopped
+  the run rather than let 429-retry exhaustion record a bogus failure; its
+  clone was deleted, and the run resumed after the 17:22 UTC window reset.
+  No cycle ever failed for a design reason in either series.
+
+| # | Criterion (issue #5650) | Verdict |
+|---|--------------------------|---------|
+| 1 | 10 consecutive green clone→patch→deploy→smoke→delete cycles | **MET** — per-service 10/10 strictly unbroken; patch mode 10 green rows with the aborted-attempt note above. |
+| 2 | ≤ 15 Railway API calls per cycle | **MET on mutations, 1 over on total calls.** Patch mode: 8 mutations (create + 3 infra deploys + 1 patchCommit + supertokens + gateway + delete). Total HTTP requests incl. polling = 16: the 8 mutations + 8 reads (populate check, domain check, ~5 status polls at 15s, post-patch refresh). Merging the populate and domain reads or widening `RW_POLL_INTERVAL` brings the total to ≤15; mutations are the scarce/priced dimension and sit at nearly half the target. |
+| 3 | Wall time ≤ today's setup+deploy | **MET with ~3x headroom.** Baseline measured live from the last successful `14-check-pr-preview.yml` deploy (run 30753555499, 2026-08-02): setup 38s + deploy 2m18s = **~176s**, excluding image builds. Patch-mode cycles complete clone→patch→deploy→smoke in ~51-55s (55-57s including the delete). |
+
+Winning mode: **patch** (`--deploy-mode patch`) with a PR-style tag. Triggers
+mode is disproven; per-service mode remains the fallback (and the only mode
+that works when the tested tag equals the template's, e.g. `:latest` smokes).
+
+### Remaining / open
+
+1. ~~Push `spike/images/*` to GHCR~~ — DONE 2026-08-02 (`:spike` tags, see the
+   push section). Remaining: an org admin flips the three packages PUBLIC in
+   the GitHub UI (no API exists), then
+   `spike/switch-template-to-ghcr-images.sh --deploy` + one patch-mode cycle
+   certifies the registry-backed path. Canonical shape = the GHCR images; the
+   startCommand variant (Option B, currently live in the template) stays as
+   the registry-free fallback.
+2. Run the CI auth check (runbook phase 4) — still pending.
+3. Sequencing note for a real rollout: keep the template's app-image tags
+   disjoint from PR tags so `environmentPatchCommit` never no-ops (see above).
+
+## Addendum 2026-08-02 (spike close-out): registry-backed validation
+
+- The three wrapper packages were made public in the GitHub UI and the template was
+  switched to them with `spike/switch-template-to-ghcr-images.sh --deploy`. All
+  three services deployed SUCCESS on the images' own entrypoints.
+- API finding: `serviceInstanceUpdate` with `startCommand: null` is a no-op (patch
+  semantics treat null as "no change"); setting `startCommand: ""` clears the
+  override. The switch script's warning caught this live; the empty-string clear is
+  the documented workaround.
+- Final proof cycle, fully registry-backed (GHCR images, no startCommand
+  overrides, zero `railway up`): **pass, 57s, 15 API calls** with tag
+  `pr-5651-a46168f`. This is the production-shaped path and lands under the ≤15
+  calls criterion.
+- One transient failure preceded it: the clone's Postgres deploy timed out at 420s
+  immediately after the template's infra services had been freshly redeployed.
+  The retry passed. Production rule: allow generous first-deploy timeouts for
+  volume-backed services in a fresh clone, and treat a single Postgres timeout as
+  retryable.
diff --git a/docs/design/railway-preview-clone-spike/research/failure-history.md b/docs/design/railway-preview-clone-spike/research/failure-history.md
new file mode 100644
index 0000000000..4734e2e247
--- /dev/null
+++ b/docs/design/railway-preview-clone-spike/research/failure-history.md
@@ -0,0 +1,124 @@
+# Railway preview pipeline: how it works and how it has failed
+
+Compiled 2026-08-02 from the workflows, scripts, and git history. This is the evidence
+base for the clone-based redesign.
+
+## Per-PR lifecycle today
+
+Entry point: `.github/workflows/14-check-pr-preview.yml` triggers on PR
+open/synchronize/reopen/ready-for-review touching `api/**`, `web/**`, `services/**`,
+`sdks/python/**`, or `hosting/railway/**`, with per-PR cancel-in-progress concurrency.
+Chain: build (42) → setup (41) → deploy (43) → tests (44). Cleanup (45) runs on PR
+close/draft-convert and a daily 06:00 UTC cron.
+
+1. Build (42): 4 images (api/web/services/runner) x 2 arches, pushed to GHCR as
+   `pr-<N>-<sha>-<arch>`, manifests merged. No Railway calls.
+2. Setup (41) runs `bootstrap.sh` with the single shared `secrets.RAILWAY_TOKEN`
+   (account-scoped, exported as `RAILWAY_API_TOKEN`). Each PR gets a dedicated Railway
+   project `agenta-oss-pr-<N>`, environment `production` (`preview-resolve-env.sh`).
+3. `bootstrap.sh`: project list/init/link (with link-failure → re-init fallback), env
+   create, 13 `railway add --service` calls, `verify_services_exist` (status --json,
+   up to 3 re-attempt rounds), 3 volumes via check-then-add retry loops, gateway
+   domain. Roughly 25-35 CLI calls.
+4. Deploy (43) runs `deploy-from-images.sh`: 2s post-bootstrap sleep (rate limit),
+   then `configure.sh`.
+5. `configure.sh`: variables for all 13 services, preferably one GraphQL
+   `variableCollectionUpsert` per service (~15-17 mutations) against
+   backboard.railway.com, CLI fallback. Previews set `CONFIGURE_SKIP_UNSETS=true`,
+   skipping ~73 `variable delete` calls. Plus link, status, 2 variable-list reads,
+   domain, 4 `environment edit` healthcheck mutations. README claims ~58 API calls
+   per deploy.
+6. `deploy-from-images.sh` continues: Postgres redeploy (tolerating "No deployment
+   found"), redis + seaweedfs `railway up` wrappers, 20s settle, alembic `up` with up
+   to 5 attempts (each failure = Postgres redeploy + settle), then 7 more `railway up`
+   calls (api, worker-streams, worker-queues, runner, services, cron, web), gateway
+   up, `smoke.sh`. Each `up` uploads a locally generated wrapper Dockerfile (FROM the
+   GHCR image) and triggers a server-side build. ~13-17 more mutations.
+7. `smoke.sh`: poll gateway domain, curl `/w`, `/api/health`, `/services/health`
+   (300s each).
+8. Tests (44): readiness polling, Playwright auth bootstrap, API/SDK/services/web
+   matrices. Read-only vs Railway.
+
+Totals per full run: ~55-75 CLI mutations + ~17 GraphQL upserts, one shared token.
+Per PR the account accrues 1 project, 1 env, 13 services, 3 volumes, 1 domain,
+O(100) variables. Every push re-runs the chain against the same project;
+cancel-in-progress can kill a run mid-mutation; the daily cron deletes previews idle
+>24h, so a quiet-but-open PR is rebuilt from scratch on its next push. "Re-run failed
+jobs" skips a green setup job, so bootstrap never repairs a half-created environment.
+
+## Failure catalog (symptom | root cause | mitigation | evidence)
+
+1. Deploys failed ~96% of the time | `variable set` timed out ~20% per call, ~15
+   calls/deploy, no retry (0.8^15) | context-aware retry in `railway_call` | 060441a840.
+2. Still-slow variable writes | CLI fans out one expensive `variableUpsert` per key |
+   one `variableCollectionUpsert` GraphQL mutation per service | 71c9492846.
+3. Deploy aborted on 429s | shared account token, hourly rate limit, ~58+ calls/deploy,
+   concurrent PRs share the budget | backoff retries, `CONFIGURE_SKIP_UNSETS`, sleeps |
+   c77ffd53bb; hosting/railway/oss/README.md rate-limit section.
+4. "Unauthorized" on every account-level call | account token aliased into
+   `RAILWAY_TOKEN`, which the CLI treats as project-scoped | removed the alias |
+   892513093c, 06c2b970af (#4392).
+5. Green setup, every later deploy fails "Service 'X' not found" forever | transient
+   `railway add` failure silently swallowed; no reconcile; re-run skips green setup |
+   `verify_services_exist` + configure's "Re-run all jobs" guidance | 24b82bc09a,
+   81a9a5c0c4 (#5566).
+6. "You are creating volumes too quickly" / duplicate volume breaks deploys |
+   separate volume throttle with non-standard error text; `volume add` non-idempotent |
+   `ensure_volume` check-before-add, 3 attempts, 15s delay | 81a9a5c0c4.
+7. "Service 'cron' not found" seconds after creation | status/read APIs lag writes |
+   `_service_id_with_retry` (6 x 5s) + CLI retry on "not found" | b46eb2a135 (#5322).
+8. `Project not found in workspace` after draft→ready cycle | `project list`
+   (cross-workspace, lags deletions) disagrees with `link` | link failure → re-init |
+   4d303c1088 (#4589).
+9. Redeploy hit wrong service / failed on fresh envs | implicit linking; fresh
+   Postgres has no deployment | explicit `--service --environment`, tolerate "No
+   deployment found" | 492a8b4e1a → de228efb8b → d63a4a2b2f.
+10. Readiness poll hung for hours | curl without timeouts | `--max-time`/
+    `--connect-timeout` + job timeout | b0b48f1152.
+11. ~6h hang in test jobs | Playwright zip extraction deadlock on Node 24 | browser
+    cache + bounded retries | comments in 44-railway-tests.yml.
+12. Gateway 504s after any redeploy | nginx resolves `*.railway.internal` once at
+    startup; internal IPs change per deploy | resolver `[fd12::10] valid=5s` +
+    variable-based proxy_pass | README.
+13. Auth session refresh failures | proxy header buffers too small for auth cookies |
+    enlarged nginx buffers | d7c09e3f94.
+14. Redis MISCONF / lost persistence | Railway non-root UID vs official redis
+    entrypoint privilege drop | 4-commit saga: volume, `RAILWAY_RUN_UID=0`,
+    entrypoint wrapper both paths | 7880842361, 32085d8bba, 22b8dde6b4, 8cb583f8b7.
+15. First alembic run fails on fresh envs | Postgres not ready | redeploy + 5
+    bounded retries | deploy-from-images.sh.
+16. Whole chain produced zero jobs silently | duplicate YAML key made workflow 43
+    invalid; Actions failed silently | 0e92a44b26.
+17. Mounts/STS broken | bare SeaweedFS image lacks advanced IAM; non-4.37 releases
+    regressed | IAM entrypoint wrapper + 4.37 pin | a6778e5dbb.
+18. Runner unreachable + store creds rotating per deploy | runner not on private
+    network; creds regenerated per run | runner fix + reuse durable creds from the
+    API service | 894c23b4db (#5485).
+19. Throttling misreported as bad token | rate-limited `whoami` classified as auth
+    failure | error classification in `require_railway_auth` | 21186ffe32.
+20. Env-parity bugs (supercronic path, venv python, worker Redis hostnames, SDK
+    source) | wrapper Dockerfiles drift from the compose baseline | per-item fixes |
+    6e5c312f16, bd26e0f726, README notes.
+21. Runner-token contract break took previews down | `AGENTA_RUNNER_TOKEN` made
+    required without updating all deploy surfaces | 4a1e9cc235.
+22. Secrets in CI logs risk | failing commands echoed args including
+    `variable set KEY=secret` | `_railway_redact` on failure paths | 63136af47e,
+    d97cf94d97.
+
+## Structural roots
+
+1. Non-idempotent CLI mutations with ambiguous outcomes dominate: `init`, `add`,
+   `environment new`, `volume add`, `up`, `redeploy` can succeed server-side while
+   reporting a timeout. Every workaround is a hand-rolled check-then-act loop per
+   resource type. Failures 5, 6, 8 are all this one gap.
+2. No desired-state reconcile; creation and configuration are split across CI jobs;
+   the only real reconcile is "delete the whole project and start over", which itself
+   caused failure 8.
+3. Railway's reads lag its writes (three distinct read paths needed retry loops).
+4. One shared rate-limit budget across all concurrent PRs; workspace tokens carry
+   higher limits but the CLI rejects them (railwayapp/cli#618).
+5. The biggest historical reliability win came from bypassing the CLI for GraphQL
+   (`variableCollectionUpsert`); the README already lists bootstrap and cleanup as
+   next candidates.
+6. A second, independent failure family is wrapper-vs-compose config drift; it ships
+   as a preview outage every time a compose-side change is not mirrored by hand.
diff --git a/docs/design/railway-preview-clone-spike/research/railway-capabilities.md b/docs/design/railway-preview-clone-spike/research/railway-capabilities.md
new file mode 100644
index 0000000000..f537025070
--- /dev/null
+++ b/docs/design/railway-preview-clone-spike/research/railway-capabilities.md
@@ -0,0 +1,79 @@
+# Railway platform capabilities relevant to clone-based previews
+
+Researched 2026-08-02 from Railway docs and community threads. Verify anything marked
+uncertain during the spike.
+
+## Environment duplication (the strongest fit)
+
+- CLI: `railway environment new pr-123 --duplicate <source>` (alias `--copy`);
+  `railway environment delete <name> -y` tears it down. This is Railway's own
+  documented CI recipe for PR environments
+  (https://docs.railway.com/guides/github-actions-pr-environment,
+  https://docs.railway.com/cli/environment).
+- GraphQL: `environmentCreate(input)` with `projectId`, `name`,
+  `sourceEnvironmentId` (clones variables and settings), `ephemeral`,
+  `skipInitialDeploys`, `stageInitialChanges`; `environmentDelete(id)` removes the
+  environment and all deployments (https://docs.railway.com/guides/manage-environments).
+- Duplication copies services, variables, and configuration. Volumes are recreated
+  (empty unless the newer volume-data-copy option applies; exact semantics
+  uncertain).
+- Known failure mode: `environmentCreate` returned HTTP 504 while the environment was
+  still created in the background (station thread, marked resolved 2025-09-08).
+  Client pattern: create → on timeout, poll `environments` by name → proceed.
+
+## Per-PR image tags
+
+- There is no CLI command to update a service's image (railwayapp/cli#815 open).
+- The API path is `serviceInstanceUpdate` (set `source.image`, scoped to the
+  environment) followed by `serviceInstanceDeployV2`; updating the image alone does
+  not redeploy.
+- Native PR environments cannot substitute a per-PR image tag at creation time, so
+  the clone-then-patch flow is required either way.
+
+## Native PR environments (not a direct fit)
+
+- Toggle in project settings; Railway auto-creates an environment per PR against the
+  linked GitHub repo and deletes it on merge/close. Variables copy except sealed
+  ones; volumes come up fresh; bot PRs skipped by default; fork PRs from outside the
+  workspace are not deployed.
+- The trigger is repo-centric: repo-connected services build the PR branch. Behavior
+  for a project whose services are all Docker-image sources is undocumented; assume
+  it does not fit our GHCR-image stack without the follow-up patch step, and verify
+  empirically if we ever want the native trigger.
+
+## Config-as-code and templates
+
+- `railway.json`/`railway.toml` is single-service only (build/deploy settings; has a
+  special `"pr"` environment override block). It cannot declare services, variables,
+  volumes, or images (https://docs.railway.com/config-as-code/reference).
+- Templates can define a full multi-service stack (images incl. private registries,
+  volumes, variables with generators, reference variables). Programmatic
+  instantiation is `templateDeployV2` with a `serializedConfig` you control, which is
+  the one path that natively supports per-PR image tags in a single deploy call.
+  Caveat: thin docs, higher schema-drift risk. This is the fallback if clone
+  fidelity fails.
+
+## Public GraphQL API
+
+- Endpoint `https://backboard.railway.com/graphql/v2`; account, workspace, or project
+  tokens. Introspection enabled; effectively "the dashboard's API": broad but not
+  contract-stable.
+- Documented rate limits: Free 100 requests/hour; Hobby 1,000 RPH / 10 RPS; Pro
+  10,000 RPH / 50 RPS; standard `X-RateLimit-*` and `Retry-After` headers.
+- Operations the CLI lacks or does worse: `environmentCreate` with source,
+  `serviceCreate` with image source and inline variables, `serviceInstanceUpdate`,
+  `serviceInstanceDeployV2`, `volumeCreate`, `templateDeployV2`, bulk
+  `variableCollectionUpsert`. Nothing is documented as idempotent; idempotency must
+  be built client-side (query by name first).
+
+## Auth constraints that bit us before (spike must re-verify in CI)
+
+- Environment creation requires an account-scoped token; workspace and project
+  tokens do not work for it, and the CLI rejects workspace tokens outright
+  (railwayapp/cli#618).
+- `RAILWAY_TOKEN` is treated as project-scoped by the CLI; the account token must be
+  passed as `RAILWAY_API_TOKEN` (#4392 regression).
+- CLI `environment delete` hangs on accounts with 2FA in non-interactive contexts;
+  use GraphQL for deletion.
+- Fork PRs do not receive repo secrets, so previews for external contributors remain
+  out of scope exactly as today.
diff --git a/docs/design/railway-preview-clone-spike/runbook.md b/docs/design/railway-preview-clone-spike/runbook.md
new file mode 100644
index 0000000000..efd6460576
--- /dev/null
+++ b/docs/design/railway-preview-clone-spike/runbook.md
@@ -0,0 +1,237 @@
+# Runbook: Railway clone-based preview spike (issue #5650)
+
+> **Historical record.** The spike scripts this runbook drove were removed
+> before merge, after WP1-WP3 productionized them: the GraphQL client and
+> template apply live in `hosting/railway/oss/template/`, the clone
+> create/destroy scripts in `hosting/railway/oss/scripts/`, the wrapper image
+> sources in `hosting/railway/oss/images/`, and the CI evidence harness is
+> `.github/workflows/48-railway-clone-preview-test.yml`. The measurements in
+> `spike/results/` remain the spike's evidence.
+
+Exact steps to run the spike end to end. Everything below runs from the repo
+root. All scripts live in `docs/design/railway-preview-clone-spike/spike/`.
+
+Success criteria (from issue #5650):
+
+1. **10 consecutive green cycles** of clone → patch → deploy → smoke → delete
+   (phase 3).
+2. **≤ 15 Railway API calls per cycle** (the `api_calls` column in
+   `spike/results/cycle-log.csv`; see the note in phase 3 about the two deploy
+   modes).
+3. **Wall time per cycle ≤ today's setup + deploy** (the combined duration of
+   the "41 - railway setup" and "43 - railway deploy" jobs on a recent PR run;
+   fetch a baseline with
+   `gh run list --workflow "14-check-pr-preview.yml" --limit 5` and open one
+   run's job timings).
+
+## Phase 0 — prerequisites
+
+### 0.1 Provide the token
+
+The spike needs a Railway **account** token (workspace and project tokens
+cannot create environments; the CLI additionally rejects workspace tokens —
+see `research/railway-capabilities.md`). Create one at
+`railway.com/account/tokens`, then store it locally:
+
+```bash
+touch ~/.agenta-railway.env && chmod 600 ~/.agenta-railway.env
+# Edit the file so it contains exactly one line:
+#   RAILWAY_API_TOKEN=<the account token>
+```
+
+Every spike script auto-sources that file when `RAILWAY_API_TOKEN` is unset.
+Never export it as `RAILWAY_TOKEN`: the CLI treats that name as
+project-scoped and account-level calls fail "Unauthorized"
+(failure-history item 4).
+
+Alternative for the CLI-driven parts only (phase 1 uses `railway` CLI via
+`bootstrap.sh`/`configure.sh`): an interactive login from a Claude session:
+
+```bash
+! npx --yes @railway/cli login
+```
+
+Note the leading `!` (runs interactively so the browser handoff works). A CLI
+login alone does NOT cover the GraphQL phases — the account token in
+`~/.agenta-railway.env` covers both, so prefer it.
+
+Verify (cheap, 1 API call, prints no secrets):
+
+```bash
+source docs/design/railway-preview-clone-spike/spike/lib-graphql.sh
+rw_require_token && rw_graphql 'query { me { name } }' | jq '.data.me'
+```
+
+### 0.2 The three wrapper images — build, push, or go registry-free
+
+Three services need custom content beyond a plain public image: the nginx
+gateway, the redis permission wrapper (failure-history item 14), and the
+SeaweedFS IAM wrapper (item 17). The self-contained build contexts live in
+`spike/images/{gateway,redis,seaweedfs}/` (byte-faithful to what
+`deploy-from-images.sh` renders per PR today; divergences documented at the
+top of each Dockerfile).
+
+**Option A — registry images (the intended production shape):**
+
+```bash
+SPIKE=docs/design/railway-preview-clone-spike/spike
+gh auth token | docker login ghcr.io -u "$(gh api user --jq .login)" --password-stdin
+for n in gateway redis seaweedfs; do
+  docker buildx build --platform linux/amd64 --load \
+    -t "ghcr.io/agenta-ai/agenta-preview-$n:spike" "$SPIKE/images/$n"
+  docker push "ghcr.io/agenta-ai/agenta-preview-$n:spike"
+done
+# New GHCR packages default to PRIVATE; make them public so Railway can pull
+# (verified: they contain no secrets — config + entrypoints reading env only).
+# There is NO API for this (PATCH returns 404): use the GitHub web UI —
+# org Packages -> agenta-preview-<n> -> Package settings -> Danger Zone ->
+# Change visibility -> Public.
+```
+
+LIVE STATUS (2026-08-02): the push is DONE — all three images are on GHCR at
+`:spike` (needed an interactive `gh auth refresh -s write:packages` first;
+without that scope every namespace fails `denied: permission_denied`; ttl.sh
+as an anonymous fallback registry does not work from this network — blob
+uploads stall). What remains is UI-only: GHCR packages default to PRIVATE and
+GitHub has NO API to change package visibility. An org admin must open each
+package (org Packages -> agenta-preview-<name> -> Package settings -> Danger
+Zone -> Change visibility) and set Public. Then run:
+
+```bash
+docs/design/railway-preview-clone-spike/spike/switch-template-to-ghcr-images.sh --deploy
+```
+
+It is pull-gated (refuses while any package is private), switches the three
+services to the GHCR images, CLEARS the Option B startCommand overrides so the
+images' own entrypoints are what deploys, and (with `--deploy`) redeploys them
+in the template for a health check. Finish with one patch-mode cycle (phase 3
+command) to certify the registry-backed path end to end.
+
+**Option B — registry-free startCommand wrappers (what the live spike runs):**
+Railway's start command overrides the image ENTRYPOINT in exec form, so the
+wrapper behavior fits in template config on PUBLIC base images — no registry
+at all:
+
+```bash
+docs/design/railway-preview-clone-spike/spike/apply-wrapper-startcommands.sh
+```
+
+This points redis at `redis:8` + a chown-then-delegate startCommand,
+seaweedfs at `chrislusf/seaweedfs:4.37` + the base64-inlined IAM entrypoint,
+and gateway at `nginx:1.27-alpine` + the base64-inlined nginx.conf (plus a
+`PORT=8080` service variable). Idempotent; 4 mutations. Keep
+`spike/images/*` and this script in sync — both derive from
+`hosting/railway/oss/`.
+
+The alembic service needs no wrapper: its `create_databases.py` step is
+replaced by an inline `psql` start command (the api image ships
+`postgresql-client-17`), so per-PR image patching keeps working for it.
+
+**Deprecated fallback (`railway up` into the template — findings Q11):** the
+live run showed clones CANNOT deploy upload-built sources (`Deployment not
+found` for gateway; redis/seaweedfs silently fall back to their plain base
+images). `preview-cycle.sh --gateway-up-interim` (a per-clone
+`railway up` of `spike/images/gateway`) remains as an escape hatch only.
+
+## Phase 1 — build the template environment (one-time) — BLOCKED ON TOKEN
+
+Creates throwaway project `agenta-oss-clone-spike` with environment
+`pr-template`: 13 image-backed services, 3 volumes, variables, healthchecks,
+plus the GraphQL fixups (start commands + wrapper env as service variables).
+
+```bash
+# With prebuilt wrapper images (phase 0.2):
+export AGENTA_GATEWAY_IMAGE="$NS/agenta-spike-gateway:v1"
+export RAILWAY_REDIS_WRAPPER_IMAGE="$NS/agenta-spike-redis:v1"
+export RAILWAY_SEAWEEDFS_WRAPPER_IMAGE="$NS/agenta-spike-seaweedfs:v1"
+# ...or leave all three unset to use the `railway up` fallback (see phase 0.2).
+
+docs/design/railway-preview-clone-spike/spike/build-template-env.sh
+
+# Option B (registry-free): run the plain build above (fallback mode is fine),
+# then reshape gateway/redis/seaweedfs onto public base images + startCommand
+# wrappers:
+docs/design/railway-preview-clone-spike/spike/apply-wrapper-startcommands.sh
+```
+
+The `railway` CLI is required (`npm i -g @railway/cli`, or shim it with
+`npx --yes @railway/cli`).
+
+The template is intentionally left **undeployed** — whether an undeployed
+template clones into a deployable environment is spike question Q5
+(`findings.md`). To debug the template itself, re-run with `--deploy`, which
+triggers all 13 deploys and smoke-tests the template env.
+
+Requires the `railway` CLI (`npm i -g @railway/cli`) and `jq`.
+
+## Phase 2 — one preview cycle
+
+```bash
+docs/design/railway-preview-clone-spike/spike/preview-cycle.sh --image-tag latest
+```
+
+- `--keep` skips the delete so you can inspect the clone in the dashboard
+  (delete it afterwards, or the next 10-cycle run still works — clones get
+  unique names).
+- `--image-tag pr-1234-abc1234` exercises a real PR tag from GHCR.
+
+Watch for the `unmergedChangesCount` warning: if it fires, image patches are
+being staged rather than applied and findings Q7 has its answer.
+
+## Phase 3 — ten consecutive cycles
+
+```bash
+# Winning mode (measured 2026-08-02): patch. MUST use an image tag that
+# differs from the template's (:latest no-ops the patch — findings, deploy-mode
+# section). Use a real pr-<n>-<sha> tag:
+docs/design/railway-preview-clone-spike/spike/preview-cycle.sh \
+    --image-tag pr-5651-a46168f --deploy-mode patch --cycles 10
+column -s, -t docs/design/railway-preview-clone-spike/spike/results/cycle-log.csv
+```
+
+- Measured budgets per cycle (2026-08-02): patch mode = 8 mutations, ~16
+  total calls, ~55s; per-service mode = 23 mutations, ~32 total calls, ~65s.
+  `--deploy-mode triggers` is a dead end (`environmentTriggersDeploy`
+  requires `serviceId`; no whole-env deploy exists).
+- Rate budget: the Hobby token allows 1,000 requests/hour. A 10-cycle patch
+  run costs ~160 calls. Debug sessions add up fast; when a call returns 429
+  the lib honors `Retry-After` (120s waits), but a burst of 429s means the
+  hour's budget is spent — pause the run rather than letting retries exhaust
+  (an exhausted retry fails the cycle).
+- Cycles are independent: a failed cycle records `fail` in the CSV and the
+  next one starts fresh, so a single flake does not abort the evidence run.
+
+## Phase 4 — CI auth check
+
+```bash
+# On a branch (never main), copy the workflow into place:
+cp docs/design/railway-preview-clone-spike/spike/ci-auth-check.yml \
+   .github/workflows/ci-auth-check.yml
+# Commit + push the branch (workflow_dispatch requires the file on a pushed ref),
+# then dispatch:
+gh workflow run railway-clone-spike-auth-check --ref <branch>
+gh run watch
+```
+
+The job proves the shared `secrets.RAILWAY_TOKEN` can authenticate at account
+level, clone the template env, and delete the clone from a GitHub runner, and
+it prints the rate-limit headers so we learn the token's real budget tier.
+Delete the workflow file from the branch when done.
+
+## Teardown
+
+Delete the throwaway project (removes all environments, services, volumes,
+and domains):
+
+```bash
+source docs/design/railway-preview-clone-spike/spike/lib-graphql.sh
+rw_require_token
+project_id="$(rw_find_project_id agenta-oss-clone-spike)"
+rw_graphql 'mutation($id: String!) { projectDelete(id: $id) }' \
+  "$(jq -nc --arg id "$project_id" '{id: $id}')"
+```
+
+Also delete the pushed `agenta-spike-*` wrapper images from the registry if
+they were pushed to a shared namespace, and remove
+`~/.agenta-railway.env` when the spike is finished if the token was minted
+just for it (revoke it in the Railway dashboard too).
diff --git a/docs/design/railway-preview-clone-spike/spike/results/cycle-log.csv b/docs/design/railway-preview-clone-spike/spike/results/cycle-log.csv
new file mode 100644
index 0000000000..c58c0d780d
--- /dev/null
+++ b/docs/design/railway-preview-clone-spike/spike/results/cycle-log.csv
@@ -0,0 +1,30 @@
+cycle,start_iso,env_name,image_tag,deploy_mode,result,clone_s,patch_s,deploy_s,smoke_s,delete_s,total_s,api_calls,note
+1,2026-08-02T12:45:05Z,pr-clone-c1-1785674705,latest,per-service,fail,4,3,35,-,0,42,22,"deploy failed"
+1,2026-08-02T12:48:27Z,pr-clone-c1-1785674907,latest,per-service,fail,4,3,35,-,-,42,24,"deploy failed; kept env pr-clone-c1-1785674907"
+1,2026-08-02T13:37:23Z,pr-clone-c1-1785677843,latest,per-service,pass,4,4,70,1,1,80,32,"+cli-up"
+1,2026-08-02T16:23:36Z,pr-clone-c1-1785687816,latest,per-service,pass,3,3,54,1,1,62,32,""
+1,2026-08-02T16:24:49Z,pr-clone-c1-1785687889,latest,triggers,fail,4,3,1,-,0,8,14,"deploy failed"
+1,2026-08-02T16:26:33Z,pr-clone-c1-1785687993,latest,per-service,pass,3,3,69,2,0,77,33,""
+2,2026-08-02T16:27:50Z,pr-clone-c2-1785688070,latest,per-service,pass,4,3,54,1,1,63,32,""
+1,2026-08-02T16:28:58Z,pr-clone-c1-1785688138,latest,per-service,pass,4,3,53,2,0,62,32,""
+2,2026-08-02T16:30:00Z,pr-clone-c2-1785688200,latest,per-service,pass,4,6,69,1,0,80,33,""
+1,2026-08-02T16:31:25Z,pr-clone-c1-1785688285,latest,per-service,pass,4,3,54,1,1,63,32,""
+2,2026-08-02T16:32:28Z,pr-clone-c2-1785688348,latest,per-service,pass,3,4,54,1,0,62,32,""
+1,2026-08-02T16:33:35Z,pr-clone-c1-1785688415,latest,per-service,pass,4,3,55,1,2,65,32,""
+2,2026-08-02T16:34:40Z,pr-clone-c2-1785688480,latest,per-service,pass,3,3,72,1,1,80,33,""
+1,2026-08-02T16:36:05Z,pr-clone-c1-1785688565,latest,per-service,pass,4,3,55,0,1,63,32,""
+2,2026-08-02T16:37:08Z,pr-clone-c2-1785688628,latest,per-service,pass,4,3,54,2,0,63,32,""
+1,2026-08-02T16:40:31Z,pr-clone-c1-1785688831,latest,patch,fail,4,1,432,-,0,437,38,"deploy failed"
+1,2026-08-02T16:48:12Z,pr-clone-c1-1785689292,latest,patch,fail,4,0,248,-,-,252,25,"deploy failed; kept env pr-clone-c1-1785689292"
+1,2026-08-02T16:53:13Z,pr-clone-c1-1785689593,pr-5651-a46168f,patch,pass,4,0,50,0,1,55,16,""
+1,2026-08-02T16:54:22Z,pr-clone-c1-1785689662,pr-5651-a46168f,patch,pass,4,0,50,1,0,55,16,""
+2,2026-08-02T16:55:17Z,pr-clone-c2-1785689717,pr-5651-a46168f,patch,pass,4,0,50,1,0,55,16,""
+1,2026-08-02T16:56:16Z,pr-clone-c1-1785689776,pr-5651-a46168f,patch,pass,4,0,50,7,0,61,16,""
+2,2026-08-02T16:57:17Z,pr-clone-c2-1785689837,pr-5651-a46168f,patch,pass,4,1,50,0,0,55,16,""
+1,2026-08-02T16:58:18Z,pr-clone-c1-1785689898,pr-5651-a46168f,patch,pass,4,0,51,2,0,57,16,""
+2,2026-08-02T16:59:15Z,pr-clone-c2-1785689955,pr-5651-a46168f,patch,pass,4,0,51,1,0,56,16,""
+1,2026-08-02T17:00:17Z,pr-clone-c1-1785690017,pr-5651-a46168f,patch,pass,4,1,51,15,1,72,16,""
+1,2026-08-02T17:22:52Z,pr-clone-c1-1785691372,pr-5651-a46168f,patch,pass,3,1,50,2,0,56,16,""
+2,2026-08-02T17:23:48Z,pr-clone-c2-1785691428,pr-5651-a46168f,patch,pass,4,1,50,1,1,57,16,""
+1,2026-08-02T18:04:06Z,pr-clone-c1-1785693846,pr-5651-a46168f,patch,fail,4,0,417,-,0,421,35,"deploy failed"
+1,2026-08-02T18:11:29Z,pr-clone-c1-1785694289,pr-5651-a46168f,patch,pass,4,0,51,2,-,57,15,"kept env pr-clone-c1-1785694289"
diff --git a/hosting/railway/oss/scripts/bootstrap.sh b/hosting/railway/oss/scripts/bootstrap.sh
index 0ef5fd0eb0..1779fc292a 100755
--- a/hosting/railway/oss/scripts/bootstrap.sh
+++ b/hosting/railway/oss/scripts/bootstrap.sh
@@ -226,10 +226,20 @@ ensure_volume() {
             return 0
         fi
 
-        if railway_call volume add --mount-path "$mount_path" --json >/dev/null; then
+        local add_output
+        if add_output="$(railway_call volume add --mount-path "$mount_path" --json 2>&1)"; then
             return 0
         fi
 
+        # Railway refusing because a volume is already mounted IS the desired
+        # end state. The volume-list pre-check above can miss existing volumes
+        # on re-runs (issue #5671), so recognize the refusal directly instead
+        # of misreading it as the creation throttle.
+        if printf "%s" "$add_output" | grep -qi "already mounted"; then
+            return 0
+        fi
+        printf "%s\n" "$add_output" >&2
+
         if [ "$attempt" -lt "$attempts" ]; then
             printf "Volume add at %s for service '%s' failed (Railway often throttles volume creation); retrying in %ds (attempt %d/%d).\n" \
                 "$mount_path" "$service" "$delay" "$attempt" "$attempts" >&2
diff --git a/hosting/railway/oss/scripts/deploy-from-images.sh b/hosting/railway/oss/scripts/deploy-from-images.sh
index 7cfea41f37..d50db481ae 100755
--- a/hosting/railway/oss/scripts/deploy-from-images.sh
+++ b/hosting/railway/oss/scripts/deploy-from-images.sh
@@ -70,6 +70,40 @@ redeploy_service_if_exists() {
     fi
 }
 
+# Redeploying a managed service stops the running container first; if Railway
+# is slow to start the replacement, its private-network DNS name disappears and
+# every dependent boots into gaierror (#5673). Never proceed past a Postgres
+# redeploy until Railway reports the deployment ACTIVE again.
+wait_for_service_active() {
+    local service="$1"
+    local attempts="${RAILWAY_SERVICE_ACTIVE_ATTEMPTS:-30}"
+    local delay="${RAILWAY_SERVICE_ACTIVE_DELAY:-10}"
+    local attempt status
+
+    for ((attempt = 1; attempt <= attempts; attempt++)); do
+        status="$(railway_call status --json 2>/dev/null \
+            | jq -r --arg env "$ENV_NAME" --arg svc "$service" \
+                '.environments.edges[].node | select(.name == $env)
+                 | .serviceInstances.edges[].node | select(.serviceName == $svc)
+                 | .latestDeployment.status // "NONE"' 2>/dev/null | head -n 1)"
+        case "$status" in
+            SUCCESS)
+                return 0
+                ;;
+            FAILED|CRASHED)
+                printf "Service '%s' deployment reached terminal status %s after redeploy.\n" \
+                    "$service" "$status" >&2
+                return 1
+                ;;
+        esac
+        sleep "$delay"
+    done
+
+    printf "Service '%s' did not become ACTIVE within %ss after redeploy; aborting early instead of cascading DNS failures.\n" \
+        "$service" "$((attempts * delay))" >&2
+    return 1
+}
+
 run_alembic_with_retries() {
     local attempt=1
 
@@ -85,6 +119,7 @@ run_alembic_with_retries() {
 
         printf "Alembic failed on attempt %s/%s, retrying after infra redeploy\n" "$attempt" "$ALEMBIC_MAX_ATTEMPTS"
         redeploy_service_if_exists "$POSTGRES_SERVICE"
+        wait_for_service_active "$POSTGRES_SERVICE" || return 1
         sleep "$INFRA_SETTLE_SECONDS"
         attempt=$((attempt + 1))
     done
@@ -243,6 +278,7 @@ sleep "${RAILWAY_POST_BOOTSTRAP_SLEEP:-5}"
 # Ensure infra picks up freshly configured credentials before migrations.
 railway_call link --project "$PROJECT_NAME" --environment "$ENV_NAME" --json >/dev/null
 redeploy_service_if_exists "$POSTGRES_SERVICE"
+wait_for_service_active "$POSTGRES_SERVICE"
 if railway_call service "$REDIS_SERVICE" >/dev/null 2>&1; then
     railway_call up "$TMP_DIR/redis" --path-as-root --service "$REDIS_SERVICE" --detach
 fi
diff --git a/web/oss/tests/playwright/acceptance/agent-chat/tests.ts b/web/oss/tests/playwright/acceptance/agent-chat/tests.ts
index ff30d66a3e..858d01c2e5 100644
--- a/web/oss/tests/playwright/acceptance/agent-chat/tests.ts
+++ b/web/oss/tests/playwright/acceptance/agent-chat/tests.ts
@@ -1,9 +1,9 @@
-import type {Page} from "@playwright/test"
-
 import {test as baseTest} from "@agenta/web-tests/tests/fixtures/base.fixture"
 import {expect} from "@agenta/web-tests/utils"
+import type {Page} from "@playwright/test"
+
+import {AGENT_APPS_UNAVAILABLE_REASON, archiveWorkflow, isAgentRevision} from "../utils/agentApps"
 
-import {AgentChatFixtures} from "./assets/types"
 import {
     ELICITATION_PAYLOAD,
     elicitationPausedTurn,
@@ -11,6 +11,7 @@ import {
     sseFulfill,
     type ElicitationPayloadFixture,
 } from "./assets/elicitationStream"
+import {AgentChatFixtures} from "./assets/types"
 
 /**
  * Agent-chat acceptance fixtures (elicitation / interaction-kinds M1, layer A).
@@ -93,20 +94,26 @@ const testWithAgentChatFixtures = baseTest.extend<AgentChatFixtures>({
                 "create variant",
             )
 
-            const revisionId = requireId(
-                await post("/workflows/revisions/commit", {
-                    workflow_revision: {
-                        workflow_id: workflowId,
-                        workflow_variant_id: variantId,
-                        slug: `${unique}rev`,
-                        name: "default",
-                        data: {uri: AGENT_URI, parameters: {agent: {}}, schemas: {}},
-                        message: "Agent",
-                    },
-                }),
-                "workflow_revision",
-                "commit revision",
-            )
+            const revisionBody = await post("/workflows/revisions/commit", {
+                workflow_revision: {
+                    workflow_id: workflowId,
+                    workflow_variant_id: variantId,
+                    slug: `${unique}rev`,
+                    name: "default",
+                    data: {uri: AGENT_URI, parameters: {agent: {}}, schemas: {}},
+                    message: "Agent",
+                },
+            })
+            const revisionId = requireId(revisionBody, "workflow_revision", "commit revision")
+
+            // Environments without the agent platform (e.g. OSS previews with the feature
+            // flags off) commit this same payload as a plain prompt revision, so the agent
+            // playground under test can never render. Skip — and archive the seed first so
+            // the misclassified app cannot pollute app lists used by other specs.
+            if (!isAgentRevision(revisionBody?.workflow_revision)) {
+                await archiveWorkflow(page, base, projectId, workflowId)
+                baseTest.skip(true, AGENT_APPS_UNAVAILABLE_REASON)
+            }
 
             seededRevisionByApp.set(workflowId, revisionId)
             return workflowId
@@ -138,7 +145,7 @@ const testWithAgentChatFixtures = baseTest.extend<AgentChatFixtures>({
 
     mockElicitationInvoke: async ({page}, use) => {
         await use(async (payload: ElicitationPayloadFixture = ELICITATION_PAYLOAD) => {
-            const calls: Array<Record<string, any>> = []
+            const calls: Record<string, any>[] = []
             let resumeText = "Thanks — I've recorded your answers."
             let n = 0
             const toolCallId = "call_elicit_1"
diff --git a/web/oss/tests/playwright/acceptance/agent-skills/skill-folder-upload.spec.ts b/web/oss/tests/playwright/acceptance/agent-skills/skill-folder-upload.spec.ts
index ee92ea1fcf..3a379544a3 100644
--- a/web/oss/tests/playwright/acceptance/agent-skills/skill-folder-upload.spec.ts
+++ b/web/oss/tests/playwright/acceptance/agent-skills/skill-folder-upload.spec.ts
@@ -15,6 +15,12 @@ import {expect} from "@agenta/web-tests/utils"
 import type {Page} from "@playwright/test"
 import {strToU8, zipSync} from "fflate"
 
+import {
+    AGENT_APPS_UNAVAILABLE_REASON,
+    archiveWorkflow,
+    queryWorkflowAgentState,
+    resolveApiBase,
+} from "../utils/agentApps"
 import {expectAuthenticatedSession} from "../utils/auth"
 import {createScenarios} from "../utils/scenarios"
 import {buildAcceptanceTags} from "../utils/tags"
@@ -140,6 +146,20 @@ test(
             expect(createResponse.ok()).toBe(true)
             const created = (await createResponse.json()) as {workflow: {id: string}}
 
+            // Environments without the agent platform (e.g. OSS previews with the feature
+            // flags off) silently create a prompt-type app here, so the Skills UI under test
+            // can never render. Skip only on that definitive signal — and archive the app
+            // first so the misclassified leftover cannot pollute other specs' app lists.
+            const projectId = basePath.match(/\/p\/([^/]+)/)?.[1] ?? ""
+            const apiBase = resolveApiBase(page)
+            const agentState = projectId
+                ? await queryWorkflowAgentState(page, apiBase, projectId, created.workflow.id)
+                : "unknown"
+            if (agentState === "not-agent") {
+                await archiveWorkflow(page, apiBase, projectId, created.workflow.id)
+            }
+            test.skip(agentState === "not-agent", AGENT_APPS_UNAVAILABLE_REASON)
+
             await page.goto(
                 `${getProjectScopedBasePath(page)}/apps/${created.workflow.id}/playground`,
                 {waitUntil: "domcontentloaded"},
diff --git a/web/oss/tests/playwright/acceptance/utils/agentApps.ts b/web/oss/tests/playwright/acceptance/utils/agentApps.ts
new file mode 100644
index 0000000000..d4c91c1454
--- /dev/null
+++ b/web/oss/tests/playwright/acceptance/utils/agentApps.ts
@@ -0,0 +1,70 @@
+import type {Page} from "@playwright/test"
+
+/**
+ * Skip reason for environments (e.g. OSS previews) where the agent platform is disabled:
+ * creating an "agent" app silently yields a prompt-type app, so agent-only UI never exists.
+ */
+export const AGENT_APPS_UNAVAILABLE_REASON =
+    "agent-type apps are not available in this environment (feature flags off)"
+
+interface WorkflowRevisionLike {
+    flags?: {is_agent?: boolean} | null
+    data?: {uri?: string | null} | null
+}
+
+/** Agent-ness is server-derived: commit infers `flags.is_agent` from the revision URI. */
+export const isAgentRevision = (revision: WorkflowRevisionLike | null | undefined): boolean =>
+    revision?.flags?.is_agent === true
+
+export const resolveApiBase = (page: Page): string => {
+    if (process.env.AGENTA_API_URL) return process.env.AGENTA_API_URL
+    const origin = new URL(page.url() || process.env.AGENTA_WEB_URL || "http://localhost:3000")
+        .origin
+    return `${origin}/api`
+}
+
+/** Best-effort archive so a non-agent leftover cannot pollute app lists used by other specs. */
+export const archiveWorkflow = async (
+    page: Page,
+    apiBase: string,
+    projectId: string,
+    workflowId: string,
+): Promise<void> => {
+    await page.request
+        .post(`${apiBase}/workflows/${workflowId}/archive?project_id=${projectId}`)
+        .catch(() => undefined)
+}
+
+/**
+ * Resolve whether the app's committed revisions mark it agent-type.
+ * Returns "unknown" while no revision is readable — callers must skip only on the definitive
+ * "not-agent" answer so transient reads cannot hide real failures in agent-capable environments.
+ */
+export const queryWorkflowAgentState = async (
+    page: Page,
+    apiBase: string,
+    projectId: string,
+    workflowId: string,
+    timeoutMs = 15000,
+): Promise<"agent" | "not-agent" | "unknown"> => {
+    const deadline = Date.now() + timeoutMs
+    do {
+        const response = await page.request
+            .post(`${apiBase}/workflows/revisions/query?project_id=${projectId}`, {
+                data: {workflow_refs: [{id: workflowId}]},
+            })
+            .catch(() => null)
+        if (response?.ok()) {
+            const body = (await response.json().catch(() => null)) as {
+                workflow_revisions?: WorkflowRevisionLike[]
+            } | null
+            const revisions = body?.workflow_revisions ?? []
+            if (revisions.some(isAgentRevision)) return "agent"
+            // Classify "not-agent" only once a data-bearing revision landed, so an early
+            // placeholder commit cannot trigger a wrong skip in agent-capable environments.
+            if (revisions.some((revision) => Boolean(revision?.data?.uri))) return "not-agent"
+        }
+        await new Promise((resolve) => setTimeout(resolve, 1000))
+    } while (Date.now() < deadline)
+    return "unknown"
+}