@erclx/canon 4.70.0 → 4.72.0

package/src/tasks/reach.ts

@@ -0,0 +1,383 @@
+import { existsSync } from 'node:fs'
+import { readdir, readFile } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import { listChangedFiles, resolveBaseRef } from '@/git-files'
+import { recordDir } from '@/record-root'
+import { splitPlanSections } from '@/records/validate'
+import { type AnswersRefused, resolvePlanReference } from '@/tasks/answers'
+import { orderingPath, readBoard } from '@/tasks/validate'
+
+const PLANS = 'plans'
+const MARKDOWN = '.md'
+const NONE_IDENTIFIED = 'None identified.'
+
+/** The one group a dispatch reads, per `standards/tasks.md`. */
+const DISPATCH_GROUP = 'Run now'
+
+export const REACH_REFUSALS = [
+  'no-plan',
+  'archived',
+  'bad-input',
+  'no-base',
+  'no-diff',
+] as const
+
+export type ReachRefusal = (typeof REACH_REFUSALS)[number]
+
+export interface ReachRefused {
+  readonly ok: false
+  readonly reason: ReachRefusal
+  readonly message: string
+  readonly detail: readonly string[]
+}
+
+/**
+ * One surface holding a path: a live plan, named by its filename stem, or a
+ * `## Run now` row, named by its task label.
+ */
+export interface Holder {
+  readonly name: string
+  readonly source: 'plan' | 'row'
+  readonly declaration: string
+  /**
+   * Whether a holding plan also carries a row in `## Run now`, and undefined on
+   * a row holder, which is one by construction.
+   *
+   * A plan with no row is the shape a plan nobody archived takes, and it is
+   * also the shape of one whose task is merely not dispatched yet, so this
+   * narrows a reader's search rather than answering it. Testing whether the
+   * holder is genuinely in flight would put a second liveness reading here
+   * beside the dispatch gate's own, which the report declines.
+   */
+  readonly rowed?: boolean
+}
+
+/**
+ * One changed path other tracks already hold, carrying every holder and the
+ * declaration each matched on. A count alone leaves the reader diffing two file
+ * lists by eye to find which pair collided.
+ *
+ * Grouped by path rather than by holder. The two sources are read separately
+ * and stay separate inside `holders`, since a board cell and a plan's own list
+ * answer different questions, but one track carrying both reported the same
+ * path twice under two names before this, and the report leads on this list.
+ */
+export interface Claim {
+  readonly path: string
+  readonly holders: readonly Holder[]
+}
+
+export interface ReachReport {
+  readonly ok: true
+  readonly plan: string
+  readonly base: string
+  readonly changed: number
+  readonly declared: readonly string[]
+  /** Leads the report. Short on nearly every branch, and the half worth acting on. */
+  readonly claimed: readonly Claim[]
+  readonly undeclared: readonly string[]
+  /** Live plans compared against, this branch's own excluded. */
+  readonly plans: number
+  /** `## Run now` rows compared against, the row citing this plan excluded. */
+  readonly rows: number
+  /** Whether an ordering file was on disk to read rows from at all. */
+  readonly board: boolean
+}
+
+export type ReachOutcome = ReachReport | ReachRefused
+
+export interface ReachOptions {
+  /**
+   * Where the git range is read, defaulting to the records root.
+   *
+   * The two part company on every ordinary run, since the plans and the board
+   * are shared scratch at the main worktree root while the branch's own commits
+   * are in a linked worktree. Reading the range at the records root there
+   * measures a checkout sitting on the trunk, so the range closes on itself and
+   * every branch reports a reach of nothing. `canon gov test-order` carries the
+   * same split as an instruction in a skill body; this one is a parameter.
+   */
+  readonly repo?: string
+  /** The far side of the range, defaulting to the trunk. */
+  readonly ref?: string
+}
+
+/**
+ * Splits an entry at the colon that opens its reason, which is the first one
+ * standing outside a backticked span.
+ *
+ * The span test is what keeps `canon:docs-sync` and a `<slug>: <title>` label
+ * from ending the subject early, and it is the ordinary case rather than a
+ * corner: a reason routinely names a skill, and a skill is spelled with a
+ * colon inside backticks.
+ */
+function subjectOf(entry: string): string {
+  let fenced = false
+
+  for (let i = 0; i < entry.length; i += 1) {
+    const char = entry[i]
+    if (char === '`') fenced = !fenced
+    else if (char === ':' && !fenced) return entry.slice(0, i)
+  }
+
+  return entry
+}
+
+/**
+ * Whether a span names a file rather than a skill, a command, or a version.
+ * It is `readPaths`' test, held here rather than shared, because that function
+ * reads a whole cell where this reads one already-split subject.
+ */
+function namesFile(span: string): boolean {
+  return span.includes('/') || /\.[A-Za-z][A-Za-z0-9]*$/.test(span)
+}
+
+/**
+ * Reads the paths a plan declares out of its `**Files to touch:**` section.
+ *
+ * A declaration is a backticked span standing as an entry's subject, ahead of
+ * the colon opening its reason. Reading every span in the entry was the
+ * alternative and it reports a pair that was never going to collide, since the
+ * standard invites an entry to explain itself and an explanation names other
+ * files: one archived plan cites `src/gate/measures.ts` inside a reason whose
+ * subject is a sandbox arm, and never wrote it. Measured over the 2026-09-08
+ * wave, the subject rule reports 6 crossing pairs against 14 for every span.
+ *
+ * An entry carrying no colon at all is taken whole. The standard requires a
+ * reason rather than the punctuation introducing it, so the alternative is
+ * reading such an entry as declaring nothing, which reports every path it
+ * names as undeclared. `standards/plan.md` fixes the colon form, so the
+ * conforming entry never reaches this fallback.
+ *
+ * A rename declares both sides, since both are paths the branch writes and
+ * both sit ahead of the colon.
+ */
+export function readDeclarations(text: string): string[] {
+  const section = splitPlanSections(text).get('Files to touch') ?? []
+  const declared: string[] = []
+
+  for (const line of section) {
+    const trimmed = line.trim()
+    if (!trimmed.startsWith('- ') || trimmed === `- ${NONE_IDENTIFIED}`)
+      continue
+
+    const spans = subjectOf(trimmed.slice(2)).match(/`[^`]+`/g) ?? []
+
+    for (const span of spans) {
+      const path = span
+        .slice(1, -1)
+        .trim()
+        .replace(/^\.\//, '')
+        .replace(/\/+$/, '')
+
+      if (namesFile(path)) declared.push(path)
+    }
+  }
+
+  return [...new Set(declared)]
+}
+
+/**
+ * Whether a declaration covers a changed path: the same file, or a folder the
+ * file sits under.
+ *
+ * Containment runs one way only. A changed path is always a file, so a
+ * declaration of `src/tasks/reach.ts` covering a change to `src/tasks/other.ts`
+ * would be the folder claim its author did not write, and the board's own
+ * `sharesPath` reads both directions because two rows can each name a folder.
+ */
+function covers(declaration: string, path: string): boolean {
+  return path === declaration || path.startsWith(`${declaration}/`)
+}
+
+function stemOf(path: string): string {
+  return basename(path, MARKDOWN)
+}
+
+/**
+ * Every live plan beside this one, as a stem and the paths it declares. The
+ * archive is a folder below this one and is never walked, so a shipped plan
+ * cannot claim a path against a branch building today.
+ */
+async function otherPlans(
+  root: string,
+  own: string,
+): Promise<{ stem: string; declared: readonly string[] }[]> {
+  const dir = recordDir(root, PLANS)
+  if (!existsSync(dir)) return []
+
+  const names = (await readdir(dir)).filter(
+    (name) => name.endsWith(MARKDOWN) && name !== basename(own),
+  )
+  names.sort()
+
+  const plans = []
+  for (const name of names) {
+    const text = await readFile(join(dir, name), 'utf8')
+    plans.push({ stem: stemOf(name), declared: readDeclarations(text) })
+  }
+
+  return plans
+}
+
+/**
+ * Every `## Run now` cell beside this branch's own row. A cell is copied from a
+ * plan's own list, so the board catches a row whose plan is absent and the
+ * plans folder catches a claim no cell carried.
+ */
+async function dispatchRows(
+  root: string,
+  own: string,
+): Promise<{
+  read: boolean
+  rows: { label: string; plan: string | undefined; touches: string[] }[]
+}> {
+  const ordering = orderingPath(root)
+  if (!existsSync(ordering)) return { read: false, rows: [] }
+
+  const { rows } = readBoard(await readFile(ordering, 'utf8'))
+  const ownStem = stemOf(own)
+
+  return {
+    read: true,
+    rows: rows
+      .filter((row) => row.group === DISPATCH_GROUP)
+      .filter((row) => row.plan === undefined || stemOf(row.plan) !== ownStem)
+      .map((row) => ({
+        label: row.label,
+        plan: row.plan === undefined ? undefined : stemOf(row.plan),
+        touches: [...(row.touches ?? [])],
+      })),
+  }
+}
+
+/**
+ * Every holder of one path, plans first. Returning a list rather than a claim
+ * per source is what keeps a track carrying both a plan and a row from reading
+ * as two tracks in a report that leads on this list.
+ */
+function holdersOf(
+  path: string,
+  plans: readonly { stem: string; declared: readonly string[] }[],
+  rows: readonly {
+    label: string
+    plan: string | undefined
+    touches: readonly string[]
+  }[],
+): Holder[] {
+  const holders: Holder[] = []
+
+  for (const plan of plans) {
+    const declaration = plan.declared.find((entry) => covers(entry, path))
+    if (declaration !== undefined) {
+      holders.push({
+        name: plan.stem,
+        source: 'plan',
+        declaration,
+        rowed: rows.some((row) => row.plan === plan.stem),
+      })
+    }
+  }
+
+  for (const row of rows) {
+    const declaration = row.touches.find((entry) => covers(entry, path))
+    if (declaration !== undefined) {
+      holders.push({ name: row.label, source: 'row', declaration })
+    }
+  }
+
+  return holders
+}
+
+/**
+ * Reads a branch back against what was written down about it: the paths its own
+ * plan declared, and the paths every other live plan or dispatch row holds.
+ *
+ * It reports and never gates, the way `canon gov test-order` does, and it
+ * writes nothing. A `Touches` cell is the controller's to correct and a plan's
+ * list is a prediction the branch outgrows, so a verb that repaired either
+ * would be answering a question the reader has not been shown yet.
+ *
+ * What it reads is what is written down, so it inherits the dispatch runbook's
+ * own blindness. A hand-launched track carries no row and a track with no plan
+ * carries no declaration, which is why the report names how many plans and rows
+ * it compared against rather than reporting clear and letting that read as a
+ * proof.
+ *
+ * The live folder is trusted rather than tested, which cuts the other way: a
+ * plan whose work merged keeps claiming its files until something archives it,
+ * and `canon tasks archive` only runs on merge, so a stranded plan reports a
+ * collision against every branch after it. The first run of this verb reported
+ * five such paths and every one was a file nobody archived. Testing a holder for
+ * liveness would put a second reading of what is in flight here, beside the
+ * dispatch gate's own, so the report names the holder and the reader decides.
+ */
+export async function planReach(
+  root: string,
+  reference: string,
+  { repo = root, ref }: ReachOptions = {},
+): Promise<ReachOutcome> {
+  const resolved = resolvePlanReference(root, reference)
+  if (!resolved.ok) return widen(resolved)
+
+  const base = await resolveBaseRef(repo, ref)
+  if (base === undefined) {
+    return refuse(
+      'no-base',
+      `No merge base against ${ref ?? 'origin/main or main'}, so the branch has no range to read.`,
+      [reference],
+    )
+  }
+
+  const changed = await listChangedFiles(repo, base)
+  if (changed === undefined) {
+    return refuse(
+      'no-diff',
+      `git could not list the files changed since ${base}, so the reach is unread rather than clear.`,
+      [reference],
+    )
+  }
+
+  const declared = readDeclarations(await readFile(resolved.path, 'utf8'))
+  const plans = await otherPlans(root, resolved.path)
+  const board = await dispatchRows(root, resolved.path)
+
+  const claimed: Claim[] = []
+  const undeclared: string[] = []
+
+  for (const path of changed) {
+    const holders = holdersOf(path, plans, board.rows)
+    if (holders.length > 0) claimed.push({ path, holders })
+    if (!declared.some((entry) => covers(entry, path))) undeclared.push(path)
+  }
+
+  return {
+    ok: true,
+    plan: resolved.plan,
+    base,
+    changed: changed.length,
+    declared,
+    claimed,
+    undeclared,
+    plans: plans.length,
+    rows: board.rows.length,
+    board: board.read,
+  }
+}
+
+/**
+ * Carries a resolution refusal through unchanged. The reasons are a subset of
+ * this verb's own, so restating the message here would put one wording in two
+ * places that ship together.
+ */
+function widen(refused: AnswersRefused): ReachRefused {
+  return refused
+}
+
+function refuse(
+  reason: ReachRefusal,
+  message: string,
+  detail: readonly string[] = [],
+): ReachRefused {
+  return { ok: false, reason, message, detail }
+}

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/standards/plan.md

@@ -61,6 +61,8 @@ The document opens with `# Feature: <short title>` and one paragraph stating wha
 - Write `None identified.` under a required section with nothing to report rather than dropping the marker. A dropped section and an unconsidered one read identically.
 - Aim `## Summary` at a person scanning the plan, not at the session executing it. The other sections carry what execution needs.
 - Give every `**Files to touch:**` entry a backticked path and something said about it. A bare path states scope and not intent, and the reason is what an executing session checks its edit against. Lead with the path or lead with a label carrying the path, whichever reads better for the entry.
+- Separate the two halves with a colon, and keep every path the entry declares ahead of it. What sits before the colon is the entry's subject and reads as a target, so both sides of a rename belong there and a file merely cited by the reason does not. A reason is free to name another path, and one entry that did was read as declaring a file its branch never wrote.
+- Read the list as what the branch sets out to write rather than as a bound on it. The ship chain writes past it on nearly every branch, since the sync skills refresh whichever context entry and public doc the change reaches, and no planner can name those before the change exists. `canon tasks plan-reach <plan>` reads the branch back against this list and every other live plan, ahead of the pull request.
 - State every count and every claim about the tree as measured during the pass that wrote the plan. A figure carried in from a summary or an earlier session is the most common way a plan ships the wrong scope.
 - Prefer a short plan over a padded one. A section filled to look thorough costs the reader the same attention as one that matters.
 

package/standards/tasks.md

@@ -67,6 +67,8 @@ Readiness is three groups under fixed headings, `## Run now`, `## Up next`, and
 
 Each group fixes its own columns, which follow from the test above it rather than from preference. Neither half of the `## Run now` test is checkable without the file set and the plan sitting beside the task.
 
+A `Touches` cell is copied from its plan's own list, so it states what the branch sets out to write rather than a bound on it, and a branch outgrows it while the row still reads as it did at dispatch. Correct the cell from the branch rather than from the plan once one is running, since the plan is the prediction that already went stale and only the diff says what was written. `canon tasks plan-reach <plan>` reads that diff against every live plan and every cell in this group, and the row's owner is the one who writes the correction: a worker never edits this board.
+
 Row position inside `## Needs a plan` is the order those tasks get planned in, top first. The three tests answer whether a task can start, which is mechanical, and none of them answers which task is worth starting, which is a judgment no column holds. Position is where that judgment is recorded, so the top row is the answer to what to plan next and a reader needs no other surface to get it. The other two groups take the same reading, and it costs them little, since a group holding what is already planned is short by construction.
 
 Position alone carries it, and no rank column exists. A number beside each row is a second thing to keep in step with the order it duplicates, and the file is edited by one session at a time, so the order the rows are written in is already unambiguous. State on each row why it sits where it does, in the same cell that carries what it is waiting on. A position with no stated reason is re-derived from memory by the next session, which is the failure the ordering replaces rather than moves.

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.