@scribe-platform/cli 0.4.0 → 0.6.0

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

@@ -0,0 +1,87 @@
+# Recipe: rendering content collections
+
+A content collection (anything without `form: true`) is a folder of files the
+admin writes directly into the repo. Your job is to read them from the `path` the
+schema declares, in the `format` it declares. That part isn't negotiable — the
+admin commits those files and expects them there. How you route, style and lay
+them out is entirely yours.
+
+## The two formats
+
+- **`yaml-frontmatter`** — markdown: `---` frontmatter, then a body. The body is
+  whichever field has `isBody: true`.
+- **`yaml`** — a plain `.yml` data file, no body.
+
+Files are named `<slug>.md` / `<slug>.yml`, and the slug is the URL slug.
+
+## With Astro content collections
+
+Glob the schema's paths. Astro wants its own `src/content.config.ts`, so keep the
+loader list in step with `.scribe.yml` rather than hardcoding one Site's names:
+
+```ts
+// src/content.config.ts
+import { defineCollection, z } from 'astro:content';
+import { glob } from 'astro/loaders';
+
+const cars = defineCollection({
+  loader: glob({ pattern: '**/*.md', base: './content/cars' }),
+  // Loose on purpose: an editor adding a field in Scribe shouldn't fail the
+  // build before you've had a chance to render it.
+  schema: z.object({
+    title: z.string(),
+    make: z.string().optional(),
+    year: z.number().optional(),
+    price: z.number().optional(),
+    images: z.array(z.string()).default([]),
+    active: z.boolean().default(true),
+  }).passthrough(),
+});
+
+export const collections = { cars };
+```
+
+Then render as usual with `getCollection('cars')`.
+
+Keep the zod schema **permissive** (`.passthrough()`, `.optional()`). A strict
+schema turns "an editor added a field" into a failed deploy, and the editor has
+no way to see why.
+
+## Images
+
+Uploaded images are committed under `public/` and the frontmatter stores the
+**absolute site path** — `/images/cars/bugatti-chiron.jpg`. Two consequences:
+
+- Don't use `astro:assets` `Image` on them; they aren't in `src/`. A plain `<img
+  src={...}>` is correct.
+- On a project page (no custom domain) the Astro `base` is `/<repo>`, so prefix
+  stored paths with it or they 404 in the demo:
+
+```astro
+---
+const base = import.meta.env.BASE_URL.replace(/\/$/, '');
+---
+<img src={`${base}${car.data.images[0]}`} alt={car.data.title} />
+```
+
+This is the single most common way a demo site looks broken while the custom
+domain version looks fine.
+
+## Don't hardcode one Client's collections
+
+The same code gets reused across Sites whose collections are named differently.
+Drive pages off the schema where it's cheap:
+
+```astro
+---
+import { contentCollections } from '../lib/scribe';
+const sections = contentCollections().filter((c) => c.name !== 'posts');
+---
+{sections.map((c) => <a href={`/${c.name}`}>{c.label ?? c.name}</a>)}
+```
+
+## Local content
+
+`scribe content pull <site>` fetches the live content into the repo so you can
+build against real data. A Site also usually keeps a `content/` folder committed,
+which is what the deploy builds from.

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

@@ -0,0 +1,126 @@
+# Recipe: build and deploy
+
+Sites deploy to GitHub Pages from their own repo. Two parts of this are a
+contract with Scribe rather than a preference: the workflow must accept
+`workflow_dispatch`, and the Astro `base` must follow `public/CNAME`.
+
+Both are checked against the deployed output by `scribe site verify <site>`, along
+with the tracker (`schema.md`) and the two form contracts (`forms.md`) — see
+RFC 0024. Run it after a deploy rather than reading this list and hoping.
+
+## Why `workflow_dispatch` matters
+
+When an editor publishes in the admin, Scribe commits the content file and then
+calls `scribe build trigger` → `dispatchWorkflow`. Without
+`workflow_dispatch: {}` the dispatch fails and **the editor's change never goes
+live** even though the admin says it saved. Keep it even if you also build on
+push.
+
+## Why the base path follows CNAME
+
+A bare project page lives at `https://<org>.github.io/<repo>/`, so Astro needs
+`base: '/<repo>'`. Once a custom domain is verified, the admin writes
+`public/CNAME` and the site serves from the root, so `base` must become `/`.
+Deciding this in the workflow means a domain going live needs no code change.
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: {}      # required — Scribe dispatches this on publish
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm install
+
+      - name: Compute Pages base path
+        id: base
+        run: |
+          if [ -f public/CNAME ]; then
+            echo "path=/" >> "$GITHUB_OUTPUT"
+          else
+            echo "path=/${{ github.event.repository.name }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - run: npm run build
+        env:
+          PUBLIC_SCRIBE_API_URL: ${{ vars.PUBLIC_SCRIBE_API_URL }}
+          PUBLIC_BASE_PATH: ${{ steps.base.outputs.path }}
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+And in `astro.config.mjs`:
+
+```js
+export default defineConfig({
+  base: process.env.PUBLIC_BASE_PATH || '/',
+  // ...
+});
+```
+
+## `PUBLIC_SCRIBE_API_URL`
+
+Where forms post. It's a **repo variable**, and GitHub resolves an unset
+`vars.*` to an empty string rather than leaving it undefined — so `??` won't
+fall back. Use `||`:
+
+```ts
+const apiBase = import.meta.env.PUBLIC_SCRIBE_API_URL || 'https://scribe.weaverdigital.io';
+```
+
+Any `PUBLIC_*` value is inlined into the client bundle at build time, so changing
+it needs a rebuild, not just a redeploy.
+
+## Local loop
+
+```
+npm install
+npm run dev                  # iterate on design
+npm run build && npm run preview
+```
+
+To test forms locally, point `PUBLIC_SCRIBE_API_URL` at a local admin
+(`http://localhost:3040`) — but note the endpoint only allows CORS from the
+Site's registered domain, so use the admin's own host or expect to test
+submissions against the deployed site.
+
+## Checklist when a deploy looks wrong
+
+- Images 404 on the demo URL but work on the custom domain → missing `base`
+  prefix (see `collections.md`).
+- Editor published but the site is stale → `workflow_dispatch` missing, or the
+  workflow failed; check the Actions tab.
+- Form says "Failed to fetch" → `PUBLIC_SCRIBE_API_URL` baked in wrong, or the
+  origin isn't the Site's registered domain.
+- Build fails after an editor added a field → the content zod schema is too
+  strict (see `collections.md`).

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

@@ -0,0 +1,318 @@
+# Recipe: forms
+
+A Site can have **as many forms as it likes**. Each one is a collection in
+`.scribe.yml` with `form: true`, each gets its own inbox and its own workflow in
+the admin, and each posts to the same endpoint with a different `collection`.
+
+Design the form however you want. Only the POST contract below is fixed.
+
+## 1. Declare the collection
+
+Write a spec file and apply it — don't hand-edit `.scribe.yml` in the repo, since
+the admin treats the committed file as the source of truth and will overwrite
+you:
+
+```yaml
+# rsvps.yml
+name: rsvps
+label: Event RSVPs
+description: Replies to the invitations on the events page.
+path: content/rsvps
+format: yaml
+form: true
+fields:
+  - { name: fullName,     type: string,  required: true }
+  - { name: email,        type: string,  required: true }
+  - { name: mobile,       type: string,  label: Mobile }
+  - { name: eventTitle,   type: string,  label: Event, required: true }
+  - { name: guests,       type: number }
+  - { name: attending,    type: boolean, label: I'll be there }
+  - { name: dietaryNotes, type: text }
+workflow:
+  states:
+    - { name: pending,   label: Awaiting reply, kind: needs-you }
+    - { name: waitlist,  label: Waitlisted,     kind: waiting }
+    - { name: confirmed, label: Confirmed,      kind: closed }
+    - { name: declined,  label: Declined,       kind: closed }
+```
+
+```
+scribe schema apply <site> --file rsvps.yml      # or --file - to pipe it in
+scribe schema show <site> rsvps                  # read it back
+```
+
+Rules the apply will enforce for you:
+
+- `status` and `createdAt` are **reserved** — they're columns on the submission,
+  not fields you declare.
+- A form collection may **not** declare an `image` field; a visitor-submitted
+  file has nowhere to be stored yet (RFC 0007).
+- `workflow.states` is a list of `{ name, label, kind }` where `kind` is
+  `needs-you`, `waiting` or `closed`. A new submission starts in the first
+  `needs-you` state, so order matters. `hidden: true` keeps a state out of the
+  filter dropdown.
+- `path` and `format` are ignored for a form collection (submissions live in the
+  database), but the parser still wants them.
+
+## 2. POST contract
+
+```
+POST /api/submissions?site=<slug>&collection=<name>
+```
+
+- **Body:** JSON, or `application/x-www-form-urlencoded`, or
+  `multipart/form-data`. Values are coerced to the declared types, so a checkbox
+  posting `"on"` becomes `true` and `"4"` becomes `4`. Posting real JSON types is
+  still better — it's unambiguous.
+- **Turnstile is required.** Send the widget's token as `cf-turnstile-response`.
+  A missing or empty token is a **401**, always — there is no bypass.
+- **Responses:** `200 {ok:true}`; `400` with a human-readable `error` for a
+  validation failure; `401` verification failed; `429` rate limited (per site and
+  IP, **shared across all of that Site's forms**); `503` with visitor-facing copy
+  in `error` when the database is unreachable — show that message as-is, it's
+  written for them; `502` when the Site's `.scribe.yml` is unusable.
+- **CORS** is allowed only from the Site's registered domain, so test from the
+  real host (or `localhost` against a local admin).
+
+Never report success on a non-2xx. A form that says "Thanks!" after a 503 loses
+the message.
+
+## 2b. Three things about a form that are contract, not style
+
+Design the markup however you like. These three are checked by
+`scribe site verify` (RFC 0024), because each one fails **silently** — nothing
+errors, the build is green, and the page looks right to whoever just deployed it.
+
+| Contract | How to satisfy it |
+|---|---|
+| The form says which collection it posts to | `data-collection="<name>"` on the `<form>`, or `collection=<name>` in its `data-endpoint`/`action` |
+| Turnstile protects it | Cloudflare's script tag, plus a `cf-turnstile` element whose `data-sitekey` is **this Site's** key |
+| It never reports a false success | the retry queue in §3, declared with `data-scribe-retry` on the `<form>` |
+
+The first is how Scribe finds your form in the built HTML at all. It is also
+already load-bearing — your submit handler reads it to build the POST URL — so
+there is no extra attribute to remember.
+
+`data-scribe-retry` is the one attribute that exists purely as a claim, because
+"this form queues a failed submission" has no other signature in the output. Put
+it on the `<form>` in the same component that implements the queue, and don't put
+it on a form that doesn't: it is read as an assertion that the behaviour below is
+present.
+
+A widget keyed to a **different** Site's `turnstileSiteKey` is as bad as no
+widget — the endpoint verifies the token against this Site's secret and 401s it.
+
+## 3. A form component
+
+Generic and schema-driven, which is the useful starting point when the fields
+come from `.scribe.yml`. Adapt or replace the markup freely.
+
+```astro
+---
+// src/components/ScribeForm.astro
+export interface Props {
+  site: string;
+  collection: string;
+  turnstileSiteKey: string;
+  fields: Array<{ name: string; label?: string; type: string; required?: boolean }>;
+  apiBase?: string;
+  submitLabel?: string;
+  /** Values the page knows that the visitor shouldn't retype, e.g. which event this is. */
+  prefill?: Record<string, string>;
+}
+
+const {
+  site, collection, turnstileSiteKey, fields,
+  apiBase = import.meta.env.PUBLIC_SCRIBE_API_URL || 'https://scribe.weaverdigital.io',
+  submitLabel = 'Send',
+  prefill = {},
+} = Astro.props;
+
+// Scoped to the collection so two forms can share a page.
+const formId = `scribe-form-${collection}`;
+
+function labelFor(f: { name: string; label?: string }) {
+  return f.label ?? f.name.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ')
+    .replace(/^./, (c) => c.toUpperCase());
+}
+// Control comes from the declared type. Name-based guessing is only for the
+// keyboard hint on an email/phone input — never for required-ness or the control.
+function inputType(f: { name: string; type: string }) {
+  if (f.type === 'number') return 'number';
+  if (/mail/i.test(f.name)) return 'email';
+  if (/phone|mobile|tel|cell/i.test(f.name)) return 'tel';
+  return 'text';
+}
+---
+<form id={formId} data-site={site} data-collection={collection} data-endpoint={`${apiBase}/api/submissions`} data-scribe-retry>
+  {fields.map((f) => (
+    prefill[f.name] !== undefined ? (
+      <input type="hidden" name={f.name} value={prefill[f.name]} />
+    ) : f.type === 'boolean' ? (
+      <label class="checkbox">
+        <input name={f.name} type="checkbox" /> {labelFor(f)}
+      </label>
+    ) : f.type === 'text' ? (
+      <label>{labelFor(f)}<textarea name={f.name} required={f.required} rows="4"></textarea></label>
+    ) : (
+      <label>{labelFor(f)}<input name={f.name} type={inputType(f)} required={f.required} /></label>
+    )
+  ))}
+  <div class="cf-turnstile" data-sitekey={turnstileSiteKey}></div>
+  <button type="submit">{submitLabel}</button>
+  <p class="form-status" role="status" aria-live="polite"></p>
+</form>
+
+<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
+<script is:inline define:vars={{ formId }}>
+  (function () {
+    const form = document.getElementById(formId);
+    if (!form) return;
+    const statusEl = form.querySelector('.form-status');
+    const say = (m) => { if (statusEl) statusEl.textContent = m; };
+
+    const { site, collection, endpoint } = form.dataset;
+    const storageKey = `scribe_pending_submission_${site}_${collection}`;
+
+    // Last resorts only. The endpoint puts visitor-facing copy in the response
+    // body (RFC 0004) so the server can change what a Visitor reads without
+    // rebuilding every Site. These two cover the cases where there is no body:
+    // the request never arrived, or it came back with nothing usable.
+    const UNREACHABLE = "We couldn't send that yet — it's saved and will retry.";
+    const GENERIC = "We couldn't send that. Please try again, or call or email us instead.";
+
+    const readPending  = () => { try { return JSON.parse(localStorage.getItem(storageKey)) ?? null; } catch { return null; } };
+    const savePending  = (p) => { try { localStorage.setItem(storageKey, JSON.stringify(p)); } catch {} };
+    const clearPending = ()  => { try { localStorage.removeItem(storageKey); } catch {} };
+
+    // Built per control rather than from FormData, so a checkbox sends a real
+    // boolean and an unchecked box sends `false` instead of being omitted.
+    function collect() {
+      const payload = {};
+      for (const el of form.elements) {
+        if (!el.name) continue;
+        if (el.type === 'checkbox') payload[el.name] = el.checked;
+        else if (el.type === 'number') payload[el.name] = el.value === '' ? null : Number(el.value);
+        else payload[el.name] = el.value;
+      }
+      return payload;
+    }
+
+    async function send(payload) {
+      const url = `${endpoint}?site=${encodeURIComponent(site)}&collection=${encodeURIComponent(collection)}`;
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+      });
+      if (res.ok) return;
+      // A non-2xx means the server answered and said why, which is a different
+      // thing from never reaching it. `answered` picks the message; `retryable`
+      // decides whether a later attempt could plausibly land.
+      const body = await res.json().catch(() => ({}));
+      const error = new Error((body.error ?? '').trim() || GENERIC);
+      error.answered = true;
+      error.retryable = res.status >= 500;
+      throw error;
+    }
+
+    form.addEventListener('submit', async (event) => {
+      event.preventDefault();
+      const payload = collect();
+      say('Sending…');
+      try {
+        await send(payload);
+        clearPending();
+        form.reset();
+        say('Thanks — we got it.');
+      } catch (err) {
+        // Never claim a success the server didn't give, and never paper over
+        // its message with ours.
+        if (err.answered) {
+          if (err.retryable) savePending(payload);
+          say(err.message);
+          return;
+        }
+        savePending(payload);
+        say(UNREACHABLE);
+      }
+    });
+
+    // Replay on the next page load, which is what makes the queue worth having.
+    (async function retryPending() {
+      const pending = readPending();
+      if (!pending) return;
+      try {
+        await send(pending);
+        clearPending();
+        say('Thanks — we got it.');
+      } catch (err) {
+        // Replaying a rejection (a validation error, a rate limit) on every
+        // page load would loop forever, so drop it and show what the server
+        // said. Anything else stays queued for next time.
+        if (err.answered && !err.retryable) {
+          clearPending();
+          say(err.message);
+        }
+      }
+    })();
+  })();
+</script>
+```
+
+**The retry queue is the part not to skip.** Without it, a submission that fails
+because the Visitor's connection dropped or the database was briefly unreachable
+is gone — and the only person who could tell you is the Visitor, who thinks they
+already got in touch. That is the single most expensive silent failure a Scribe
+Site has, which is why `data-scribe-retry` is checked rather than suggested.
+
+One subtlety worth knowing: a replay reuses the **stored payload**, which still
+carries the `cf-turnstile-response` from the original attempt. Turnstile tokens
+are short-lived, so a replay much later is rejected as a 401 — `answered` and not
+`retryable`, so it is dropped with the server's message rather than looping. The
+queue's real job is the retry that happens seconds or minutes later, not days.
+
+Note `cf-turnstile-response`: the Turnstile widget injects a hidden input with
+that name into the form, so `collect()` picks it up automatically. If you build
+the payload by hand, include it explicitly.
+
+## 4. Put it on a page
+
+Placement is entirely yours — the schema says nothing about where a form goes.
+Read the collection out of the schema and pass its fields in:
+
+```astro
+---
+// src/pages/events/[...slug].astro
+import ScribeForm from '../../components/ScribeForm.astro';
+import { loadScribeSchema } from '../../lib/scribe';   // see schema.md
+
+const schema = loadScribeSchema();
+const rsvps = schema.collections.find((c) => c.name === 'rsvps');
+const { event } = Astro.props;
+---
+<h2>Coming along?</h2>
+<ScribeForm
+  site={schema.site}
+  collection="rsvps"
+  turnstileSiteKey={schema.turnstileSiteKey}
+  fields={rsvps.fields}
+  submitLabel="Send my RSVP"
+  prefill={{ eventTitle: event.data.title }}
+/>
+```
+
+`prefill` is how a form on a detail page captures its context — the visitor
+never types which event they're replying to, and the submission arrives in the
+inbox already saying so.
+
+## Gotchas
+
+- **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).
+- **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
+  loop above avoids this; if you use `FormData`, add a hidden companion input.

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

@@ -0,0 +1,141 @@
+# Recipe: reading the schema
+
+`.scribe.yml` sits in the Site's repo root and is the contract between Scribe and
+the Site: it names the collections, their fields, where content lives, and which
+collections are forms. The admin keeps it current — editors change it through the
+UI and the CLI writes to it — so the committed copy is authoritative at build
+time.
+
+**Read it directly. Don't generate a config file from it.** Older sites have a
+`scripts/generate-config.mjs` that flattened the schema into a `site-config.ts`;
+that layer lost field types and could only ever represent one form, which is why
+RFC 0010 drops it.
+
+## A loader
+
+```ts
+// src/lib/scribe.ts
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parse } from 'yaml';
+
+export interface ScribeField {
+  name: string;
+  type: 'string' | 'text' | 'number' | 'boolean' | 'date' | 'select' | 'rich-text' | 'image';
+  label?: string;
+  required?: boolean;
+  hidden?: boolean;
+  isBody?: boolean;
+  options?: Array<string | { value: string; label?: string }>;
+}
+
+export interface ScribeCollection {
+  name: string;
+  path: string;
+  format?: 'yaml' | 'yaml-frontmatter';
+  label?: string;
+  description?: string;
+  form?: boolean;
+  fields: ScribeField[];
+  view?: { primary?: string; sort?: string; fields?: string[] };
+  workflow?: { states?: Array<{ name: string; label?: string; kind?: string; hidden?: boolean }> };
+}
+
+export interface ScribeSchema {
+  site: string;
+  siteName?: string;
+  turnstileSiteKey?: string;
+  umamiWebsiteId?: string;
+  umamiScriptUrl?: string;
+  collections: ScribeCollection[];
+}
+
+let cached: ScribeSchema | undefined;
+
+/** Build-time only — reads the repo's own `.scribe.yml`. */
+export function loadScribeSchema(): ScribeSchema {
+  // Resolve from the working directory, NOT from `import.meta.url`. Astro
+  // bundles this module into `dist/.prerender/chunks/`, so a module-relative
+  // path looks for `.scribe.yml` next to the bundle and fails the build with
+  // `ENOENT: .../dist/.scribe.yml`.
+  cached ??= parse(readFileSync(resolve(process.cwd(), '.scribe.yml'), 'utf-8')) as ScribeSchema;
+  return cached;
+}
+
+export const formCollections = () => loadScribeSchema().collections.filter((c) => c.form === true);
+export const contentCollections = () => loadScribeSchema().collections.filter((c) => c.form !== true);
+export const collection = (name: string) =>
+  loadScribeSchema().collections.find((c) => c.name === name);
+```
+
+Needs `yaml` in the Site's dependencies (a `devDependency` is fine — this only
+runs at build time, and CI installs dev deps before `npm run build`).
+
+## What the keys mean
+
+| Key | Meaning |
+|---|---|
+| `site` | the Site slug — what you pass as `?site=` when submitting a form |
+| `siteName` | display name |
+| `turnstileSiteKey` | public Turnstile key for forms |
+| `umamiWebsiteId` | analytics id for this Site — **render it, see below** |
+| `umamiScriptUrl` | where the analytics tracker is served from |
+| `collections[].path` | where content files live, relative to the repo root |
+| `collections[].format` | `yaml-frontmatter` (markdown with a body) or `yaml` (data only) |
+| `collections[].form` | `true` means submissions, not files — **no content to render** |
+| `fields[].isBody` | this field is the markdown body, not frontmatter |
+| `fields[].hidden` | internal; don't render it, don't put it on a form |
+| `view.primary` / `view.sort` | the editor's preferred title and sort field |
+
+A `form: true` collection has **no files in the repo** — its submissions are rows
+in Scribe's database, readable in the admin or via
+`scribe submission list`/`export`. Don't try to render it as content.
+
+## Analytics — put the tracker in your layout
+
+Scribe writes `umamiWebsiteId` and `umamiScriptUrl` into `.scribe.yml` when it
+provisions a Site (ADR 0001). **Nothing renders them for you** — a Site whose
+layout omits this snippet collects no visitor data at all, and the Client's
+monthly Report has an empty website section.
+
+In the `<head>` of your base layout:
+
+```astro
+---
+import { loadScribeSchema } from '../lib/scribe';
+const { umamiWebsiteId, umamiScriptUrl } = loadScribeSchema();
+---
+{umamiWebsiteId && umamiScriptUrl && (
+  <script defer src={umamiScriptUrl} data-website-id={umamiWebsiteId}></script>
+)}
+```
+
+Both guards matter: a Site provisioned before analytics existed, or one where
+registration failed, has neither key, and a `<script>` with no id is a request
+that reports nothing.
+
+**This is the one thing here you cannot fix later.** Analytics data is not
+retroactive — Umami only knows about visits that happened while the script was
+on the page. A month shipped without it is a month that stays empty forever, so
+add it when you build the layout, not when someone asks for a Report.
+
+`scribe site verify <site>` checks the **deployed pages** for it, every page it
+can reach rather than just the homepage — which is the point. A Site can have
+the tracker in one layout and serve some pages through another, and the repo
+looks fine either way. Rod's Auto Body renders through `Site.astro` while still
+carrying an unused `Base.astro`; patching the obvious file there would have
+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.
+
+## From the CLI instead
+
+Useful when you want the schema without a checkout, or to inspect it while
+working:
+
+```
+scribe schema show <site>              # readable summary
+scribe schema show <site> rsvps        # one collection
+scribe schema show <site> --json       # raw, for piping
+```