@erclx/canon 5.17.0 → 5.19.0

package/src/slides/convert/svg.ts

@@ -0,0 +1,38 @@
+/**
+ * The colors an inline SVG inherited from the page it was drawn in. Inside a
+ * slide nothing supplies `color` or a custom property, so a vector handed over
+ * as written renders every `currentColor` and `var(--*)` paint as black.
+ */
+export interface SvgColors {
+  /** The element's computed `color`, which is what `currentColor` reads. */
+  readonly color: string
+  /** Every custom property the element computed, keyed with its leading `--`. */
+  readonly vars: Readonly<Record<string, string>>
+}
+
+const NAMESPACE = 'http://www.w3.org/2000/svg'
+
+/**
+ * Rewrites the paints that depend on the page into the values the browser
+ * computed for them. A custom property the page never set takes its own
+ * fallback where it carries one, and stays as written otherwise, since the
+ * browser drew that paint as invalid too.
+ */
+export function resolveSvgColors(markup: string, colors: SvgColors): string {
+  const withVars = markup.replace(
+    /var\(\s*(--[\w-]+)\s*(?:,\s*([^()]*(?:\([^()]*\))?[^()]*))?\)/g,
+    (match, name: string, fallback: string | undefined) =>
+      colors.vars[name] ?? fallback?.trim() ?? match,
+  )
+  const withColor = withVars.replace(/\bcurrentColor\b/gi, colors.color)
+  return withNamespace(withColor)
+}
+
+/**
+ * An SVG serialized out of an HTML document carries no namespace, and a
+ * standalone file without one is not read as SVG at all.
+ */
+function withNamespace(markup: string): string {
+  if (/^<svg\b[^>]*\sxmlns=/.test(markup)) return markup
+  return markup.replace(/^<svg\b/, `<svg xmlns="${NAMESPACE}"`)
+}

package/src/slides/convert/walk.ts

@@ -0,0 +1,444 @@
+import type {
+  BoxStyle,
+  ElementRecord,
+  Rect,
+  Rgba,
+  ShadowRecord,
+  TableCellRecord,
+  TextContent,
+  TextRun,
+} from '@/slides/convert/shapes'
+
+/** What one laid-out slide hands back across `page.evaluate`. */
+export interface WalkedSlide {
+  readonly background: Rgba
+  readonly records: ElementRecord[]
+}
+
+/** Set on every walked element, so a screenshot finds the one a record names. */
+export const ID_ATTRIBUTE = 'data-canon-id'
+
+/**
+ * Runs inside the laid-out page and returns one record per drawable element in
+ * document order. Playwright serializes this function to source, so every
+ * helper it calls is declared inside its own body: a reference to anything at
+ * module scope typechecks and then throws in the page.
+ *
+ * Text gathers along the inline flow. A block holding text takes every run its
+ * inline descendants carry, so `<strong>` inside `<p>` is one shape with two
+ * runs, while a block-level child is walked on its own. Images, SVGs, and
+ * tables consume their whole subtree.
+ *
+ * Each walked element is tagged with `idAttribute` set to its record id.
+ */
+export function walkSlide(idAttribute: string): WalkedSlide {
+  const canvas = document.createElement('canvas')
+  canvas.width = 1
+  canvas.height = 1
+  const context = canvas.getContext('2d', { willReadFrequently: true })
+
+  const rgba = (value: string): Rgba => {
+    if (!context || !value || value === 'transparent') {
+      return { hex: '000000', alpha: 0 }
+    }
+    context.clearRect(0, 0, 1, 1)
+    context.fillStyle = '#000000'
+    context.fillStyle = value
+    context.fillRect(0, 0, 1, 1)
+    const [r = 0, g = 0, b = 0, a = 0] = context.getImageData(0, 0, 1, 1).data
+    const hex = [r, g, b]
+      .map((channel) => channel.toString(16).padStart(2, '0'))
+      .join('')
+      .toUpperCase()
+    return { hex, alpha: Math.round((a / 255) * 100) / 100 }
+  }
+
+  const px = (value: string): number => Number.parseFloat(value) || 0
+
+  const splitTopLevel = (value: string): string[] => {
+    const parts: string[] = []
+    let depth = 0
+    let current = ''
+    for (const char of value) {
+      if (char === '(') depth += 1
+      if (char === ')') depth -= 1
+      if (char === ',' && depth === 0) {
+        parts.push(current.trim())
+        current = ''
+      } else {
+        current += char
+      }
+    }
+    if (current.trim()) parts.push(current.trim())
+    return parts
+  }
+
+  const shadows = (value: string): ShadowRecord[] => {
+    if (!value || value === 'none') return []
+    return splitTopLevel(value).map((part) => {
+      const colorMatch = /[a-z-]+\([^)]*\)|#[0-9a-f]+/i.exec(part)
+      const rest = colorMatch ? part.replace(colorMatch[0], ' ') : part
+      const [x = 0, y = 0, blur = 0] = (rest.match(/-?[\d.]+px/g) ?? []).map(px)
+      return {
+        x,
+        y,
+        blur,
+        color: rgba(colorMatch?.[0] ?? 'rgb(0, 0, 0)'),
+        inset: /\binset\b/.test(rest),
+      }
+    })
+  }
+
+  const rectOf = (domRect: DOMRect): Rect => ({
+    x: domRect.left,
+    y: domRect.top,
+    w: domRect.width,
+    h: domRect.height,
+  })
+
+  const boxStyle = (element: Element, bounds: Rect): BoxStyle => {
+    const style = getComputedStyle(element)
+    const radius = style.borderTopLeftRadius.endsWith('%')
+      ? (px(style.borderTopLeftRadius) / 100) * Math.min(bounds.w, bounds.h)
+      : px(style.borderTopLeftRadius)
+    return {
+      background: rgba(style.backgroundColor),
+      borderWidth: {
+        top: px(style.borderTopWidth),
+        right: px(style.borderRightWidth),
+        bottom: px(style.borderBottomWidth),
+        left: px(style.borderLeftWidth),
+      },
+      borderColor: rgba(style.borderTopColor),
+      borderStyle: style.borderTopStyle,
+      radius,
+      padding: {
+        top: px(style.paddingTop),
+        right: px(style.paddingRight),
+        bottom: px(style.paddingBottom),
+        left: px(style.paddingLeft),
+      },
+      shadows: shadows(style.boxShadow),
+      raw: {
+        backgroundImage: style.backgroundImage,
+        transform: style.transform,
+        filter: style.filter,
+        clipPath: style.clipPath,
+        mask: style.maskImage || 'none',
+        mixBlendMode: style.mixBlendMode,
+        backdropFilter: style.backdropFilter || 'none',
+        borderWidth: style.borderWidth,
+        borderColor: style.borderColor,
+        borderStyle: style.borderStyle,
+        borderRadius: style.borderRadius,
+      },
+    }
+  }
+
+  const describe = (element: Element): string => {
+    const tag = element.tagName.toLowerCase()
+    if (element.id) return `${tag}#${element.id}`
+    const className = element.getAttribute('class')?.trim().split(/\s+/)[0]
+    return className ? `${tag}.${className}` : tag
+  }
+
+  const isInlineFlow = (element: Element): boolean => {
+    const tag = element.tagName.toLowerCase()
+    if (tag === 'img' || tag === 'svg' || tag === 'table') return false
+    return getComputedStyle(element).display === 'inline'
+  }
+
+  const transformText = (text: string, transform: string): string => {
+    if (transform === 'uppercase') return text.toUpperCase()
+    if (transform === 'lowercase') return text.toLowerCase()
+    if (transform === 'capitalize') {
+      return text.replace(/\b\p{L}/gu, (letter) => letter.toUpperCase())
+    }
+    return text
+  }
+
+  /**
+   * Collects the runs of `root`'s inline flow, adding every inline element it
+   * passed through to `consumed`. `deep` follows block children too, which a
+   * table cell needs since it is drawn as one cell however it nests.
+   */
+  const gatherRuns = (
+    root: Element,
+    consumed: Set<Element>,
+    deep: boolean,
+  ): TextRun[] => {
+    const runs: TextRun[] = []
+    let breakPending = false
+    const visit = (node: Node): void => {
+      for (const child of Array.from(node.childNodes)) {
+        if (child.nodeType === Node.TEXT_NODE) {
+          const parent = child.parentElement
+          if (!parent) continue
+          const style = getComputedStyle(parent)
+          const text = (child.textContent ?? '').replace(/\s+/g, ' ')
+          if (!text.trim() && !runs.length) continue
+          if (!text) continue
+          const spacing = style.letterSpacing
+          const isUnderlined = (inline: Element): boolean => {
+            for (let at: Element | null = inline; at; at = at.parentElement) {
+              if (
+                getComputedStyle(at).textDecorationLine.includes('underline')
+              ) {
+                return true
+              }
+              if (at === root) break
+            }
+            return false
+          }
+          const highlightOf = (inline: Element): Rgba | undefined => {
+            if (inline === root) return undefined
+            const ground = rgba(getComputedStyle(inline).backgroundColor)
+            return ground.alpha > 0 ? ground : undefined
+          }
+          runs.push({
+            text: transformText(text, style.textTransform),
+            color: rgba(style.color),
+            fontSize: px(style.fontSize),
+            fontWeight: Number(style.fontWeight) || 400,
+            italic: style.fontStyle === 'italic',
+            underline: isUnderlined(parent),
+            fontFamily: style.fontFamily,
+            letterSpacing: spacing === 'normal' ? 0 : px(spacing),
+            highlight: highlightOf(parent),
+            href: parent.closest('a[href]')?.getAttribute('href') ?? undefined,
+            breakBefore: breakPending || undefined,
+          })
+          breakPending = false
+        } else if (child instanceof Element) {
+          if (child.tagName.toLowerCase() === 'br') {
+            breakPending = true
+            consumed.add(child)
+          } else if (deep || isInlineFlow(child)) {
+            consumed.add(child)
+            visit(child)
+          }
+        }
+      }
+    }
+    visit(root)
+    return tidyRuns(runs)
+  }
+
+  /** Collapses the spaces the browser would, across run boundaries included. */
+  const tidyRuns = (runs: TextRun[]): TextRun[] => {
+    const tidied: TextRun[] = []
+    for (const run of runs) {
+      const previous = tidied.at(-1)
+      let text = run.text
+      if (!previous || run.breakBefore || previous.text.endsWith(' ')) {
+        text = text.replace(/^ /, '')
+      }
+      if (text) tidied.push({ ...run, text })
+    }
+    const last = tidied.at(-1)
+    if (last) tidied[tidied.length - 1] = { ...last, text: last.text.trimEnd() }
+    return tidied.filter((run) => run.text.length > 0)
+  }
+
+  const textContent = (element: Element, runs: TextRun[]): TextContent => {
+    const style = getComputedStyle(element)
+    const fontSize = px(style.fontSize)
+    return {
+      runs,
+      align: style.textAlign,
+      lineHeight:
+        style.lineHeight === 'normal' ? fontSize * 1.2 : px(style.lineHeight),
+      fontSize,
+    }
+  }
+
+  const renderedText = (element: Element): string => {
+    const text =
+      element instanceof HTMLElement ? element.innerText : element.textContent
+    return (text ?? '').replace(/\s+/g, ' ').trim()
+  }
+
+  const layoutBox = (element: Element, bounds: Rect): Rect => {
+    if (getComputedStyle(element).transform === 'none') return bounds
+    if (!(element instanceof HTMLElement)) return bounds
+    const w = element.offsetWidth
+    const h = element.offsetHeight
+    return {
+      x: bounds.x + (bounds.w - w) / 2,
+      y: bounds.y + (bounds.h - h) / 2,
+      w,
+      h,
+    }
+  }
+
+  const records: ElementRecord[] = []
+  const ids = new Map<Element, number>()
+  const consumed = new Set<Element>()
+
+  const parentId = (element: Element): number | null => {
+    let ancestor = element.parentElement
+    while (ancestor) {
+      const id = ids.get(ancestor)
+      if (id !== undefined) return id
+      ancestor = ancestor.parentElement
+    }
+    return null
+  }
+
+  const consumeSubtree = (element: Element): void => {
+    for (const descendant of Array.from(element.querySelectorAll('*'))) {
+      consumed.add(descendant)
+    }
+  }
+
+  const SKIPPED = new Set(['script', 'style', 'template', 'noscript', 'link'])
+
+  for (const element of Array.from(document.body.querySelectorAll('*'))) {
+    if (consumed.has(element)) continue
+    const tag = element.tagName.toLowerCase()
+    if (SKIPPED.has(tag)) continue
+    if (!element.checkVisibility({ visibilityProperty: true })) continue
+
+    const id = records.length + 1
+    const bounds = rectOf(element.getBoundingClientRect())
+    const base = {
+      id,
+      parent: parentId(element),
+      selector: describe(element),
+      box: layoutBox(element, bounds),
+      bounds,
+      style: boxStyle(element, bounds),
+      text: renderedText(element),
+    }
+    ids.set(element, id)
+    element.setAttribute(idAttribute, String(id))
+
+    if (element instanceof HTMLImageElement) {
+      records.push({
+        ...base,
+        kind: 'image',
+        src: element.currentSrc || element.src,
+        alt: element.alt,
+      })
+      continue
+    }
+
+    if (element instanceof SVGSVGElement) {
+      consumeSubtree(element)
+      const style = getComputedStyle(element)
+      const vars: Record<string, string> = {}
+      for (const [, name] of element.outerHTML.matchAll(
+        /var\(\s*(--[\w-]+)/g,
+      )) {
+        if (!name) continue
+        const value = style.getPropertyValue(name).trim()
+        if (value) vars[name] = value
+      }
+      records.push({
+        ...base,
+        kind: 'svg',
+        markup: element.outerHTML,
+        colors: { color: style.color, vars },
+        alt:
+          element.getAttribute('aria-label') ??
+          element.querySelector('title')?.textContent ??
+          '',
+      })
+      continue
+    }
+
+    if (element instanceof HTMLTableElement) {
+      consumeSubtree(element)
+      const rows = Array.from(element.rows).map((row) =>
+        Array.from(row.cells).map((cell): TableCellRecord => {
+          const cellBounds = rectOf(cell.getBoundingClientRect())
+          return {
+            ...textContent(cell, gatherRuns(cell, new Set(), true)),
+            box: cellBounds,
+            colspan: cell.colSpan,
+            rowspan: cell.rowSpan,
+            style: boxStyle(cell, cellBounds),
+            verticalAlign: getComputedStyle(cell).verticalAlign,
+          }
+        }),
+      )
+      records.push({ ...base, kind: 'table', rows })
+      continue
+    }
+
+    const gathered = new Set<Element>()
+    const runs = gatherRuns(element, gathered, false)
+    for (const inline of gathered) consumed.add(inline)
+    if (runs.length === 0) {
+      records.push({ ...base, kind: 'box' })
+      continue
+    }
+
+    const blockChild = Array.from(element.children).find(
+      (child) =>
+        !consumed.has(child) &&
+        !SKIPPED.has(child.tagName.toLowerCase()) &&
+        child.checkVisibility() &&
+        !getComputedStyle(child).display.startsWith('inline'),
+    )
+    const box = blockChild
+      ? {
+          ...base.box,
+          h: Math.max(0, blockChild.getBoundingClientRect().top - base.box.y),
+        }
+      : base.box
+
+    const style = getComputedStyle(element)
+    const isListItem =
+      style.display === 'list-item' && style.listStyleType !== 'none'
+    const list = isListItem
+      ? {
+          style: style.listStyleType,
+          depth: (() => {
+            let depth = 0
+            let ancestor = element.parentElement
+            while (ancestor) {
+              if (ancestor.tagName === 'UL' || ancestor.tagName === 'OL') {
+                depth += 1
+              }
+              ancestor = ancestor.parentElement
+            }
+            return depth
+          })(),
+          ordinal:
+            (element.parentElement instanceof HTMLOListElement
+              ? element.parentElement.start
+              : 1) +
+            Array.from(element.parentElement?.children ?? [])
+              .filter((sibling) => sibling.tagName === 'LI')
+              .indexOf(element),
+        }
+      : undefined
+
+    records.push({
+      ...base,
+      box,
+      kind: 'text',
+      content: textContent(element, runs),
+      list,
+      inlineStyles: Array.from(gathered)
+        .filter((inline) => inline.tagName !== 'BR')
+        .map((inline) =>
+          boxStyle(inline, rectOf(inline.getBoundingClientRect())),
+        ),
+    })
+  }
+
+  const ground = (element: Element): Rgba =>
+    rgba(getComputedStyle(element).backgroundColor)
+  const bodyGround = ground(document.body)
+  const htmlGround = ground(document.documentElement)
+  const background =
+    bodyGround.alpha > 0
+      ? bodyGround
+      : htmlGround.alpha > 0
+        ? htmlGround
+        : { hex: 'FFFFFF', alpha: 1 }
+
+  return { background, records }
+}

package/src/teach/browser/reload.ts

@@ -0,0 +1,9 @@
+/* Spliced in by `canon teach up` at serve time and never written to a page, so
+   the server sends a message only once a refresh has landed on disk. */
+export function reload(path: string): void {
+  var source = new EventSource(path)
+  source.onmessage = function () {
+    source.close()
+    location.reload()
+  }
+}

package/src/teach/nav.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs'
-import { readdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { readdir, readFile, rm } from 'node:fs/promises'
 import { join, posix, relative } from 'node:path'
 import {
   TEACH_SIDEBAR_BREAKPOINT,
@@ -37,6 +37,7 @@ import {
   type WorkspaceSummary,
   writeStylesheet,
 } from '@/teach/workspace'
+import { writeIfChanged } from '@/teach/write-if-changed'
 
 const BRAND_MARK = 'assets/brand/mark.svg'
 
@@ -1162,7 +1163,7 @@ async function rewriteLesson(
   }
 
   const linked = linkAuthoredRegion(wrapMain(html), targets, file)
-  await writeFile(path, linked.html)
+  await writeIfChanged(path, linked.html)
   return { ok: true, file, unresolved: linked.unresolved }
 }
 
@@ -1234,9 +1235,9 @@ export async function generateNav(
 
   const dir = teachDir(root)
   const rootPath = join(dir, 'index.html')
-  await writeFile(rootPath, renderRootPage(listed.workspaces))
+  await writeIfChanged(rootPath, renderRootPage(listed.workspaces))
 
-  await writeFile(
+  await writeIfChanged(
     join(dir, TEACH_STYLESHEET),
     buildDesignCss(undefined, {
       embedFonts: TEACH_FONT_FACES,
@@ -1273,7 +1274,7 @@ export async function generateNav(
     }
 
     const contentsPath = join(root, detail.path, 'index.html')
-    await writeFile(
+    await writeIfChanged(
       contentsPath,
       await renderContentsPage(
         root,
@@ -1292,7 +1293,7 @@ export async function generateNav(
         continue
       }
 
-      await writeFile(
+      await writeIfChanged(
         join(root, detail.path, TEACH_REFERENCE, renderedReferenceName(file)),
         await renderReferencePage(root, listed.workspaces, detail, metas, file),
       )

package/src/teach/workspace.ts

@@ -7,6 +7,7 @@ import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { type BodyLine, bodyLines } from '@/markdown/scan'
 import { recordDir } from '@/record-root'
 import { TEACH_FONT_FACES } from '@/teach/fonts'
+import { writeIfChanged } from '@/teach/write-if-changed'
 
 export const TEACH_REFUSALS = [
   'no-teach',
@@ -1132,7 +1133,7 @@ export async function writeStylesheet(
   const path = join(root, rel)
 
   await mkdir(join(root, assetsDir), { recursive: true })
-  await writeFile(
+  await writeIfChanged(
     basePath,
     buildDesignCss(undefined, {
       banner: STYLESHEET_BASE_BANNER,

package/src/teach/write-if-changed.ts

@@ -0,0 +1,17 @@
+import { readFile, writeFile } from 'node:fs/promises'
+
+/**
+ * Writes `text` to `path` only when the file does not already hold it, and
+ * reports whether it wrote. `canon teach up` watches the folder `nav` writes
+ * into, so a pass that rewrites unchanged bytes raises the events that start
+ * the next pass, and an unchanged mtime is what lets the loop settle.
+ */
+export async function writeIfChanged(
+  path: string,
+  text: string,
+): Promise<boolean> {
+  const current = await readFile(path, 'utf8').catch(() => undefined)
+  if (current === text) return false
+  await writeFile(path, text)
+  return true
+}

package/standards/architecture.md

@@ -73,18 +73,24 @@ A decision says why it won and rarely says when that reason stops holding, so an
 - Draft it from the harm the decision prevents, never from the mechanism it uses. A mechanism can keep working long after the reason for choosing it is gone, so re-checking it confirms the wrong fact.
 - Place the sentence after the reasoning and before any verification anchor, so the anchor stays the entry's last sentence.
 - Give a heading holding several principles one sentence, for the premise they share, rather than one per principle.
-- Adopt the requirement by stating the clause `Every decision closes with a revisit sentence.` in the record itself. The clause is the record's own, like the cap, so a checker reads it from the file and gates only a record that states it. A record stating none is reported and never gated.
+- Adopt the requirement by stating the clause `Every decision closes with a revisit sentence.` in the record itself. The clause is the record's own, like the caps, so a checker reads it from the file and gates only a record that states it. A record stating none is reported and never gated.
 - A checker reads presence alone. A vacuous sentence passes it, so the sentence is only as useful as the finding it names.
 
-## Entry cap
+## Caps
 
-Every session pays for this file before any work starts, so a heavy read is a real cost. A file that reads heavy is carrying too many decisions, not decisions written too long, so the bound is a count of decisions rather than of words.
+Every session pays for this file before any work starts, so a heavy read is a real cost. Weight comes from two places, too many decisions and decisions written too long, so the record caps both, and caps the open risks beside them.
 
-- State the cap in the record itself as a clause of the form `This record holds at most <n> decisions.` The cap is the record's own, so a checker reads it from the file, and a record stating none is measured and never gated.
-- Set the cap near one decision per slot plus a small margin.
-- At the cap, merge two decisions or retire one before adding another, and name which in the change that does it. Never compress a decision's prose to fit, and never pack two decisions under one heading, which the count cannot see.
+- State each cap in the record itself. A checker reads only these spellings, so a clause worded another way is reported and never gated:
+  - `This record holds at most <n> decisions.`
+  - `at most <n> words a decision`, counting a decision's prose below its heading, fenced lines left out
+  - `at most <n> risk bullets`, counting every list item under `## Risks / open questions`, nested ones included
+- The three can share one sentence, such as `This record holds at most 12 decisions, at most 150 words a decision, and at most 6 risk bullets.` Each cap is the record's own, so a record stating none is measured and never gated, and the template states the entry cap alone so the other two are adopted on purpose.
+- Set the decision cap near one decision per slot plus a small margin, the word cap near what one trade takes to state, about 150, and the risk cap at what a reader holds in mind at once, about 6.
+- At the decision cap, merge two decisions or retire one before adding another, and name which in the change that does it. Never pack two decisions under one heading, which the count cannot see.
+- At the word cap, cut a decision to the choice, the alternative that lost, the reason, and the revisit sentence. What it sheds is a mechanism or a measurement, which goes to the domain context entry it constrains, never under a second heading.
+- At the risk cap, drop what is no longer open before adding a risk.
 - Retire a decision by moving it to the domain context entry it constrains, not by deleting its reasoning.
-- A word count, for the file and for each decision, is read alongside the judgment when one is available, and it never gates.
+- The whole file's word count stays a report, read alongside the judgment, and never gates.
 - Yield to the paragraph weight checkpoint in `markdown.md`. A paragraph past the checkpoint is a defect no length guideline licenses.
 
 ## Template

package/standards/requirements.md

@@ -36,6 +36,10 @@ Does not govern:
 
 Use `## Problem`, `## Goals`, `## Non-goals`, `## MVP features`, and `## Constraints`. Add `## Distribution` when the rule below applies. Add `## Worldview` when the project holds beliefs that shape every decision, and keep a belief there only when it changes a decision, since a padded worldview turns into a second goals list. Add `## Premise` when the project exists to answer a question, stated as the question and what would count as an answer, never as the answer measured so far. Drop a section rather than pad it with filler.
 
+## Length
+
+This file loads into every session, so its weight is paid before any work starts. Cap it by stating the clause `This record holds at most <n> words.` in the record itself, where a checker reads it and counts every word below the frontmatter. The cap is the record's own, so a record stating none is measured and never gated. Set it near 600, and at the cap cut a goal or a constraint that no longer changes a decision before adding one.
+
 ## Lifecycle
 
 Once every entry in the MVP list, or in a later scope section, has shipped, delete the section. Git keeps the old text, and the document states the project as it stands. Do not annotate an entry as shipped and leave it in place. While any entry is unshipped, do not renumber the list or append to it.

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

@@ -75,7 +75,7 @@ jobs:
 
       - 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."
+        run: echo "::notice::CLOUDFLARE_API_TOKEN or CLOUDFLARE_ACCOUNT_ID is not set, skipping deploy. Run the deploy-app 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
@@ -110,7 +110,7 @@ jobs:
           accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
           wranglerVersion: '3.90.0'
           # Fill in this project's Pages project name, set when the
-          # deploy-cloudflare skill runs wrangler pages project create.
+          # deploy-app skill runs wrangler pages project create.
           command: pages deploy dist --project-name=REPLACE_WITH_PROJECT_NAME --branch=${{ github.ref_name }}
 
       # `canon pr preview` reads this line out of the run log, so the marker is

package/tooling/cloudflare/reference.md

@@ -20,7 +20,7 @@ Three values in the seeded file have no generic default and are set once, right
 
 - 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 `deploy-${{ github.ref_name }}`, which is enough for a single-deploy project. Give the `deploy` prefix a project-specific name only if the project runs more than one deploy workflow, and keep the ref suffix.
-- The Pages project name, written twice as `REPLACE_WITH_PROJECT_NAME`: once in the `--project-name` flag on the `wrangler pages deploy` command and once as `PROJECT_NAME` in the cleanup job. Set both to the name the `deploy-cloudflare` skill creates the Pages project under.
+- The Pages project name, written twice as `REPLACE_WITH_PROJECT_NAME`: once in the `--project-name` flag on the `wrangler pages deploy` command and once as `PROJECT_NAME` in the cleanup job. Set both to the name the `deploy-app` skill creates the Pages project under.
 
 ## Re-sync