@erclx/canon 5.40.0 → 5.42.0

package/src/tasks/answers.ts

@@ -1,8 +1,15 @@
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { basename, isAbsolute, relative, resolve } from 'node:path'
+import { branchRefs } from '@/git/worktree'
+import { fanInBranch, fanInFindings, readFanInMembers } from '@/tasks/fan-in'
 import { isUnder } from '@/tasks/paths'
-import { JUDGED_APART_REMEDY, readLivePlans, stackPairs } from '@/tasks/stack'
+import {
+  JUDGED_APART_REMEDY,
+  readLivePlans,
+  type StackPlan,
+  stackPairs,
+} from '@/tasks/stack'
 import { recordDir, recordDirs } from '@/roots/record'
 import {
   hasStagedBatches,
@@ -49,6 +56,28 @@ export interface PlanAnswers {
 
 export type AnswersOutcome = PlanAnswers | AnswersRefused
 
+/**
+ * Whether `refs/remotes/origin/<branch>` exists, or `null` when the read
+ * itself failed. Injected so the gate is testable without a repository.
+ */
+export type RemoteBranchReader = (
+  root: string,
+  branch: string,
+) => Promise<boolean | null>
+
+/**
+ * Reads the remote-tracking ref as the last fetch left it, so a member pushed
+ * since then reads as absent and holds its integrator, which fails safe. The
+ * local head is not read, since it exists mid-build and a pushed branch is the
+ * only signal a member writes when it is done.
+ */
+export const originBranchPushed: RemoteBranchReader = async (root, branch) => {
+  const report = await branchRefs(branch, root)
+  if (!report.readable) return null
+
+  return report.refs.includes(`refs/remotes/origin/${branch}`)
+}
+
 /**
  * A reference that named a live plan, carrying the absolute path a reader opens
  * and the root-relative spelling a record reports.
@@ -217,6 +246,7 @@ export function resolvePlanReference(
 export async function planAnswers(
   root: string,
   reference: string,
+  readRemoteBranch: RemoteBranchReader = originBranchPushed,
 ): Promise<AnswersOutcome> {
   const resolved = resolvePlanReference(root, reference)
   if (!resolved.ok) return resolved
@@ -233,7 +263,8 @@ export async function planAnswers(
   }
 
   const stem = basename(resolved.path, '.md')
-  const pairs = stackPairs(await readLivePlans(root))
+  const live = await readLivePlans(root)
+  const pairs = stackPairs(live)
 
   for (const { child, parent, shared } of pairs) {
     if (child !== stem) continue
@@ -244,6 +275,8 @@ export async function planAnswers(
     })
   }
 
+  open.push(...(await fanInEntries(root, stem, text, live, readRemoteBranch)))
+
   return {
     ok: true,
     plan: resolved.plan,
@@ -252,6 +285,50 @@ export async function planAnswers(
   }
 }
 
+/**
+ * A plan whose fan-in set disagrees holds on `Fan-in set`, on either side,
+ * since an integrator listing an archived member would otherwise read that
+ * member's leftover branch as done. An integrator whose set agrees holds on
+ * `Fan-in pending` until every member branch is on origin.
+ */
+async function fanInEntries(
+  root: string,
+  stem: string,
+  text: string,
+  live: readonly StackPlan[],
+  readRemoteBranch: RemoteBranchReader,
+): Promise<OpenQuestion[]> {
+  const entries: OpenQuestion[] = fanInFindings(live)
+    .filter(({ record }) => record === `${stem}.md`)
+    .map(({ message }) => ({ label: 'Fan-in set', why: message }))
+
+  const branches = readFanInMembers(text).map(fanInBranch)
+  if (branches.length === 0 || entries.length > 0) return entries
+
+  const pushed = await Promise.all(
+    branches.map((branch) => readRemoteBranch(root, branch)),
+  )
+
+  if (pushed.includes(null)) {
+    return [
+      {
+        label: 'Fan-in pending',
+        why: 'git could not read the member branches on origin, so the set is unread rather than done.',
+      },
+    ]
+  }
+
+  const absent = branches.filter((_, index) => pushed[index] !== true)
+  if (absent.length === 0) return []
+
+  return [
+    {
+      label: 'Fan-in pending',
+      why: `waits on ${absent.map((branch) => `\`${branch}\``).join(', ')} reaching origin. Fetch, then read again.`,
+    },
+  ]
+}
+
 function refuse(
   reason: AnswerRefusal,
   message: string,

package/src/tasks/fan-in.ts

@@ -0,0 +1,176 @@
+import type { Finding } from '@/records/validate'
+import { PLAN_BRANCH_TYPE } from '@/tasks/branch'
+import { constraintBullets, type StackPlan } from '@/tasks/stack'
+
+const PLAN_PREFIX = 'feature-'
+
+const MEMBER_OF = /\bfan[- ]in member of\s+/gi
+
+const FANS_IN = /\bfans in\s+/gi
+
+/**
+ * A backticked slug may drop the `feature-` prefix, and a bare one must carry
+ * it. Without the prefix a bare word is indistinguishable from the prose that
+ * follows the list, so `Fans in feature-a and the rest` would read `the` as a
+ * member.
+ */
+const TICKED_SLUG = /^`((?:feature-)?[a-z0-9][a-z0-9-]*)`/i
+const BARE_SLUG = /^(feature-[a-z0-9][a-z0-9-]*)/i
+
+const LIST_SEPARATOR = /^\s*(?:,\s*(?:and\s+)?|and\s+)/i
+
+function stemOf(slug: string): string {
+  const lower = slug.toLowerCase()
+
+  return lower.startsWith(PLAN_PREFIX) ? lower : `${PLAN_PREFIX}${lower}`
+}
+
+function leadingSlug(text: string): { stem: string; rest: string } | null {
+  const match = TICKED_SLUG.exec(text) ?? BARE_SLUG.exec(text)
+  const slug = match?.[1]
+  if (match === null || slug === undefined) return null
+
+  return { stem: stemOf(slug), rest: text.slice(match[0].length) }
+}
+
+/** Every slug in the list standing after each match of `phrase`, in order. */
+function readList(text: string, phrase: RegExp, many: boolean): string[] {
+  const stems: string[] = []
+
+  for (const bullet of constraintBullets(text)) {
+    for (const match of bullet.matchAll(phrase)) {
+      let rest = bullet.slice((match.index ?? 0) + match[0].length)
+
+      for (;;) {
+        const slug = leadingSlug(rest)
+        if (slug === null) break
+        stems.push(slug.stem)
+        if (!many) break
+
+        const separator = LIST_SEPARATOR.exec(slug.rest)
+        if (separator === null) break
+        rest = slug.rest.slice(separator[0].length)
+      }
+    }
+  }
+
+  return [...new Set(stems)]
+}
+
+/** The integrators a member plan names, which a conforming member holds one of. */
+export function readFanInIntegrators(text: string): string[] {
+  return readList(text, MEMBER_OF, false)
+}
+
+/** The members an integrator plan fans in, in the order its merges run. */
+export function readFanInMembers(text: string): string[] {
+  return readList(text, FANS_IN, true)
+}
+
+/**
+ * The branch a member builds on, derived the way `planBranch` derives it, since
+ * the integrator merges and the dispatch gate reads the branch the worker took.
+ */
+export function fanInBranch(stem: string): string {
+  const slug = stem.startsWith(PLAN_PREFIX)
+    ? stem.slice(PLAN_PREFIX.length)
+    : stem
+
+  return `${PLAN_BRANCH_TYPE}/${slug}`
+}
+
+function unmatched(stem: string, subject: string, message: string): Finding {
+  return { kind: 'fan-in-unmatched', record: `${stem}.md`, subject, message }
+}
+
+/**
+ * Every place a fan-in set's two sides disagree across the live plans.
+ *
+ * An absent plan is reported rather than skipped, unlike `stackFindings`. The
+ * caller hands over the live folder only, so a member archived after it merged
+ * reads as absent, and an integrator still listing it would otherwise take its
+ * leftover branch on origin as a member that finished.
+ *
+ * A member two integrators list is reported on each of them rather than paired
+ * with whichever sorts first, since either merge would carry it.
+ */
+export function fanInFindings(plans: readonly StackPlan[]): Finding[] {
+  const integratorsOf = new Map(
+    plans.map((plan) => [plan.stem, readFanInIntegrators(plan.text)]),
+  )
+  const membersOf = new Map(
+    plans.map((plan) => [plan.stem, readFanInMembers(plan.text)]),
+  )
+  const listers = new Map<string, string[]>()
+  for (const [integrator, members] of membersOf) {
+    for (const member of members) {
+      listers.set(member, [...(listers.get(member) ?? []), integrator])
+    }
+  }
+
+  const findings: Finding[] = []
+
+  for (const { stem } of plans) {
+    const integrators = integratorsOf.get(stem) ?? []
+
+    for (const integrator of integrators) {
+      if (integrators.length > 1) {
+        findings.push(
+          unmatched(
+            stem,
+            integrator,
+            `is a fan-in member of ${integrators.map((name) => `\`${name}\``).join(' and ')}. A member fans in to one integrator.`,
+          ),
+        )
+      } else if (!membersOf.has(integrator)) {
+        findings.push(
+          unmatched(
+            stem,
+            integrator,
+            `is a fan-in member of \`${integrator}\`, which is not a live plan. Write the integrator's plan, or drop the member bullet.`,
+          ),
+        )
+      } else if (!(membersOf.get(integrator) ?? []).includes(stem)) {
+        findings.push(
+          unmatched(
+            stem,
+            integrator,
+            `is a fan-in member of \`${integrator}\`, whose \`Fans in\` bullet does not list it.`,
+          ),
+        )
+      }
+    }
+
+    for (const member of membersOf.get(stem) ?? []) {
+      const others = (listers.get(member) ?? []).filter((name) => name !== stem)
+
+      if (others.length > 0) {
+        findings.push(
+          unmatched(
+            stem,
+            member,
+            `fans in \`${member}\`, which ${others.map((name) => `\`${name}\``).join(' and ')} also fans in. A member fans in to one integrator.`,
+          ),
+        )
+      } else if (!integratorsOf.has(member)) {
+        findings.push(
+          unmatched(
+            stem,
+            member,
+            `fans in \`${member}\`, which is not a live plan. An archived member is not a finished one, so drop it from the list or restore its plan.`,
+          ),
+        )
+      } else if (!(integratorsOf.get(member) ?? []).includes(stem)) {
+        findings.push(
+          unmatched(
+            stem,
+            member,
+            `fans in \`${member}\`, which does not name it as its integrator.`,
+          ),
+        )
+      }
+    }
+  }
+
+  return findings
+}

package/src/tasks/stack.ts

@@ -41,7 +41,7 @@ export interface StackPair {
  * One string per `**Constraints:**` bullet, with a wrapped continuation line
  * joined to the bullet it belongs to.
  */
-function constraintBullets(text: string): string[] {
+export function constraintBullets(text: string): string[] {
   const bullets: string[] = []
 
   for (const line of splitPlanSections(text).get('Constraints') ?? []) {

package/tooling/astro/reference.md

@@ -4,25 +4,49 @@
 
 ## Overview
 
-The astro stack covers Astro + TypeScript projects: content sites, marketing sites, blogs, and docs. Interactive islands use React only. Output is static. It ships golden configs for `astro.config.mjs`, `vitest.config.ts` (using `getViteConfig` from `astro/config`), `playwright.config.ts` (preview-server backed), a `tsconfig.json` that extends `astro/tsconfigs/strict`, an `eslint.config.js` that keeps ESLint for this stack alone, and a `.prettierrc` that formats `.astro` files alone.
+The astro stack covers Astro + TypeScript projects, being content sites, marketing sites, blogs, and docs. Interactive islands use React only and output is static.
+
+It ships golden configs for `astro.config.mjs`, `vitest.config.ts`, `playwright.config.ts` (preview-server backed), and a `tsconfig.json` extending `astro/tsconfigs/strict`. An `eslint.config.js` keeps ESLint for this stack alone, and a `.prettierrc` formats `.astro` files alone.
 
 ## Scaffold checklist
 
 1. Scaffold with `bunx create-astro@latest`. Choose `TypeScript: Strict`. Skip git init and install.
-2. Add React integration: `bunx astro add react`. Do not use `astro add tailwind`. That command installs the v3 integration. Tailwind v4 arrives via the web manifest.
-3. Install web tooling: `canon tooling sync web . --write`
-4. Install astro adapter: `canon tooling sync astro . --write`
+2. Add React with `bunx astro add react`. Never use `astro add tailwind`, which installs the v3 integration. Tailwind v4 arrives via the web manifest.
+3. Install web tooling with `canon tooling sync web . --write`.
+4. Install the astro adapter with `canon tooling sync astro . --write`.
 5. Extend the `ci` and `development` context entries under `canon/context/` per the web reference's extend sections plus the astro rows below.
 6. Run `bun run lint:fix`, then `bun run format`, then `bun run check`.
 
 ## What ships as golden configs
 
-- `astro.config.mjs`: `@astrojs/react` integration, `@tailwindcss/vite` in `vite.plugins`, `@/` path alias via `vite.resolve.alias`, `ASTRO_SITE` env for the `site` field. Port `4321` plus `WORKTREE_PORT_OFFSET` at `server.port`, with `strictPort` under `vite.server` and `vite.preview`. Astro merges the user's `vite` block into the config backing both its dev and its static preview server, and feeds `server.port` through as the preview port, so the port sits at the top level while the bind guarantee sits under `vite`.
-- `vitest.config.ts`: uses `getViteConfig` from `astro/config` (not `mergeConfig`). jsdom, globals, setup file, `passWithNoTests: true`, v8 coverage, `**/*.astro` in coverage excludes.
-- `playwright.config.ts`: all browsers, `webServer` runs `bun run build && bun run preview` on port `4321` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`. Astro's dev/prod gap is wide (MDX, island hydration, asset optimization), so E2E always tests the built `dist/`. `DIST_PREBUILT` set in the environment drops the `build` half, running `bun run preview` alone against a `dist/` a prior CI job already produced.
-- `tsconfig.json`: extends `astro/tsconfigs/strict`, adds `skipLibCheck`, `vitest/globals` and `@testing-library/jest-dom/vitest` in types, `@/` paths.
-- `card.config.mjs`, `card-src/pages/og-card.astro`, and `scripts/check-card-exclusion.sh`: the social card route, its structural build exclusion, and the check enforcing it. See `## Social card route` below.
-- `eslint.config.js`: this stack's own flat config, since the web layer lints with oxlint, which parses no `.astro` file. Adds `eslint-plugin-astro` (`.astro` parser via `astro-eslint-parser`). React-hooks scoped to `.jsx`/`.tsx` only (`.astro` is not React). The shared block's `files` selector includes `.astro`, so `check-file/filename-naming-convention` reaches `.ts`, `.tsx`, and `.astro` under `KEBAB_CASE`, overriding Astro's own PascalCase component convention deliberately, on the ground that a component's name in markup comes from the import binding rather than the filename. `.js` and `.jsx` stay out of the rule's own pattern, matching `web` and `nextjs`. `check-file/folder-naming-convention` reaches every `src/**` folder except `__tests__` and the whole `pages/` subtree, which carries its own off-block for the bracket-named dynamic routes and nested slug folders Astro's file-based routing produces. See `canon/context/surfaces/tooling.md` for the measurement.
+### Astro and test configs
+
+The configs below wire Astro into the web layer's test setup.
+
+- `astro.config.mjs` adds `@astrojs/react`, `@tailwindcss/vite` in `vite.plugins`, the `@/` alias via `vite.resolve.alias`, and `ASTRO_SITE` for the `site` field.
+- It serves port `4321` plus `WORKTREE_PORT_OFFSET` at `server.port`, with `strictPort` under `vite.server` and `vite.preview`.
+- Astro feeds `server.port` through as the preview port but merges the `vite` block into the config backing both servers, so the port sits at the top level and the bind guarantee under `vite`.
+- `vitest.config.ts` uses `getViteConfig` from `astro/config`, not `mergeConfig`, with jsdom, globals, the setup file, `passWithNoTests: true`, v8 coverage, and `**/*.astro` in coverage excludes.
+- `tsconfig.json` adds `skipLibCheck`, `vitest/globals` and `@testing-library/jest-dom/vitest` in types, and `@/` paths.
+
+### Playwright config
+
+`playwright.config.ts` runs all browsers, with `webServer` running `bun run build && bun run preview` on port `4321` plus `WORKTREE_PORT_OFFSET` and `reuseExistingServer: false`.
+
+- Astro's dev/prod gap is wide (MDX, island hydration, asset optimization), so E2E always tests the built `dist/`.
+- `DIST_PREBUILT` in the environment drops the `build` half, running `bun run preview` alone against a `dist/` a prior CI job produced.
+
+### ESLint config
+
+`eslint.config.js` is this stack's own flat config, since the web layer lints with oxlint, which parses no `.astro` file. It adds `eslint-plugin-astro` with `astro-eslint-parser`.
+
+- React hooks apply to `.jsx` and `.tsx` only, since `.astro` is not React.
+- `check-file/filename-naming-convention` reaches `.ts`, `.tsx`, and `.astro` under `KEBAB_CASE`, overriding Astro's PascalCase on purpose, since markup names a component by its import binding.
+- `.js` and `.jsx` stay out of that rule, matching `web` and `nextjs`.
+- `check-file/folder-naming-convention` reaches every `src/**` folder except `__tests__` and the `pages/` subtree, which has its own off-block for bracket-named dynamic routes and slug folders.
+- `canon/context/surfaces/tooling.md` carries the measurement behind both naming rules.
+
+The social card files also ship as golden configs, being `card.config.mjs`, `card-src/pages/og-card.astro`, and `scripts/check-card-exclusion.sh`. See `## Social card route` below.
 
 ## Typecheck
 
@@ -30,73 +54,90 @@ The astro stack covers Astro + TypeScript projects: content sites, marketing sit
 
 ## Vitest scope
 
-Unit-test React island components (`.tsx`) only. Do not test `.astro` files. Page-level behavior is verified by Playwright against rendered output.
+Unit-test React island components (`.tsx`) only. Do not test `.astro` files, since Playwright verifies page-level behavior against rendered output.
 
-Vitest is pinned to `^5` in the web manifest, which supports the Vite 8 that Astro 7 bundles. The earlier `^3` pin avoided `^4` bundling rolldown-vite, which ignored the esbuild JSX config in `@vitejs/plugin-react`. Astro now bundles Vite 8 itself, so that conflict no longer applies.
+Vitest is pinned to `^5` in the web manifest, which supports the Vite 8 that Astro 7 bundles. The earlier `^3` pin dodged `^4` bundling rolldown-vite, which ignored the esbuild JSX config in `@vitejs/plugin-react`. Astro bundling Vite 8 itself ended that conflict.
 
 ## Formatting (extend)
 
-- Format `.astro` files with Prettier and every other file with oxfmt. oxfmt loads no Prettier plugin, so it cannot parse `.astro`.
-- Load `prettier-plugin-astro` first in `.prettierrc`'s plugins, then `prettier-plugin-tailwindcss` last (per its docs), with a parser override for `.astro` files.
+- Format `.astro` files with Prettier and every other file with oxfmt, which loads no Prettier plugin and cannot parse `.astro`.
+- Load `prettier-plugin-astro` first in `.prettierrc`'s plugins and `prettier-plugin-tailwindcss` last, with a parser override for `.astro` files.
 - Ignore `**/*.astro` in this stack's `.oxfmtrc.json`, so the two formatters never touch one file.
-- Copy every other option from base's `.oxfmtrc.json` into this one by hand. Scan takes the child config over the parent's whole file, so a change to base's options is lost here until it is copied.
+- Copy every other option from base's `.oxfmtrc.json` by hand. Scan takes the child config over the parent's whole file, so a change to base's options is lost here until copied.
 - Override `check:format` and `format` to run oxfmt, then Prettier over `**/*.astro`.
 
 ## ESLint
 
 - Override `lint` and `lint:fix` back to `eslint . --max-warnings 0`, since the web layer sets them to oxlint.
-- Install the ESLint packages here (`eslint@^9`, `@eslint/js`, `typescript-eslint`, `eslint-config-prettier`, `eslint-plugin-react-hooks`, `eslint-plugin-vitest`, `globals`), since the web layer no longer ships them. Pin `eslint@^9`: ESLint 10 dropped the `LegacyESLint` shim `typescript-eslint@8` still imports.
+- Install `eslint@^9`, `@eslint/js`, `typescript-eslint`, `eslint-config-prettier`, `eslint-plugin-react-hooks`, `eslint-plugin-vitest`, and `globals`, since the web layer no longer ships them.
+- Pin `eslint@^9`, because ESLint 10 dropped the `LegacyESLint` shim `typescript-eslint@8` still imports.
 - Expect the web layer's `.oxlintrc.json` in the target. Nothing runs it here.
 
 ## Development docs (extend)
 
-Append to the `## Scripts` table:
+Append these rows to the `## Scripts` table.
 
-| `bun run dev` | Start the Astro dev server on port 4321, plus this worktree's port offset. |
-| `bun run build` | Run `astro check` then build the static output. |
-| `bun run preview` | Serve the built site locally. |
-| `bun run astro` | Expose the Astro CLI. |
-| `bun run typecheck` | Run `astro check`. |
+| Command             | Purpose                                                         |
+| ------------------- | --------------------------------------------------------------- |
+| `bun run dev`       | Start the Astro dev server on 4321 plus this worktree's offset. |
+| `bun run build`     | Run `astro check` then build the static output.                 |
+| `bun run preview`   | Serve the built site locally.                                   |
+| `bun run astro`     | Expose the Astro CLI.                                           |
+| `bun run typecheck` | Run `astro check`.                                              |
 
 ## CI docs (extend)
 
-In `canon/context/development/ci.md`, the Typecheck row's assertion reads: `` `astro check` passes ``. The Build row's assertion reads: `` `astro build` succeeds ``. <!-- audit-ignore-citations: canon/context/development/ci.md -->
+In `canon/context/development/ci.md`, the Typecheck row asserts `` `astro check` passes `` and the Build row asserts `` `astro build` succeeds ``. <!-- audit-ignore-citations: canon/context/development/ci.md -->
 
 ## Social card route
 
-The social card is a route the project keeps rather than a page a render writes and deletes, so re-rendering it after a rename is an edit to one string and a re-capture instead of another pass through `draft-identity`'s pick loop with an operator in it. `canon:draft-identity` writes the picked composition into the route and captures it through the server below.
+The social card is a route the project keeps rather than a page a render writes and deletes. Re-rendering it after a rename is an edit to one string and a re-capture, not another pass through the `draft-identity` pick loop.
+
+`canon:draft-identity` writes the picked composition into the route and captures it through the server below.
 
 ### What ships
 
-- `card.config.mjs`: a second Astro config whose `srcDir` points at `./card-src`, which the main config's page router never reads. That is what excludes the card from the published build structurally rather than by a filename convention, the same mechanism `scenarios.astro` reaches for with `import.meta.env.DEV`. Its base port is `4421` plus `WORKTREE_PORT_OFFSET`, outside the band `astro.config.mjs` serves from, so a card server and a dev server of one worktree never contend.
-- `card-src/pages/og-card.astro`: the route, shipped as a working placeholder so it serves before any pick has been taken. It imports the project's own global stylesheet, which is what lets the composition read real tokens and real fonts instead of typed copies. It reads `--color-background` and `--color-text`, the names `canon design css` emits, and sets no `font-family` at all so the card inherits the project's body font rather than reading a font token the design system does not emit.
-- `scripts/check-card-exclusion.sh`: fails when the route's `<meta name="og-card-marker">` tag reaches `dist/`, and fails when the route dropped that tag, since the marker is what the leak test reads for.
-- `bun run card:dev` serves the route. `bun run card:check` runs the exclusion check, which base's verify runner, `scripts/verify.ts`, also runs after its build stage whenever the script is installed.
+The route is a second config, an exclusion check, and two scripts. The page itself is covered below.
+
+- `card.config.mjs` is a second Astro config whose `srcDir` points at `./card-src`, which the main config's page router never reads. That excludes the card from the published build structurally.
+- `card.config.mjs` uses base port `4421` plus `WORKTREE_PORT_OFFSET`, outside the band `astro.config.mjs` serves from, so a worktree's card and dev servers never contend.
+- `scripts/check-card-exclusion.sh` fails when the route's `<meta name="og-card-marker">` tag reaches `dist/`, and when the route dropped the tag, since the leak test reads it.
+- `bun run card:dev` serves the route and `bun run card:check` runs the exclusion check, which base's `scripts/verify.ts` also runs after its build stage when the script is installed.
 
-### Why each piece is shaped that way
+### Stylesheet and tokens
 
-The stylesheet import points at `@/styles/global.css`. A project keeping its stylesheet elsewhere retargets that one line, and an unresolved path then refuses the card server by name, which is the loud direction rather than the convenient one. The quiet failure it replaces is a card captured against no stylesheet at all: it renders as an unstyled box and reports success.
+`card-src/pages/og-card.astro` ships as a working placeholder, so it serves before any pick. It imports the project's global stylesheet to read real tokens and fonts, uses `--color-background` and `--color-text` as `canon design css` emits them, and sets no `font-family`, so the card inherits the body font.
 
-A custom property the stylesheet does not define is the same silent failure in a second costume. It takes its fallback, captures cleanly and reports success, so the card ships on typed values while reading as though it read real ones. That is why the route names only properties `canon design css` emits, and why a project retargeting the stylesheet import checks the names against what its own stylesheet defines.
+- The import points at `@/styles/global.css`. A project keeping its stylesheet elsewhere retargets that one line.
+- An unresolved path refuses the card server by name. That is the loud direction, replacing a card captured against no stylesheet that renders unstyled and reports success.
 
-The exclusion is a check rather than a convention because the route has three consumers and only one of them can be enforced. The card server reads it, the capture reads it, and the published build must not carry it.
+- A custom property the stylesheet does not define fails the same silent way. It takes its fallback, captures cleanly, and ships typed values.
+- So the route names only properties `canon design css` emits, and a project retargeting the import checks the names against its own stylesheet.
 
-`.card` is declared at 600x315, half of the 1200x630 target. `canon capture` opens every page at a fixed 2x device scale factor with no flag to change it, so a half-size element is what lands the captured PNG on the literal size. Declaring it at 1200x630 captures at 2400x1260.
+### Exclusion and card size
+
+The exclusion is a check rather than a convention because the route has three consumers and only one can be enforced. The card server reads it, the capture reads it, and the published build must not carry it.
+
+`.card` is declared at 600x315, half of the 1200x630 target. `canon capture` opens every page at a fixed 2x device scale factor with no flag to change it, so a half-size element lands the PNG on the literal size. Declaring 1200x630 captures at 2400x1260.
 
 ### Why v1 is Astro-only
 
-Astro is the one web stack whose config gives a route a structural build exclusion. Next's App Router has no build-time route exclusion at all, and it needs none on the path it will take, since `ImageResponse` is that framework's own production mechanism and a card route there is meant to be served. `vite-react` builds a single-page app with no page router, so a card is a second Rollup entry rather than a route.
+Astro is the one web stack whose config gives a route a structural build exclusion.
+
+- Next's App Router has no build-time route exclusion, and needs none on its path, since `ImageResponse` is that framework's production mechanism and a card route there is meant to be served.
+- `vite-react` builds a single-page app with no page router, so a card is a second Rollup entry rather than a route.
 
 ## Gitignore (extend)
 
-`[gitignore]` groups this stack edits, restated here per the manifest-to-reference symmetry:
+These `[gitignore]` groups mirror the manifest.
 
 - `"# Astro" = [".astro/"]`
 - `"# Social card" = ["card-dist/"]`
 
 ## Scenario switcher
 
-- `src/components/dev/scenarios.astro` ships as a golden config, always overwritten on sync, since it is toolkit-authored infrastructure rather than a file a project hand-edits.
-- Import it into a page under test to drive candidate treatments of one decision by hand, selected by a query parameter, with a switcher for moving between them.
-- Guarded by `import.meta.env.DEV`, so it renders nothing and ships nothing in a production build.
-- Astro-only. It uses `is:inline`, `define:vars`, and `set:html`, which only the `.astro` file format parses. `vite-react` gets no equivalent until a real decision drives one.
+`src/components/dev/scenarios.astro` ships as a golden config, always overwritten on sync, since it is toolkit-authored infrastructure rather than a file a project hand-edits.
+
+- Import it into a page under test to drive candidate treatments of one decision by hand, selected by a query parameter, with a switcher between them.
+- It is guarded by `import.meta.env.DEV`, so it renders nothing and ships nothing in a production build.
+- It is Astro-only, using `is:inline`, `define:vars`, and `set:html`, which only the `.astro` format parses. `vite-react` gets no equivalent until a real decision drives one.