@scribe-platform/cli 0.6.0 → 0.8.0

package/dist/lib/update-check.d.ts

@@ -0,0 +1,46 @@
+export declare const PACKAGE_NAME = "@scribe-platform/cli";
+/**
+ * Compares two dotted numeric versions. Returns true when `candidate` is newer
+ * than `current`.
+ *
+ * Deliberately not a semver dependency: this package publishes plain
+ * `major.minor.patch` and the one judgement call — what to do with a
+ * prerelease suffix — is answered by ignoring it. A `0.8.0-beta.1` compares
+ * equal to `0.8.0`, so someone already on the beta is not told to "update" to
+ * the release they effectively have, and someone on `0.7.0` is offered it.
+ * Shipping a prerelease to `latest` is not something this project does.
+ */
+export declare function isNewer(candidate: string, current: string): boolean;
+export interface UpdateCheck {
+    current: string;
+    /** Null when the registry couldn't be reached. */
+    latest: string | null;
+    updateAvailable: boolean;
+    /**
+     * False when the registry could not be reached.
+     *
+     * Reported separately from `latest` so a caller can't say "up to date" when
+     * it means "couldn't ask" — the two are the same shape and only one of them
+     * is a fact.
+     */
+    reachable: boolean;
+}
+/**
+ * Whether a newer CLI has been published.
+ *
+ * Runs on **every** session start, with no cache. An earlier version cached
+ * the answer for a day to keep a round trip off the front of each
+ * conversation; measuring it made that look like the wrong trade — 210ms
+ * against being up to a day late on a fix, plus a cache that silently
+ * swallowed the environment override this is tested with. Checking every time
+ * is both faster to the user and less code.
+ */
+export declare function checkForUpdate(current: string): Promise<UpdateCheck>;
+/**
+ * What `npm install -g` is pointed at.
+ *
+ * Overridable so the whole update path can be exercised against a local
+ * `npm pack` tarball before anything is published — see TESTING-UPDATES.md.
+ */
+export declare function installSpec(): string;
+//# sourceMappingURL=update-check.d.ts.map

package/dist/lib/update-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check.d.ts","sourceRoot":"","sources":["../../src/lib/update-check.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY,yBAAyB,CAAC;AAsBnD;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAiBnE;AAuBD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,eAAe,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAe1E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC"}

package/dist/lib/update-check.js

@@ -0,0 +1,103 @@
+export const PACKAGE_NAME = '@scribe-platform/cli';
+/**
+ * The published package is **public**, so this is a plain unauthenticated GET
+ * — no `npm view` subprocess, no auth, no dependency on the admin app knowing
+ * which CLI version is current.
+ *
+ * The `-/package/<name>/dist-tags` route rather than the package document:
+ * it answers in ~200ms with 18 bytes, where the full packument is 30KB of
+ * every version ever published. At that price the check can run at every
+ * session start instead of being cached, which is the difference between
+ * Ashley getting a fix now and getting it tomorrow.
+ */
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+/**
+ * Short on purpose. This runs at session start, in front of someone waiting to
+ * type, and a registry that is slow is indistinguishable from one that is down
+ * — in both cases the right answer is to stop waiting and carry on unupdated.
+ */
+const FETCH_TIMEOUT_MS = 3_000;
+/**
+ * Compares two dotted numeric versions. Returns true when `candidate` is newer
+ * than `current`.
+ *
+ * Deliberately not a semver dependency: this package publishes plain
+ * `major.minor.patch` and the one judgement call — what to do with a
+ * prerelease suffix — is answered by ignoring it. A `0.8.0-beta.1` compares
+ * equal to `0.8.0`, so someone already on the beta is not told to "update" to
+ * the release they effectively have, and someone on `0.7.0` is offered it.
+ * Shipping a prerelease to `latest` is not something this project does.
+ */
+export function isNewer(candidate, current) {
+    const parts = (v) => v
+        .split('-')[0]
+        .split('.')
+        .map((n) => Number.parseInt(n, 10))
+        .map((n) => (Number.isNaN(n) ? 0 : n));
+    const a = parts(candidate);
+    const b = parts(current);
+    for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+        const left = a[i] ?? 0;
+        const right = b[i] ?? 0;
+        if (left !== right)
+            return left > right;
+    }
+    return false;
+}
+/** The registry's `latest` dist-tag, or null if it can't be reached in time. */
+async function fetchLatest() {
+    const registry = process.env.SCRIBE_CLI_REGISTRY ?? DEFAULT_REGISTRY;
+    const url = `${registry}/-/package/${PACKAGE_NAME.replace('/', '%2F')}/dist-tags`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const res = await fetch(url, { signal: controller.signal });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return body.latest ?? null;
+    }
+    catch {
+        // Offline, slow, rate-limited, or a registry that answered with something
+        // unexpected. All the same from here: no opinion about updates.
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Whether a newer CLI has been published.
+ *
+ * Runs on **every** session start, with no cache. An earlier version cached
+ * the answer for a day to keep a round trip off the front of each
+ * conversation; measuring it made that look like the wrong trade — 210ms
+ * against being up to a day late on a fix, plus a cache that silently
+ * swallowed the environment override this is tested with. Checking every time
+ * is both faster to the user and less code.
+ */
+export async function checkForUpdate(current) {
+    // Ahead of the fetch and never persisted. This is the knob the local test
+    // recipe turns — see TESTING-UPDATES.md.
+    const forced = process.env.SCRIBE_CLI_LATEST;
+    if (forced) {
+        return { current, latest: forced, updateAvailable: isNewer(forced, current), reachable: true };
+    }
+    const latest = await fetchLatest();
+    return {
+        current,
+        latest,
+        updateAvailable: latest !== null && isNewer(latest, current),
+        reachable: latest !== null,
+    };
+}
+/**
+ * What `npm install -g` is pointed at.
+ *
+ * Overridable so the whole update path can be exercised against a local
+ * `npm pack` tarball before anything is published — see TESTING-UPDATES.md.
+ */
+export function installSpec() {
+    return process.env.SCRIBE_CLI_PACKAGE ?? `${PACKAGE_NAME}@latest`;
+}
+//# sourceMappingURL=update-check.js.map

package/dist/lib/update-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check.js","sourceRoot":"","sources":["../../src/lib/update-check.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scribe-platform/cli",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Command-line interface for Scribe CMS — scaffold sites, edit content, and triage form submissions from the terminal",
   "license": "MIT",
   "author": "Dave Weaver",

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, 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), and for the agency's prospect pipeline (logging calls, follow-ups, won/lost). 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, 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,6 +27,9 @@ 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/README.md`](./recipes/README.md) lists the five things that are a hard
 contract (because Scribe writes into the repo) as opposed to advice.
@@ -32,6 +40,16 @@ contract (because Scribe writes into the repo) as opposed to advice.
   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 +78,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 +206,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 +244,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 +276,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 +318,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
 
@@ -291,29 +402,62 @@ placeholder / link out to somewhere else on purpose. Don't default to that — t
 "add a photo of X" as "go get a real image and commit it," not "find any URL that
 renders."
 
-## Deleting a site
+## Taking a site down: archive, restore, delete
 
 ```
-scribe site delete <slug> [--yes]
+scribe site archive <slug>              # offline + read-only; deletes nothing
+scribe site restore <slug>              # back online, exactly as it was
+scribe site list --archived             # the archived ones (plain `list` hides them)
+scribe site delete <slug> [--yes]       # permanent; only works on an archived site
 ```
 
-Permanent — deletes the GitHub repo (schema, content, Astro source) and every Mongo
-record for the site, which since RFC 0004 includes its submissions and their event
-history. No undo. Prompts to retype the
-slug unless `--yes` is passed. Requires an **unrestricted** API key (no
-`siteSlugs` restriction) — same rule as `site add`; a key scoped to only that
-site is rejected. Same action is in the admin UI: account menu → **Settings**
-(super-admin only) → **Danger zone**.
-
-Deleting also drops the site's domain from the Turnstile widget — but only if no
-other site still uses that domain, so removing one demo never breaks the contact
-form on the rest. A `Warning:` in the output means that cleanup didn't happen and
-the stale domain is still on the widget; harmless, but tidy it up in Cloudflare.
-
-Side effect worth knowing: if an API key's `siteSlugs` was only that one site,
-deleting it leaves that key with an empty `siteSlugs` array — which the API treats
-as **unrestricted** (every site), not inert. A key scoped to exactly the site you
-delete comes out of it more powerful, not revoked.
+**Archive is how a site comes down** (RFC 0026). It turns GitHub Pages off, so the
+website stops loading. It archives the repo on GitHub, so it is read-only but still
+there. It stops the site's forms accepting submissions and removes the site from
+every list people work from. **Nothing is deleted**: content, schema, submissions and
+their history, requests, metrics and who had access all stay. `scribe site restore`
+brings it back, turning Pages on and starting a deploy, so the site is live again
+in a minute or two. Both need a read-write key belonging to Agency staff. A site
+user's key is refused, even for their own site.
+
+**When someone asks you to delete, remove or take down a site, archive it.** It
+can be undone, so this is an ordinary request for you to carry out, not one to hand
+back:
+
+1. Run `scribe site list` and name the exact slug and its live URL back to them,
+   along with anything that sounds like a sibling they want kept (the `-v2` they're
+   removing versus the `v1` that's live).
+2. Tell them what archiving does: the site goes offline and nothing is deleted. It
+   only touches that one site, not Scribe, their other sites or their account.
+3. When they confirm the slug, run `scribe site archive <slug>` and report the output,
+   including how to bring it back.
+
+`scribe site delete` is a different thing, and it is permanent. It deletes the GitHub
+repo (Astro source, schema, content) and every record Scribe holds for the site,
+including its submissions and their history. There is no undo. It refuses a live site
+with a 409 telling you to archive first, so a single command can never destroy a live
+site. Only run it when the person has explicitly asked for permanent deletion of a
+site that is already archived. "Delete" on its own almost always means "take it
+down", which is what archive does. Without `--yes` it prompts for the slug to be
+retyped. From a shell with no terminal (yours) it exits instead of waiting, so after
+that explicit request it's `--yes`. It needs an **unrestricted** API key (no
+`siteSlugs` restriction), the same rule as `site add`. In the admin, archiving is
+under the site's **Settings → Danger zone**. Restore and **Delete permanently** are on
+the archived site's page in the Staff console: **Sites → Archived**.
+
+An archived site's other commands (`content`, `schema`, `submission`, `build`, …)
+return a 409 saying it's archived, because its repo is read-only. Restore it first.
+Its slug stays taken while it's archived, so `site add` with the same slug says so.
+
+Archiving and deleting both drop the site's domain from the Turnstile widget, but
+only if no other *live* site still uses it, so removing one demo never breaks the
+contact form on the rest. Restoring adds it back. A `Warning:` in the output means
+that cleanup didn't happen. It's harmless, but tidy it up in Cloudflare.
+
+Side effect of the permanent delete worth knowing: if an API key's `siteSlugs` was
+only that one site, deleting it leaves that key with an empty `siteSlugs` array,
+which the API treats as **unrestricted** (every site), not inert. Archiving doesn't
+touch keys at all.
 
 ## `.scribe.yml` field reference
 
@@ -350,10 +494,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,14 @@ 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 |
+
+`requests.md` and `prospects.md` are the odd ones out — they're about the
+agency's own work (its queue and its sales pipeline) 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