caracms 0.7.0 → 0.8.0

package/bin/templates/railway-cloud.ts.txt

@@ -0,0 +1,73 @@
+import { defineRailway, github, preserve, project, redis, ref, service } from "railway/iac";
+
+// A caracms site's Railway project, as code (written by `caracms init` from the
+// template for a site on CaraCMS Cloud). From the site's root: `railway config
+// plan` shows what would change, `railway config apply` makes it so. Plan
+// first, every time.
+//
+// On CaraCMS Cloud the site's GitHub access, images, forms and email, and video
+// all come through CARACMS_CLOUD_KEY, so the project is the site and its Redis
+// (the editor's drafts and sessions): no buckets, no imgproxy.
+//
+// What this file doesn't do, set by hand on Railway: create the project, the
+// site's domain, Redis's volume and start command (Railway's Redis template
+// makes them), the secrets' values, and the optional secrets below until
+// they're wanted.
+
+// ---- The site's names: a new site edits this block and nothing else. ----
+const SITE = "{{SITE}}";
+// The repo Railway builds from (the editor's repo is the one linked in CaraCMS Cloud).
+const REPO = "{{GITHUB_REPO}}";
+// Railway's region for the services.
+const REGION = "europe-west4-drams3a";
+// The site is the repo's root: no watch paths, so every push to main deploys.
+const WATCH_PATHS: string[] = [];
+const BUILD_COMMAND = "{{BUILD}}";
+const START_COMMAND = "{{START}}";
+// -------------------------------------------------------------------------
+
+export default defineRailway(() => {
+  // The editor's drafts and sessions.
+  const kv = redis("Redis", { region: REGION });
+  // Sleeps when idle. redis() takes only a region, so it's set on the node.
+  kv.deploy = { ...kv.deploy, sleepApplication: true };
+
+  const site = service("site", {
+    source: github(REPO, { branch: "main", checkSuites: false }),
+    build: { buildCommand: BUILD_COMMAND, watchPatterns: WATCH_PATHS },
+    start: START_COMMAND,
+    healthcheck: "/health",
+    replicas: { [REGION]: 1 },
+    deploy: { restartPolicyMaxRetries: 3 },
+    env: {
+      // ---- Written here: literals and Railway references ----
+      NODE_ENV: "production",
+      // The public address (canonical links, the sitemap, og:url). At launch it
+      // becomes the client's domain, written out as "https://<domain>".
+      SITE_URL: "https://${{RAILWAY_PUBLIC_DOMAIN}}",
+      REDIS_URL: ref(kv, "REDIS_URL"),
+
+      // ---- Set by hand on Railway: names only, the values never live here ----
+      // On a fresh project these stay unset and the plan doesn't mention them.
+      // The site's key from app.caracms.com (a key labelled for this environment).
+      CARACMS_CLOUD_KEY: preserve(),
+      // The editor's sign-in.
+      CARACMS_SECRET: preserve(),
+      CARACMS_ALLOW: preserve(),
+      CARACMS_BACKUP_USER: preserve(),
+      CARACMS_BACKUP_PASSWORD: preserve(),
+      // Try again on a failed publish redeploys through this project token.
+      CARACMS_RAILWAY_TOKEN: preserve(),
+      // Optional. The form's spam check: the site key is baked in at build, so
+      // a change needs a redeploy.
+      TURNSTILE_SITE_KEY: preserve(),
+      TURNSTILE_SECRET_KEY: preserve(),
+      // Optional. Pre-launch password ("user:password"); unset means public.
+      CARACMS_PRELAUNCH: preserve(),
+    },
+  });
+
+  return project(SITE, {
+    resources: [site, kv],
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caracms",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "A visual CMS for Astro sites, with content in git.",
   "license": "MIT",
   "type": "module",

package/skills/caracms-adopt/SKILL.md

@@ -22,12 +22,16 @@ Start from a clean git checkout (untracked files are fine). The order is:
    (or `pnpm add caracms --save-exact`).
 2. **Commit the install** (`package.json` and the lockfile). `init --write` refuses while
    tracked files have uncommitted changes, so that its own change is one diff to review.
-3. **`npx caracms init`**, the dry run (below), and read it.
-4. **`npx caracms init --write`**.
+3. **`npx caracms init --cloud`** (or `--self-hosted`), the dry run (below), and read it.
+   The flag is the site's mode, where its services come from: choosing it is
+   `caracms-hosting` → section 1. Always pass it: run without a terminal, `init` won't
+   pick a mode, and on a new site it writes nothing and exits 1.
+4. **`npx caracms init --cloud --write`** (or `--self-hosted --write`).
 5. **Install again** (`npm install` / `pnpm install`): `init` adds dependencies to
    `package.json`.
 
-**`npx caracms init`** is a dry run: it writes nothing and prints
+**`npx caracms init --cloud`** (or `--self-hosted`) without `--write` is a dry run: it
+writes nothing and prints
 
 - one line per file: `add` (a new file), `edit` (an existing one), `link` / `unlink` (a
   skill link in `.claude/skills/`);
@@ -49,8 +53,8 @@ adapter in middleware mode; an Astro outside caracms's range, or none; a Tina si
 port, not `init`; an untracked leftover `tina/__generated__/` is only a note). `init --write` also refuses with uncommitted changes
 to tracked files: usually the install of step 1, not yet committed.
 
-Read the diff. Then **`npx caracms init --write`**, install again (`npm install` /
-`pnpm install`), and commit that as one change.
+Read the diff. Then **`npx caracms init --cloud --write`** (or `--self-hosted --write`),
+install again (`npm install` / `pnpm install`), and commit that as one change.
 
 pnpm 12.11 and later may print `Agent skills awaiting approval: caracms` after the install.
 That's pnpm's own gate: it links the skills a dependency ships into `.claude/skills/` only
@@ -61,7 +65,7 @@ unapproved, and don't approve it in passing (`pnpm approve` also reviews build s
 `init` added:
 
 - `caracms.config.ts`: a `pages` collection at `/` (nested), one `text` block, no text
-  styles;
+  styles, and `services: 'cloud'` (or `'self-hosted'`), the mode;
 - `src/components/caracms/Page.astro` (the page component) and `TextBlock.astro`;
 - `src/pages/[...path].astro`, the one catch-all, which serves every document with an
   address (the pages today; a collection added later needs no route of its own, section
@@ -75,7 +79,7 @@ unapproved, and don't approve it in passing (`pnpm approve` also reviews build s
 - the skill links and a block in `CLAUDE.md`;
 - with `--railway` only, `.railway/railway.ts` (when the site had none) and `railway`
   (dev). Without it, `init` prints the variables any host needs instead. Where and how
-  the site runs (Railway, Render, Fly, a VPS) is the caracms README's Hosting section.
+  the site runs (Railway, Render, Fly, a VPS) is `caracms-hosting` → section 2.
 
 Then `astro build`: every existing page must still build. The pages stay prerendered, but
 the output moves to `dist/client/` and `dist/server/`, and `npm start` is now
@@ -83,8 +87,9 @@ the output moves to `dist/client/` and `dist/server/`, and `npm start` is now
 (its own built-site checks, a script) needs the new paths: the pages are in
 `dist/client/`.
 
-Re-run `init` after updating caracms: it re-links the skills and refreshes the CLAUDE.md
-block and the schemas. On a set-up site with nothing to do it says
+Re-run `init` after updating caracms: it reads the mode from the config, re-links the
+skills and refreshes the CLAUDE.md block and the schemas. On a set-up site with nothing
+to do it says
 `caracms init: nothing to do. caracms is set up here.`
 
 ## 2. Set up the comparison before changing a page
@@ -107,9 +112,12 @@ are `content/pages/<path>.json` and `content/<collection>/<slug>.json`, the buil
 `dist/client/`), not what they check. A check that a page's own CSS isn't on another page
 is the exception (section 4).
 
-**Images need the media variables** in the site's `.env` (never committed):
-`CARACMS_MEDIA_URL` (imgproxy's origin), `IMGPROXY_KEY`, `IMGPROXY_SALT` and `S3_BUCKET`
-to show images, plus `S3_ENDPOINT`, `S3_REGION`, `S3_ACCESS_KEY_ID` and
+**Images need credentials** in the site's `.env` (never committed). On CaraCMS Cloud
+that's `CARACMS_CLOUD_KEY` alone: a key labelled for this laptop, made in
+app.caracms.com (`caracms-hosting` → section 1); it shows, imports and uploads images,
+and makes `astro dev` live on the site's real repo. Self-hosted, it's the media
+variables: `CARACMS_MEDIA_URL` (imgproxy's origin), `IMGPROXY_KEY`, `IMGPROXY_SALT` and
+`S3_BUCKET` to show images, plus `S3_ENDPOINT`, `S3_REGION`, `S3_ACCESS_KEY_ID` and
 `S3_SECRET_ACCESS_KEY` to import and upload them. Without them `astro dev` draws a
 caracms image as nothing, and `astro build` stops with a sentence naming what's missing.
 If they aren't there, say so; don't invent values.
@@ -333,7 +341,8 @@ editor's uploads are) and prints one JSON array on stdout:
 - It reads `S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET`, `S3_ACCESS_KEY_ID` and
   `S3_SECRET_ACCESS_KEY` from the environment, else the site's `.env`. On CaraCMS Cloud it
   reads `CARACMS_CLOUD_KEY` instead (the same places) and uploads to the site's cloud
-  folder, with the same output; with both set it refuses.
+  folder, with the same output. It goes by the config's `services`: the other mode's
+  variables, if set, are ignored with one warning naming them.
 - The same image again writes nothing and prints its key with `"existed": true`. It never
   deletes anything.
 - JPEG, PNG, WebP, AVIF, HEIC/HEIF, GIF and SVG, up to 40 MB and 50 megapixels. If any file
@@ -527,3 +536,11 @@ node .claude/skills/caracms-adopt/look-same.mjs --playwright /tmp/look-same \
 
 Work on a branch and open a pull request; never commit to `main` directly, and never
 touch the `drafts` branch.
+
+## 11. Before the first deploy: `caracms-hosting`
+
+The site's hosting is `caracms-hosting`'s, not this skill's. Before the site is first
+deployed with caracms, `init` must have run with the mode (`--cloud` or `--self-hosted`,
+section 1), so `caracms.config.ts` has `services`; then follow `caracms-hosting`: the
+host for the server (section 2), and, for a site that ran self-hosted and is going onto
+the cloud, the move list `init --cloud` prints (section 3).

package/skills/caracms-hosting/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: caracms-hosting
+description: Set up where a caracms site runs — choose its mode (CaraCMS Cloud or self-hosted, the `services` field in caracms.config.ts) and run `caracms init --cloud` or `--self-hosted`, put its server on a host (Railway through `init --railway`; Render, Fly or a VPS by hand), move a self-hosted site onto the cloud by following `init`'s move list in order, and read the cloud's refusals (a storage or video limit, the daily email limit, a switched-off team, a revoked key, the GitHub App not installed) with what to do for each. Use before a site's first deploy, when moving a site between modes, when changing its host, or when the cloud says no.
+---
+
+# Where a caracms site runs
+
+A site makes three choices, and they're separate:
+
+- **Where it starts** (Tina, an existing Astro site, …) decides which skill converts it:
+  `caracms-tina`, `caracms-adopt`. Those skills hand over to this one before the first
+  deploy.
+- **Its mode**, where its services come from (GitHub access, media, forms and email,
+  video): **CaraCMS Cloud** or **self-hosted**. Section 1.
+- **Where its server runs**: a cloud site still runs its own Node server and Redis
+  somewhere. Section 2.
+
+**The config says the mode; the variables don't.** `services` in `caracms.config.ts`
+(`'cloud'` or `'self-hosted'`, inside `defineSite({ … })`) is the one source of truth.
+Variables from the other mode are leftovers to retire, never a second opinion: with the
+field set, the site ignores them and says so once at build, once at the server's first
+request and once from `media import`:
+
+> S3_BUCKET is set, but this site runs on CaraCMS Cloud (caracms.config.ts): it's ignored.
+> Remove it once the old bucket and imgproxy are retired.
+
+A config with no `services` field behaves as caracms did before the field existed (the
+key decides, and the key beside the site's own variables is refused). The next `init`
+with a mode adds the field.
+
+Detail lives in the caracms README (`node_modules/caracms/README.md`): **Hosting** (what
+every host needs, the variables, each host) and **Hosting → CaraCMS Cloud** (the key,
+images, forms and email, video, `media push`, working locally). This skill is the order
+to do things in; read those sections for the rest, rather than guessing.
+
+Commands run from the site's root: `npx caracms …`, or `pnpm caracms …` in a pnpm site.
+
+## 1. Choose the mode and run `init` with it
+
+| Mode | The site's server needs | On its host |
+|---|---|---|
+| **CaraCMS Cloud** | `CARACMS_CLOUD_KEY`, plus the site's own `SITE_URL`, `REDIS_URL`, `CARACMS_SECRET`, sign-in (`CARACMS_ALLOW` and/or the backup sign-in), Turnstile | the site and Redis |
+| **Self-hosted** | a GitHub token or App and `GITHUB_REPO`, the media bucket and imgproxy, a submissions bucket, Resend, Mux, plus everything in the row above but the key | the site, Redis, two buckets, imgproxy |
+
+The full list, per variable, is the README's *Hosting → The variables*.
+
+**CaraCMS Cloud** is for a site CaraCMS runs: it has a team and a site in
+app.caracms.com, its repo linked there, and the caracms GitHub App installed on that
+repo. **Self-hosted** is for a site that keeps its own buckets, imgproxy, Resend and
+GitHub credential. If the brief or the person hasn't said which, ask. Don't pick one
+from what variables happen to be in `.env`.
+
+**Always pass the flag.** `init` asks for the mode only when a person is at a terminal;
+run by an agent or a script, it won't pick one. On a new site it writes nothing, exits 1
+and says to run it again with `--cloud` or `--self-hosted`; on a site already set up it
+does everything else, leaves the field out and says "Mode not set: run
+`caracms init --cloud` or `--self-hosted`."
+
+```sh
+npx caracms init --cloud            # the dry run: read it
+npx caracms init --cloud --write    # writes services: 'cloud' and the rest
+```
+
+(`--self-hosted` the same way. Both flags at once is a problem.)
+
+- `init` writes the field as the first property of the `defineSite({` literal, or
+  replaces an existing `services` property. If the config's `defineSite` argument isn't
+  a literal, it writes nothing and names the line to add by hand: add it, then run `init`
+  again.
+- A second `init` reads the mode from the config and asks nothing; it re-links the
+  skills and refreshes the CLAUDE.md block (whose first line says where the site runs)
+  and the schemas. Run it after every caracms update.
+- **A flag that contradicts the field is a move**, not an error: `--cloud` on a
+  self-hosted site prints the move list (section 3); `--self-hosted` on a cloud site
+  prints the way back (section 3, the end).
+- **`init --cloud` checks the key** when it finds one (the environment, then `.env`): it
+  shows the site and team the key belongs to, the linked repo, and whether the App is
+  installed on it, or the cloud's own sentence for a refused key (section 4). No key: it
+  says where to make one and carries on. **Never print, paste or commit a key.**
+
+**One key per place the site runs**, each labelled in app.caracms.com: "Railway" for
+the host, "Rich's laptop" for a laptop's `.env`, "staging" for a staging deploy.
+Revoking one never touches the others. Leave `CARACMS_CLOUD_URL` unset (it's only for
+working on CaraCMS Cloud itself). On a laptop a cloud key makes `astro dev` live on the
+site's real repo and folder; without one, `astro dev` edits content on disk as always.
+
+**A production build needs the key.** With `services: 'cloud'` and no
+`CARACMS_CLOUD_KEY`, `astro build` (and `pnpm build` on a laptop, which is a production
+build) fails, and a production server's `/admin` answers 503, with:
+
+> This site runs on CaraCMS Cloud (caracms.config.ts), but CARACMS_CLOUD_KEY isn't set.
+> Make a key for it in app.caracms.com.
+
+It never falls back to self-hosted variables that happen to be set.
+
+## 2. Where the server runs
+
+Every host needs what the README's *Hosting* opens with: one instance, HTTPS, a deploy
+whenever `main` changes, `SITE_URL` the same at build and run time, and the server
+started with `caracms start`. The mode only changes which variables go on it (section 1).
+Off Railway, Fly and Render, `CARACMS_CLIENT_IP_HEADER` is required too (*Hosting → The
+visitor's IP*).
+
+Each host below is its own section. **A new host is a new section here**, written the
+same way: how it's set up, the variables per mode, anything it does differently. The
+rest of this skill doesn't change for it.
+
+### Railway
+
+**Set up by `init`.** `init --railway` writes `.railway/railway.ts`, the file that
+describes the whole Railway project, when the site has none:
+
+- `--cloud --railway`: the site and Redis, nothing else.
+- `--self-hosted --railway`: the site, Redis, the media and submissions buckets, and
+  imgproxy.
+
+Then the README's *Hosting → Railway* (the IP header and commit come by default; "Try
+again" uses `CARACMS_RAILWAY_TOKEN`). Set `CARACMS_CLOUD_KEY` (the "Railway" key) on the
+site's service on a cloud site.
+
+**`init` never rewrites an existing `.railway/railway.ts`.** `railway config apply`
+makes the project match the file, deleting what the file no longer declares. So:
+
+- **Never run `railway config apply` on a file cut down to the site and Redis before
+  `caracms media push` has finished** (section 3, step 3): it would delete the media
+  bucket the images are still being copied from.
+- Never apply a file you haven't read against the environment it would change. A
+  production file a template wrote (a Tina template site's) can switch its CDN off; set
+  production's variables with `railway variables --set` instead.
+- Before any apply, `railway config plan` shows what it would create, change or delete.
+  Read it.
+
+### Render
+
+By hand, from the README's *Hosting → Render*: one instance (no autoscaling), the IP
+default to check, the commit Render sets. Put the mode's variables (section 1) on the
+web service, Redis beside it (*Hosting → Redis*). A self-hosted site also needs its two
+buckets and an imgproxy somewhere the server can reach.
+
+### Fly
+
+By hand, from the README's *Hosting → Fly*: one machine, a GitHub Action to deploy on a
+push to `main`, the IP header. The mode's variables as Fly secrets; Redis (Upstash works,
+in the site's region). A self-hosted site needs its buckets and imgproxy elsewhere.
+
+### A VPS
+
+By hand, from the README's *Hosting → A VPS, behind Caddy or nginx*: the proxy,
+`CARACMS_CLIENT_IP_HEADER` set to match it, a deploy on a push to `main`, Redis. The
+mode's variables in the server's environment.
+
+## 3. The move: self-hosted to CaraCMS Cloud
+
+**Follow the list `init --cloud` prints, in its order.** On a site that's self-hosted
+(the field says so, or there's none and the site has a `.railway/railway.ts` with
+buckets or imgproxy, or media, video, forms or GitHub variables in `.env`),
+`npx caracms init --cloud --write` writes `services: 'cloud'` and prints the steps to
+finish the move, each with the check that says it worked. Only steps that apply are
+printed. Don't reorder them, skip a check, or fit a list of your own to the site.
+
+**`init` only sees the repo.** The list names every variable the cloud replaces and marks
+the ones it found in `.env` or `railway.ts`; the host may have more. Open the host's
+variables page and check it against the full list.
+
+The replaced variables:
+
+- media: `S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET`, `S3_ACCESS_KEY_ID`,
+  `S3_SECRET_ACCESS_KEY`, `IMGPROXY_KEY`, `IMGPROXY_SALT`, `CARACMS_MEDIA_URL`
+- video: `MUX_TOKEN_ID`, `MUX_TOKEN_SECRET`
+- forms and email: `SUBMISSIONS_S3_BUCKET`, `SUBMISSIONS_S3_ACCESS_KEY_ID`,
+  `SUBMISSIONS_S3_SECRET_ACCESS_KEY`, `RESEND_API_KEY`, `FORMS_FROM`
+- GitHub: `CARACMS_GITHUB_TOKEN`, `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`, `GITHUB_REPO`
+
+(`GITHUB_WEBHOOK_SECRET` isn't on it: the cloud has no webhook, so it's unused and
+harmless.)
+
+The list's steps, for orientation (what `init` prints is the one to follow):
+
+1. The site and a key in app.caracms.com, the App on the repo, then open the site's page
+   in app.caracms.com (the cloud refreshes the install state only when that page opens, a
+   repo is linked or the site mints a token). *Check:* `init --cloud` again shows "App
+   installed".
+2. Commit and push the field. **The host's build then fails with "CARACMS_CLOUD_KEY isn't
+   set" until step 4.** That's expected: the old deployment keeps serving. Don't "fix"
+   it by reverting the field.
+3. Copy the images: `caracms media push`, with the old bucket's `S3_*` on its command line
+   (README: *Moving a site's images in*). *Check:* `failed: 0`, and a second run skips
+   everything. It stops at the storage limit with the cloud's sentence (section 4).
+4. Set `CARACMS_CLOUD_KEY` on the host and **leave the old variables in place** (they're
+   ignored). *Check:* the deploy's logs name them as ignored; the editor signs in; an
+   upload lands in the cloud.
+5. Video, if `MUX_TOKEN_*` was found: each clip uploaded again in the editor and placed
+   where the old one was (no copy command; old clips keep playing until replaced).
+   *Check:* no page plays from the old account.
+6. Remove the replaced variables from the host, one by one. *Check:* the next deploy logs
+   no "ignored" lines.
+7. Retire, **only once 4–6 hold**: imgproxy, the media bucket, the GitHub token or App on
+   this repo, Resend. **Keep the submissions bucket** until its old submissions are
+   exported or no longer wanted (the cloud doesn't copy them, and its inbox doesn't show
+   them), and **keep the old Mux account** until step 5 is finished.
+8. Cut `.railway/railway.ts` down to the site and Redis (what `--cloud --railway` writes,
+   keeping the site's own names). *Check:* `railway config plan` shows nothing to create
+   or change.
+
+**Retiring can't be undone by git.** Deleting a bucket, a service or an account is the
+person's call: say what's ready to go and let them do it, or do it when they say so.
+Everything before step 7 can be reverted with git and the host's variables.
+
+**The way back** (cloud to self-hosted): `npx caracms init --self-hosted --write` writes
+the field and prints the README's leaving notes: copy the site's cloud folder to a bucket
+of your own (the keys in content stay the same), set the self-hosted variables, and stand
+up what the mode needs on the host (section 2).
+
+## 4. When the cloud says no
+
+The cloud refuses in its own sentence, and caracms shows that sentence as it is: in the
+build log, on `/admin` (a 503, with the public site still serving), in the editor while
+it's open, in `media push` / `media import` output, or on a submission in the inbox.
+**Never answer a refusal by setting the site's own variables:** with
+`services: 'cloud'` they're ignored.
+
+Who's who: **CaraCMS** runs the cloud (staff, in admin.caracms.com); the **site's team**
+owns the site in app.caracms.com (its keys, its repo). Limits and switching a team on
+are CaraCMS's; keys and the repo are the team's.
+
+| The sentence (its code) | What to do |
+|---|---|
+| "This site has reached its storage limit in CaraCMS Cloud (…). Ask CaraCMS to raise it." (`upload_limit`) | Uploads and `media push` stop there. Tell the person: CaraCMS raises the limit. Then run `media push` again (it skips what's copied). Don't delete images to make room. |
+| "This site has reached its video limit in CaraCMS Cloud (…). Ask CaraCMS to raise it." (`video_limit`) | New clips are refused; existing ones play. CaraCMS raises it. A clip counts once Mux has finished it, so one upload can go past the limit. |
+| "Not emailed: this site reached its daily email limit in CaraCMS Cloud (…). Ask CaraCMS to raise it." (on a submission in the inbox) | The submission is stored and readable in the inbox; its email is never sent later. The limit is 50 a day (UTC) unless CaraCMS has set another, and CaraCMS can raise it. For a test, a laptop never emails (submissions go to `.caracms/submissions/`, emails to the log). |
+| "This site has sent the most sign-in emails CaraCMS Cloud sends in a day. Try again tomorrow." (`sign_in_limit`) | Sign-in links stop until the next day. The backup sign-in (`CARACMS_BACKUP_USER` / `_PASSWORD`) still works, if it's set. |
+| "This site's team is switched off. Ask CaraCMS to switch it back on." (`team_off`) | Builds fail, `/admin` answers 503, the running site's public pages keep serving. Only CaraCMS can switch it back on; tell the person. |
+| "That site key was revoked. Make a new one in app.caracms.com." (`revoked_key`) | Make a new labelled key for that place (host, laptop, staging), set it where the old one was (the host's variable or `.env`), redeploy or restart. Don't reuse another place's key. |
+| "That site key isn't one we know." (`unknown_key`) | A mistyped or truncated key, a key for a deleted site, or `CARACMS_CLOUD_URL` pointing at another cloud. Check the variable's value has no stray quotes or spaces, unset `CARACMS_CLOUD_URL`, else make a new key. |
+| "The caracms GitHub App isn't installed on <repo>, or that repo doesn't exist. Install the App on it: <link>" (`app_not_installed`) | Install the App from the link on that repo only. The cloud refreshes its record of the install only when the site's page in app.caracms.com opens (or a repo is linked, or the site mints a token), so open the site's page there, then run `init --cloud` again: it shows "App installed". The next visit to `/admin` tries again. If it is installed, the repo linked in app.caracms.com is the wrong one: the team fixes it there (a changed repo reaches the site at its next start). |
+| "This site has no GitHub repo in CaraCMS Cloud yet. Ask CaraCMS to set one." (`no_repo`; what `/admin` shows. `POST /v1/github/token` answers it as "A team owner can pick one in app.caracms.com.") | A team owner links the repo in app.caracms.com, then the App goes on it. The site still builds meanwhile. |
+| "CaraCMS Cloud couldn't be reached, so the site can't be built. Try again in a minute." (`unreachable`) | Retry the build. A running site keeps serving. If it persists, tell the person; don't switch the mode. |
+| "This site runs on CaraCMS Cloud (caracms.config.ts), but CARACMS_CLOUD_KEY isn't set. Make a key for it in app.caracms.com." | Not the cloud refusing: the key is missing where the site is built or runs (section 1). Expected during the move's steps 2–3. |
+
+The README's *Hosting → CaraCMS Cloud* has each of these in context.

package/skills/caracms-tina/SKILL.md

@@ -21,6 +21,8 @@ Read with this skill:
   preview (section 8). This skill is the Tina-specific order; adopt's page-by-page
   method doesn't apply, since the script converts every page at once.
 - `caracms-content`: the content files the script writes.
+- `caracms-hosting`: the mode `init` is run with, the host, and (on CaraCMS Cloud) the
+  move list to follow at the switch. Hosting is that skill's, not this one's.
 - Beside this file: **`tina-to-caracms.mjs`**, the reference script (its header is its
   manual), and **`field-kinds.md`**, the mapping table: how each Tina field kind becomes a
   caracms field and value.
@@ -64,9 +66,13 @@ Work on a branch (`caracms-port`, say) in a worktree of the site. Commit after e
 3. **Delete `content/`** (git keeps it). `init` refuses a `content/` that isn't caracms's.
 4. **Switch the adapter to standalone:** `@astrojs/node` with `mode: 'standalone'`.
    `caracms start` serves `dist/server/entry.mjs` and refuses any other mode.
-5. **`npx caracms init`**, read the dry run, then **`npx caracms init --write`** and install
-   again (caracms-adopt → section 1). It links the four skills, writes the config, the
-   CLAUDE.md block and the health route. **A template site already has a
+5. **`npx caracms init --cloud`** (or `--self-hosted`), read the dry run, then
+   **`npx caracms init --cloud --write`** (or `--self-hosted --write`) and install again
+   (caracms-adopt → section 1). The flag is the site's mode: choosing it is
+   `caracms-hosting` → section 1, and it's always passed (without a terminal `init`
+   won't pick one). It links the skills, writes the config (with `services`), the
+   CLAUDE.md block and the health route. On a site with a template's `railway.ts`,
+   `--cloud` also prints the move list: hold it for the switch (section 9). **A template site already has a
    `.railway/railway.ts` that describes production: leave it alone and never apply it**
    (applying it can switch production's CDN off). `init` treats a site that has one as
    a Railway site and leaves the file untouched, which is the expected outcome. Set the
@@ -366,16 +372,30 @@ in the editor and in `validate`, naming the page.
 ## 7. Images
 
 - **Keep the bucket keys.** The template's images are imgproxy URLs over the media bucket
-  (`…/unsafe/plain/s3://<bucket>/uploads/…`); the script keeps each `uploads/…` key, so no
-  image is copied and the bucket only grows.
+  (`…/unsafe/plain/s3://<bucket>/uploads/…`); the script keeps each `uploads/…` key, so the
+  content never needs rewriting for where the images live, and the bucket only grows.
 - **`w`/`h` are found once** and cached in `scripts/tina-media-sizes.json` (commit it). The
   first run needs the images reachable (their Tina URLs) or the bucket (`S3_*`); after
   that the cache answers. `validate` warns on any image still missing its size.
-- **imgproxy:** caracms signs every URL (`CARACMS_MEDIA_URL`, `IMGPROXY_KEY`,
+Where the images are served from then depends on the mode (`services`, section 1 step 5):
+
+- **On CaraCMS Cloud:** the keys are kept and `caracms media push` copies them, under the
+  same `uploads/…` keys, from the template's bucket into the site's cloud folder (README:
+  *Moving a site's images in*; `caracms-hosting` → section 3, step 3). The content doesn't
+  change, and the cloud serves them signed from `img.caracms.cloud`, so **no signed
+  imgproxy goes up beside the old one**. Run the push with the bucket's `S3_*` on its
+  command line before the branch environment's first build that shows images, and again
+  before the switch for anything uploaded in Tina since (it skips what's copied).
+  `CARACMS_CLOUD_KEY` alone shows images (a key per place: the laptop, the branch
+  environment). The template's own imgproxy keeps serving Tina's site untouched until
+  the switch.
+- **Self-hosted:** caracms signs every URL (`CARACMS_MEDIA_URL`, `IMGPROXY_KEY`,
   `IMGPROXY_SALT`, `S3_BUCKET`). The template's production imgproxy is unsigned and its
   URLs are cached by the CDN, so **never give it a key while Tina runs**: stand up a new,
-  signed imgproxy beside it, reading the same bucket. Without the media variables the
-  preview draws no images, and a build stops with a sentence naming them.
+  signed imgproxy beside it, reading the same bucket.
+
+In both, without the credentials (the key, or the media variables) the preview draws no
+images, and a build stops with a sentence naming what's missing.
 
 ## 8. Forms
 
@@ -413,19 +433,26 @@ The port is deployed from its branch to its own environment, **never production*
 template sites run on Railway, so this section is written for it. A site on another host
 needs the same pieces there (the caracms README's Hosting section has each host):
 
-- A new environment in the site's Railway project (`caracms`), with its own `web`, Redis, a
-  signed imgproxy and its own submissions bucket. It reads the live media bucket (caracms
-  only ever adds to a bucket). Its variables copy production's where they carry over
-  (`RESEND_API_KEY`, `FORMS_FROM`, the site's `MUX_TOKEN_*`, `CARACMS_ALLOW` from the
-  template's admin allow list), and it deploys from the port branch.
+- A new environment in the site's Railway project (`caracms`), with its own `web` and
+  Redis, deploying from the port branch, and `CARACMS_ALLOW` from the template's admin
+  allow list. Then, by mode:
+  - **On CaraCMS Cloud:** a key of its own, labelled for the environment in
+    app.caracms.com, as `CARACMS_CLOUD_KEY`; no imgproxy, buckets, Resend, Mux or GitHub
+    variables (the key replaces them). Its images are the ones `media push` copied
+    (section 7).
+  - **Self-hosted:** a signed imgproxy and its own submissions bucket. It reads the live
+    media bucket (caracms only ever adds to a bucket). Its variables copy production's
+    where they carry over (`RESEND_API_KEY`, `FORMS_FROM`, the site's `MUX_TOKEN_*`).
 - **`CARACMS_MAIN_BRANCH` and `CARACMS_DRAFTS_BRANCH`** name caracms's two branches
   (default `main` and `drafts`). Set them to the port branch and its own drafts branch
   (`caracms-port`, `caracms-drafts`) **before anyone signs in**: a Publish there then
   commits to the port branch and redeploys the environment, and the live site's `main`
   never moves. With the defaults, the first Publish would land caracms's content on the
   live site's `main`.
-- A GitHub credential on the environment, as for any caracms site: a fine-grained token
-  on the site's repo, or the App (the caracms README → Hosting → GitHub).
+- Self-hosted, a GitHub credential on the environment, as for any caracms site: a
+  fine-grained token on the site's repo, or the App (the caracms README → Hosting →
+  GitHub). On the cloud, the caracms App on the repo covers it (`caracms-hosting` →
+  section 1).
 - Convert with `--recipients <agency address>`, so test submissions never reach the client.
 - **Never `railway config apply` against production**: production's variables are set
   with `railway variables --set` (a template's Railway file can switch its CDN off).
@@ -433,6 +460,9 @@ needs the same pieces there (the caracms README's Hosting section has each host)
 **The switch** (its own task, later): Tina is frozen, the script is re-run on the latest
 `main` without `--recipients`, the branch is merged, production's variables move to
 caracms's (the branch variables unset), and Tina's imgproxy and variables retire.
+Production's hosting is `caracms-hosting`'s: before the merge deploys, follow it (the
+host, section 2; on the cloud, the move list `init --cloud` printed, in its order,
+retiring nothing until its checks hold, section 3).
 
 ## 10. Before calling it done
 

package/src/cloud-middleware.ts

@@ -17,10 +17,15 @@
  * package's own. The build ignores `github.repo`: a site with no repo linked still builds.
  * The key beside the site's own forms and email variables fails it too (caracms-cloud M4
  * Decision 22), whether or not the media is the cloud's.
+ *
+ * With the config's `services` (caracms-cloud M5): `'self-hosted'` never fetches (the key is
+ * ignored); `'cloud'` without the key fails the build with Decision 4's sentence. The build
+ * names the ignored variables once, here; the server, at its first request (`cloudMedia`).
  */
 import type { MiddlewareHandler } from 'astro';
 import { CLOUD_NO_MEDIA, CLOUD_UNREACHABLE_BUILD, isCloudRefusal, heldCloudSettings, loadCloudSettings } from './live/cloud.ts';
 import { cloudFormsConflict } from './live/mode.ts';
+import { CLOUD_KEY_MISSING_PROBLEM, servicesEnv, type Services } from './live/services.ts';
 import { cloudMedia } from './media.ts';
 
 type Env = Record<string, string | undefined>;
@@ -63,12 +68,17 @@ export const onRequest: MiddlewareHandler = async (_context, next) => {
 	return next();
 };
 
-/** The build's start: the settings, or an Error with the sentence that fails the build. Nothing for a site off the cloud. */
-export async function cloudSettingsForBuild(env: Env = process.env): Promise<void> {
+/**
+ * The build's start: the settings, or an Error with the sentence that fails the build. Nothing for a site off the cloud.
+ * `services` is the config's (the integration passes it: this runs outside the bundle, where the build's defines don't reach).
+ */
+export async function cloudSettingsForBuild(env: Env = process.env, services: Services | null = null): Promise<void> {
+	env = servicesEnv(env, services);
+	if (services === 'cloud' && !env.CARACMS_CLOUD_KEY?.trim()) throw new Error(`caracms: ${CLOUD_KEY_MISSING_PROBLEM}`);
 	// caracms-cloud M4 Decision 22: the key with the site's own forms and email variables fails the build too.
 	const conflict = cloudFormsConflict(env);
 	const forms = conflict ? [conflict] : [];
-	const cloud = cloudMedia(env);
+	const cloud = cloudMedia(env, services);
 	if (!cloud) {
 		if (forms.length) throw new Error(`caracms: ${forms.join(' ')}`);
 		return;

package/src/config.ts

@@ -253,8 +253,19 @@ export interface SiteConfig {
 	 * whose pages all show the site's own title.
 	 */
 	titleFallback?: TitleFallback;
+	/**
+	 * Where the site's services come from (caracms-cloud M5 Decision 1): GitHub access,
+	 * media, forms and email, video. `'cloud'`: CaraCMS Cloud, through `CARACMS_CLOUD_KEY`.
+	 * `'self-hosted'`: the site's own variables. The other mode's variables are ignored,
+	 * with a warning (live/services.ts). Unset, the key decides, as before M5 (Decision 3).
+	 * `caracms init --cloud` or `--self-hosted` writes it.
+	 */
+	services?: Services;
 }
 
+/** The config's `services` values (live/services.ts). */
+export type Services = 'cloud' | 'self-hosted';
+
 /** The config's `titleFallback` values (head.ts). */
 export type TitleFallback = 'page-and-brand' | 'site';
 
@@ -366,6 +377,8 @@ export interface ResolvedSite {
 	titleSeparator: string;
 	/** What a page without its own `seo.title` falls back to (`'page-and-brand'` when the config sets none). */
 	titleFallback: TitleFallback;
+	/** Where the site's services come from (caracms-cloud M5 Decision 1); null when the config doesn't say. */
+	services: Services | null;
 	/**
 	 * M8 Decision 10: the URLs the site's own `src/pages/` serves (code-routes.ts), read by the
 	 * integration at setup (and by the commands). Absent before then: nothing is reserved.
@@ -628,7 +641,13 @@ export function resolveSite(config: SiteConfig, root: string): ResolvedSite {
 		fail(`titleFallback must be 'page-and-brand' (the page's title and the site's name) or 'site' (Site Settings' title on every page) (got ${JSON.stringify(config.titleFallback)}).`);
 	}
 
-	return { root, collections, blocks, textStyles, page: abs(config.page), brand, sharedFolder, phoneLinesWidth, repoPath: repoPath!, timeZone, forms, titleSeparator, titleFallback };
+	// caracms-cloud M5 Decision 1: where the site's services come from.
+	const services = config.services ?? null;
+	if (services !== null && services !== 'cloud' && services !== 'self-hosted') {
+		fail(`services must be 'cloud' (CaraCMS Cloud) or 'self-hosted' (the site's own GitHub access, bucket, imgproxy and so on) (got ${JSON.stringify(config.services)}).`);
+	}
+
+	return { root, collections, blocks, textStyles, page: abs(config.page), brand, sharedFolder, phoneLinesWidth, repoPath: repoPath!, timeZone, forms, titleSeparator, titleFallback, services };
 }
 
 interface FieldCheck {