@scribe-platform/cli 0.6.0 → 0.8.0

package/skills/scribe-site-builder/recipes/domains.md

@@ -0,0 +1,151 @@
+# Taking a site live on a custom domain
+
+One command does all of it. Reach for `scribe site promote` whenever the ask is
+"publish the site at example.com", "point the domain at the site", "take it
+live", or "set up the custom domain".
+
+```
+scribe site promote <site> --domain example.com --dns-only   # check DNS, change nothing
+scribe site promote <site> --domain example.com              # cut over
+```
+
+## Before the cutover: does the client even have a domain?
+
+The agency user drives this whole thing themselves and is not a developer, so the
+part that needs help is usually everything *before* `promote`. Work it in this
+order, and say which step you're on.
+
+**1. Find out what exists.** Don't take "we have a website" as "we have DNS we can
+edit".
+
+```
+dig +short NS example.com          # who runs the DNS — this is the one that matters
+dig +short example.com             # where the name points today, if anywhere
+dig +short MX example.com          # mail. See the warning below.
+whois example.com | head -30       # registrar, expiry, status (may be privacy-masked)
+```
+
+The registrar on the invoice and the company running the DNS are often different.
+**Follow the nameservers**, because that is where the records have to be added.
+A `whois` that finds nothing registered is also the availability answer.
+
+**2. If they don't own one, the client buys it.** They pay, it is registered in
+their name, and they own it outright — never buy it on their behalf and never put
+it in the agency's registrar. Help with the choice (business name, `.com` or the
+local equivalent first, short, sayable on the phone, no hyphens or clever
+spellings, nothing that pins them to one service or street), check candidates with
+`whois`, and suggest they turn on auto-renew. Then they register it and come back
+with access.
+
+**3. Get DNS access.** Either their registrar login, or a call where they click
+while you read out the records. Either is fine; the second is often faster. What
+they're looking for is the screen listing records by type (`A`, `CNAME`, `MX`,
+`TXT`) with an "Add record" button — every registrar names that screen
+differently ("DNS", "Advanced DNS", "Manage DNS", "Nameservers").
+
+Teach the shape of the task, not one provider's clicks. There is no supported
+registrar; the client uses whatever they already have.
+
+**4. Protect their email before you touch anything.** If `dig MX` returns records,
+that domain carries their mail. The cutover only needs `A`/`CNAME` records for
+the website — **say out loud that the `MX` and mail-related `TXT` records stay
+exactly as they are**, and then make sure that is true. Breaking a client's email
+is far worse than a late website, and it is the one mistake in this flow with no
+quick undo from your side.
+
+**5. Mind the old site.** If the domain currently serves a live website, the
+switch is publicly visible. Agree a time rather than surprising them mid-trading.
+
+Only then move on to `--dns-only` and the cutover below.
+
+## You do not need GitHub admin rights
+
+The Pages configuration call (`PUT /repos/<org>/<repo>/pages`) is made by the
+**admin app**, using Scribe's org-scoped token — not by the signed-in user's
+GitHub account. A site user with a write-scoped API key can run the whole
+cutover. If you catch yourself checking whether someone can administer the repo,
+you are off the supported path: go back to `scribe site promote`.
+
+Corollary: **never** set any of this by hand — not `gh api .../pages`, not the
+GitHub Pages settings page, not a hand-written `public/CNAME`. Each one alone
+produces a broken site (see "Repairing a half-finished cutover" below).
+
+## What promote actually does
+
+In order, each step asserting current state before it writes:
+
+1. Checks that DNS already resolves to GitHub Pages — and refuses to continue if
+   not, because step 2 kills the old project-page URL.
+2. Commits `public/CNAME`. The deploy workflow keys off that file: present means
+   Astro builds with `base: '/'`, absent means `base: '/<repo>'`.
+3. Registers the domain with GitHub Pages via the API. **Both step 2 and step 3
+   are required.** The repo's workflow uses `build_type: workflow`, and Pages
+   does not read `CNAME` out of a build artifact — so the file alone changes the
+   base path without ever requesting a certificate, and the API call alone
+   serves the site from the root with every asset still pointing at `/<repo>/`.
+4. Sets `PUBLIC_SCRIBE_API_URL` so the contact form reaches the admin app, and
+   clears `PUBLIC_BASE_PATH`.
+5. Updates the `Site` record — this is the hostname the public submissions
+   endpoint accepts CORS from.
+6. Adds the domain to the Turnstile widget's allowed-domain list.
+7. Re-enforces HTTPS, and dispatches a deploy.
+
+## DNS
+
+`--dns-only` prints the exact records. In short:
+
+| Hostname | Records |
+|---|---|
+| Bare domain (`example.com`) | all four GitHub Pages **A** records |
+| Subdomain (`www.example.com`) | one **CNAME** → `<org>.github.io` |
+
+**In Cloudflare the record must be DNS-only (grey cloud), not proxied.** The
+orange-cloud proxy blocks the ACME challenge GitHub uses to issue the
+certificate, and promote will refuse with a `cloudflare-proxied` message.
+
+`www` is not automatic. If a bare domain is the target and the client also wants
+`www.example.com` to work, add a `www` CNAME → `<org>.github.io` at the
+registrar; GitHub then redirects it to the apex on its own. Nothing in Scribe
+needs to change for that.
+
+## Re-running is the fix
+
+Promotion is idempotent and there is deliberately no `site demote`. If a run
+fails partway it prints which steps completed; fix the cause and run the same
+command again.
+
+The most common "failure" isn't one: setting a custom domain clears
+`https_enforced`, and GitHub refuses to turn it back on until the certificate
+exists. Promote retries at the end and warns if it isn't ready. Wait a few
+minutes, re-run, done. Until then `http://` won't serve the site.
+
+## Repairing a half-finished cutover
+
+The three pieces of state — the `Site` record's domain, the Pages custom domain,
+and `public/CNAME` — can each be set independently, and nothing in
+`scribe site verify` currently compares them. A half-state looks healthy and
+serves nothing.
+
+| Symptom | What's missing |
+|---|---|
+| Domain 404s, no certificate ever issued | Pages custom domain not registered |
+| Page loads but every asset/link 404s | `public/CNAME` missing, so the build still uses `base=/<repo>` |
+| Old `github.io/<repo>` URL broke and the new domain isn't up | `public/CNAME` landed before the Pages domain was set |
+| Form rejected with a CORS error on the new host | `Site` record still names the old domain |
+
+The fix for all four is the same: `scribe site promote <site> --domain
+example.com`. It reconciles whatever is already correct and writes the rest.
+
+## `site update --domain` is not this
+
+```
+scribe site update <site> --domain example.com    # record + Turnstile ONLY
+```
+
+It rewrites the stored hostname and syncs the Turnstile widget. It does not
+touch DNS, `public/CNAME`, or Pages. Using it to go live leaves a site that
+claims a domain serving nothing — the exact half-state above. The CLI now
+refuses when it detects a cutover (a site still on `<org>.github.io` being moved
+to a real hostname) and points at `promote`; `--record-only` overrides it.
+
+Legitimate use: correcting a typo in a domain that is already live.

package/skills/scribe-site-builder/recipes/forms.md

@@ -310,8 +310,11 @@ inbox already saying so.
 
 - **Two forms, one page:** fine, as long as element ids are unique. The snippet
   above scopes everything to `scribe-form-<collection>`.
-- **`notify:` does not send email.** It's parsed and logged by a console mailer
-  only. Don't promise a client notifications (RFC 0009 is the real thing).
+- **New submissions are emailed** (RFC 0009), but `notify:` is only for addresses
+  with **no Scribe account** — a shared `office@` inbox. Site users on the Site are
+  subscribed by default and manage it themselves under Your Profile → Email
+  notifications; agency admins are opted out by default and opt in per Site. Adding
+  a Scribe user's address to `notify:` is redundant, not helpful.
 - **Rate limiting is per Site and IP, not per form**, so hammering one form while
   testing will also throttle the others.
 - **An unchecked checkbox in `FormData` is absent, not `false`.** The payload

package/skills/scribe-site-builder/recipes/prospects.md

@@ -0,0 +1,192 @@
+# Recipe: prospects
+
+Ashley's calling pipeline lives in Scribe as Clients with `status: 'prospect'`.
+This recipe is about **recording and nurturing prospects she already has** —
+logging what happened on a call, scheduling the next touch, and moving one
+through the funnel. Finding new leads is not covered here: wherever a name comes
+from (a Places sweep, a referral, a drive-by), this recipe starts once it exists.
+
+The same operations are available two ways — `scribe prospect …` on the command
+line, and the `list_prospects` / `get_prospect` / `create_prospect` /
+`log_prospect_call` / `set_prospect_status` MCP tools. They are the same
+endpoints; use whichever the session has.
+
+§3 is the part to actually read. Everything else is mechanics.
+
+## 1. The pipeline
+
+Four statuses, and a prospect only ever sits in the first one:
+`prospect` → `active` (won) or `lost`, with `active` ↔ `churned` afterwards for
+a real client. Nothing is deleted on the way through — a lost prospect keeps its
+whole call log, because the reason it was lost is the point of recording it.
+
+```
+scribe prospect create "A+ Plumbing" \
+  --contact-name "Dana" --phone "555-0101" \
+  --note "Found on the Yelp sweep — no website, 4.6 stars over 90 reviews"
+
+scribe prospect list --due                 # who to call today
+scribe prospect show <id>                  # the full call log before dialling
+
+scribe prospect log <id> \
+  --note "Left a voicemail, no callback yet" \
+  --outcome left-message \
+  --next 2026-10-14
+
+scribe prospect status <id> active         # won
+scribe prospect status <id> lost --reason "Nephew builds their sites"
+```
+
+`list` defaults to a table and takes `--json` for parsing; so does every other
+subcommand. `--status` and `--search` filter, and the default list is
+due-sorted — soonest or most overdue first, undated prospects last.
+
+## 1b. Always pass `--outcome` on a real call
+
+`--outcome` is how far the attempt got, shallowest to deepest:
+
+| Outcome | Use when |
+|---|---|
+| `no-answer` | Nobody picked up |
+| `left-message` | Voicemail, or a message left with someone |
+| `gatekeeper` | Spoke to a person, but not the decision-maker |
+| `reached` | Spoke to the decision-maker |
+| `meeting-set` | Spoke to them **and** got a forward commitment |
+
+**It is optional in the CLI and should be treated as required for any note that
+describes a contact attempt.** It is the only input to the prospect's warmth, so
+a call logged without it leaves the pipeline reading colder and less-worked than
+it really is — and a prospect that was genuinely called three times without an
+outcome recorded will never show as `stalled`, so Ashley keeps calling a dead
+number.
+
+Leave it off only for a note that wasn't an attempt: research, a finding from a
+sweep, a reminder to self.
+
+## 1c. Reading warmth
+
+Every prospect carries a derived `warmth` plus an attempt count. Nothing stores
+it — it is computed from the call log every time it's read, so it changes on its
+own as a prospect goes quiet.
+
+| Warmth | Means | Worth more effort? |
+|---|---|---|
+| `hot` | Meeting set, recently | Yes — this is the closest to a sale |
+| `warm` | Real conversation, recently | Yes |
+| `untouched` | Nobody has called yet | Yes — needs a first attempt |
+| `cold` | Tried a few times, or a conversation that went quiet | Yes — re-warmable |
+| `stalled` | Called repeatedly and **never once** reached a human | No — this one is spent |
+
+`stalled` is the only warmth that means stop. Note that a prospect you once
+reached can never stall, however many no-answers follow — a conversation
+happened, so going quiet is re-warmable rather than unreachable.
+
+Sort with `--sort warm` to rank by likelihood to buy, or `--sort neglected` to
+find prospects nobody has followed up on. `--sort neglected` is worth running
+periodically: a prospect with no follow-up date never appears in `--due` at all,
+so it's the only way those surface.
+
+## 1d. "Do I need more leads?"
+
+```
+scribe prospect pipeline
+```
+
+Reports counts per warmth and a **workable** total, which is everything except
+`stalled`. Read the shape, not the total — a wall of `cold` that hasn't hit the
+stall cutoff is a calling backlog and the answer is "go call them", while a wall
+of `stalled` with workable near zero is a real shortage and the answer is "go
+find names". A low workable count is the signal to prospect; a low total with
+healthy warmth is not.
+
+## 2. Logging a call is the only way to reschedule
+
+`scribe prospect log` is the one command that moves `nextFollowUpAt`. There is
+no "set the follow-up date" command, deliberately: a date that changed with no
+note is a reschedule nobody can explain a month later. Every change to when
+Ashley next calls someone arrives attached to a dated note saying why.
+
+- `--note <text>` is **required**. A reschedule with nothing to say is still
+  worth a sentence ("no answer, trying again Tuesday").
+- `--next <date>` (re)schedules; `--clear-next` removes the scheduled follow-up
+  entirely. They're mutually exclusive.
+- Omit both and the note is appended with the existing follow-up untouched.
+
+Notes are append-only. Nothing edits or deletes one, from either surface.
+
+## 3. What to do unprompted, and what to ask about first
+
+Nothing below is enforced by the CLI or the API — there is no approval flag to
+set and no permission that blocks any of it. It is a judgment call every time,
+and this table is the judgment. Ashley's use of Claude here is a long-term
+mixture of "just handle it" and "check with me first"; getting this wrong in the
+cautious direction wastes a message, and getting it wrong in the other direction
+means she finds out a prospect was written off without her.
+
+| Action | Do it, or propose it? |
+|---|---|
+| `prospect log` — recording a call, a voicemail, a reschedule | **Do it.** This is the routine nurture action. It's additive, it's reversible by logging again, and asking first defeats the point. Include `--outcome`. |
+| `prospect list` / `prospect show` / `prospect pipeline` | **Do it.** Read-only. |
+| `prospect create` | **Check for a near-duplicate first** — `prospect list --search "<part of the name>"`. A clean miss means create it. Anything that looks like the same business under a different spelling, propose it rather than creating a second record. |
+| `prospect update` — a name fix, a new phone number | **Do it** when the correction is unambiguous (a typo, a number from a call she just logged). Propose a wholesale rename. |
+| `prospect status … lost` | **Propose it, with the reason, and wait for a yes.** It removes the prospect from her working list. Being wrong here looks identical to her forgetting about them. |
+| `prospect status … active` | **Always Ashley's call.** A won deal is a business fact she knows and the data doesn't. Never infer it from an enthusiastic note. |
+
+The two `status` rows are the load-bearing ones. When proposing either, say which
+prospect, which reason, and what the last note said — enough that she can answer
+without opening the console.
+
+## 4. Where this is a contract, and where it's advice
+
+| Contract | Advice |
+|---|---|
+| `nextFollowUpAt` changes **only** through `prospect log` — nothing else writes it | How far out to schedule a follow-up |
+| Notes are append-only; no surface edits or deletes one | How much detail to put in a note |
+| A status move never deletes anything, including `lost` | When to give up on a prospect |
+| Deletion isn't in the CLI or the API at all — it's console-only | — |
+| Warmth is derived from the call log; there's no field to set | Which warmth is worth your attention today |
+| `outcome` is a **contact result** only — there is no `demo-sent` | Whether a given note needs an outcome at all |
+
+## Gotchas
+
+- **A prospect's demo site is a real Scribe Site.** Ashley builds it in the CMS
+  because the CMS is what she's selling — own repo in the org, same as a
+  production site (RFC 0006). Create it with the normal `scribe site add`
+  flow; a won deal provisions nothing new, it just points `site.clientId` at the
+  now-`active` Client. RFC 0001's original summary describes a shared static
+  `demos` repo — that is historical and was never built. Don't repeat it.
+- **Attaching that Site to the Client is console-only.** There is no `scribe`
+  command and no `--client` flag on `site add`: it's the **Client** box on
+  Staff console → **Sites** → the site. So "they bought" is two actions — the
+  status move, which you can run, and the attach, which you hand over as a step
+  for Ashley to click. Say both; an `active` Client whose Site is still attached
+  to nobody reads as "nobody is being billed for it" on that page.
+- **`lost` is a status, not a delete.** A lost prospect keeps its whole call log
+  and gains a `lostReason`. It also stays in the default list — both
+  `prospect list` and the console's prospects view cover `prospect` **and**
+  `lost` — so narrow with `--status prospect` to see only live ones. What a
+  lost prospect does drop out of is the due queue: `--due` is prospect-only.
+- **There is no `scribe prospect delete`**, and no `DELETE` under
+  `/api/v1/prospects`. Deleting a Client is reachable only from the staff
+  console, behind its confirmation dialog. If something genuinely needs
+  removing, that's a thing to hand to Ashley, not to work around.
+- **Every prospect command needs a staff-role API key.** A non-staff key gets a
+  403 from the whole `/api/v1/prospects` surface, and a read-only key gets one
+  from everything except `list` and `show`.
+- **`--due` is "now or overdue", not "upcoming".** A prospect scheduled for next
+  week won't appear until the date arrives. Use `prospect list` for the whole
+  funnel.
+- **A prospect with no follow-up scheduled sorts last, not first.** Undated
+  isn't urgent — but it does mean nobody has decided what happens next, so it's
+  worth surfacing to Ashley if one sits there. `--sort neglected` is how.
+- **`demo-sent` is not an outcome**, and neither is `not-interested`. The first
+  is just a note; the second is `prospect status <id> lost --reason ...`.
+  Outcomes record how far a *contact attempt* got, nothing else.
+- **Warmth decays on its own.** A `hot` prospect you don't log anything against
+  becomes `warm` and then `cold` with no action from anyone, because the clock
+  moved. That's intended — it's what stops a stale meeting looking like your
+  best lead — but it means warmth you read last week may differ today.
+- **Don't treat warmth as a prediction.** It's a triage order. The real buying
+  signal is usually in the note prose ("lost a bid because the GC couldn't find
+  them online"), which the enum flattens. Read the notes before telling Ashley
+  who's closest to buying; use the sort to decide where to start reading.

package/skills/scribe-site-builder/recipes/requests.md

@@ -0,0 +1,145 @@
+# Recipe: requests
+
+A **Request** is a Client asking the Agency to do work — a content change, a new
+page, a bug report, a question (RFC 0005). It is the mirror image of a
+submission, and conflating the two is the mistake to avoid:
+
+| | Who wrote it | Who owes the answer | Where it lives |
+|---|---|---|---|
+| **Submission** | a Visitor, through the Client's form | the Client | `scribe submission …`, per site + collection |
+| **Request** | the Client, through their dashboard | **the Agency — you** | `scribe request …`, one queue across every site |
+
+Requests belong to the relationship rather than to a repo: nothing about one is
+in the site's files, and archiving a site doesn't touch them.
+
+§4 is the part to actually read. The rest is mechanics.
+
+## 1. The queue
+
+```
+scribe request list                        # the queue, oldest activity first
+scribe request list --unassigned           # nobody has picked these up
+scribe request list --mine                 # claimed by this key's owner
+scribe request list --site rods-auto-body  # one site's requests
+scribe request list --status done --all    # finished ones, normally hidden
+scribe request show <id>                   # the ask + the whole thread
+```
+
+`list` is the staff queue, so it defaults to **oldest first** — a queue is worked
+from the end that has waited longest — and **hides `done`/`cancelled`**. Asking
+for a closed status by name shows it anyway, so `--status done` doesn't come back
+empty. `--json` on anything; the table prints the ids you need.
+
+`total` in the JSON (and the line under the table) is the whole result, not the
+page. A queue quietly showing 25 of 60 is how one stops being believed.
+
+**Every command here needs a staff-role key.** A site user's key gets a 403 from
+the whole surface, because a thread carries internal notes and claiming one only
+means something from inside the Agency. A key restricted to specific sites must
+pass `--site`, rather than being handed a "queue" that is silently a subset.
+
+## 2. The statuses, and the one that reads backwards
+
+Fixed by the platform — unlike a form's workflow, there is nothing per-site to
+read out of `.scribe.yml`.
+
+| Status | Means | Who owes the next action |
+|---|---|---|
+| `open` | Filed, nobody has picked it up | **The Agency** |
+| `in-progress` | Picked up, and the Client has been told | The Agency |
+| `waiting-on-you` | **Waiting on the *Client*** | The Client |
+| `done` | Finished | Nobody |
+| `cancelled` | Dropped | Nobody |
+
+**`waiting-on-you` is phrased from the Client's side**, because they read it on
+their own dashboard — it is the Client who is being waited on, not Ashley. Read
+as an agency instruction it means the opposite of what it says, and it is the one
+status an agent will get backwards. The CLI prints "Waiting on client" beside it
+for exactly this reason.
+
+Use it only when the work genuinely cannot continue without an answer: it puts a
+"needs you" badge on the Client's dashboard. When they reply, the request comes
+back to `open` on its own.
+
+## 3. Working one
+
+```
+scribe request claim <id>                          # take it; --release hands it back
+scribe request reply <id> --message "On it — today."
+scribe request reply <id> --message "DNS still at their old host" --internal
+scribe request status <id> waiting-on-you
+scribe request status <id> done
+```
+
+The loop that matches how the queue is meant to read:
+
+1. `request show <id>` — the whole thread, before touching anything.
+2. `request claim <id>`.
+3. A short visible reply saying it's picked up. **A reply on an `open` request
+   moves it to `in-progress` by itself** — don't follow it with a `status` call.
+4. Do the work. Usually this is an ordinary content/design change in the site's
+   repo: the request names its site, and `page` often names the page.
+5. Reply with what changed, including the URL, **then** `status done`.
+
+**Never mark a request done without a visible reply.** From the Client's side a
+request that silently turns Done is indistinguishable from being ignored, and
+they have no way to see what was changed.
+
+An **internal note** (`--internal`) is Agency-only: filtered out of every read a
+Client can reach, and it emails nobody. It also moves no status — thinking out
+loud isn't picking something up. Use it for what you found, especially anything
+that needs Dave.
+
+## 4. What to do unprompted, and what to show her first
+
+Nothing below is enforced. There is no approval flag on any of these commands,
+and the API will do whatever it is asked.
+
+| Action | Do it, or propose it? |
+|---|---|
+| `request list` / `request show` | **Do it.** Read-only. |
+| `request claim` | **Do it.** It's a label saying someone is on this, and `--release` undoes it. |
+| `request reply --internal` | **Do it.** The Client never sees it, nothing is emailed, and a note nobody needed is harmless. |
+| The actual work — a content change, a fix, a new page | **Do it**, to the same standard as any other edit: preview before publishing, and say what you changed. |
+| `request reply` (visible) | **Show her the text first**, unless she has said otherwise this session. It is emailed to the Client the moment it's sent, it is permanent, and it speaks for her business. |
+| `request status done` / `cancelled` | **Propose it.** Closing a request is a claim that the work is finished, and the Client reads the close. |
+| `request status waiting-on-you` | **Propose it**, and say what you'd be asking for. It parks the request on the Client's desk. |
+
+The visible-reply row is the load-bearing one, and it is the difference between
+a useful agent and an embarrassing one. "Draft it and let me read it" is the
+default posture; she can and will say "just send them" for a run of routine
+ones, which is a fine thing to honour for that session.
+
+A good way to offer the whole thing, if she asks you to work the queue: do the
+changes, show each reply before sending, propose each close.
+
+## 5. Where this is a contract, and where it's advice
+
+| Contract | Advice |
+|---|---|
+| A Request is created **only** by the Client — there is no `scribe request create`, and no POST on `/api/v1/requests` | What to do when they ask by phone instead |
+| A visible reply on an `open` request moves it to `in-progress` | How quickly to acknowledge |
+| Internal notes are filtered server-side from every Client-reachable read | How much to put in one |
+| Messages are append-only — nothing edits or deletes one | — |
+| A visible reply or a status change emails the Client; an internal note does not | — |
+| `assignTo` is only ever "me" or "nobody" — assigning someone else isn't built | When to release one |
+| Nothing is ever deleted, including a cancelled request | — |
+
+## Gotchas
+
+- **There is no `create`.** A Request filed by the Agency on the Client's behalf
+  would put words in their mouth and make the queue a measure of us rather than
+  of them. If a Client asks for something by phone, either do it as an ordinary
+  edit or ask them to file it so there's a thread. Say that rather than looking
+  for a flag.
+- **A reply is email.** Each one reaches the Client's inbox immediately; there is
+  no draft state and no recall. Compose it as the message it is.
+- **Claiming is Agency-private.** The Client never sees who holds their request —
+  the assignment writes an internal note, not a thread message, so "why isn't
+  Ashley on this one?" is a question they can't ask.
+- **Re-running a status change is safe.** A no-op transition writes no message
+  and sends no email, so setting `done` twice doesn't double-notify.
+- **`--all` is history, not a wider filter.** It only adds `done` and
+  `cancelled`; everything else is in the default list already.
+- **Requests survive their site being archived**, and are unreachable through
+  anything in the repo. Don't go looking for them in the site's files.

package/skills/scribe-site-builder/recipes/schema.md

@@ -129,6 +129,30 @@ produced a clean commit, a green deploy, and no tracking at all.
 Cookieless, so it needs no consent banner, and `defer` keeps it off the
 critical path.
 
+## Changing a collection that already holds content
+
+`scribe schema apply <site> --file <spec>` upserts **one whole collection by
+name** — so the spec you send *is* the collection afterwards. A field you leave
+out is a field you removed. Read the current definition first
+(`scribe schema show <site> <collection>`), edit that, and send it back; never
+write a spec from memory for a collection that already exists.
+
+What each kind of change costs, because a schema edit and a content edit are
+different risks:
+
+| Change | Effect on existing entries |
+|---|---|
+| Add a field | Harmless. Existing entries read it as empty. Add `required: true` only if you're also filling it in, or every existing entry becomes invalid. |
+| Remove a field | The content files keep the value, but nothing reads it and the admin stops showing it. Effectively lost. |
+| Rename a field | There is no rename — it is a remove plus an add, and the old values do not follow. Moving them means editing every content file. |
+| Change a field's type | The declared type generates the build's validation, so an entry whose value no longer fits **breaks the site build** rather than failing quietly. |
+| Remove a collection | `scribe schema remove` **deletes its content folder too**. |
+
+So when someone asks to "rename that field" or "change services to use a number
+for price", say what it will do to the entries that already exist before you run
+it. On a form collection the same applies to its submissions, which are in the
+database and far harder to reconcile than files in a repo.
+
 ## From the CLI instead
 
 Useful when you want the schema without a checkout, or to inspect it while