Astro 5 → 6 migration

.github/workflows/ci-pr.yml

@@ -0,0 +1,47 @@
+# PR-triggered CI on PRs targeting `main`.
+# Runs `astro check` (TypeScript + Astro templates) and a full build.
+# The `build-pr` job name is referenced as a required status check on
+# the `protect-main` ruleset — see docs/TECH_STACK.md §8.4.
+#
+# `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` opts into Node 24 for JS-based
+# actions, ahead of GitHub's runtime default flip on 2026-06-02.
+
+name: CI — PR
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-pr-${{ github.head_ref }}
+  cancel-in-progress: true
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+jobs:
+  build-pr:
+    name: build-pr
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Astro check
+        run: npm run check
+
+      - name: Build
+        run: npm run build

CLAUDE.md

@@ -11,6 +11,23 @@ Read these in order:
 3. `docs/BASELINE_COPY.md` — editorial content for every page. Use verbatim.
 4. `design/handoff-bundle/README.md` — the Claude Design export, if present.
 
+## Workspace bootstrap
+
+After the docs above, orient against the working state:
+
+1. `plans/BOOTSTRAP.md` — current project state, in-flight topics, recent
+   decisions. The slow-moving entry point.
+2. `plans/INDEX.md` — table of contents for the workspace. Claude-maintained
+   via propose-then-validate; never hand-edited.
+3. `plans/HANDOFFS/` — if a file dated within the last week exists, read the
+   most recent one before acting; it carries the previous session's tail
+   state.
+
+Working artefacts (plans, sub-agent reports, drafts, decision logs) live
+under `plans/active/<topic>/`; closed work lives under `plans/_archive/`.
+Naming, write-path, and INDEX-maintenance conventions: `plans/meta/conventions.md`.
+Sub-agents dispatch on Opus by default; Sonnet only for mechanical tasks (justification in prompt frontmatter).
+
 ## Core principles
 
 - This is a **content website**, not an application. Prioritize performance,
@@ -44,6 +61,44 @@ feel.
 **Pass 2 — remaining pages.** After Pass 1 is validated in real deployment,
 implement Products (with empty state), Contact, Impressum, Datenschutz, and 404.
 
+## Gate-based handoff pattern
+
+Pass 1 shipped a working production system on the first production deploy
+despite three failed staging attempts. The discipline below is what made that
+possible; Pass 2 should follow it.
+
+- For implementation work involving multiple decision points (token
+  conversions, multi-step deploys, significant architecture changes), produce
+  a plan document first and surface it for review before starting. Don't
+  begin implementation until explicit approval.
+- For each significant commit or deploy, pause at named gates (e.g., after
+  `wrangler.jsonc` is written, before first deploy) and wait for confirmation.
+- For diagnostic work, report findings before making changes. Don't edit
+  based on an assumed fix until the diagnostic has been reviewed.
+- Surface uncertainty as explicit open questions in plans, not resolved
+  silently.
+
+## Process rules from Pass 1
+
+Specific technical lessons worth codifying:
+
+- **Token conversion verification.** When translating design tokens between
+  framework versions, diff against **both** the source preset **and** any
+  companion CSS-custom-property file in the handoff bundle. Presets may omit
+  aliases that the companion file declares for readability. The Pass 1
+  missing-`--color-bg` bug slipped through because verification compared the
+  converted file against the preset only.
+- **Wrangler environment inheritance.** `wrangler.jsonc` top-level config does
+  **not** inherit into named environments for several keys: `observability`,
+  `vars`, `routes`, `name`, `main`, `compatibility_flags` (and more). Declare
+  these inside each `env.*` block when using `--env` in `wrangler deploy`.
+- **Primary-source verification for API / namespace questions.** When a task
+  depends on version-specific API behavior (framework routing, build-tool
+  namespaces, CLI permissions), verify against primary sources — the
+  framework's own source code, official docs, maintainer statements in
+  issues/discussions — before assuming. A targeted sub-agent with web search
+  is a valid escalation pattern and was used three times in Pass 1.
+
 ## Skills
 
 When writing or modifying UI components, invoke the `frontend-design` skill.

astro.config.mjs

@@ -13,6 +13,13 @@ export default defineConfig({
       prefixDefaultLocale: false,
     },
   },
+  // Disable smartypants so Markdown body content preserves the ASCII
+  // apostrophes ('), straight quotes, and `--` from BASELINE_COPY.md
+  // verbatim. The default (enabled) silently rewrites them to typographic
+  // forms, violating the "use copy verbatim" project rule.
+  markdown: {
+    smartypants: false,
+  },
   vite: {
     plugins: [tailwindcss()],
   },