@scribe-platform/cli 0.4.0 → 0.6.0

package/dist/lib/skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../../src/lib/skill.ts"],"names":[],"mappings":"AAKA,sFAAsF;AACtF,eAAO,MAAM,UAAU,wBAAwB,CAAC;AAEhD,6DAA6D;AAC7D,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAOhD;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,MAAM,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAWjC;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,kBAAkB,CAaxG;AAED,2EAA2E;AAC3E,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG5C"}

package/dist/lib/skill.js

@@ -0,0 +1,70 @@
+import { cpSync, existsSync, lstatSync, mkdirSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** The Claude Code skill this package ships, as both its directory and skill name. */
+export const SKILL_NAME = 'scribe-site-builder';
+/** Where Claude Code discovers globally-installed skills. */
+export function skillDestination() {
+    return join(homedir(), '.claude', 'skills', SKILL_NAME);
+}
+/**
+ * The skill bundled with this install, or null if it can't be found. Two
+ * candidates, tried in order:
+ *
+ *  1. `<package>/skills/<name>` — a published tarball, where `prepack`
+ *     (scripts/bundle-skill.mjs) copied the repo's skill in.
+ *  2. `<repo>/skills/<name>` — a dev checkout, where the skill only exists at
+ *     the monorepo root.
+ *
+ * Both are the same number of levels up from this file whether it runs as
+ * `src/lib/skill.ts` (tests) or `dist/lib/skill.js` (published).
+ *
+ * Resolved at call time, on purpose: `scribe update` calls this *after* `npm
+ * install -g` has replaced this package's files, so it reads the skill that
+ * ships with the version just installed rather than the one the running process
+ * started with.
+ */
+export function bundledSkillPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        join(here, '..', '..', 'skills', SKILL_NAME),
+        join(here, '..', '..', '..', '..', 'skills', SKILL_NAME),
+    ];
+    return candidates.find((candidate) => existsSync(join(candidate, 'SKILL.md'))) ?? null;
+}
+/** lstat without throwing, so a missing path and a broken symlink are both answerable. */
+function lstatOrNull(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Copies the bundled skill into ~/.claude/skills, replacing whatever is there.
+ *
+ * A **symlink** at the destination is left untouched: that's a dev checkout
+ * pointing at the repo's own skills/ directory, and overwriting it with a copy
+ * would silently detach the author's live editing target.
+ */
+export function installSkill(options = {}) {
+    const source = options.source === undefined ? bundledSkillPath() : options.source;
+    const dest = options.dest ?? skillDestination();
+    if (!source)
+        return { status: 'missing-source' };
+    const existing = lstatOrNull(dest);
+    if (existing?.isSymbolicLink())
+        return { status: 'symlink', dest };
+    mkdirSync(dirname(dest), { recursive: true });
+    rmSync(dest, { recursive: true, force: true });
+    cpSync(source, dest, { recursive: true });
+    return { status: 'installed', dest };
+}
+/** Shortens a path for display, so output reads `~/.claude/skills/...`. */
+export function tildify(path) {
+    const home = homedir();
+    return path.startsWith(home) ? `~${path.slice(home.length)}` : path;
+}
+//# sourceMappingURL=skill.js.map

package/dist/lib/skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.js","sourceRoot":"","sources":["../../src/lib/skill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAc,MAAM,SAAS,CAAC;AACvF,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,sFAAsF;AACtF,MAAM,CAAC,MAAM,UAAU,GAAG,qBAAqB,CAAC;AAEhD,6DAA6D;AAC7D,MAAM,UAAU,gBAAgB;IAC9B,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,MAAM,UAAU,GAAG;QACjB,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,CAAC;QAC5C,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,CAAC;KACzD,CAAC;IACF,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AACzF,CAAC;AAOD,0FAA0F;AAC1F,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,CAAC;QACH,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,UAAqD,EAAE;IAClF,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IAClF,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,gBAAgB,EAAE,CAAC;IAEhD,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAEjD,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,QAAQ,EAAE,cAAc,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAEnE,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/C,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;AACvC,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACtE,CAAC"}

package/dist/lib/verify-report.d.ts

@@ -0,0 +1,5 @@
+import type { VerifyReport } from './client.js';
+/** Whether anything actually failed. The caller's exit code hangs off this, and a skip never contributes. */
+export declare function verifyFailed(report: VerifyReport): boolean;
+export declare function printVerifyReport(report: VerifyReport, write?: (line: string) => void): void;
+//# sourceMappingURL=verify-report.d.ts.map

package/dist/lib/verify-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-report.d.ts","sourceRoot":"","sources":["../../src/lib/verify-report.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAUhD,6GAA6G;AAC7G,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAE1D;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAkB,GAAG,IAAI,CAwCzG"}

package/dist/lib/verify-report.js

@@ -0,0 +1,54 @@
+/**
+ * Printing an RFC 0024 verification. Shared by `scribe site verify` and
+ * `scribe site deploy`, so a deploy's verdict reads identically to a standalone
+ * one and there is no second opinion about what counts as a failure.
+ */
+const MARK = { pass: '✓', fail: '✗', skip: '–' };
+/** Whether anything actually failed. The caller's exit code hangs off this, and a skip never contributes. */
+export function verifyFailed(report) {
+    return report.failed.length > 0;
+}
+export function printVerifyReport(report, write = console.log) {
+    write(`\nVerifying "${report.slug}" — ${report.url}`);
+    if (report.pagesChecked.length === 0) {
+        // Not a failure. A Site provisioned minutes ago has nothing deployed to look
+        // at, and saying so is more useful than five identical skip lines.
+        write('\n  Nothing deployed yet — no page could be fetched, so nothing was checked.');
+        for (const error of report.pageErrors)
+            write(`    ${error.url} — ${error.reason}`);
+    }
+    else {
+        const suffix = report.truncated ? ` (capped — more pages exist than were checked)` : '';
+        write(`  ${report.pagesChecked.length} page(s) checked${suffix}\n`);
+    }
+    for (const check of report.checks) {
+        write(`  ${MARK[check.state] ?? '?'} ${check.name.padEnd(10)} ${check.message}`);
+        for (const line of check.detail ?? [])
+            write(`      ${line}`);
+    }
+    if (report.pagesChecked.length > 0 && report.pageErrors.length > 0) {
+        write('\n  Pages that could not be fetched (not counted either way):');
+        for (const error of report.pageErrors)
+            write(`    ${error.url} — ${error.reason}`);
+    }
+    for (const error of report.repoErrors)
+        write(`\n  ! ${error}`);
+    write('');
+    if (verifyFailed(report)) {
+        write(`  ${report.failed.length} check(s) failed: ${report.failed.join(', ')}`);
+    }
+    else if (report.pagesChecked.length === 0) {
+        // Not "all checks passed". `dispatch` reads repo files and runs for every
+        // Site, deployed or not, so a count of what passed would read as a clean
+        // bill of health for a Site nothing is serving. This Site is deliberately
+        // not recorded as verified either.
+        write('  Nothing about the deployed Site was checked, so it is not recorded as verified.');
+        write('  Deploy it, then run this again.');
+    }
+    else {
+        const skipped = report.skipped.length > 0 ? `, ${report.skipped.length} not applicable` : '';
+        write(`  All ${report.ran} applicable check(s) passed${skipped}.`);
+    }
+    write('');
+}
+//# sourceMappingURL=verify-report.js.map

package/dist/lib/verify-report.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scribe-platform/cli",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Command-line interface for Scribe CMS — scaffold sites, edit content, and triage form submissions from the terminal",
   "license": "MIT",
   "author": "Dave Weaver",
@@ -32,6 +32,7 @@
   "files": [
     "bin",
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -43,6 +44,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "prepack": "node scripts/bundle-skill.mjs",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest",
     "lint": "tsc -p tsconfig.json --noEmit",
     "prepublishOnly": "npm run build"

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

@@ -0,0 +1,390 @@
+---
+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). Two ways to do it on demand:
+
+   ```
+   scribe site deploy my-site      # dispatch, wait for the build, then verify
+   scribe build trigger my-site    # dispatch and return immediately
+   ```
+
+   **Prefer `site deploy`.** It waits for the Pages run and then checks the
+   deployed pages against Scribe's five site invariants (RFC 0024) — the tracker,
+   the spam protection on any form, the submission retry queue, the deploy
+   trigger the admin publishes through, and the base path. Every one of those
+   fails silently: nothing errors, the build is green, and the page looks right.
+   `--skip-verify` exists and prints what it gave up.
+
+   `build trigger` stays as the fire-and-forget primitive. It is debounced to once
+   per 5 minutes per site, so repeat calls in that window are a silent no-op —
+   and it tells you nothing about whether the result is correct.
+
+   `scribe site verify my-site` runs the checks on their own, against whatever is
+   currently live. Exits non-zero on a failure, so it works in a script.
+
+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.