@scribe-platform/cli 0.10.0 → 0.12.0

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

@@ -95,16 +95,43 @@ export default defineConfig({
 
 ## `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 `||`:
+Where forms post. It's an **organisation variable** on the GitHub org that owns
+the repo, so every Site follows one value and nobody has to remember to set it
+per repo. Don't add a repo-level variable of the same name: it shadows the org
+one, and `scribe site verify`'s `binding` check reports it as a failure for that
+reason.
+
+**It has no default in a production build, and that is deliberate.** Any
+`PUBLIC_*` value is inlined into the client bundle at build time, so a Site that
+falls back to a guess ships the wrong endpoint — posting a Visitor's message to
+whichever Scribe the fallback named, found out, if ever, by a Client wondering
+why nobody replied. So a missing value fails `astro build` instead. Note that
+`binding` does **not** cover this: it asserts no repo-level override exists, not
+that the org value resolves to anything.
+
+GitHub resolves an unset `vars.*` to an empty string rather than leaving it
+undefined, so `??` would not fall back and an empty value has to count as
+missing:
 
 ```ts
-const apiBase = import.meta.env.PUBLIC_SCRIBE_API_URL || 'https://scribe.weaverdigital.io';
+function scribeApiBase(): string {
+  const configured = import.meta.env.PUBLIC_SCRIBE_API_URL?.trim();
+  if (configured) return configured;
+  if (import.meta.env.PROD) {
+    throw new Error(
+      'PUBLIC_SCRIBE_API_URL is unset. Set it as an organisation variable on the GitHub org that owns ' +
+        'this repo — it has no default in a production build, so this Site posts nowhere by accident.',
+    );
+  }
+  // Dev only, and a *local* admin rather than production: the point of failing
+  // loudly is that a Site cannot reach a real Client's database by omission.
+  return 'http://localhost:3040';
+}
 ```
 
-Any `PUBLIC_*` value is inlined into the client bundle at build time, so changing
-it needs a rebuild, not just a redeploy.
+Call it where the endpoint is actually needed, not at the top of a component
+that takes the endpoint as a prop — otherwise it throws at a caller who already
+supplied one.
 
 ## Local loop
 
@@ -114,10 +141,11 @@ 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.
+`npm run dev` needs no env file: with nothing set, `scribeApiBase()` above
+returns `http://localhost:3040`, which is where a local admin listens. Set
+`PUBLIC_SCRIBE_API_URL` only to point somewhere else. Either way the endpoint
+allows CORS from the Site's registered domain only, so use the admin's own host
+or expect to test submissions against the deployed site.
 
 ## Checklist when a deploy looks wrong
 
@@ -127,5 +155,8 @@ submissions against the deployed site.
   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 with *"PUBLIC_SCRIBE_API_URL is unset"* → the org variable is
+  missing or scoped to selected repositories that don't include this one. That
+  is the check working: fix the variable rather than adding a fallback.
 - 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

@@ -126,13 +126,33 @@ export interface Props {
   prefill?: Record<string, string>;
 }
 
+// Where forms post. **No default in a production build, deliberately** — see
+// `deploy.md`. Dev falls back to a local admin, never production, so
+// `npm run dev` works with no env file and still cannot write to a real
+// Client's database by accident.
+function scribeApiBase(): string {
+  const configured = import.meta.env.PUBLIC_SCRIBE_API_URL?.trim();
+  if (configured) return configured;
+  if (import.meta.env.PROD) {
+    throw new Error(
+      'PUBLIC_SCRIBE_API_URL is unset. Set it as an organisation variable on the GitHub org that owns ' +
+        'this repo — it has no default in a production build, so this Site posts nowhere by accident.',
+    );
+  }
+  return 'http://localhost:3040';
+}
+
 const {
   site, collection, turnstileSiteKey, fields,
-  apiBase = import.meta.env.PUBLIC_SCRIBE_API_URL || 'https://scribe.weaverdigital.io',
+  apiBase: apiBaseProp,
   submitLabel = 'Send',
   prefill = {},
 } = Astro.props;
 
+// Resolved after the props, and only when `apiBase` was not passed: a caller who
+// named it has already answered the question `scribeApiBase()` would throw about.
+const apiBase = apiBaseProp ?? scribeApiBase();
+
 // Scoped to the collection so two forms can share a page.
 const formId = `scribe-form-${collection}`;
 

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

@@ -0,0 +1,207 @@
+# Recipe: being found
+
+> **The commands below are yours to run, not hers to read.** If she's asking
+> what this is or how to do it, answer it the way *Who you're talking to* in
+> [`../SKILL.md`](../SKILL.md) says to: what it is, what she'd say to get it,
+> what's her call, and an offer to do it now.
+
+Everything `scribe site seo <site>` checks, and how to make each one pass.
+
+**This is a going-live job, not a build-time one.** Build the site the way the
+client wants it; then, before promoting, run the check and work through
+whatever it lists. Each failure names the fix below, so the report is the work
+list.
+
+**Run `scribe site seo <site>` before `scribe site promote`**, not after. Going
+live is the deadline for being findable, not the starting gun — and `promote`
+refuses on a failure, the same way it already refuses when DNS is not ready.
+
+Four checks (`robots`, `sitemap`, `canonical`, `indexable`) skip until the site
+is on the client's own domain. That is expected, not a problem, and not
+something to fix — before the cutover they are all asking about the wrong
+address.
+
+`robots` is the one worth understanding, because the site looks wrong when it
+is not. A crawler only ever reads `robots.txt` from the **root of a domain**.
+A site on the free Scribe address lives at `<org>.github.io/<repo>/`, so the
+file a crawler would read belongs to the whole org, not to this site — the
+site's own `public/robots.txt` lands at `/<repo>/robots.txt`, where nothing
+looks. Write the file anyway; it starts working the moment the domain is
+live.
+
+## The four files
+
+Almost everything here comes from four pieces. A site with all four passes all
+eleven checks.
+
+### 1. `site` in `astro.config.mjs`
+
+Nothing else works without it. Astro needs the site's real address to build
+absolute URLs, and a canonical or a sitemap entry that is not absolute is not
+valid.
+
+```js
+import { defineConfig } from 'astro/config';
+import sitemap from '@astrojs/sitemap';
+
+export default defineConfig({
+  // The live address. Set it to the client's domain from the start, even
+  // before the cutover — it is what the sitemap and every canonical are built
+  // from, and it is the one value that cannot be derived from the environment.
+  site: 'https://riversidedental.com',
+  base: process.env.PUBLIC_BASE_PATH || '/',
+  integrations: [sitemap()],
+});
+```
+
+`npm install @astrojs/sitemap` first. The integration writes `sitemap-index.xml`
+and `sitemap-0.xml` into `dist/` on every build, so the page list can never go
+stale the way a hand-written one does.
+
+### 2. `public/robots.txt`
+
+```
+User-agent: *
+Allow: /
+
+Sitemap: https://riversidedental.com/sitemap-index.xml
+```
+
+Three things the check looks for: that the file exists at all, that it does not
+carry a blanket `Disallow: /`, and that it names a `Sitemap:` line. A commented
+`# Sitemap:` does not count.
+
+### 3. A `<SeoHead>` component
+
+One component, used by every layout, so a page cannot be built that forgets
+half of it. This is the piece that covers five of the eleven checks at once.
+
+```astro
+---
+// src/components/SeoHead.astro
+interface Props {
+  title: string;
+  description: string;
+  /** Falls back to the site-wide card image. */
+  image?: string;
+}
+
+// The default is resolved against `Astro.site` below, so it stays correct on
+// the free Scribe address as well as on the client's domain.
+const { title, description, image = '/og-card.png' } = Astro.props;
+
+// Astro.site comes from astro.config.mjs. Astro.url.pathname is this page.
+const canonical = new URL(Astro.url.pathname, Astro.site);
+const imageUrl = new URL(image, Astro.site);
+---
+<title>{title}</title>
+<meta name="description" content={description} />
+<link rel="canonical" href={canonical} />
+
+<meta property="og:title" content={title} />
+<meta property="og:description" content={description} />
+<meta property="og:image" content={imageUrl} />
+<meta property="og:url" content={canonical} />
+<meta property="og:type" content="website" />
+```
+
+Then in the layout:
+
+```astro
+---
+import SeoHead from '../components/SeoHead.astro';
+const { title, description } = Astro.props;
+---
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width" />
+    <SeoHead title={title} description={description} />
+  </head>
+  <body><slot /></body>
+</html>
+```
+
+**`lang="en"` on `<html>` is its own check** and is easy to drop when a layout
+gets rewritten.
+
+**Every page passes its own title and description.** Two pages sharing either
+one is a failure, not a warning — it is the normal result of a layout setting a
+default that a page forgets to override, and it cannot be seen by looking at any
+single page.
+
+### 4. The business, in structured data
+
+On the home page only. This is what puts a business in a local result rather
+than a plain blue link.
+
+```astro
+---
+const business = {
+  '@context': 'https://schema.org',
+  '@type': 'LocalBusiness',       // or a more specific type: Dentist, Plumber, HairSalon
+  name: 'Riverside Dental',
+  url: 'https://riversidedental.com',
+  telephone: '+1-717-555-0100',
+  address: {
+    '@type': 'PostalAddress',
+    streetAddress: '14 Market Street',
+    addressLocality: 'Lancaster',
+    addressRegion: 'PA',
+    postalCode: '17602',
+    addressCountry: 'US',
+  },
+  areaServed: 'Lancaster County, PA',
+};
+---
+<script type="application/ld+json" set:html={JSON.stringify(business)} />
+```
+
+`name`, `url` and `telephone` are what the check requires. The address and
+`areaServed` are not checked and are worth having anyway — they are most of what
+a local result is made of.
+
+**A business that does not want its street address public can leave
+`address` out** and keep `areaServed`. Google's own guidance is that a business
+customers do not visit should hide the address and declare a service area.
+
+**Do not mark up reviews you are displaying for yourself.** Google reserves
+review markup for a site reviewing *other* businesses, and a demo's placeholder
+five stars is exactly the thing that gets a site penalised.
+
+## The two smaller ones
+
+**`contactable`** — a phone number on the home page and on any contact page. A
+`tel:` link counts, and so does a plain number in the text. This exists because
+a real site went live with its number on four guide articles and on none of the
+pages anybody lands on.
+
+```astro
+<a href="tel:+17175550100">(717) 555-0100</a>
+```
+
+**`alt`** — every `<img>` needs an `alt` attribute. `alt=""` passes and is the
+correct markup for a decorative image; a *missing* attribute is the failure.
+
+## What the checks will not tell you
+
+Eleven checks are mechanical. The things that actually decide whether a site
+ranks are not, and `scribe site seo` ends by asking about them rather than
+pretending to measure them:
+
+- Does the site say which town and area the business serves, on the pages a
+  visitor lands on? A local business that never names its town is the single
+  most common reason one does not show up.
+- Is there real client proof — a name, a review, a photo of finished work —
+  rather than a placeholder?
+- Is there a page for each main thing they sell, rather than one page with
+  sections? One page cannot rank for six different searches.
+- Does the contact form sit next to a privacy policy, if it collects a name,
+  email or phone?
+- Would someone who has never heard of this business understand what it does
+  from the home page alone?
+- Is the business claimed on Google with the same name, address and phone number
+  as the site?
+
+Ask the client. "Not yet" is a real answer — the point is that it gets said
+before the site goes live, not that every site has all six.