@scribe-platform/cli 0.4.0 → 0.5.0

package/README.md

@@ -32,6 +32,21 @@ It defaults to the hosted admin at `https://scribe.weaverdigital.io` — pass
 scribe login --token <key> --api-url http://localhost:3000
 ```
 
+## Update
+
+```
+scribe update
+```
+
+Installs the latest `@scribe-platform/cli` and copies the bundled
+`scribe-site-builder` Claude Code skill into `~/.claude/skills/`, so the CLI and
+the instructions Claude reads move together. Restart Claude Code afterwards — it
+only discovers skills at session start.
+
+Requires a global npm install; it refuses to guess for a checkout, `npx`, or
+another package manager. A symlinked `~/.claude/skills/scribe-site-builder` is
+left untouched, so a dev checkout's live skill isn't replaced by a copy.
+
 ## Commands
 
 Run `scribe <group> --help` for the full options on any of these.

package/dist/commands/update.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerUpdateCommand(program: Command): void;
+//# sourceMappingURL=update.d.ts.map

package/dist/commands/update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/commands/update.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgDpC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAoD5D"}

package/dist/commands/update.js

@@ -0,0 +1,93 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CliExit, runAction } from '../lib/cli-utils.js';
+import { installSkill, tildify } from '../lib/skill.js';
+const PACKAGE_NAME = '@scribe-platform/cli';
+/** This install's own package root — `<global npm root>/@scribe-platform/cli` when installed globally. */
+function packageRoot() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+/** The version recorded on disk right now, which is the new one once `npm install -g` has run. */
+function installedVersion(root) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8'));
+        return pkg.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function npm(args, inherit) {
+    return spawnSync('npm', args, {
+        stdio: inherit ? 'inherit' : 'pipe',
+        encoding: 'utf-8',
+        // npm is a shell script/.cmd on Windows, so it isn't directly executable there.
+        shell: process.platform === 'win32',
+    });
+}
+/** True when `root` sits inside npm's global package directory — i.e. `npm install -g` owns this install. */
+function isGlobalInstall(root) {
+    const result = npm(['root', '-g'], false);
+    if (result.status !== 0 || typeof result.stdout !== 'string')
+        return false;
+    // Both sides get realpath'd: nvm, Homebrew and Volta all hand out globals
+    // through symlinked prefixes, so a raw string compare gives false negatives.
+    const real = (path) => {
+        try {
+            return realpathSync(path);
+        }
+        catch {
+            return path;
+        }
+    };
+    const globalRoot = real(result.stdout.trim());
+    return real(root).startsWith(globalRoot + sep);
+}
+export function registerUpdateCommand(program) {
+    program
+        .command('update')
+        // Aliased because `scribe site update` already exists: someone reaching for
+        // "upgrade the tool" shouldn't hit a dead end over which word we chose.
+        .alias('upgrade')
+        .description('Update the scribe CLI and the Claude Code skill that ships with it')
+        .action(runAction(async () => {
+        const root = packageRoot();
+        if (!isGlobalInstall(root)) {
+            console.error(`This scribe isn't a global npm install — it's running from ${root}.`);
+            console.error('Update it the way it was installed. For a normal install that is:');
+            console.error(`  npm install -g ${PACKAGE_NAME}@latest`);
+            process.exitCode = 1;
+            throw new CliExit();
+        }
+        const before = installedVersion(root);
+        console.log(`Updating ${PACKAGE_NAME}${before ? ` (currently ${before})` : ''}...`);
+        const install = npm(['install', '-g', `${PACKAGE_NAME}@latest`], true);
+        if (install.status !== 0) {
+            console.error(`\nnpm install -g ${PACKAGE_NAME}@latest failed.`);
+            console.error("If that was a permission error (EACCES), fix npm's global prefix or re-run it with sudo.");
+            process.exitCode = 1;
+            throw new CliExit();
+        }
+        // npm has replaced this package's files in place. The code already
+        // running is the old version, but everything below reads from disk, so
+        // the skill installed is the one that ships with the new version.
+        const after = installedVersion(root);
+        console.log(after && after !== before ? `\nUpdated to ${after}.` : `\nAlready on the latest version${after ? ` (${after})` : ''}.`);
+        const skill = installSkill();
+        if (skill.status === 'missing-source') {
+            console.error("The CLI updated, but its bundled skill wasn't where this version expected it.");
+            console.error('Run `scribe update` once more — the newer code knows where to look.');
+            process.exitCode = 1;
+            return;
+        }
+        if (skill.status === 'symlink') {
+            console.log(`Skill: left ${tildify(skill.dest)} alone — it's a symlink into a checkout.`);
+            return;
+        }
+        console.log(`Skill: installed scribe-site-builder to ${tildify(skill.dest)}.`);
+        console.log('\nRestart Claude Code so it picks up the updated skill.');
+    }));
+}
+//# sourceMappingURL=update.js.map

package/dist/commands/update.js.map

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

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAepC,wBAAgB,aAAa,IAAI,OAAO,CAevC;AAED,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBpC,wBAAgB,aAAa,IAAI,OAAO,CAgBvC;AAED,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -6,6 +6,7 @@ import { registerContentCommands } from './commands/content.js';
 import { registerSubmissionCommands } from './commands/submission.js';
 import { registerSchemaCommands } from './commands/schema.js';
 import { registerBuildCommands } from './commands/build.js';
+import { registerUpdateCommand } from './commands/update.js';
 // Read from package.json at runtime rather than hardcoding: `../package.json`
 // resolves to the package root from both `dist/index.js` (published) and
 // `src/index.ts` (tests), so `scribe --version` can't drift from the release.
@@ -22,6 +23,7 @@ export function createProgram() {
     registerSubmissionCommands(program);
     registerSchemaCommands(program);
     registerBuildCommands(program);
+    registerUpdateCommand(program);
     return program;
 }
 export { ScribeClient, ScribeApiError } from './lib/client.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,8EAA8E;AAC9E,yEAAyE;AACzE,8EAA8E;AAC9E,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,CAC5B,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAC5C,CAAC;AAEzB,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAC9B,OAAO;SACJ,IAAI,CAAC,QAAQ,CAAC;SACd,WAAW,CAAC,uCAAuC,CAAC;SACpD,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,0BAA0B,CAAC,OAAO,CAAC,CAAC;IACpC,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAE/B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,8EAA8E;AAC9E,yEAAyE;AACzE,8EAA8E;AAC9E,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,CAC5B,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAC5C,CAAC;AAEzB,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAC9B,OAAO;SACJ,IAAI,CAAC,QAAQ,CAAC;SACd,WAAW,CAAC,uCAAuC,CAAC;SACpD,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,0BAA0B,CAAC,OAAO,CAAC,CAAC;IACpC,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAE/B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/lib/skill.d.ts

@@ -0,0 +1,45 @@
+/** The Claude Code skill this package ships, as both its directory and skill name. */
+export declare const SKILL_NAME = "scribe-site-builder";
+/** Where Claude Code discovers globally-installed skills. */
+export declare function skillDestination(): string;
+/**
+ * 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 declare function bundledSkillPath(): string | null;
+export type SkillInstallResult = {
+    status: 'installed';
+    dest: string;
+} | {
+    status: 'symlink';
+    dest: string;
+} | {
+    status: 'missing-source';
+};
+/**
+ * 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 declare function installSkill(options?: {
+    source?: string | null;
+    dest?: string;
+}): SkillInstallResult;
+/** Shortens a path for display, so output reads `~/.claude/skills/...`. */
+export declare function tildify(path: string): string;
+//# sourceMappingURL=skill.d.ts.map

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scribe-platform/cli",
-  "version": "0.4.0",
+  "version": "0.5.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,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`).

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

@@ -0,0 +1,231 @@
+# 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.
+
+## 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`}>
+  {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; };
+
+    form.addEventListener('submit', async (event) => {
+      event.preventDefault();
+
+      // Built per control rather than from FormData, so a checkbox sends a real
+      // boolean and an unchecked box sends `false` instead of being omitted.
+      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;
+      }
+
+      const url = `${form.dataset.endpoint}?site=${encodeURIComponent(form.dataset.site)}`
+        + `&collection=${encodeURIComponent(form.dataset.collection)}`;
+
+      say('Sending…');
+      try {
+        const res = await fetch(url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(payload),
+        });
+        if (!res.ok) {
+          // The server's copy is written for the visitor on 400/503; prefer it.
+          const data = await res.json().catch(() => ({}));
+          say(data.error || "Sorry — we couldn't send that. Please try again.");
+          return;
+        }
+        form.reset();
+        say('Thanks — we got it.');
+      } catch {
+        say("Sorry — we couldn't reach us just now. Please call or email instead.");
+      }
+    });
+  })();
+</script>
+```
+
+Note `cf-turnstile-response`: the Turnstile widget injects a hidden input with
+that name into the form, so the loop above 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,99 @@
+# 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;
+  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 |
+| `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.
+
+## 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
+```