@erclx/canon 4.70.0 → 4.71.0

package/README.md

@@ -8,7 +8,7 @@ canon is a CLI and Claude Code plugin that stops your AI conventions drifting ap
 
 ![The canon catalog, listing skills, governance rules, and standards with the count each ships, the workflow skills named, and a sample of the rule and standard names](assets/hero.png)
 
-The counts above are read from the catalogs when the image is built, so they're what the repo actually ships today.
+The counts above are read from the catalogs when the image is built, so they're what the repo actually ships today. See it live at [canon.erclx.dev](https://canon.erclx.dev).
 
 ## It runs on itself
 

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.70.0",
+  "version": "4.71.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/canon-cli/SKILL.md

@@ -62,6 +62,10 @@ Run `canon tooling sync <stack> <target> --check` for the list resolved against
 - `commitlint.config.js`
 - `scripts/verify.sh`
 
+### cloudflare
+
+- `.github/workflows/deploy.yml`
+
 ### nextjs
 
 - `eslint.config.js`

package/claude/skills/deploy-cloudflare/REQUIREMENT.md

@@ -0,0 +1,37 @@
+---
+name: deploy-cloudflare
+description: What the Cloudflare Pages setup gap is, which of the four manual steps this skill closes, and why the credential and the custom domain stay the operator's
+---
+
+# Deploy Cloudflare requirement
+
+## Gap
+
+Without this skill, a Cloudflare Pages setup is a sequence performed from memory. Three of its four repeated acts touch a service rather than the tree, so no workflow file can absorb them, and one of the acts has already cost a broken deploy: the account ID displayed in the Cloudflare dashboard is truncated, and a value copied from there is wrong in a way that only shows up at deploy time.
+
+## Must
+
+- Create the Pages project through `wrangler pages project create`
+- Fetch the account ID from `wrangler`'s own authenticated session rather than have it typed or pasted
+- Stop for the operator to issue the API token and run `gh secret set CLOUDFLARE_API_TOKEN` themselves
+- Verify both secrets are present with `gh secret list` before continuing
+- Stop for the operator to attach the custom domain in the dashboard
+- Call `wrangler` and `gh` directly for every step those tools already cover
+
+## Must not
+
+- Accept a Cloudflare API token as input in any form. The toolkit verifies a secret exists, never what it contains.
+- Reimplement `wrangler pages project create` or `gh secret set` as a hand-built API call
+- Open a pull request or merge
+
+## Guards
+
+- `wrangler` not authenticated: stop and name the login command
+- `gh` not authenticated: stop and name the login command
+- A secret missing after the token stop: stop and name which one
+
+## Out of scope
+
+- Attaching a custom domain through the Cloudflare REST API instead of the dashboard. Measured absent from `wrangler pages` at plan time and the REST API was not read, so the dashboard stop stays for this pass.
+- Running the deploy itself once secrets and the domain are set. That is the seeded `tooling/cloudflare/configs/.github/workflows/deploy.yml` workflow, triggered by a push to main.
+- Reconfiguring an existing Pages project's build settings.

package/claude/skills/deploy-cloudflare/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: deploy-cloudflare
+description: Sets up a Cloudflare Pages deploy for the current project by creating the Pages project, fetching the account ID, and stopping twice for the operator to issue the API token and attach the custom domain. Calls `wrangler` and `gh` rather than reimplementing them. Use when asked to "set up Cloudflare deploy", "deploy this to Cloudflare Pages", "set up the Pages project", or "connect this repo to Cloudflare". Do NOT use to run an already-configured deploy, which the seeded workflow does on push, or to reconfigure an existing Pages project's build settings.
+---
+
+# Deploy Cloudflare
+
+Runs the one-time setup a Cloudflare Pages deploy needs before the seeded `deploy.yml` workflow can run, stopping twice for the two acts only the operator can take.
+
+## Guards
+
+- If `wrangler whoami` fails, stop: `❌ wrangler is not authenticated. Run wrangler login, then re-invoke.`
+- If `gh auth status` fails, stop: `❌ gh is not authenticated. Run gh auth login, then re-invoke.`
+- Never accept a Cloudflare API token as input, in a prompt, an argument, or a file. Verify a secret's presence with `gh secret list` rather than asking for or reading its content.
+- Never reimplement `wrangler pages project create` or `gh secret set` as a hand-built HTTP call. Call the tools directly.
+- If the project name is not supplied, derive it from the repository's own name (`basename` of `git remote get-url origin`, stripped of a trailing `.git`) and confirm it in the preview rather than asking first.
+
+## Step 1: create the Pages project
+
+```bash
+wrangler pages project create <project-name>
+```
+
+Report the command's own failure output and stop rather than retrying on a name collision. A project already existing under that name is the operator's to resolve.
+
+## Step 2: fetch and set the account ID
+
+Fetch the account ID from `wrangler`'s own authenticated session rather than asking the operator to copy it from the dashboard. The dashboard displays the account ID truncated, and a value copied from there fails the deploy silently:
+
+```bash
+wrangler whoami
+```
+
+Parse the account ID from that output and pipe it into the secret rather than printing it to the transcript first:
+
+```bash
+echo "<account-id>" | gh secret set CLOUDFLARE_ACCOUNT_ID
+```
+
+## Step 3: stop for the API token
+
+Stop: `⏸ Create a Cloudflare API token with Pages edit permission at the Cloudflare dashboard, then run: gh secret set CLOUDFLARE_API_TOKEN. Re-invoke this skill once that's done.`
+
+This is the one credential the skill never touches. Resume only once the operator confirms the token is set.
+
+## Step 4: verify both secrets
+
+```bash
+gh secret list
+```
+
+- Both `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` present: continue.
+- Either missing: stop and name which one, with the command that sets it.
+
+## Step 5: stop for the custom domain
+
+Stop: `⏸ Attach the custom domain to the <project-name> Pages project in the Cloudflare dashboard, then confirm here. Whether this can run through the API instead of the dashboard is out of scope for this skill, per its REQUIREMENT.md.`
+
+## Step 6: hand off
+
+Report that setup is complete and name the seeded workflow (`tooling/cloudflare/configs/.github/workflows/deploy.yml`, synced via `canon tooling sync cloudflare . --write`) as what deploys on the next push. Do not invoke `git-pr` or `git-ship` from here. The operator or the controlling session decides when to open that pull request.

package/claude/skills/{identity → draft-identity}/REQUIREMENT.md

@@ -1,9 +1,9 @@
 ---
-name: identity
+name: draft-identity
 description: Why the mark and the card are one pick rather than two, and where the size sequence and the write folder come from before either is drafted
 ---
 
-# Identity requirement
+# Draft identity requirement
 
 ## Gap
 

package/claude/skills/{identity → draft-identity}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: identity
+name: draft-identity
 description: Drafts a project's logo mark through draft-and-pick's render-and-pick loop, then composes the picked mark into an icon sequence and a 1200x630 social card. Use when asked to "make a logo", "design a logo mark", "create a favicon", "build the icon set", "generate a social card", "make an og:image", or "draft the logo and social card together". Do NOT use to mutate an existing logo file directly, which is a plain edit, or to record the mark's construction rules in DESIGN.md, which is out of scope.
 ---
 
-# Identity
+# Draft identity
 
 One identity rendered twice: the same mark sized down to an icon sequence and composed with type into the social card sized up. Drafting both from one pick keeps the mark and its card composition from settling on shapes that do not match.
 

package/claude/skills/ux-audit/SKILL.md

@@ -18,6 +18,7 @@ Read these in parallel from the project root, skipping any that do not exist:
 - `.claude/DESIGN.md`: visual intent, tokens, typography, spacing rules
 - `.claude/wireframes/index.md` + every `.claude/wireframes/<surface>.md`, each a flat file or a grouped surface's own `.claude/wireframes/<surface>/index.md` and the siblings it lists: intended UI layout, UI copy, interaction rules. Surfaces are loaded one file at a time during Step 3. Per `${CLAUDE_SKILL_DIR}/../../standards/wireframes.md`, these carry layout and intent, not implementation detail.
 - `.claude/REQUIREMENTS.md`: feature scope and non-goals
+- A committed capture beside the surface's own source, when the project has one. A rendered surface reads differently composed than it reads written, and a capture is the only artifact here that shows the composed result rather than the markup. Absent one, note that this audit reads source only, and keep going. This is a stated fallback, not a stop: a project with no capture yet, or a capture mid-rebuild, still gets a source-only audit rather than losing the skill entirely.
 
 ## Step 2: identify surfaces
 
@@ -34,6 +35,8 @@ For each surface, look for:
 
 Use `.claude/DESIGN.md` and the per-surface `.claude/wireframes/<surface>.md` files, each a flat file or a grouped surface's own `.claude/wireframes/<surface>/index.md` and the siblings it lists, as ground truth for intent. For each implementation surface, read the matching wireframe file before flagging drift. Observations only, no implementation suggestions or fixes.
 
+Where Step 1 found a committed capture for this surface, judge composed output (spacing, overlap, contrast, wrapping) against it rather than inferring layout from markup alone, which reports what the surface renders rather than what its source implies. Where none exists, judge from source alone and say so in that surface's findings, since a source-only read cannot see what only a render would show.
+
 ## Step 4: report and persist
 
 ### Report format

package/docs/workflow/ai-workflow.md

@@ -305,7 +305,7 @@ This section is the corpus the coverage claim is measured against: every name `c
 | `canon:draft-slides`      | For a deck, drafted as `.claude/SLIDES.md` and rendered to PowerPoint                             |
 | `canon:draft-screencast`  | For a recording script with beats and defaults already seeded                                     |
 | `canon:record-screencast` | For compiling and running a screencast draft into a recording and a still                         |
-| `canon:identity`          | For a project's logo mark and its social card, drafted through `draft-and-pick`'s pick loop       |
+| `canon:draft-identity`    | For a project's logo mark and its social card, drafted through `draft-and-pick`'s pick loop       |
 
 ### Answer a question at any point
 

package/docs/workflow/visual-design-workflow.md

@@ -40,7 +40,7 @@ A cell no source anchors ends in `? verify`, and the preview shows that marker b
 - `canon:ux-audit` for UX gap detection on existing surfaces
 - `canon:ux-measure` for what a running surface costs to paint, read against published thresholds
 - `canon:draft-and-pick` for a call settled by looking, drafting several candidates onto one page and taking your pick
-- `canon:identity` to draft a project's logo mark and compose it into an icon sequence and a social card, through `draft-and-pick`'s own render-and-pick loop
+- `canon:draft-identity` to draft a project's logo mark and compose it into an icon sequence and a social card, through `draft-and-pick`'s own render-and-pick loop
 - Anthropic's `frontend-design` plugin optional for light visual steering
 
 ### When to pick

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.70.0",
+  "version": "4.71.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/claude/cases/misc.ts

@@ -15,7 +15,7 @@ export const MISC_CASES: readonly SkillCase[] = [
   {
     prompt:
       'This project has no logo yet. Draft one and give me a social card to go with it.',
-    expect: 'identity',
+    expect: 'draft-identity',
   },
   {
     prompt: 'Fire up the dev server the way this project documents it.',
@@ -47,4 +47,8 @@ export const MISC_CASES: readonly SkillCase[] = [
     prompt: 'Is there a page anywhere in this repo that covers retries?',
     expect: 'index-lookup',
   },
+  {
+    prompt: 'Connect this repo to Cloudflare Pages and set up the deploy.',
+    expect: 'deploy-cloudflare',
+  },
 ]

package/src/commands/teach.ts

@@ -384,6 +384,7 @@ async function runStylesheet(
         root,
         slug: outcome.slug,
         path: outcome.path,
+        basePath: outcome.basePath,
         written: outcome.written,
       })}\n`,
     )
@@ -393,6 +394,7 @@ async function runStylesheet(
   intro('canon teach stylesheet')
   logStep(outcome.written ? 'Written' : 'Already present, left alone')
   logInfo(outcome.path)
+  logInfo(outcome.basePath)
   outro()
   return 0
 }

package/src/gate/measures.ts

@@ -708,6 +708,72 @@ export const readmeCitations: Measure = async (ctx) => {
   }
 }
 
+/**
+ * `deploy-site.yml` and `pr-visual-checks.yml` each carry their own literal
+ * copy of the eight path globs a landing-page change should trigger on, per
+ * Question 2 in `.canon/plans/archive/feature-render-visibility.md`. A YAML
+ * anchor cannot cross files here, so the two copies are read live and compared
+ * rather than one asserting a literal the other could drift behind unnoticed,
+ * mirroring how `web/e2e/home.spec.ts`'s rule-group test already reads live.
+ */
+export const visualPathGlobs: Measure = async (ctx) => {
+  const deployPath = '.github/workflows/deploy-site.yml'
+  const visualPath = '.github/workflows/pr-visual-checks.yml'
+  const deployFile = join(ctx.root, deployPath)
+  const visualFile = join(ctx.root, visualPath)
+
+  if (!existsSync(deployFile) || !existsSync(visualFile)) {
+    return {
+      emissions: [],
+      unmeasured: `${deployPath} or ${visualPath} is absent, so no path list was compared.`,
+    }
+  }
+
+  const deploy = Bun.YAML.parse(readFileSync(deployFile, 'utf8')) as {
+    readonly on?: { readonly push?: { readonly paths?: readonly string[] } }
+  }
+  const visual = Bun.YAML.parse(readFileSync(visualFile, 'utf8')) as {
+    readonly on?: {
+      readonly pull_request?: { readonly paths?: readonly string[] }
+    }
+  }
+
+  const deployPaths = deploy.on?.push?.paths ?? []
+  const visualPaths = visual.on?.pull_request?.paths ?? []
+
+  if (deployPaths.length === 0 || visualPaths.length === 0) {
+    return {
+      emissions: [],
+      unmeasured: `${deployPath} or ${visualPath} carries no path list to compare.`,
+    }
+  }
+
+  const onlyDeploy = deployPaths.filter((path) => !visualPaths.includes(path))
+  const onlyVisual = visualPaths.filter((path) => !deployPaths.includes(path))
+
+  if (onlyDeploy.length === 0 && onlyVisual.length === 0) {
+    return {
+      emissions: [
+        info(
+          `${deployPaths.length} path glob(s) agree between ${deployPath} and ${visualPath}`,
+        ),
+      ],
+    }
+  }
+
+  return {
+    emissions: [
+      ...onlyDeploy.map((path) =>
+        warn(`${deployPath} carries ${path}, absent from ${visualPath}`),
+      ),
+      ...onlyVisual.map((path) =>
+        warn(`${visualPath} carries ${path}, absent from ${deployPath}`),
+      ),
+    ],
+    failure: `${deployPath} and ${visualPath} carry different path globs. Bring the two lists back into agreement.`,
+  }
+}
+
 /**
  * `canon sandbox coverage` moves only when a person runs it, so a scenario added
  * with no expectation ships unnoticed.

package/src/gate/stages.ts

@@ -12,6 +12,7 @@ import {
   shippedReferences,
   standardCriteria,
   unreferencedRules,
+  visualPathGlobs,
 } from '@/gate/measures'
 import { SHIPPED_CORPORA } from '@/shipped/references'
 
@@ -424,6 +425,16 @@ export const STAGES: readonly Stage[] = [
     skipped: 'Neither copy.ts nor README.md changed, so no citation was read',
     checks: [{ kind: 'measure', measure: readmeCitations }],
   },
+  {
+    // Scoped to the two files carrying the literal path-glob copy, so an edit
+    // to either one runs the check.
+    id: 'visual-path-globs',
+    label: 'Visual check path globs',
+    scope: /^\.github\/workflows\/(deploy-site|pr-visual-checks)\.yml$/,
+    skipped:
+      'Neither deploy-site.yml nor pr-visual-checks.yml changed, so no path list was compared',
+    checks: [{ kind: 'measure', measure: visualPathGlobs }],
+  },
   {
     id: 'seed-standards',
     label: 'Seed standards',

package/src/migrate/skill-names.ts

@@ -24,6 +24,16 @@ import { defineRenameRules, type RenameRules } from '@/migrate/rename'
  * Every name takes two words. Ten of these would have landed as a bare single
  * word under a plain strip, and a bare word such as `review` or `docs` is a
  * substring of ordinary prose with no token left for a later sweep to find.
+ *
+ * No bare single-word name may ever join this map, whatever prefix it would
+ * otherwise take. `wholeToken: true` below matches a standalone word rather
+ * than a namespaced compound, so a one-word key rewrites every unrelated use
+ * of that word too. `identity` proved it: a dry run against a fifth row
+ * reading `'identity': 'draft-identity'` reported 112 occurrences across 43
+ * files, most of them a variable, field, or type name spelling the bare word
+ * rather than the skill, including `readonly identity: SelfIdentity` at
+ * `src/sessions/resolve.ts:255`, which the rewrite would have turned into
+ * invalid TypeScript. The row was never added.
  */
 export const SKILL_NAME_MAP: Readonly<Record<string, string>> = {
   'claude-address-review': 'review-address',

package/src/teach/workspace.ts

@@ -42,9 +42,20 @@ export const TEACH_ASSETS = 'assets'
  * The one stylesheet every lesson in a workspace links. The name is fixed here
  * rather than chosen per lesson, because the second lesson has to reach the
  * file the first one wrote and a name composed twice is a name that can differ.
+ * This file is workspace-owned: `writeStylesheet` writes it once and leaves it
+ * alone, since a lesson adds its own rules here. It imports `TEACH_STYLESHEET_BASE`
+ * for the tokens and components, which is the half a resync may always replace.
  */
 export const TEACH_STYLESHEET = 'course.css'
 
+/**
+ * The seeded half of a workspace's styling, imported by `TEACH_STYLESHEET`.
+ * `writeStylesheet` rewrites this file from the design source on every call,
+ * since nothing workspace-authored lives in it, which is what lets a design
+ * token move without a `--force` flag discarding a workspace's lesson rules.
+ */
+export const TEACH_STYLESHEET_BASE = 'base.css'
+
 /**
  * The mission heading whose list a session reads as exit criteria. The writer,
  * the reader below, and the record validator all match this one spelling, so a
@@ -1001,31 +1012,40 @@ export interface StylesheetWritten {
   readonly slug: string
   /** Relative to the root, so a caller prints a path a reader can open. */
   readonly path: string
-  /** False when the workspace already held one and this call left it alone. */
+  /** Relative to the root, the re-synced seed `path` imports. */
+  readonly basePath: string
+  /** False when the workspace already held `path` and this call left it alone. */
   readonly written: boolean
 }
 
 export type StylesheetOutcome = StylesheetWritten | TeachRefused
 
-const STYLESHEET_BANNER = [
+const STYLESHEET_BASE_BANNER = [
   'Seeded by `canon teach stylesheet` from the design source in',
-  'src/design/tokens.ts. The tokens and the two components below are the',
-  'system this workspace renders in. Add lesson rules under them and read a',
-  'value through its custom property rather than restating the hex, which is',
-  'what let one workspace fork the palette from every other.',
+  'src/design/tokens.ts, and rewritten on every call. The tokens and the two',
+  'components below are the system this workspace renders in. Read a value',
+  'through its custom property rather than restating the hex, which is what',
+  'let one workspace fork the palette from every other. Add lesson rules to',
+  `${TEACH_STYLESHEET} instead, which imports this file and is never rewritten.`,
 ].join('\n   ')
 
+const stylesheetSeed = (): string =>
+  `@import url('./${TEACH_STYLESHEET_BASE}');\n`
+
 /**
- * Writes a workspace's one stylesheet from the design source.
+ * Writes a workspace's stylesheet pair from the design source.
  *
- * Every workspace used to carry a hand-authored copy, which is how the course
- * palette forked once per workspace. The name is fixed at `TEACH_STYLESHEET`
- * and the folder at `TEACH_ASSETS` for the same reason a second lesson has to
- * reach the file the first one wrote, and this is what puts the values in it.
+ * Every workspace used to carry one hand-authored file, which is how the
+ * course palette forked once per workspace. The names are fixed at
+ * `TEACH_STYLESHEET` and `TEACH_STYLESHEET_BASE`, and the folder at
+ * `TEACH_ASSETS`, for the same reason a second lesson has to reach the files
+ * the first one wrote and names composed twice can differ.
  *
- * An existing stylesheet is left alone rather than replaced. A workspace adds
- * lesson rules to this file as it goes, so overwriting would discard them, and
- * `--force` is the caller saying it wants the seed back.
+ * `TEACH_STYLESHEET_BASE` carries the tokens and the components and is
+ * rewritten every call, since nothing workspace-authored lives in it.
+ * `TEACH_STYLESHEET` imports it, carries a workspace's own lesson rules, and
+ * is written once and left alone, since overwriting it would discard them.
+ * `--force` is the caller saying it wants that file's seed back too.
  */
 export async function writeStylesheet(
   root: string,
@@ -1036,22 +1056,39 @@ export async function writeStylesheet(
   if (!found.ok) return found
 
   const workspace = found.workspace
-  const rel = join(workspace.path, TEACH_ASSETS, TEACH_STYLESHEET)
+  const assetsDir = join(workspace.path, TEACH_ASSETS)
+  const baseRel = join(assetsDir, TEACH_STYLESHEET_BASE)
+  const rel = join(assetsDir, TEACH_STYLESHEET)
+  const basePath = join(root, baseRel)
   const path = join(root, rel)
 
-  if (existsSync(path) && !force) {
-    return { ok: true, slug: workspace.slug, path: rel, written: false }
-  }
-
-  await mkdir(join(root, workspace.path, TEACH_ASSETS), { recursive: true })
+  await mkdir(join(root, assetsDir), { recursive: true })
   await writeFile(
-    path,
+    basePath,
     buildDesignCss(undefined, {
-      banner: STYLESHEET_BANNER,
+      banner: STYLESHEET_BASE_BANNER,
       embedFonts: TEACH_FONT_FACES,
       components: TEACH_STYLESHEET_COMPONENTS,
     }),
   )
 
-  return { ok: true, slug: workspace.slug, path: rel, written: true }
+  if (existsSync(path) && !force) {
+    return {
+      ok: true,
+      slug: workspace.slug,
+      path: rel,
+      basePath: baseRel,
+      written: false,
+    }
+  }
+
+  await writeFile(path, stylesheetSeed())
+
+  return {
+    ok: true,
+    slug: workspace.slug,
+    path: rel,
+    basePath: baseRel,
+    written: true,
+  }
 }

package/tooling/cloudflare/configs/.github/workflows/deploy.yml

@@ -0,0 +1,103 @@
+name: Deploy
+# canon-no-seed: a stack-specific deploy workflow with no root counterpart by design, parameterized per project on sync rather than mirrored from one.
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      # Fill in this project's own build inputs. A single glob covering the
+      # source tree is enough for most projects; widen it to cover every
+      # path the build reads when it draws on content living elsewhere.
+      - 'src/**'
+  workflow_dispatch:
+
+# Fill in a concurrency group name unique to this project. A second push
+# while a deploy is in flight publishes the newer commit rather than racing
+# it, and the running job is left to finish so a half-uploaded site is never
+# what a reader lands on.
+concurrency:
+  group: deploy
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: 📦 Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install Dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build
+        run: bun run build
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist
+          retention-days: 1
+
+  deploy:
+    name: 🚀 Deploy
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check for Cloudflare secrets
+        id: secrets-check
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        run: |
+          if [ -z "$CLOUDFLARE_API_TOKEN" ] || [ -z "$CLOUDFLARE_ACCOUNT_ID" ]; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Skip notice
+        if: steps.secrets-check.outputs.skip == 'true'
+        run: echo "::notice::CLOUDFLARE_API_TOKEN or CLOUDFLARE_ACCOUNT_ID is not set, skipping deploy. Run the deploy-cloudflare skill to finish setup."
+
+      # This job builds nothing and still needs a toolchain. The checkout
+      # below brings bun.lock, wrangler-action reads it, picks bun on the
+      # strength of it, and installs wrangler with that, so a deploy with no
+      # bun on PATH fails before it reaches Cloudflare. Dropping these steps
+      # as dead weight breaks the deploy on every push.
+      - name: Checkout
+        if: steps.secrets-check.outputs.skip == 'false'
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        if: steps.secrets-check.outputs.skip == 'false'
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Download artifact
+        if: steps.secrets-check.outputs.skip == 'false'
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish
+        if: steps.secrets-check.outputs.skip == 'false'
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          # Fill in this project's Pages project name, set when the
+          # deploy-cloudflare skill runs wrangler pages project create.
+          command: pages deploy dist --project-name=REPLACE_WITH_PROJECT_NAME --branch=${{ github.ref_name }}

package/tooling/cloudflare/manifest.toml

@@ -0,0 +1,5 @@
+[stack]
+name = "cloudflare"
+extends = ""
+runtime = "bun"
+scaffold = ""

package/tooling/cloudflare/reference.md

@@ -0,0 +1,24 @@
+# Tooling cloudflare reference
+
+## Overview
+
+The cloudflare stack ships one parameterized GitHub Actions workflow that deploys a static build to Cloudflare Pages. It is keyed on host rather than on framework and carries no dependencies, seeds, or scripts of its own, so it syncs onto a project already carrying `astro`, `vite-react`, or any other stack at the same root without colliding.
+
+## Deploy workflow
+
+- Separate `build` and `deploy` jobs, connected by an uploaded artifact, converged on the shape already running in the closest prior art rather than invented fresh.
+- The deploy job checks for `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` before doing anything else, and skips with a `::notice::` rather than failing when either is absent. A first merge lands ahead of the Pages project existing, and this guard is what keeps that push green.
+- `--branch=${{ github.ref_name }}` on every deploy, which gives every branch a Cloudflare preview URL rather than only `main`.
+- The deploy job checks out the repository and installs Bun even though it builds nothing. `wrangler-action` resolves its package manager from `bun.lock` in the checkout, and dropping that step breaks the deploy on every push once the toolchain it relies on silently goes missing.
+
+## Parameters a project fills in by hand
+
+Three values in the seeded file have no generic default and are set once, right after sync:
+
+- The `paths:` filter under the `push` trigger. The shipped default is a single `src/**` glob. Widen it to cover every path the build reads when the build draws on catalogs or generated content living outside `src/`.
+- The `concurrency.group` name. The shipped default is the bare string `deploy`, which is enough for a single-deploy project. Give it a project-specific name only if the project runs more than one deploy workflow.
+- The `--project-name` flag on the `wrangler pages deploy` command. Set it to the name the `deploy-cloudflare` skill creates the Pages project under.
+
+## Re-sync
+
+`configs/` is golden and always overwrites. Re-running `canon tooling sync cloudflare . --write` after hand-editing any of the three parameters above discards that edit and restores the shipped defaults. Re-fill the parameters after any re-sync rather than expecting the file to preserve them.