@scribe-platform/cli 0.2.2 → 0.5.0

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

@@ -0,0 +1,373 @@
+---
+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.
+---
+
+# 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.
+
+## Recipes — read the one you need
+
+Per RFC 0010 the Astro site is **yours to design**. Scribe doesn't supply a
+template you must conform to; it supplies patterns. Load the relevant file
+instead of reading all of them:
+
+| Recipe | Use it when |
+|---|---|
+| [`recipes/schema.md`](./recipes/schema.md) | you need the Site's collections and field types |
+| [`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/README.md`](./recipes/README.md) lists the five things that are a hard
+contract (because Scribe writes into the repo) as opposed to advice.
+
+## 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.
+- **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
+  submissions to a repo any more: a submission is a Mongo document with a status and
+  an append-only event history, and `content/<form-collection>/` doesn't exist.
+- **`.scribe.yml`** at the repo root is the schema — every collection (content type)
+  and its fields, plus which collections are forms. Prefer the CLI over hand-editing,
+  because it validates before committing and because the admin treats the committed
+  file as authoritative: `scribe schema show <site>` to read,
+  `scribe schema apply <site> --file <spec>` to create or replace a whole collection,
+  `scribe schema add`/`remove` for a bare stub or a removal. Hand-editing still works
+  for a one-line tweak in a clone.
+- **A Site can have many forms.** Each `form: true` collection gets its own inbox,
+  its own workflow states and its own nav badge in the admin, and posts to
+  `/api/submissions?site=…&collection=…`. See `recipes/forms.md`.
+- **No merge tooling.** Admin-UI edits and local edits both land as commits on the
+  same repo. If they touch the same file, resolve it with plain `git pull` / merge —
+  there's no `scribe` conflict command.
+- **`scripts/generate-config.mjs` is legacy.** Sites scaffolded before RFC 0010 have
+  it, and it regenerates `src/content.config.ts` and `src/site-config.ts` on
+  `predev`/`prebuild` — so in those repos, don't hand-edit those two files, it will
+  overwrite you. It flattens the schema lossily (field *names* with no types, and
+  only the **first** `form: true` collection), so a site that needs real types or a
+  second form should read `.scribe.yml` directly instead — see `recipes/schema.md`.
+  New sites shouldn't add it.
+
+## 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.
+- **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
+  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:
+
+```
+scribe update
+```
+
+Two things to know:
+
+- **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 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).
+
+## Workflow: building a new site
+
+1. **Scaffold.**
+   ```
+   scribe site add --slug my-site
+   ```
+   Creates the GitHub repo, pushes the Astro starter template
+   (home/blog/contact pages, a default `.scribe.yml` with `posts` and `inquiries`
+   collections), and registers the site with the admin — one call.
+   `--name` sets a display name (defaults to the slug); `--form-collection` renames
+   the default contact-form collection (defaults to `inquiries`).
+
+   `--domain` and `--turnstile-key` are both optional and normally omitted. The
+   domain defaults to the `scribe-platform.github.io` Pages host every new site is
+   served from, and the Turnstile site key defaults to the shared widget configured
+   on the admin app — one widget covers all sites, scoped by its allowed-domain
+   list rather than by key. Pass them only to override those defaults. The real
+   customer domain comes later, at step 8.
+
+2. **Clone it locally.**
+   ```
+   scribe site clone my-site
+   ```
+   Plain `git clone`. Nothing Scribe-specific happens locally — `npm run dev` works,
+   `.scribe.yml` is just a file in the repo root.
+
+3. **Define/edit the schema.** Hand-edit `.scribe.yml` — add fields under
+   `collections[].fields[]` (see field reference below). Once saved,
+   `npm run dev` / `npm run build` locally regenerate the Astro content types
+   automatically (via `predev`/`prebuild`) — no separate sync step. A `git push` of
+   `.scribe.yml` is enough to reach the admin, which reads it live from GitHub,
+   cached **8 minutes** per repo — after a schema push, the admin UI may lag up to
+   8 minutes before showing it.
+
+4. **Build content locally.** Normal Astro dev loop — content files live under
+   `content/<collection>/*` per the collection's `path`/`format`.
+
+5. **Push to Scribe.** Two ways:
+   - `git push` — commits schema and/or content straight to the repo. Normal path.
+   - `scribe content publish <site> <file>` — pushes one local file through the
+     API, validating it against the schema server-side first (a raw `git push`
+     skips that validation).
+
+6. **Admin-UI edits, pulled back down.** The admin UI writes commits to the same
+   repo — `git pull` locally to pick them up. Conflicts resolve as ordinary git
+   merge conflicts, nothing purpose-built.
+
+7. **Deploy.** Any push to the repo's default branch runs `.github/workflows/deploy.yml`
+   automatically (build + GitHub Pages). `scribe build trigger my-site` dispatches
+   the same workflow on demand without a new commit — debounced to once per 5
+   minutes per site, so repeat calls in that window are a silent no-op.
+
+8. **Domain cutover — only when a customer's own hostname is ready.** Skip this
+   entirely for demo sites; the GitHub Pages default already works.
+
+   Check what DNS the domain needs first. This changes nothing:
+   ```
+   scribe site promote my-site --domain example.com --dns-only
+   ```
+   It prints the records to add at the registrar. An apex domain needs the four A
+   records; a subdomain needs only the CNAME. **In Cloudflare the record must be
+   DNS-only (grey cloud), not proxied** — the orange-cloud proxy blocks the
+   challenge GitHub uses to issue the site's certificate.
+
+   Once the records are in place and resolving:
+   ```
+   scribe site promote my-site --domain example.com
+   ```
+   This does the whole cutover in one go: writes `public/CNAME`, registers the
+   domain with GitHub Pages, points the contact form at the admin app, updates the
+   hostname the public form endpoint accepts submissions from, adds the domain to
+   the Turnstile widget, enforces HTTPS, and redeploys.
+
+   It **refuses to run until DNS actually points at GitHub Pages**, because the
+   cutover kills the old project-page URL — if DNS isn't ready the site is
+   unreachable at both addresses. Fix the DNS and run it again rather than reaching
+   for `--force`.
+
+   **Re-running is safe and is the fix for anything that goes wrong.** Every step
+   checks the current state before writing, so a run that fails halfway is repaired
+   by running the same command again. If it reports that GitHub is still issuing
+   the certificate, wait a few minutes and re-run to finish — until then `http://`
+   won't serve the site.
+
+   If it prints a `Warning:` about the Turnstile widget, the domain list did **not**
+   sync — fix it in the Cloudflare dashboard, or the contact form silently rejects
+   real visitors on that domain.
+
+   `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.
+
+## Working an existing site
+
+```
+scribe content list <site> [--collection <name>] [--json]
+scribe content read <site> <path> [--json]
+scribe content publish <site> <file>                # validates against schema
+scribe content delete <site> <path>
+scribe content versions <site> <path> [--json]       # commit history
+scribe content revert <site> <path> --sha <sha>      # checks out old version as new commit
+
+scribe schema show <site> [collection] [--json]                # read the schema
+scribe schema apply <site> --file <spec|->                     # create/replace a whole collection
+scribe schema add <site> <collection-name> [--path <path>]     # bare stub only, no fields
+scribe schema remove <site> <collection-name>                  # deletes its folder too
+
+scribe submission list <site> <collection> [--status <status>] [--page <n>] [--json]
+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 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,
+  an `image` field on a form collection, or a malformed workflow is reported before
+  anything is committed. `--file -` reads from a pipe. Full worked example in
+  [`recipes/forms.md`](./recipes/forms.md).
+- `scribe schema add` only appends a bare `{name, path}` stub with no fields; it's for
+  starting a content collection interactively. There is still no *field*-level
+  command — `schema apply` replaces the whole collection, so include every field.
+- `scribe content publish` reads a **local file at the given repo-relative path**,
+  parsing `---`-delimited YAML/JSON frontmatter (or a bare YAML/JSON object with no
+  body).
+- `scribe submission list` paginates (1-based `--page`); `--json` gives the whole page
+  object, so `total` tells you whether there's a page 2.
+- **`<id>` is a Mongo ObjectId**, as printed by `submission list` — not a filename and
+  not a repo path. There's no path inference any more; submissions aren't files.
+- `--note` **appends** to the submission's history. It never overwrites an earlier
+  note, and it leaves the submission's own `updatedAt` alone — a note is something
+  someone wrote *about* the lead, not a change to it.
+- `submission export` writes to stdout unless `--out` is given, so it pipes
+  (`scribe submission export my-site inquiries > leads.csv`). CSV is for a
+  spreadsheet and is lossy on purpose: its columns come from the collection's schema,
+  so the header row is identical between exports even when a batch left a field blank,
+  and it carries no history and no visitor IP or user agent. `--format json` is
+  lossless, with each submission's events nested under it.
+- `submission delete` is permanent, cascades the submission's history, and needs a
+  **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.
+
+## Images — never hotlink, always commit the file
+
+**A `type: image` field is just a string.** Nothing in Scribe validates that its
+value is an uploaded image — the schema doesn't know or care whether you write
+`/uploads/some-photo.jpg` or `https://images.unsplash.com/photo-xyz`. When you (the
+agent) are hand-authoring content files directly in a cloned repo — which is the
+normal CLI workflow — **do not put an external image URL (Unsplash or otherwise)
+into an image field's value.** It looks fine at first glance and then quietly means
+the site depends forever on a third-party host it doesn't control, the image was
+never actually reviewed/chosen for that specific listing, and it breaks the "this
+site's content lives in this repo" model the rest of Scribe assumes.
+
+Instead, every image an agent puts into content must be a **real file committed to
+the site's own repo**, the same way the admin's own upload feature does it:
+
+1. Get the actual image bytes — download it (a real stock photo, something the
+   user supplied, whatever the source) to a local temp file.
+2. Save it into the cloned repo at `public/uploads/<name>`, with a name unique
+   enough not to collide (mirror the admin's own convention:
+   `<timestamp>-<safe-filename>`, letters/digits/`._-` only).
+3. Reference it in the content file's frontmatter as `/uploads/<name>` — a
+   repo-relative path, not the original external URL.
+4. Commit and push (`public/uploads/...` + the content file) together, same as any
+   other content change. There's no `scribe` CLI command for this — it's a plain
+   file in the repo, same as everything else.
+
+This applies to `list: true` image fields too — one committed file per array entry,
+same convention. A single-image field (`type: image`, no `list`) and a list one both
+end up as `/uploads/...` paths; only the shape (string vs. array of strings)
+differs.
+
+The one case where a bare external URL is fine: the user explicitly says to leave a
+placeholder / link out to somewhere else on purpose. Don't default to that — treat
+"add a photo of X" as "go get a real image and commit it," not "find any URL that
+renders."
+
+## Deleting a site
+
+```
+scribe site delete <slug> [--yes]
+```
+
+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.
+
+## `.scribe.yml` field reference
+
+Per collection: `name`, `label`, `path`, `format` (`yaml-frontmatter` for normal
+content; also
+`json-frontmatter`/`toml-frontmatter`/`yaml`/`json`/`toml`/`datagrid`/`code`/`raw`),
+`fields[]`, `view` (`{primary, sort, fields, search, default}` — controls the admin
+list view), and the Scribe extensions `description` (shown under the title on the
+collection's list/inbox page in the admin), `form: true` (renders as an inbox),
+`workflow: {states}` (form collections only), `notify: [...]` (recipients on new
+submissions).
+
+On a **form collection** specifically, since RFC 0004 moved submissions into Mongo:
+
+- **Many per site is supported and normal.** Every `form: true` collection is an
+  independent inbox with its own workflow, badge and `?collection=` value; a schema
+  with two of them needs no special handling. The rate limiter is the one shared
+  thing — it's keyed per Site and IP, not per form.
+- **Submitted values are coerced to the declared type** before validation, so a
+  form posting `FormData` works: a checkbox's `"on"` becomes `true`, `"4"` becomes
+  `4`. A value that can't be coerced still fails with a readable message. JSON
+  bodies, url-encoded and multipart are all accepted.
+- `path` and `format` are **ignored** — there are no files to lay out. Leave them;
+  they're harmless, and the parser doesn't read them for a form collection.
+- `workflow` takes `{states: [...]}` only. The old `field:` key is gone, and so is the
+  legacy shorthand where `states` was a list of bare strings — a schema still written
+  that way now fails to parse rather than being silently guessed at. Each state is an
+  object: `{name, label, kind, hidden}`, where `kind` is `needs-you` | `waiting` |
+  `closed` (it drives the inbox's nav badge, which counts `needs-you`) and `hidden`
+  keeps a state like `spam` out of the default view while leaving it selectable.
+- **`status` and `createdAt` are reserved field names** and can't be declared in
+  `fields[]`. `status` is a real column on the submission and `submittedAt` replaces
+  `createdAt`; both render as columns the schema doesn't have to mention.
+- **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.
+
+Per field: `name`, `type`, `label`, `required`, `default`, `pattern`, `hidden`,
+`readonly`, `isBody` (this field is the markdown body, not frontmatter), `list`
+(`true` or `{min, max, collapsible}`), `options` (for `type: select`). For
+`type: image` fields specifically, see **Images** above — its value (or each
+value in the array, if `list`) must be a committed `/uploads/...` path, not an
+external URL.
+
+**Field `type` — stick to the implemented list.** The admin has a working editor
+for: `string`, `text`, `rich-text`, `number`, `boolean`, `date`, `image`, `select`.
+The type enum also accepts `block`, `code`, `file`, `object`, `reference`, `uuid` —
+these parse fine but the admin has no editor for them yet, so a field using one
+falls back to a raw/unstyled view. Don't reach for them unless that's specifically
+acceptable for this site.
+
+**Quote date- and time-like values in `string` fields.** When hand-writing a
+content file, `when: 2026-09-28` or `at: 12:30` is read by Astro's YAML loader as
+a Date and a number, not a string — so a field declared `type: string` fails its
+generated `z.string()` schema and **the site build breaks**. Write
+`when: "2026-09-28"`. Fields declared `type: date` are immune (they generate
+`z.coerce.date()`, which takes either form), and anything written by the admin or
+by `scribe content publish` is quoted for you. This only bites on raw hand-edited
+files committed with `git push`.
+
+## Gotchas
+
+- Schema changes are instant locally, but cached **8 minutes** in the admin/API
+  after a push — don't chase "why hasn't this shown up yet" faster than that.
+- `scribe site clone` is a thin `git clone` wrapper — once cloned, it's an ordinary
+  git repo, nothing more.
+- A raw `git push` of content skips schema validation; `scribe content publish`
+  doesn't.
+- There's no merge-conflict tooling anywhere in the CLI — resolve like any git
+  conflict.

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

@@ -0,0 +1,31 @@
+# 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
+building, and ignore the rest. There is no template to conform to and no
+generated config to keep in sync.
+
+| Recipe | Use it when |
+|---|---|
+| [`schema.md`](./schema.md) | you need to know what collections and fields a Site has |
+| [`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 |
+
+## The part that isn't advice
+
+Scribe doesn't only serve the Site — it **writes into the Site's repo** and
+triggers its build. The admin commits content files and uploaded images, writes
+`public/CNAME` when a domain is verified, and `scribe build trigger` dispatches
+the deploy workflow. So these five things are a contract, not a preference:
+
+1. Content lives at each collection's `path`, in its `format`.
+2. Images live under `public/` at the path stored in the item's frontmatter.
+3. The presence of `public/CNAME` decides Astro's `base`.
+4. The deploy workflow accepts `workflow_dispatch`.
+5. Forms POST to `/api/submissions?site=<slug>&collection=<name>`.
+
+Get one of these wrong and the failure shows up *after* an editor hits publish,
+on the live site, not while you're building. Everything else — routing, styling,
+page structure, which pages exist, where a form goes — is yours.

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,122 @@
+# 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`.
+
+## 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`).