@scribe-platform/cli 0.7.0 → 0.9.0

package/skills/scribe-site-builder/SKILL.md

@@ -1,14 +1,19 @@
 ---
 name: scribe-site-builder
-description: Guides building a website on Scribe CMS end to end — designing the Astro site freely against Scribe as its backend, editing the `.scribe.yml` schema, adding one or many forms, the local dev loop, pushing content, and deploying — using the `scribe` CLI and the recipes in `recipes/`. Also the reference for working an existing Scribe site (adding fields/collections, publishing content, triaging form submissions, archiving, restoring or deleting a site). Use whenever the user wants to build/create/start a new website or site with Scribe, add a form to a site, work on an existing Scribe site, or asks about the `scribe` CLI.
+description: Guides building a website on Scribe CMS end to end — designing the Astro site freely against Scribe as its backend, editing the `.scribe.yml` schema, adding one or many forms, the local dev loop, pushing content, and deploying — using the `scribe` CLI and the recipes in `recipes/`. Also the reference for working an existing Scribe site (adding fields/collections, publishing content, triaging form submissions and inquiries, renaming, archiving, restoring or deleting a site), for taking a site live on a custom domain — checking whether a client has a domain, buying one, DNS/CNAME setup, GitHub Pages domain config, HTTPS — for the queue of requests clients have sent the agency (triaging, claiming, replying, closing), for the agency's prospect pipeline (logging calls, follow-ups, won/lost), and for proofs — sending a client work to review (logo boards, mockups, colour schemes), reading what they said, and sending the next version. Use whenever the user wants to build/create/start a new website or site with Scribe, add a form to a site, work on an existing Scribe site, publish/launch/go live with a site, point a site at a domain, set up or fix a custom domain or DNS for a Scribe site, work the inquiries a site has received, triage or reply to a client's request for work, log a call or follow-up with a prospect or client, wants to send a client something to look at or approve (logo ideas, mockups, options, a proof), asks what a client said about work they were sent, wants to do another round or version of something a client reviewed, or asks about the `scribe` CLI.
 ---
 
 # Building a site with Scribe
 
-Source of truth: this file is the merged, agent-facing version of
-`docs/BUILDER-GUIDE.md` and `docs/AGENT-GUIDE.md` in the
-`ai-xerro-agent/projects/scribe` repo. If those docs and this one ever
-disagree, the repo docs win — this file may be behind.
+**This file and the `recipes/` beside it are the whole reference.** They ship
+inside the `@scribe-platform/cli` npm package and are installed with it, so
+everything needed to drive Scribe is here or in `scribe <command> --help`.
+There is no repo to consult and no wiki to look up — if something seems to be
+missing, it is a gap worth telling Dave about, not a file to go hunting for.
+
+(It is generated from `docs/BUILDER-GUIDE.md` and `docs/AGENT-GUIDE.md` in the
+Scribe repo. That matters only to whoever edits it there; those paths do not
+exist on a machine that installed the CLI from npm.)
 
 ## Recipes — read the one you need
 
@@ -22,16 +27,49 @@ instead of reading all of them:
 | [`recipes/collections.md`](./recipes/collections.md) | rendering editor-managed content |
 | [`recipes/forms.md`](./recipes/forms.md) | adding one or more forms |
 | [`recipes/deploy.md`](./recipes/deploy.md) | build/deploy setup or debugging |
+| [`recipes/domains.md`](./recipes/domains.md) | anything about a domain — whether the client has one, getting them one, the DNS, taking a site live on it, fixing one |
+| [`recipes/requests.md`](./recipes/requests.md) | working the queue of jobs clients have asked the agency for |
+| [`recipes/prospects.md`](./recipes/prospects.md) | logging calls and follow-ups on prospects (not site-building) |
+| [`recipes/proofs.md`](./recipes/proofs.md) | sending a client work to review — logo boards, mockups, options — and working the rounds |
 
 [`recipes/README.md`](./recipes/README.md) lists the five things that are a hard
 contract (because Scribe writes into the repo) as opposed to advice.
 
+## Sending a client work to look at: it's a Proof, never an artifact
+
+If the ask is "send them some logo ideas", "show the client these options",
+"get her to approve the mockup" or anything else where a **client looks at
+work and reacts to it**, that is a Proof: read
+[`recipes/proofs.md`](./recipes/proofs.md).
+
+Three rules, in full, because getting them wrong is expensive:
+
+1. **Never run `scribe proof send` without an explicit yes to that send.** It
+   emails a real person and freezes a version permanently. Everything else in
+   the proof workflow is reversible.
+2. **Never use the Artifact tool for client review work**, even when the word
+   "artifact" is used. A claude.ai artifact needs an account to open, is
+   branded Claude rather than the agency, and nothing a client says on it
+   reaches their record — the three problems Proofs exist to fix.
+3. **A Proof needs a client to belong to.** No prospect yet? Offer to create
+   one first.
+
 ## Mental model
 
 - **A site = a GitHub repo.** Schema, content, and the Astro source all live in one
   repo. The admin app and the `scribe` CLI are both just clients that read/write
   files in it via the GitHub API; a local `git clone` is a third client reading/writing
   the same files via git.
+- **Scribe owns the repo's GitHub Pages settings — never set them by hand.** The
+  custom domain, `public/CNAME`, HTTPS enforcement and the build's base path are
+  all written by `scribe site promote`, in one idempotent run. Do **not** reach for
+  `gh api .../pages`, the GitHub web UI, or a hand-written `public/CNAME`: setting
+  one without the others leaves the site 404ing, and the Pages call needs repo
+  admin that a site user doesn't have. The CLI doesn't need it — the admin app
+  makes that call with Scribe's own org token, so a write-scoped API key is enough.
+  If something about a domain looks like it needs a GitHub permission you lack,
+  that's the signal you're on the wrong path, not that you need Dave.
+  See [`recipes/domains.md`](./recipes/domains.md).
 - **Form submissions are the exception — they live in MongoDB, not the repo** (RFC
   0004). A Visitor's name, email and message used to be committed as a YAML file into
   the site's public repo, which published them to the open internet. Nothing writes
@@ -60,41 +98,61 @@ contract (because Scribe writes into the repo) as opposed to advice.
 
 ## Setup (once)
 
-- **CLI**: confirm `scribe --help` works. If it's not found, `npm link` from
-  `packages/cli` in the `ai-xerro-agent/projects/scribe` repo.
+- **CLI**: confirm `scribe --help` works. If it's not found:
+  `npm install -g @scribe-platform/cli`. (Working inside a clone of the Scribe
+  repo itself? `npm link` from `packages/cli` instead — but that is a
+  maintainer's setup, not a user's.)
 - **Login**: `scribe login --token <key>` — mint the key from the
-  admin UI (sign in → account menu → **API Tokens** → New token). Defaults to the
-  hosted admin at `https://scribe.weaverdigital.io`; add `--api-url <url>` only to
-  point at a different instance (a local dev/Docker admin). Writes
-  `~/.scribe/config.json`; every other command reads from there, no per-invocation
-  `--token` flag. If a command fails with a raw `fetch failed`, that's not an API
+  admin UI (sign in → account menu → **API Tokens** → New token). This is the
+  whole machine setup: it writes `~/.scribe/config.json`, installs this skill,
+  and turns on auto-updates. Defaults to the hosted admin at
+  `https://scribe.weaverdigital.io`; add `--api-url <url>` only to point at a
+  different instance (a local dev/Docker admin). Every other command reads that
+  config, no per-invocation `--token` flag. If a command fails with a raw `fetch failed`, that's not an API
   error — it means `apiUrl` in that config doesn't point at anything listening;
   re-run `scribe login` with the right URL.
 
 ## Keeping Scribe up to date
 
-`scribe update` updates the CLI **and** reinstalls this skill, which ships inside
-the `@scribe-platform/cli` npm package:
+**This normally happens by itself and needs no attention.** `scribe login`
+installs this skill and registers a Claude Code `SessionStart` hook that checks npm for
+a newer `@scribe-platform/cli` at the start of **every** session and installs
+it — CLI and this skill together — *before* the session's skills are scanned.
+So a session either started on the current version or was brought to it before
+anyone typed. That is the whole reason the check runs at session start rather
+than mid-conversation: there is never a new skill sitting on disk that the
+running session can't see.
+
+If an update did install, the hook says so in this session's context. Don't
+relay it; it's already done.
+
+If the hook reports that an update **failed** to install, that is for Dave, not
+for the user — it will be an npm permissions or registry problem. Say so plainly
+and carry on; the old version still works.
+
+`scribe update` also runs the whole thing by hand:
 
 ```
-scribe update
+scribe update                  # update the CLI + this skill now
+scribe update --check          # just report whether a newer version exists
+scribe update --install-hook   # repair the auto-update hook if it went missing
 ```
 
-Two things to know:
+One caveat: this **only works for a global npm install** (`npm install -g
+@scribe-platform/cli`). In a dev checkout of the scribe repo it refuses, and if
+`~/.claude/skills/scribe-site-builder` is a symlink into a checkout it leaves it
+alone — that's an author editing the skill in place.
 
-- **Tell the user to restart Claude Code afterwards.** Claude Code only discovers
-  skills at session start, so the session that ran the update is still reading the
-  old copy of this file. If you need the new instructions in the current session,
-  read `~/.claude/skills/scribe-site-builder/SKILL.md` from disk instead of waiting
-  for a restart.
-- **It only works for a global npm install** (`npm install -g
-  @scribe-platform/cli`). In a dev checkout of the scribe repo it refuses, and if
-  `~/.claude/skills/scribe-site-builder` is a symlink into a checkout it leaves it
-  alone — that's an author editing the skill in place.
+Run it by hand when the user says there's a new version, or when a CLI command
+fails in a way that suggests this skill is behind the API (an option the CLI
+doesn't recognise, a command that no longer exists) — the session-start check
+runs before the session, so anything published since then is not here yet.
 
-Run it when the user says there's a new version, or when a CLI command fails in a
-way that suggests this skill is behind the API (an option the CLI doesn't
-recognise, a command that no longer exists).
+**If a hand-run update installs a new version mid-session**, tell the user in one
+sentence, in their words: *"I've updated Scribe — close this chat and start a new
+one so I pick up the new instructions."* Then stop relying on anything in this
+file that the update might have changed; if you need the new text now, read
+`~/.claude/skills/scribe-site-builder/SKILL.md` from disk.
 
 ## Workflow: building a new site
 
@@ -168,6 +226,11 @@ recognise, a command that no longer exists).
 8. **Domain cutover — only when a customer's own hostname is ready.** Skip this
    entirely for demo sites; the GitHub Pages default already works.
 
+   If it *isn't* ready — the client may not own a domain, may not know who holds
+   it, or may have mail on it — that part is the bulk of the work and is in
+   [`recipes/domains.md`](./recipes/domains.md) under "Before the cutover". The
+   client buys their own domain, at their own registrar, in their own name.
+
    Check what DNS the domain needs first. This changes nothing:
    ```
    scribe site promote my-site --domain example.com --dns-only
@@ -201,12 +264,22 @@ recognise, a command that no longer exists).
    sync — fix it in the Cloudflare dashboard, or the contact form silently rejects
    real visitors on that domain.
 
+   **You do not need GitHub repo admin rights for any of this.** The Pages API call
+   is made by the admin app using Scribe's org token, so a write-scoped API key is
+   enough. If you find yourself checking whether the user can administer the repo,
+   you've left the supported path.
+
    `scribe site update my-site --domain example.com` only edits the stored record
-   and the Turnstile widget. Use it to correct a domain, never to cut a site over.
+   and the Turnstile widget. Use it to correct a domain, never to cut a site over —
+   the CLI now refuses that and points at `promote`. Deeper reference, including how
+   to repair a half-finished cutover: [`recipes/domains.md`](./recipes/domains.md).
 
 ## Working an existing site
 
 ```
+scribe site promote <site> --domain <domain> [--dns-only]   # take it live on a real domain
+scribe site update <site> --turnstile-key <key>             # correct stored settings only
+
 scribe content list <site> [--collection <name>] [--json]
 scribe content read <site> <path> [--json]
 scribe content publish <site> <file>                # validates against schema
@@ -223,8 +296,19 @@ scribe submission list <site> <collection> [--status <status>] [--page <n>] [--j
 scribe submission update <site> <collection> <id> [--status <s>] [--note <n>]
 scribe submission export <site> <collection> [--format csv|json] [--status <s>] [--out <file>]
 scribe submission delete <site> <collection> <id> [--yes]        # staff only
+
+scribe request list [--site <slug>] [--status <s>] [--type <t>] [--mine|--unassigned] [--all] [--page <n>]
+scribe request show <id>                            # the ask + the whole thread, internal notes included
+scribe request claim <id> [--release]
+scribe request reply <id> --message <text> [--internal]
+scribe request status <id> <open|in-progress|waiting-on-you|done|cancelled>
 ```
 
+- **"Publish/launch the site at example.com" means `scribe site promote`** — the full
+  domain cutover in one command — step 8 of the build workflow above, and in full in
+  [`recipes/domains.md`](./recipes/domains.md). It is not `content publish`, and
+  it is not `site update --domain` (which only rewrites the stored record and would
+  leave the site 404ing on the new host — the CLI refuses that now and tells you so).
 - `scribe schema apply` is the way to add a form (or any collection with fields): it
   takes a YAML/JSON file describing **one whole collection**, upserts it by `name`,
   and validates through the admin's own parser first — so a reserved `status` field,
@@ -254,6 +338,53 @@ scribe submission delete <site> <collection> <id> [--yes]        # staff only
   **staff** role — a site user's API key gets a 403. It prompts for the id unless
   `--yes` is passed. There is deliberately no equivalent in the admin UI, so don't go
   looking for a delete button on the inbox.
+- **`scribe request` is the other queue, and the opposite direction.** A submission is
+  a Visitor contacting the *client*; a Request is the **client contacting the agency**
+  to ask for work. One cross-site queue, staff-only, nothing in any repo. Three things
+  to know before touching it, with the rest in
+  [`recipes/requests.md`](./recipes/requests.md):
+  - **`waiting-on-you` means waiting on the _client_** — every status is phrased for
+    the Client's own dashboard. Read as an instruction to the agency it means the
+    opposite of what it says.
+  - **A visible `reply` is an email to the client**, sent immediately and permanently.
+    Show the user the text before sending unless they've said not to bother.
+    `--internal` is the Agency-only note: no email, invisible to the client, moves no
+    status.
+  - **There is no `create`.** A Request comes from the Client; filing one for them
+    would put words in their mouth. Say so rather than hunting for a flag.
+
+## A site's two names, and the jobs only the admin UI can do
+
+A site has a **slug** and a **display name**, and only one of them moves.
+
+- The **slug** (`riverside-dental`) is the site's identity: the repo name, the
+  Pages URL, `?site=` on the submissions endpoint, and the argument to every
+  `scribe` command. **There is no rename** — not in the CLI, not in the admin.
+  Moving a site to a different slug means provisioning a new site. So when
+  someone is choosing a slug, it is worth one sentence of care up front.
+- The **display name** is a label, and is editable any time: in the Staff console,
+  **Sites → the site → the Name field** at the top of the Details card, saved on
+  blur. It is allowed on archived sites too. `scribe site add --name` sets it at
+  creation; nothing in the CLI changes it afterwards.
+
+A rename reaches the consoles and notification subjects and **nothing a Visitor
+sees** — not the URL, and not `.scribe.yml`'s `siteName`, which is the website's
+own copy of its name in a repo the rename doesn't write to. If the name is wrong
+on the published pages too, that's a separate content edit in the repo.
+
+Three other things live only in the Staff console, so route the user there rather
+than hunting for a flag:
+
+| Job | Where |
+|---|---|
+| Rename (display name) | Sites → the site → Name |
+| Attach a site to a Client, or detach it | Sites → the site → **Client** |
+| Star a site (sorts it to the top of the Sites list, and is what the staff Home page's Sites card shows) | Sites → the star |
+
+And one that isn't available at all: **creating a login for a client's own
+people**. There is no `scribe` command for it and no self-serve invite — user
+management is super-admin only. "Give the client access to edit their content" is
+a request to hand to Dave, with the site slug and who needs the login.
 
 ## Images — never hotlink, always commit the file
 
@@ -383,10 +514,21 @@ On a **form collection** specifically, since RFC 0004 moved submissions into Mon
 - **An `image` field is rejected** on a form collection. The old path uploaded a
   Visitor's file straight into the public repo, and a Mongo document is the wrong place
   for a blob. Deferred to RFC 0007 (object storage).
-- **`notify:` does not send email.** It runs, but through a `ConsoleMailer` that only
-  logs — no address has ever received anything. Real delivery is RFC 0009. Don't
-  promise a client they'll be emailed on a new submission; the inbox and its
-  `needs-you` badge are the actual notification today.
+- **New submissions are emailed** (RFC 0009, on RFC 0021's mailer), and
+  `notify:` is no longer how a *person* subscribes. Who gets one:
+  - **Site users on that Site are subscribed by default** — a lead nobody hears
+    about is the bug this closes, so the people whose business it is are opted in
+    unless they opt out.
+  - **Agency admins are not**, because they can reach every Site. They opt in per
+    Site per collection, under **Your Profile → Email notifications** in the admin.
+  - **`notify: [...]` now means addresses with no Scribe account** — a shared
+    `office@` inbox. Don't put a Scribe user's address in it; they manage their own.
+
+  The mail is best-effort and never fails the Visitor's POST, and `Reply-To` is
+  the Visitor's own address when the form has a field named `email` — that exact
+  name is the only signal, so a form whose address field is called something else
+  gets no `Reply-To`. So a client *can* be promised email on a new submission. The
+  inbox and its `needs-you` badge remain the thing of record.
 
 Per field: `name`, `type`, `label`, `required`, `default`, `pattern`, `hidden`,
 `readonly`, `isBody` (this field is the markdown body, not frontmatter), `list`

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

@@ -1,8 +1,7 @@
 # Recipes
 
-Patterns for building an Astro site against Scribe as the backend. Per
-[RFC 0010](../../../docs/proposals/0010-agent-authored-forms.md) these are
-**advice, not enforcement** — read the one you need, adapt it to the site you're
+Patterns for building an Astro site against Scribe as the backend. Per RFC
+0010 these are **advice, not enforcement** — read the one you need, adapt it to the site you're
 building, and ignore the rest. There is no template to conform to and no
 generated config to keep in sync.
 
@@ -12,6 +11,15 @@ generated config to keep in sync.
 | [`collections.md`](./collections.md) | rendering content (posts, products, events) that editors manage in Scribe |
 | [`forms.md`](./forms.md) | putting one or more forms on the Site |
 | [`deploy.md`](./deploy.md) | setting up or debugging the build and deploy |
+| [`domains.md`](./domains.md) | finding out whether a client has a domain, getting them one, the DNS, taking a Site live on it, or repairing one |
+| [`requests.md`](./requests.md) | working the queue of jobs clients have asked the agency for |
+| [`prospects.md`](./prospects.md) | recording and nurturing prospects in the calling pipeline |
+| [`proofs.md`](./proofs.md) | sending a client work to review (logo boards, mockups) and working the rounds |
+
+`requests.md`, `prospects.md` and `proofs.md` are the odd ones out — they're
+about the agency's own work (its queue, its sales pipeline, and the work it
+sends clients to review) rather than anything in a Site's repo, and they live
+here because the `scribe` CLI is the interface for all of it.
 
 ## The part that isn't advice
 

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